Branching Choices

Branching choices turn a story into scenes joined by choices. Each choice can need a mark, be blocked by one, set marks, or vanish after one use. Show open choices first, refuse locked ones without changing anything, and let the reader go back with the marks restored.

Also called: Story branches, Choice-based story, Choose your path, Branching story.

A fox girl in a green cloak holds a lantern at a fork in a forest path with three glowing ways ahead: to a cottage, to a river with a boat and to a stormy tower, while a thorn-covered gate blocks a fourth way behind her. — Marrowfen Paths, an invented storybook adventure. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Branching Choices" to my game.

What it should do: Choices make the reader a part of the story. The player feels that what they pick matters when later scenes remember it, when some paths close and others open, and when a bad pick can be taken back without leaving the story in a broken state.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> choosing
  choosing: Several choices
  single: One way on
  stuck: Dead end
  ended: Story ends
  choosing --> single: next scene has one way
  choosing --> stuck: next scene has no way
  choosing --> ended: story reaches an ending
  single --> choosing: next scene has choices
  single --> stuck: next scene has no way
  single --> ended: story reaches an ending
  stuck --> choosing: reader goes back
  stuck --> single: reader goes back
  ended --> [*]
```

Use these starting values:
- maxChoices: 4
- showLockedChoices: 1
- historyLimit: 20 scenes

Watch out for these common mistakes:
- Going back undoes the step but not what it did: Tell your AI: save the scene, the marks and the used-up choices together before every step, and restore all three when going back.
- A scene with no way out: Tell your AI: check every scene for at least one choice that can always be taken, and let the reader go back out of a dead end while you fix it.
- A choice that leads nowhere: Tell your AI: look up the target first, and if it is missing, refuse the whole choice and change nothing.
- A locked choice that is still clickable: Tell your AI: show locked choices, but refuse them when taken, with nothing changed.
- More choices than fit on the screen: Tell your AI: list open choices first, cut the list after that, and warn the author when a scene has more choices than the limit.
- A one-time choice that comes back: Tell your AI: remember used-up choices by scene and choice, and hide them from the list, not just lock them.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

Choices make the reader a part of the story. The player feels that what they pick matters when later scenes remember it, when some paths close and others open, and when a bad pick can be taken back without leaving the story in a broken state.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Several choices → One way on: next scene has one way
Several choices → Dead end: next scene has no way
Several choices → Story ends: story reaches an ending
One way on → Several choices: next scene has choices
One way on → Dead end: next scene has no way
One way on → Story ends: story reaches an ending
Dead end → Several choices: reader goes back
Dead end → One way on: reader goes back

Good starting values

Value	Start with	What it changes
maxChoices	4	The most choices shown at once. Four fit on a phone screen and can still be told apart in a glance. Above that, readers start skimming and the last ones are hardly ever picked.
showLockedChoices	1	One shows choices the reader cannot take yet, greyed out, after the open ones. It tells them that the story has more to offer and makes a second playthrough tempting. Zero keeps secrets hidden.
historyLimit	20 scenes	How many scenes the reader can step back through. Twenty is enough to undo a bad run of picks without keeping the whole story. Zero turns going back off, for stories where every pick must stand.

What usually goes wrong

Going back undoes the step but not what it did

If going back only returns to the old scene, the marks the step set are still there. The reader walks back into a scene with a key they never took, or a one-time choice that is still used up.

Fix: Tell your AI: save the scene, the marks and the used-up choices together before every step, and restore all three when going back.

A scene with no way out

A scene that is not an ending but offers no choice leaves the reader stuck, often because a choice needs a mark they cannot get.

Fix: Tell your AI: check every scene for at least one choice that can always be taken, and let the reader go back out of a dead end while you fix it.

A choice that leads nowhere

A choice that points to a scene that does not exist can set its marks and use itself up before the move fails, leaving the story damaged.

Fix: Tell your AI: look up the target first, and if it is missing, refuse the whole choice and change nothing.

A locked choice that is still clickable

A choice shown greyed out but accepted when clicked lets the reader skip the lock, and the story assumes marks they do not have.

Fix: Tell your AI: show locked choices, but refuse them when taken, with nothing changed.

More choices than fit on the screen

When a scene has more choices than the limit, the extra ones silently disappear, or locked choices push open ones out of the list.

Fix: Tell your AI: list open choices first, cut the list after that, and warn the author when a scene has more choices than the limit.

A one-time choice that comes back

A choice that is meant to be used once appears again when the reader returns to the scene, so they can repeat a reward.

Fix: Tell your AI: remember used-up choices by scene and choice, and hide them from the list, not just lock them.

How to check it works

The reader is at a scene with open choices. They take one: They arrive at the scene it leads to, and the step is remembered on the trail.
A choice needs a mark the reader does not have. They try to take it: It is refused, and the scene, marks and trail stay as they were.
A choice sets a mark and another choice needs it. The reader takes the first: The mark is set and the second choice opens.
A one-time choice has been taken. The reader comes back to its scene: It is not listed any more and cannot be taken.
A scene with three open choices and one locked choice, locked choices shown. The choices are listed: The open ones come first and the locked one last.
The same scene, locked choices hidden. The choices are listed: Only the three open ones appear.
A scene with one locked choice listed first and three open ones, and a limit of three. The choices are listed: The three open ones are shown and the locked one is left out.
A choice that is blocked once the reader has a certain mark. The reader sets that mark and tries the choice: It is locked and refused.
The reader took a choice that set a mark. They go back: They are in the old scene, the mark is gone and the choice is available again.
A step-back limit of 2 and four steps taken. The reader goes back three times: The first two work and the third is refused.
The step-back limit is zero. The reader takes a step and tries to go back: Going back is refused.
A choice that sets a mark and leads to a scene that does not exist. The reader takes it: It is refused, and no mark is set and nothing is used up.
The reader is in a scene that is not an ending and offers no choice. They try a choice and then go back: The choice is ignored and going back takes them out.
The reader has reached an ending. They take a choice or go back: Both are refused.
A choice name that is not in the scene. The reader takes it: It is ignored.
A choice that sets the same mark and can be taken again. The reader takes it three times: The mark is listed once.

Works well with

Dialogue System: A dialogue can be a branching scene where each choice is a reply. Keep the marks in one place so both read the same facts. Show the line first, then the choices that go with it.
Multiple Endings: The endings do not need to be reachable by one single path, but every ending should have at least one. Let the choices set the marks, and decide the ending from the marks at the end.
Quest Log: A choice that starts or finishes a quest should do it in the step, so going back does not leave the log out of date. Update the log in the same step as the choice.

Variations: Timed Dialogue Choices.

Common questions

how do i add a branching story to my game

Paste this: Add branching choices. The story is a set of scenes, and each scene lists choices that lead to other scenes. A choice can need a mark, be blocked by a mark, set marks, and be one-time. Show open choices first and locked ones greyed out after them, refuse locked ones without changing anything, and let the reader go back with the marks restored.

should locked choices be shown or hidden

Showing them greyed out is a good start. It tells the reader that the story can go elsewhere, and a second playthrough becomes tempting. Hide them when the lock itself would give away a surprise.

how many choices should a scene offer

Two to four. Fewer feels like no choice, more is skimmed, and the last ones are rarely picked. If a scene needs more, split it into two steps.

what happens to the marks when the player goes back

They go back too. Save the scene, the marks and the used-up choices together before every step, and restore all of them, or the reader ends up in an old scene with new facts.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

19 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it