Dynamic Narrative Engine –
This engine is designed to handle the complex, under-the-hood logic of card games, roguelikes, and choose-your-own-adventure stories.
The most important concept to remember is Separation of Logic and Visuals. This plugin acts as your invisible game master. It calculates probabilities, manages inventory, tracks history, and builds decks.
Core Concepts
The engine revolves around five major data types:
Metrics: Numerical variables (e.g., Health, Gold, Depth). You can set strict minimum and maximum bounds for these, ensuring a player's health never drops below 0 or goes above 100, even when complex status effects are ticking.
Tags: Text-based variables (e.g., Class: Warrior, HasTorch: true). Perfect for tracking inventory flags or story states.
Cards: The core encounters or events. Each card has a Draw Weight (determining how likely it is to appear) and can be restricted to specific Categories (e.g., "Combat", "Shop", "Exploration").
Options: The choices attached to a card. Options can be locked or unlocked based on the player's current Metrics or Tags.
Effects: The consequences of picking an Option or playing a Card. Effects can happen instantly (e.g., +50 Gold) or over time (e.g., -5 Health for 3 Turns).
The Standard Game Loop
1. Initialization (On Start of Layout)
Start by telling the engine to Hard Reset. Then, define your world: set up your Metric bounds, starting Tag values, and build your card database.
Example: Create the "Goblin_Ambush" card, add the "Fight" and "Flee" options, and set the effects for picking them.
2. Deck Building & Drawing
You do not need to manually manage the deck. When you call the Advance Turn action, the engine does the following:
Evaluates all active status effects (ticking poison, regeneration, etc.).
Looks at every card in your database and checks its Inclusion Rules (e.g., Is the player Depth >= 5? Have they played this card before?).
Automatically shuffles all valid cards and draws one based on its weight.
Fires the On Any Card Drawn trigger.
3. Displaying the UI
When On Any Card Drawn triggers, you use the plugin's expressions to update your visuals:
Set your Title Text to DynamicNarrative.CurrentCardName.
Generate buttons for the options using a For loop from 0 to DynamicNarrative.OptionCount(DynamicNarrative.CurrentCardName) - 1.
Check if each option is valid using the Is Option Valid condition, and grey out the button if the player doesn't meet the requirements.
4. Making a Choice
When the player clicks a button, use the Play Option action. The engine will instantly calculate the effects, update the metrics, and log the card in the player's history. From there, you simply call Advance Turn to start the loop all over again.
Advanced Features
'OR' Condition Breaks: By default, if a card has multiple rules (e.g., Depth >= 5 AND HasTorch = true), all must be met. By inserting an Add 'OR' Condition Break, you can create alternate pathways for a card to be drawn or an effect to trigger.
Chance & Fallbacks: You can assign a percentage chance to an option's effect. If you also set a Fallback Effect, the engine will automatically execute the fallback if the main percentage chance fails—perfect for traps, gambles, and attacks.
The Hand System: Building a deckbuilder rather than a dungeon crawler. The plugin includes a robust Hand and Discard Pile system. Draw multiple cards to a specific hand, play them via index, and shuffle discard piles back into the draw pool automatically.
Save / Load State: The entire engine state (history, metrics, decks, and active effects) can be exported as a single JSON string using GetStateAsJSON, making save systems incredibly easy to implement.