Story Progression nodes let you plan your story as a map of scenes, like chapters, and connect them into paths. While someone plays, an AI called the Story Director reads the scene you wrote for the current node, watches what the player does, and guides the narrator. When the story reaches what you described for a next node, it moves there. The player still plays freely; your nodes decide where the story is heading.
Story Progression is one of the three tools of the Mana Game Engine, next to Triggers and In-Game Images / Video. You can use it on its own or together with them.
The Three Kinds of Nodes
Pick one from the Add Node menu.
What’s Inside a Node
| Part | What it’s for |
|---|---|
| Title | The node’s name. Use 1 to 26 letters, numbers or spaces, and give every node a different title. The Story Director sees titles too, so make them say what the scene is: “Caught By Guards” beats “Node 3”. Double-click a title to rename it. |
| Branch entry condition | When the story should move into this node, written as something that happens in the story: “A guard spots the player or the alarm goes off.” Story Initialization has none, since the story always starts there. |
| Scene direction | What should happen while the story is in this node: the goal of the scene, the mood, what to reveal and what to hold back. The Story Director turns it into guidance for the narrator each turn. |
| Number of turns | Roughly how long the scene should last, from 1 to 1,000 turns (new nodes start at 8). It’s a pacing guide for the Story Director, not a timer. |
| Run Trigger | Triggers that run when the story enters this node, such as showing a story text, changing a variable or showing an image. See Working With Triggers below. |
| entry and next dots | The connections. A line from one node’s next dot (right side) to another node’s entry dot (left side) means “this scene can come after that one”. |
How the Story Moves Forward
What happens on every turn of a story with progression nodes.
- The player takes a turnThey Say, Do or write their move as usual.
- The Story Director reads the situationIt looks at the scene direction of the node the story is in, the entry conditions of every node connected to it, the story so far and the player’s new move. While it works, the player sees a “Directing Story” step.
- It decides what this turn needsLet the scene carry on, give the narrator a direction for this turn, or move the story into one of the connected next nodes because its entry condition has been met.
- Entering a node runs its triggersIf the story just moved into a new node, its triggers set to Immediately run now, before the narration is written, so the narrator already knows about them.
- The narrator writes the turnIt follows the Story Director’s direction, so when the story has just moved, that same turn is already written for the new scene. Triggers set to After narration run once the player has revealed the whole turn.
Branching: A Heist Example
One scene, two possible outcomes, and the player’s choices pick which.
A node can have more than one next connection. That’s a branch: each connected node waits for its own entry condition, and whichever one the story reaches first is where it goes. Here is a museum heist with four nodes. The Plan leads to Infiltrate, and Infiltrate branches into Caught or Escape.
Guards close in and the heist is over, but the player can still try to bluff or bargain their way out.
Sirens start in the distance as the crew races to the getaway van. The scene ends with a celebration at the safehouse.
This is what you would type into each node:
| Node | Branch entry condition | Scene direction |
|---|---|---|
| The Plan (Story Initialization) | None. The story always starts here. | The crew meets in the back room of a jazz bar to go over the museum blueprints. Let the player choose their role and ask questions. |
| Infiltrate | The crew leaves the bar and heads to the museum. | Night inside the Lumen Museum. Describe the patrols, the cameras and the locked vault. Give the player chances to be clever and chances to slip up. |
| Caught | A guard or camera spots the player, or the alarm goes off. | Guards close in and the heist is over. Let the player try to talk, bluff or bargain their way out. |
| Escape | The player gets the Star of Lumen out of the vault without being seen. | The crew races to the getaway van as sirens start in the distance. End on a celebration at the safehouse. |
Connections: The Plan → Infiltrate, Infiltrate → Caught, Infiltrate → Escape.
During Infiltrate, the Story Director checks both entry conditions every turn. If the player trips a laser, the story moves to Caught. If they crack the vault and slip out, it moves to Escape. If neither has happened yet, the story stays in Infiltrate and the director keeps steering the scene with its scene direction.
Branches can also come back together, and a connection can lead back to an earlier node, for example a town square the player keeps returning to between quests. The only limits: nothing can connect into Story Initialization, and a node can’t connect to itself.
Cut Scenes
Use a Cut Scene when a moment matters too much to leave to the AI, like a big reveal or a dramatic entrance. In the heist, you could put a Cut Scene called Vault Opens between Infiltrate and Escape, with the entry condition “The player cracks the vault lock.” Attach a trigger like the one below. On the turn the story enters Vault Opens, the player reads your text and sees your image, and no AI narration is written.
From the next turn on, Vault Opens works like a regular node, so write its scene direction for what comes right after your scene, such as “The player has the jewel in hand. Now they have to get out.” Then connect it to Escape (and to Caught, if things can still go wrong).
Build Your First Progression
From an empty map to a playable branch.
- Open the editorIn your story setup, find Mana Game Engine, choose Enabled, then press Create New (or Edit Triggers if your story already has some).
- Switch to Story ProgressionUse the menu at the top of the left panel and pick Story Progression.
- Add the openingPress Story Initialization on the empty map. Add a scene direction if you want to guide the opening beyond your Starting Prompt.
- Add your next scenePress Add Node (or right-click the empty grid) and choose Story Progression. Double-click its title to rename it.
- Fill it inWrite the Branch entry condition and the Scene direction, and set the Number of turns with the arrows or by typing a number.
- Connect themDrag from the next dot on the right of your opening node to the entry dot on the left of the new node. Press Esc to cancel a connection you’re drawing.
- Branch outAdd more nodes and give one node two or more next connections wherever the story can go different ways.
- Save and playPress Save. The editor tells you if anything is missing. Then start your story and play through it.
Right-click a node to Rename, Collapse, Duplicate or Delete it. Duplicate copies its text and triggers into a new node.
To remove a connection, click its line and press the red ✕. To move one, drag its end from the entry dot to another node.
Scroll to zoom, drag the empty grid to move around, and use the fit button in the corner to see the whole map.
Every Story Progression and Cut Scene node needs a title, an entry condition and a scene direction before you can save, even nodes you haven’t connected yet. Unconnected nodes are kept, but the story never reaches them.
Working With Triggers
Every node has a Run Trigger field. Type to search your triggers, pick one, and add more with + Trigger. When the story enters the node, its triggers run in the order they’re listed. A trigger you attach this way doesn’t need an Event, because entering the node starts it. Its Conditions still apply, and a trigger that also has an Event runs on that Event as well.
Next to each attached trigger you choose when it runs. Cut Scene nodes don’t have this choice: their triggers are the whole turn, so they all run at once.
| Timing | When it runs | Good for |
|---|---|---|
| Immediately | As soon as the story enters the node, before that turn’s narration is written. | Things the narrator should know this turn, like an LLM Inject or Modify Custom Instructions action. |
| After narration | Once the player has revealed the whole turn. | Things that should come after the scene, like a story text, an image or ending the progression. |
Triggers can also end the progression. The Exit story progression action stops the Story Director, and the story carries on as a normal Realism story. Attached to the Escape node with After narration, this trigger counts the win, shows a closing line and hands the story back to free play:
Node text can use your variables, too. Type a variable’s name in double curly braces, like {{clues}}, in an entry condition or scene direction, and the Story Director sees its current value each turn. For a mystery, an entry condition such as “The detective has gathered enough evidence to name the killer (clues found: {{clues}} of 3)” lets your clue-counting triggers and your nodes work together.
Tips for Writing Good Nodes
- Write entry conditions as events the Story Director can spot in the story. “The player opens the sealed door” works better than “Chapter 2 starts”.
- Make sibling branches clearly different, so only one fits at a time. If Caught and Escape could both be true, the director has to guess.
- Keep scene directions about goals, mood and pacing, not word-for-word lines. The narrator still writes the prose. When you need exact wording, use a Cut Scene.
- Leave room for the player. Describe what can happen in the scene, not exactly what the player does.
- Match Number of turns to the size of the scene: 3 or 4 for a tense standoff, 10 or more for exploring a city.
- Give every path somewhere to land: a final scene with a clear ending, or a trigger that exits story progression.
Testing Your Progression
While playing your own story, type /mana and open the Story progression tab. The Story progression card shows the node you’re in, how many turns you’ve spent there, and the next nodes the story can move to. Press Jump to branch to move your play-through to any node without replaying from the start: the turn count resets and that node’s triggers run on your next turn. Only the story’s creator gets this button.
Good To Know
Stories with Story Progression play in Realism mode. When a player starts one, the other gameplay modes show “This story does not support this mode yet.”
Players don’t see your node map. The story preview shows how many story branches your story has.
Redo and rewind roll the progression back too. If a turn moved the story into a new node, removing that turn puts the story back where it was and undoes the variable changes and story texts that node’s triggers made.
The Story Director is its own AI step each turn, charged in coins on top of narration. Players choose its model under Workflow Models, and you can suggest one on the Recommended Settings tab.
Do I need Story Progression to use triggers?
No. Story Progression is optional. Triggers, variables and In-Game Images / Video all work in a story without any nodes, and a story with no nodes plays like a normal story.
Does the story have to follow my nodes exactly?
No. Your nodes set the direction and the Story Director steers toward it, but the player plays freely and the AI writes the scenes. What the player does decides which branch the story takes and when.
What happens when the Number of turns runs out?
Nothing forces a move. Number of turns is a pacing guide for the Story Director, which still decides when the story moves on. The story can also move sooner if a next node’s entry condition is met.
What happens at a node with no next connection?
The story stays in that node and keeps following its scene direction for as long as the player keeps playing. To hand the story back to free play instead, attach a trigger with the Exit story progression action.
Can the story go back to an earlier node?
Yes, if you draw a connection back to it. Any node except Story Initialization can be a connection’s target, so you can build loops such as a hub the player returns to. A node can’t connect to itself.
Can I have more than one Story Initialization node?
No. Every progression has exactly one Story Initialization node, which is where the story starts. Duplicate is turned off for it.
Why won’t the editor save my progression?
Every Story Progression and Cut Scene node needs a title, a branch entry condition and a scene direction, including nodes you haven’t connected yet. Titles must be different from each other and use only letters, numbers and spaces. When you press Save, the editor lists anything that needs fixing.
Does Story Progression cost players more coins?
Yes, a little. The Story Director runs as its own AI step each turn and is charged in coins, even when the narration model is free, and Story Progression turns always use Two Pass Mode. Players pick their Story Director model under Workflow Models.
Do I have to replay my story from the start to test a later node?
No. While playing your own story, type /mana, open the Story progression tab and press Jump to branch to move straight to any node. Only the story’s creator can do this.