Planning Branching Dialogue
Every dialogue you write knows its own variables, and nothing else. It doesn't know that the player who reaches it may have already burned the bridge it talks about, or skipped the scene where they learned the name it mentions. Those mistakes stay invisible until a playtester walks into them, and by then they are expensive to fix.
The Route Planner is a map of your story above the dialogues. You group dialogues into scenes, chapters and arcs, link them into the routes a player can take, and say what each part needs and leaves behind. LoreHub then checks every route while you plan. This guide walks through it on a small example story.
The example: Grey Harbour
To keep things concrete, we will plan the opening of a small mystery. A lamplighter arrives in a fogbound harbour town where the ferryman has vanished. The harbour warden, Ida, has an explanation ready. The player can believe her, or break into the ferryman's boathouse at night and find his ledger. Either way, the lighthouse lamp goes dark at the end of the chapter, and what the player knows by then shapes the next one.
Three variables carry the story between its parts. All of them are booleans, and a variable nobody has set yet counts as false:
trusts_idahas_ledgermet_keeper
You add them in the Variables panel on the left of the game page, the same variables the Dialogue Builder uses for options and conditions. Create them before you write contracts, because a contract can only talk about variables the story already has.
1. Organise the story into scopes
A route scope is a folder in the dialogue explorer that also has a map. There are two kinds, and you choose the kind when you create the scope:
| Kind | Holds | Use it for |
|---|---|---|
| Scope of scopes | Other scopes, in order | Arcs and chapters: the big shape of the story |
| Scope of dialogues | Dialogues, in order | Scenes: a few dialogues that play out together |
The top level of the explorer holds scopes, so a story starts with a scope of scopes, such as an arc. A scope never mixes the two kinds; if a chapter needs both scenes and a loose dialogue, put that dialogue in a scene of its own. Dialogues that aren't in any scope yet stay at the bottom of the explorer, so nothing gets lost while you reorganise.
Drag a dialogue or a scope in the explorer to move it, or drop it straight onto a scope's map. Rename a scope from its menu, and use Take out of the scope to lift something back out. A scope can only be deleted once it is empty, so deleting one never deletes your dialogues.
Start a scope's name with a short id in square brackets, like[2a] Ida's story. The map shows2ain a tile on the card, which makes the order of a chapter readable at a glance, and the letter tells everyone that 2a and 2b are alternatives, not a sequence.
2. Lay out the route map
Click a scope in the explorer to open its route map. The map shows one card for each thing the scope holds: scene cards on a chapter's map, dialogue cards on a scene's map. Every map has a START on the left and an END on the right, which stand for "where the player enters this scope" and "where they leave it".
| To | Do this |
|---|---|
| Add a card | Double-click empty space on the map, use the create buttons, or drag a dialogue or scope in from the explorer. |
| Link two cards | Drag from the red port on a card's right edge to another card. |
| Rename a card | Press F2, or click the name of the selected card. |
| Open a card | Double-click it: a scope opens its own map, a dialogue opens in the Dialogue Builder. |
Links are one-way and follow the player: from START or a card, to a card or END. A card with two links out is a fork. Card positions are saved for everyone, every change can be undone, and each scope remembers where you last panned and zoomed, so coming back to a big chapter doesn't mean finding your place again. The scope you have open is part of the page's address too, so you can send a teammate a link straight to it.
trusts_ida, and both branches meet again at The lamp goes dark. 3. Say what each part needs: contracts
A scope can have an enforced contract. Select its card on the parent's map and the inspector on the right shows two lists:
Requires
What a route must have set before it enters this scope. You pick a variable and tick every value the scope accepts. Ida's story requires trusts_ida = true: it only makes sense if the player took Ida at her word.
Produces
What this scope sets for the routes that leave it. When a variable can end either way, add it twice, once per value. Fog on the quay produces trusts_ida = true and trusts_ida = false, because the player decides there.
The card shows the same lists. Each requirement has a pin on the card's left and each produced variable a pin on its right. Hover a variable to trace the thread back to the card its value comes from. When a link only carries some of the routes into the next card, it gets a label such as ⑂ only if trusts_ida = true, so you can read the branching rule without opening anything.
Contracts belong to scopes, not to single dialogues. That is deliberate: a scene's contract is a promise about the whole scene, and the dialogues inside it are free to get there however they like. If you need a check between two dialogues, that is usually a sign they are two scenes.
A chapter is a scope too, so it gets its own contract on the arc's map. Chapter 1 promises to produce has_ledger as either value, and the arc can branch on it without knowing anything about the boathouse:
4. Read the checks
Every requirement on a card gets a mark. LoreHub follows each route back from the card to the nearest card that produces the variable, or to START when nothing does, and compares what can arrive with what the card accepts:
| Mark | Meaning | In Grey Harbour |
|---|---|---|
| ✓ Always met | Every route in brings an accepted value. | The lamp goes dark needs met_keeper = true, and the quay always sets it. |
| ⑂ Branch | Only routes with an accepted value continue here. This is how a story forks. | Only players who believed Ida reach her version of events. |
| ✕ Never met | No route in brings an accepted value. The card can't be played from here. | See the broken map below. |
On top of the marks, the server runs a route check on the whole map and shows it at the top of the inspector. It walks every route from START to END, forking wherever a card produces more than one value, and either tells you that every route is playable, with how many it checked, or lists what is wrong. Say a writer adds a confrontation scene after Ida's story:
The check reports the problems a playtester would otherwise find for you:
A card nothing reaches, or a card that leads nowhere
No route from START gets to it, or it has no link on to another card or END, so routes through it never finish.
A requirement nothing sets
A route reaches a card without ever setting a variable the card requires. Either an earlier card should produce it, or the scope itself should require it from outside.
A value with nowhere to go
A card produces a value that no linked card accepts, like the broken map above. The player makes a choice the story can't continue from.
A promise the scope doesn't keep
The scope's own contract says it produces something, but a route reaches END without it. Chapter 1 promises has_ledger; a route that skipped both 2a and 2b would break that promise to the arc.
An ambiguous route
After a card, the same route could go on to more than one card that requires something. If The boathouse accepted trusts_ida = true as well, a player who believed Ida would fit both 2a and 2b, and the story wouldn't know which to play. A fork where none of the next cards requires anything is fine: that is the player's free choice.
A loop
A link goes back to a card already on the route. It is reported, and the other routes are still checked.
Very large maps can have more routes than the check walks in one go. When that happens, it says so instead of pretending everything is fine, and splitting the map into smaller scopes brings it back into range.
5. Go down into the dialogues
Double-click a scene card and you are on that scene's map, where the cards are dialogues. Each dialogue card shows how many nodes it has, which is a quick way to spot a scene where one dialogue does all the work. Forks here are the player's free choice, because dialogues don't carry contracts; the branching that matters to the rest of the story is already promised by the scene's contract.
has_ledger is now true. Double-click a dialogue card to open it in the Dialogue Builder and write it. The breadcrumbs at the top of the page show the scopes the dialogue sits in, so you can climb back to the scene, the chapter or the arc in one click. Inside the dialogue, set the variables the scene promises: in the boathouse, the option where the player pockets the ledger sets has_ledger to true.
6. Plan together
The planner is live. When someone on your team moves a card, links two scenes or edits a contract, your map updates on its own, and you can see who else has the story open. Changes to scopes and contracts also appear in Recent changes, with what was added and removed, so a writer coming back after a few days can see how the chapter moved.
A good split of work: the lead writer owns the arc and chapter maps and their contracts, and each writer owns a few scenes. As long as a scene keeps its contract, it can be rewritten freely, and the route check tells everyone the moment it doesn't.
A checklist for your own story
I. What are the arcs and chapters?
Create the scopes of scopes first and put them in order. Don't write dialogue yet.
II. Where does the player make a choice that matters later?
Each of those choices is a variable. Add it in the Variables panel and name it after the fact it records, like trusts_ida, not after the scene that sets it.
III. What does each scene need, and what does it leave?
Write the Requires and Produces of every scene card, and link the cards. Use [1], [2a], [2b] ids for order and alternatives.
IV. Does the route check say every route is playable?
Fix every ✕ and every reported problem now, while it costs a link or a contract row instead of a rewrite.
V. Do the dialogues keep the scene's promises?
Open each scene, write its dialogues, and make sure they set the variables the scene's contract produces.
Branching stories don't usually fail because a single dialogue is bad. They fail at the seams between dialogues, where nobody is looking. The Route Planner puts those seams on one map and checks them every time the map changes, so you can spend playtesting on whether the story is good, not on whether it holds together.
Try it in the LoreHub app, read more about the Dialogue Builder, and for feedback, please join Discord.