=== Adventurebook ===
Contributors: icetear
Donate link: https://adventurebook.net
Tags: adventure, storybook, interactive, adventurebook, storytelling
Requires at least: 5.2
Tested up to: 7.1
Stable tag: 1.0.38
Requires PHP: 7.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Lets you create interactive Storybooks or Roleplay-Like Adventurebooks.

== Description ==

Adventurebook is a plugin that allows you to create interactive storybooks or roleplay-like adventure books on your WordPress site. With Adventurebook, you can craft engaging narratives where readers can make choices that influence the outcome of the story.

Key Features:

* Interactive Storytelling: Create stories with multiple paths and endings based on reader choices.
* Easy-to-Use Interface: User-friendly tools to design and manage your adventure books.
* Customizable Options: Tailor the appearance and functionality of your adventure books to fit your style.
* Multimedia Support: Enhance your stories with images. Add audio to pages that will be played automatically when the page is loaded (if your browser permits).
* Character and Item Management: For "Game"-type Adventurebooks, manage items and creatures that characters can interact with.
* Combat System: A simple turn-based combat system for "Game"-type Adventurebooks, allowing characters to engage with creatures.
* Script Editor: Create custom scripts to add dynamic elements to your adventure books.
* Responsive Design: Ensure your adventure books look great on all devices.

Whether you're an author looking to publish interactive stories or a teacher wanting to create engaging learning materials, Adventurebook provides the tools you need to bring your narratives to life.
Get started today and captivate your audience with immersive storytelling!

See it in action:

- Travel through Cologne (german) (Story-type): https://koeln.adventurebook.net
- Travel on the Camino (german) (Game-type): https://camino.gaida.de
- Relaxing Journey (english, incl. Google Translate) (Story-type): https://adventurebook.net/relaxing-journey/
- The Morning After (german, incl. Google Translate) (Story-type): https://adventurebook.net/der-morgen-danach/
- Play Demoworld (english, incl. Google Translate) (Game-type): https://adventurebook.net/play-demoworld/

The "Demoworld" Adventurebook is also included in the premium version of the plugin as demo content to help you get started.

== Screenshots ==

1. Adventurebook embedded in a page.
2. Adventurebook embedded in a page with different decisions.
3. Adventurebook book management.
4. Adventurebook item management.
5. Adventurebook item editor.
6. Adventurebook book page editor.
7. Character management embedded in a page ("Game"-type Adventurebook only).
8. A fight with a creature in a "Game"-type Adventurebook.

== Installation ==

1. Upload the `adventurebook` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Use the 'Adventure Books' menu item to create and manage your adventure books.

For a step-by-step video guide, visit:

