Home
Welcome to the cyoa-interactive-story-builder wiki!
This WordPress plugin allows you to create interactive, choose-your-own-adventure-style stories directly on your WordPress site. Engage your readers by letting them decide the course of the story, making for a unique and personalized reading experience.
- Stories: Create stories with hierarchical parent-child relationships to define different paths.
- Characters, Locations, Vehicles, Weapons: Manage these entities and link them to your stories.
- Parallel Universes: Create alternate versions of stories.
- Storylines: Organize stories into different narratives.
- Character Types, Location Types, etc.: Categorize your entities for better organization.
- Season and Episode: Assign seasons and episodes to your stories.
- Entity Linking: Easily link characters, locations, vehicles, and weapons to stories.
- Choices: Display choices to readers, allowing them to decide the next path.
- Next Episode Links: Automatically generate links to the next episode or season.
- Parallel Universe Switching: Let users explore alternate versions of episodes. [Docs]
- Save Progress: Users can save their progress per universe.
-
Resume Reading Shortcode:
[iasb_resume_reading]allows users to resume where they left off.
- D3.js Visualization: Visualize your story structure in the admin area using D3.js.
- Enhanced Navigation: Display breadcrumbs to help users navigate through the story.
- Clone or download this repository to your local machine.
- Upload the plugin files to the
/wp-content/plugins/directory of your WordPress installation.
- Go to the 'Plugins' menu in WordPress and activate the CYOA Interactive Adventure Story Builder plugin.
- Navigate to the 'Stories' section in the WordPress admin to start creating your interactive stories.
- Use the 'Characters', 'Locations', 'Vehicles', and 'Weapons' custom post types to create entities and link them to stories.
- Use the 'Story Manager' under the 'Stories' menu to visualize and manage your story structure.
-
Add New Story:
- Go to
Stories > Add Newto create a new story segment. - Use the Parent attribute to create hierarchical relationships between story segments.
- Go to
-
Assign Taxonomies:
- Categorize your stories using Storyline, Parallel Universe, Season, and Episode taxonomies.
-
Link Entities:
- In the story editor, link characters, locations, vehicles, and weapons using the provided meta boxes.
-
Set Season and Episode:
- Use the Season and Episode meta boxes to organize your story segments chronologically.
-
Create Entities:
- Use the Characters, Locations, Vehicles, and Weapons custom post types to create and manage entities.
-
Assign Types:
- Categorize entities using Character Type, Location Type, Vehicle Type, and Weapon Type taxonomies.
-
Story Manager:
- Navigate to
Stories > Story Managerto view a visual representation of your story structure using D3.js.
- Navigate to
-
Reading Stories:
- Users can read stories and make choices that lead them through different paths.
-
Switching Universes:
- If alternate versions exist, users can switch between parallel universes to explore different outcomes.
-
Resume Reading:
- Logged-in users can resume their progress using the
[iasb_resume_reading]shortcode.
- Logged-in users can resume their progress using the
-
[iasb_resume_reading]: Displays a 'Resume Reading' button for logged-in users to continue where they left off. -
[iasb_resume_reading]: Displays a 'Resume Reading' button for logged-in users to continue where they left off. -
[user_story_name]: Displays the logged in user name
Usage Examples Example 1: Display Content Only to Administrators `[conditional_content role="administrator"]
This content is only visible to administrators.
[/conditional_content]`Example 2: Display Content Based on Story Progress
Assuming story_id corresponds to the storyline's term ID or post ID as per your implementation. `[conditional_content story_id="123" season="2" episode="5"]
You have unlocked this special scene because you've reached Season 2, Episode 5!
[/conditional_content]`Example 3: Combine Role and Story Progress Conditions
`[conditional_content role="subscriber" story_id="123" season="3" episode="10"]
Subscribers who have reached Season 3, Episode 10 can see this exclusive content.
[/conditional_content]`Explanation:
The content within the shortcode will only be displayed if the user meets all specified conditions. If multiple attributes are provided, all must be satisfied for the content to render.
// Function to override the user story name with character profile name
function myplugin_override_user_story_name($output, $atts) {
$user_id = get_current_user_id();
if ($user_id) {
// Retrieve the character profile ID associated with the user
$character_profile_id = get_user_meta($user_id, 'iasb_character_profile_id', true);
if ($character_profile_id) {
// Get the character's name from the profile
$character_name = get_the_title($character_profile_id);
if ($character_name) {
$output = esc_html($character_name);
}
}
}
return $output;
}
add_filter('iasb_user_story_name', 'myplugin_override_user_story_name', 10, 2);- The plugin automatically displays breadcrumb navigation and 'Next Episode' links in the story templates.
Yes, you can customize the templates by copying the template files from the plugin's templates directory into your theme and modifying them as needed.
In our Wiki, you can learn how to use Advanced Custom Fields (ACF) to add new entity types—such as Lore, Organizations, and Laws—to your stories created with the CYOA Story Builder plugin.
Yes, user progress tracking is available for logged-in users. This allows users to resume their reading across sessions.
Use the Parallel Universe and Storyline taxonomies to categorize your story segments. By assigning different universes or storylines to similar episodes, you can create alternate versions. See the Wiki for more details.
