=== Adventurebook ===
Contributors: icetear
Donate link: https://adventurebook.gaida.de/
Tags: adventure, book, interactive, story, roleplay
Requires at least: 5.2
Tested up to: 6.8
Stable tag: 1.0
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.
- 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!

== 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 book page editor.
6. Character management embedded in a page ("Game"-type Adventurebook only).
7. "Game"-type Adventurebook embedded in a page with decisions and items.

== 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.

== How to Use ==

1. After activating the plugin, navigate to the 'Adventure Books' menu in your WordPress dashboard.
2. Click on 'Add New Adventure Book' to start creating your adventure book.
3. Use the editor to add pages, choices, and multimedia elements to your book.
4. Publish your adventure book and share it with your audience!
5. Use the shortcode `[adventurebook id="X"]` (where X is the ID of your adventure book) to embed the book on any page or post.
6. Create book pages using the "Book Pages" menu.
7. Set the starting page by selecting the bookpage of your choice on the Adventurebook edit page.

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

1. Create a page for character management with the shortcode `[adventurebook_character_overview]`.
2. Set this page in the Adventurebook settings (Wordpress Admin -> Settings -> Adventurebook).
3. Create a new Adventurebook of type "Game".
4. Create a page for the book with the shortcode `[adventurebook id="X"]`, where X is the ID of your adventure book.
5. The adventurebook will be embedded in this page.
6. Create items in the "Adventurebook Items" menu.
7. Create book pages and add item spawns to the pages.
8. Set the starting page by selecting the bookpage of your choice on the Adventurebook edit page.

== 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 (Wordpress Admin -> Settings -> Adventurebook).
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.

= 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.

== 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 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.

- 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


== TODOs ==

- Item Respawns
- Moving Enemies: Enemies can spawn at different locations