[youtube https://youtu.be/-y0JtnjRWwQ]


== How to Use ==

1. After activating the plugin, navigate to the 'Adventure Books' menu in your WordPress dashboard.
1. Click on 'Add New Adventure Book' to start creating your adventure book frame. Just enter a title and maybe a short description.
1. Save the adventure book.
1. Add pages by editing your adventure book and using the 'Add New Book Page' button on the right side of the editor. 
Alternatively, you can manage your book pages using the 'Book Pages' menu. Be sure to set the filter to the correct book. 
2. When editing a book page, you can add choices by using the 'Add Decision Option' button at the bottom. 

    Each choice can link to another (existing) page in the book, allowing for branching narratives. Be sure to first create the target pages before linking them.
1. You can add a single image to each book page using the 'Book Page Image' option in the editor.
1. After having added a decision to a page, you can restrict the choice to characters that have a specific item.
    
    This applies to Game-type Adventurebooks.
To do this, choose "Restriction Type" -> "Item" and then enter the code of the item that the character must have to be able to choose this option.
E.g. if you restrict a decision to the item with code "key_gold", only characters that have this item in their inventory can choose this option.


== How to setup a Game-type Adventurebook ==

1. Create a page for character management with the shortcode `[adventurebook_character_overview]`.
1. Set this page in the Adventurebook settings.
1. Create a new Adventurebook of type "Game".
1. Create a page for the book with the shortcode `[adventurebook id="X"]`, where X is the ID of your adventure book.
1. The adventurebook will be embedded in this page.
1. Create items in the "Adventurebook Items" menu. You can upload an image for the item and define stats. For details, see below.
1. Create creatures in the "Adventurebook Creatures" menu. You can upload an image for the creature and define stats. For details, see below.
1. Create book pages and add item spawns / creature spawns to the pages. For details, see below.
1. Set the starting page by selecting the bookpage of your choice on the Adventurebook edit page.

== Items ==

Items are defined in the "Adventurebook Items" menu. Every item has a code, a name, a description, stats and an image.
The code is a unique human readable identifier for the item, e.g. "key_gold".
Stats are depending on the chosen Combat System. In the free version, only the "Simple" combat system is available.

E.g. a longsword could be defined by:

* code: sword_longsword
* name: Longsword
* description: A sharp longsword.
* stats: Slot=Weapon,Damage=10,Value=15
* image: (upload an image of a longsword)


== Creatures ==

Creatures are defined in the "Adventurebook Creatures" menu. Every creature has a code, a name, a description, hostility, attackability, xp value, stats, loottable and an image.
The code is a unique human readable identifier for the creature, e.g. "goblin".
Stats are depending on the chosen Combat System. In the free version, only the "Simple" combat system is available.

E.g. a goblin could be defined by:

* code: goblin
* name: Goblin
* description: A small green goblin. Looks hostile.
* hostility: hostile
* attackability: can be attacked
* xp value: 5
* stats: Health=20,Damage=5,Armor=2
* loottable: sword_longsword:20:1:1,leather_armor:10:1:1
* image: (upload an image of a goblin)

The loottable defines which items the creature can drop when defeated. The format is:
`item_code:chance:min_amount:max_amount`
E.g. `sword_longsword:20:1:1` means that the creature has a 20% chance to drop 1 longsword when defeated.
For gold/money, use the item code "money".
E.g. `money:100:5:15` means that the creature will always drop between 5 and 15 gold when defeated.

== Combat Systems ==

To make the plugin more flexible, different combat systems can be chosen.
Currently, only the "Simple" combat system is available in the free version.
In the "Simple" combat system, the currency is set to "Gold".

= Character Stats =

Character Stats for the "Simple" combat system are:

* Health (Defaults to 35)
* CurHealth
* Wealth (Gold) (Defaults to 10)
* XP (Defaults to 0)
* Slots (Defaults to 'Weapon,Shield,Armor')

internal use only:
* initiative (Defaults to 0)
* attack (Defaults to 0)
* armor (Defaults to 0)
* defense (Defaults to 0)

= Creature Stats =

Creature Stats for the "Simple" combat system are:

* Health
* Damage
* Armor

= Item Stats =

Item Stats for the "Simple" combat system are:

* Value

  how much (Gold) the item is worth when selling it to a shop

* Armor

    how much armor the item provides when equipped

* Damage

    how much damage the item provides when equipped

* Slot

    if the slot of an item matches any slot of a character, the item can be equipped by the character.
In the Simple Combat System, the available slots are 'Weapon', 'Shield' and 'Armor'. Only one item can be equipped per slot.

Examples:

* A sword could have the slot 'Weapon' and damage 10.
* A shield could have the slot 'Shield' and armor 5.
* A leather armor could have the slot 'Armor' and armor 3.
* A chain mail could have the slot 'Armor' and armor 7.

If a player has a leather armor equipped, his armor stat is 3.
If he equips the chain mail, the leather armor will be unequipped and the armor stat will be 7.

= Combat =

* When a character visits a page with creature spawns, he can choose to attack a creature.
* The combat is turn-based. For each turn, the initiative is calculated randomly.
* The character and the creature attack each other until one of them has 0 or less health.
* If the character wins, he gets XP and Gold (Wealth) according to the creature's stats. The creature is removed from the page and will respawn after the set respawn time.
* If the character loses, he is moved back to the starting page / his respawn point and his health is fully restored.
* If the initiative of the character is higher than the initiative of any hostile creature on the page, he surprises the creature and gets a free turn before the combat starts.
* If an enemy is not hostile, but can be attacked, the character can choose to attack it, turning it hostile.

Damage dealt: Damage Value (Attacker) - Armor Value (Defender), minimum 1 damage.


== Frequently Asked Questions ==

= How do I install Adventurebook? =
To install Adventurebook, download the plugin from the WordPress plugin repository or upload the `adventurebook` folder to your `/wp-content/plugins/` directory. Then, activate the plugin through the 'Plugins' menu in your WordPress dashboard.
IMPORTANT: For game-type Adventurebooks, you need to have a page for the character management with the shortcode [character_overview].
Set this page in the Adventurebook settings.
After having created an adventure book, you need to create a page for the book with the shortcode [adventurebook id="X"], where X is the ID of your adventure book.
The adventurebook will be embedded in this page.

= How do I create a new adventure book? =
After activating the plugin, navigate to the 'Adventure Books' menu in your WordPress dashboard and click on 'Add New Adventure Book' to start creating your adventure book.

= How do I add pages to the book? =
You can add pages by editing your adventure book and using the 'Add New Book Page' button on the right side of the editor.
Manage your book pages using the 'Book Pages' menu.

= How do I create choices for the readers? =
When editing a book page, you can add choices by using the 'Add Decision Option' button at the bottom.
Each choice can link to another (existing) page in the book, allowing for branching narratives. Be sure to first create the target pages before linking them.

= How do I restrict access to certain pages? =
This applies to Game-type Adventurebooks. After having added a decision to a page, you can restrict the choice to characters that have a specific item.
To do this, choose "Restriction Type" -> "Item" and then enter the code of the item that the character must have to be able to choose this option.
E.g. if you restrict a decision to the item with code "key_gold", only characters that have this item in their inventory can choose this option.

= Can I add images and videos to my adventure books? =
You are allowed to add a single image to each book page using the 'Book Page Image' option in the editor.

= Do WordPress Galleries work in Adventurebook pages? =
Yes, WordPress Galleries work in Adventurebook pages. You can create a gallery using the standard WordPress gallery shortcode.
Please let the gallery link to the media file so that the images open in a lightbox when clicked.

= Is Adventurebook compatible with all themes? =
Adventurebook is designed to work with most WordPress themes. However, for the best experience, we recommend using a theme that supports custom post types.
Make sure that you have enough width to display the book content properly if using the "Game" type Storybook. You need space for the image, the description and the character stats.

= Is there a premium version available? =
Yes, there is a premium version of Adventurebook available with additional features and support. Visit our website for more information: https://adventurebook.net


== CHANGELOG ==

= 1.0.38 =

* Maintenance release: verified compatibility with WordPress 7.1. No functional
  changes.

= 1.0.37 =

* Geo map: shops are now marked with a small euro badge on their marker (next to
  the stamp star), so players can see at a glance where they can buy things.

= 1.0.36 =

* Geo map: the routes between places are now drawn as connecting lines, so the
  book's map shows the whole network at a glance.

= 1.0.35 =

* Geo map: places that award a pilgrim stamp are now marked with a golden star
  on their marker (the green/blue colour still shows visited/not visited).

= 1.0.34 =

* Geo map: places the current character has already visited are now shown with a
  green marker (unvisited places stay blue).
* Fix: visited-page tracking now reads the list that is actually written when a
  character moves, so the map reflects real progress.

= 1.0.33 =

* i18n: translated the remaining English labels in the character info ("Wealth")
  and the pilgrim passport ("Pilgrim Passport", "pilgrim stamp").

= 1.0.32 =

* Layout: on narrow screens the page content now uses the full width (the empty
  character-card column is properly removed instead of leaving a gap).
* Layout: reduced the large empty space between the site menu and the page title.

= 1.0.31 =

* Fix: for characters with an empty inventory the character card emitted one
  extra closing tag, which prematurely closed the game layout container. As a
  result the page title and text were pushed below the character card instead of
  sitting to its left. The card now correctly floats to the right of the title
  and page content.
* Cached character/inventory markup is now cleared automatically on plugin
  updates, so layout fixes take effect immediately.

= 1.0.30 =

* Layout: the page title is now a full-width row across the top; below it the page
  image with wrapping text sits on the left and the character card on the right
  (previously the title shared the top row beside the card).
* Fix: the admin stylesheet is now also versioned with the plugin version, so the
  editor screens pick up CSS changes after an update instead of a cached copy.

= 1.0.29 =

* i18n: completed the German translation of the character overview and pilgrim
  passport (labels such as "Development Points", "Effects", "Collectible Bonuses"
  and the passport texts were still shown in English). Regenerated .mo/.l10n.php.

= 1.0.28 =

* Fix: the stylesheet is now versioned with the plugin version, so browsers reliably
  load the current CSS after an update instead of a stale cached copy.

= 1.0.27 =

* Layout: the game view now uses a robust two-column grid — page content (title,
  image, text, decisions) on the left, the character card on the right — instead of a float.

= 1.0.26 =

* Layout: the character card now floats to the top-right, with the page title on the
  left and the page image and text flowing below it (previously the card dropped below the title).

= 1.0.25 =

* Fix: character overview icons now display correctly (they used the "regular"
  Font Awesome style, which is mostly unavailable in the free set — switched to "solid").
* Fix: the drop-cap initial letter is now only applied to the first paragraph of a
  page, no longer to image credits or following paragraphs.
* Layout: the game content keeps a readable maximum width on wide screens; image
  credits render smaller and more discreetly.

= 1.0.24 =

* Introducing the Pilgrim Passport (Premium):
  * New script command "collect_stamp code|Name|Emoji|Color" collects a passport
    stamp for the character. It is idempotent, so it is safe on pages that can be
    entered more than once.
  * New script command "if_stamp_goto code|key" branches on already-owned stamps.
  * New shortcode "[adventurebook_pilgrim_pass book_id="123"]" shows the collected
    stamps as CSS "ink stamps" (name, date, motif); the stamps also appear in the
    character overview.
  * Stamp/passport wording can be overridden by the combat system (the Pilgrim
    Combat System labels them "pilgrim stamp" / "Pilgrim Passport").

= 1.0.23 =

* Introducing the Geo Map (Premium):
  * Each adventurebook page can now store real-world coordinates (latitude/longitude)
    via the new "Geo Coordinates" meta box, including a "show on map" toggle.
  * New shortcode "[adventurebook_geo_map book_id="123" height="480"]" renders an
    interactive OpenStreetMap with one marker per page (popup with title and teaser).
  * Based on Leaflet 1.9.4, bundled locally with the plugin — no API key and no
    external CDN required (map tiles are loaded from openstreetmap.org).
  * Coordinates are exposed in the REST API (adventurebook_page meta) for
    programmatic editing.

= 1.0.22 =

* Introducing Effects:
  * New script command "add_effect effect_name|effect_type|duration|power"
    * Adds an effect to the character for the given duration (in rounds).
    * Effect types:
      * drunk: Reduces the character's combat stats by the given power.
      * heal: Heals the character by the given power each round.
      * poison: Damages the character by the given power each round.
  * New script command "remove_effect effect_name"
    * Removes the effect with the given name from the character.
  * New script command "if_effect_goto effect_name|key"
    * If the character has the effect with the given name, jump to the given key in the script.
  * Effects are displayed in the character overview.
* Introducing Recipes (Premium):
  * New script command "if_has_recipe_ingredients_goto" and "use_recipe".
  * Items that use a recipe script can define the recipe in the stat "UseData".
  * E.g. "wood:1;club:1" means that the item can be used to create 1 club if the character has 1 wood.
* Items can now have unlimited use by setting the "Charges" stat to -1.
* Enemies can have a stat "Gamevar" which contains the name of a game variable.
  * When the enemy is defeated, the game variable will be set to "1".
  * This can be used to restrict decisions based on whether an enemy has been defeated or not.
* New page type "Bank":
  * Characters can deposit and withdraw money (Wealth).
  * Buying items and training skills will now also work with money in the bank.

= 1.0.21 =

* Fix a bug in the Quick Access Meta Box (admin edit book page)

= 1.0.20 =

* Refactoring Item Spawns. Now Items can respawn.
* Money will drop as an item from creatures. Use the item code "money" for defining money in the loottable of a creature.
* Restyling.
* More Inline Editing Options
* When an admin is logged in and has inline editing enabled, he won't receive damage in combat.
* 2h Weapons now work. If a character equips a 2h weapon, the shield slot will be blocked. Define a 2h weapon by setting it's stat "Slot" to "Weapon+Shield".
* Admins can now kill creatures directly from the combat screen.
* Add indefinite articles ("a", "an") to enemy names in the combat screen.
* Add "Might" to the Character and Enemy overview (Admin), this is for comparison.
* Add new script commands.

= 1.0.19 =

* Refactoring Health. You just need to set "Health" as a stat for characters and creatures.
  The current health of a character or creature is automatically stored in "CurHealth".
* New Premium Feature: Auto Map (Admin Menu) - will show an interactive map of all pages and their connections.
* Visited zones are now saved in the character stats as "VisitedZones" (comma separated list of page IDs).
* New skill "First Aid" (ArM Combat System, premium only)
  * Characters with this skill can heal themselves.
* Shop restyling

= 1.0.18 =

* Character overview now shows the inventory items with their images

= 1.0.17 =

* Add some missing files
* Fix some output escaping and input sanitizing issues

= 1.0.16 =

* Show decisions in the book pages overview.
* New script command "set_var_random var_name|min_value|max_value"
  * Sets the variable with the given name to a random value between min_value and max_value (inclusive).
* New script command "teleport location_id"
  * Teleports the character to the given location ID.
* Export and Import options for exporting only certain parts of an adventurebook (e.g. only items, only creatures, only pages, only scripts).

= 1.0.15 =

* Add option to turn inline editing on/off in the Adventurebook settings.
* Add inline editing of pages, item spawns and creature spawns in the book page edit screen.
* Add option to jump to a page directly if inline editing is enabled.
* Add option to remove all pages, items, creatures and scripts including used images when deactivating the plugin.

= 1.0.14 =

* Add alternate page ids for enemy spawns. When an enemy spawns he will spawn on one of the given pages randomly.
* Add Option to enable/disable keyboard navigation (1-9 to select a decision).
* Add Import and Export functionality for whole adventurebooks (including pages, items, creatures, scripts).

= 1.0.13 =

* Updated Screenshots
* New script command "add_skill skill_name=value" (premium only)
* New script command "if_stat_goto" (premium only)
* New script command "if_skill_goto" (premium only)
* Add <, > and = to the script commands "if_stat_goto", "if_skill_goto" and "if_var_goto"
* New decision type "skill"
* Import Script commands from SAGA
* Export the whole book to a JSON file
* Refactored character stats handling
* Move Settings page to the adventurebook menu
* Show decision only if restriction is fulfilled
* Items can now have Charges (e.g. a potion with 3 charges)
* Added Ars Magica like Combat System (premium only)

= 1.0.12 =

* Changed website URL in the readme.txt and plugin header to https://adventurebook.net

= 1.0.11 =

* Sell item button now shows in the topbar on small screens too
* Fix a bug causing your wealth not to decrease when buying an item in a shop

= 1.0.10 =

* Restyling for small screens (usage of shortcode in sidebar widgets)
* Error fixing

= 1.0.8 =

* Add automatic numbering of decisions and listen to keyboard input (1-9) to select a decision
* Add Option (Admin -> Settings -> Adventurebook) for setting a fixed content height for the adventurebook content area
  * If the content exceeds this height, a scrollbar will be shown
  * This prevents the page from jumping when the content height changes
  * 0 means no fixed height

= 1.0.7 =

* Script Editor: Scripts are now sorted by keys
* Script Editor: Instead of typing the command code, you can select the command from the list of available commands
* New script command `jump key` (premium only)
  * jumps to the specified key
* New script command `remove_money amount` (premium only)
  * removes the amount of money from the character
* In "Story"-Type Adventurebooks:
  * Removed Restrictions for decisions
  * Removed Enemy Spawns, Item Spawns, Book-Type Selection, Shop-Options
* New restriction type: game_var
  * Checks a game_var for a specific value (game_var_name=abc), if you want to compare numbers you can use <, > and =
* New restriction type: stat
  * Checks a character stat for a specific value (stat_name=123). You can use <, > and =.
    E.g. "Wealth>99" is fulfilled when the character has 100 (Simple Combat System: "Gold").
* Add an Audio file to a book page (mp3, ogg, wav)
* If an audio file is set, it will be played automatically when the page is loaded (if your browser permits)
* A "Play Audio" button will be shown right next to the page title

= 1.0.6 =

* show "wait one round" only in game-type adventurebooks
* remove icon from "wait one round" button
* completed english (us) and german translations
* better content styling

= 1.0.5 =

* add gallery css to the adventurebook.css (WP Gallery now works in adventurebook pages)

= 1.0.4 =

* Added some information to the readme.txt
* Added banners

== UPGRADE NOTICE ==

None yet.

== Technical Details ==

The following information is for the Adventurebook Type "Game".

# Item Definitions (table `_adventurebook_item_definitions`)

Every item in the world/game has a definition. The definition is stored in the table `_adventurebook_item_definitions`.
The definition contains non-mutable information about the item.

* `id`
* `code` (unique human readable identifier, used for restrictions e.g.)
* `name`
* `description`
* `stats`
* `image-url`

# Item Spawns (table `_adventurebook_item_spawns`)

Defines a spawn point for an item. The spawn point is a zone.
When a new character is created, all items that have a spawn point will be added to the zone (page).

* `item_id`
* `page_id`

# Items (table `_adventurebook_items`)

Defines an item that a character can find in his adventure.

* `id`
* `code`
* `character_id`
* `location_id`

# Scripts (table `_adventurebook_scripts`)

Defines a script that can be attached to a page and is executed when the page is visited / reloaded.

* `id`
* `code` (unique human readable identifier, used to attach the script to a page)
* `name` (will not be displayed to the user)
* `commands` (the commands that will be executed, array in json format)


== SCRIPT COMMANDS ==

Scripts can be attached to book pages and are executed when the page is visited / reloaded, e.g. each time the user clicks on a decision that leads to this page,
or when attacking, equipping, unequipping, buying, selling, using an item.
A script can be attached to an adventurebook page by selecting the script in the "Script" dropdown on the page edit screen.
Every script line needs a unique key (it is a jumpmark).
The second input field is the command. The third input field is optional and can contain parameters for the command, usually separated by "|".

The following script commands can be used in a script.

* `output text`
Outputs the given text to the user. Supported placeholders:
  * {var:varname}: Replaced with the value of the game variable "varname".
  * {stat:statname}: Replaced with the value of the character's stat "statname".
  * {itemcount:itemcode}: Replaced with the count of the item "itemcode" in the character's inventory.
  * {charactername}: Replaced with the name of the character.

* `output text|text color`
Outputs the given text to the user in the given color. Color can be a color name (e.g. "red") or a hex color (e.g. "#ff0000").

* `show_key_link text|key`
Outputs the text as a clickable button and links it to a certain key in the script.

* `add_item item_code`
Gives the item with the given code to the character.

* `remove_item item_code`
Removes the item with the given code from the character.

* `if_item_is_here_goto item_code|key`
If the item with the given code is in the current location, jump to the given key in the script.

* `heal amount`
Heals the character by the given amount. If the amount is -1, the character will be fully healed.

* `stop`
Stops the execution of the script and sets the key to 0, so that the script will be executed from the beginning the next time the page is visited.


= Script Example =

`100     output         A wooden bench is here.`
`110     showkeylink    Sit down and take a rest|200`
`120     stop`
`200     output         You sit down on the bench and take a rest. You feel better.|green`
`210     heal           10`
`220     stop`

Note: The premium version of the plugin comes with different premade scripts.

== PLANNED ==

