Docs/Story foundations

Story Flow

This page explains how a branching story is built on Verhaler. It covers what you write, what your Reader does with it, and how the pieces fit together. The rest of the handbook goes deeper into the same parts.

The building blocks

Four building blocks make up every Verhaler book:

  • Book: the book itself. Title, cover, description, Tags, and the price your Reader pays.
  • Chapters: where your story lives. A Chapter holds paragraphs, Headers, images, videos, and Triggers, in any order.
  • Glossary Items: a small page for every character, place, item, or faction your story refers to. Each one carries its own Facts, which the rest of the book can check and change as the story unfolds.
  • Triggers: small event blocks you place in Chapters. They react to what your Reader has done. One can reveal a character or a hidden Chapter, change a Fact, or open a Dice Template.

Then there are the seven Dynamic Components: Decision Templates, Dice Templates, Dialogue Templates, Combat Templates, Trade Screens, Calculations, and Backgrounds. These are the parts your Reader plays through. You build each one once, name it, and a Trigger opens it when the story needs it. Two of them work a little differently. A Trigger never opens a Calculation: other pieces read it instead. A Background doesn't open at all. It changes what the page looks like.

Paragraphs are 800 characters

Paragraphs are capped at 800 characters. If you type past the cap, the editor moves the last word into a new paragraph. If you backspace across the gap, the paragraphs merge again.

The cap exists for two reasons. Most Readers are on phones, and short paragraphs read better on a small screen. The cap also lets the platform track where your Reader is in the story.

Note
Headers, media, and Triggers don't count toward the 800. Only the story text does.

How a story branches

The Chapter order in your sidebar is for you, not your Reader. Readers can move through Chapters in a different order. The same Chapter can be reached from several places, and some Chapters only appear if something specific happened earlier.

Branching comes from Triggers. A Trigger can branch directly: it reveals a Chapter or Header your Reader couldn't reach before. It can also branch indirectly, by opening a Decision Template or a Dice Template. Then what your Reader picks or rolls decides which paths open up.

Once your story has more than a couple of branches, the Story Canvas draws the whole shape: every Chapter, Header and Trigger, with each choice and dice outcome under the Trigger that opens it.

A reveal makes a Chapter reachable

Every branch in a Verhaler book comes from a reveal. A Chapter or a Header that is Hide by default does not exist for your Reader. A reveal makes it part of the book for them. If it is the next one in your order, they read on into it.

A reveal never moves your Reader. They stay where they are, at the Trigger or the choice that revealed it, and reaches the new Chapter by reading on. So the Chapter you want them to read next goes next in your order.

A reveal does not add the Chapter to their Chapter list either. In a published book, that list only offers Chapters your Reader has already reached, so they cannot jump ahead. Your own Reading Simulation lists every revealed Chapter, so you can jump around while testing. To let the Reader choose a path, a Decision Template is the way.

Visible Chapter
The Spouter-Inn
A Trigger at the end opens the Decision Template 'A bed for the night'.
Hidden by default
A room upstairs
'Pay for a room' reveals this one.
Hidden by default
A night in the stable
'Sleep in the stable' reveals this one.

Whichever the Reader picks, they are still standing at the end of The Spouter-Inn. The revealed Chapter is now reachable and they read on into it. The other one stays hidden, so they never know it was there.

A choice reveals one of two hidden Chapters. Nothing moves the Reader: they reach it by reading on.
  • A reveal only does something to a hidden thing. A Chapter that is visible from the start is already reachable, so revealing it changes nothing. The pattern is always the pair: a Chapter hidden by default, then a reveal. The reveal can come from a Trigger, a Decision Template choice, a dice outcome, or the end of a combat.
  • The other branch stays hidden. Nothing has to hide the path not taken, because it was never revealed. A Trigger can hide something again later, for a door that closes behind the Reader.
  • It works on parts of a Chapter too. A Header with Hide by default on holds back everything under it until a reveal. So one Chapter can hold both endings of a scene, and show only the one the Reader earned.
Tip
Wherever the handbook says "reveal a Chapter", it means this. Your Reader still reads on to get there.

How Dynamic Components reach the Reader

Dynamic Components live in their own sidebar tab, not inside your Chapters. They reach your Reader one way: a Trigger opens them. You point one of the Trigger's results at the Dynamic Component you want to run. When your Reader reaches the Trigger and any conditions you've set are met, the component opens.

You build a Dynamic Component once and can open it from any number of Triggers, in any number of Chapters. The Dynamic Components overview covers what each kind does, and the Triggers page explains how to open them.

Glossary Items run alongside

Glossary Items aren't part of the reading path. They sit alongside it, and your Reader can open them from mentions in your text. Each one carries:

  • A short title and a one-line description.
  • A wiki body: the same editor as Chapters, but for reference reading rather than the story itself. Lore, descriptions, anything your Reader might look up.
  • A Fact Card: named values you and the rest of your book can check and change as things happen. Numbers, yes/no flags, lists, inventories.
  • Optional settings for what the story can do with it. An Item can be carried and traded, and a Character or Creature can be played and can fight. The Character and Creature settings and Item settings sections say which switch does what.

Typing @ anywhere in your text lets you pick a Glossary Item to mention. Your Reader can open a mention once that item has been revealed to them. The Glossary Items page covers all of this in detail.

The lifecycle of a book

Writing on Verhaler follows three steps:

  1. Write. You draft Chapters and Glossary Items in any order. Triggers go where the story should react to what your Reader does. Dynamic Components are built in their own sidebar tab.
  2. Test. Reading Simulation lets you play your own book. The editor switches to the Reader's view, and you walk through the story as a real Reader will. The Story Canvas lets you jump in at any Chapter, Header or Trigger. You decide each fork on the way, or let it pick a way for you, so you don't have to replay everything from the start each time.
  3. Publish. Your first publish makes Edition 1 of your book, a copy Readers read from. After that, new Chapters go out as an Expansion, on top of what's already out, and a fix to what's out goes out as the next Edition. See Publishing for how Editions and Expansions work.