Docs/Story foundations

Chapters

A Chapter holds your story. You write the words, add Triggers where the story should respond to what your Reader has done, and mention your Glossary Items in the text. A book can have any number of Chapters. The order in your sidebar isn't necessarily the order your Reader moves through them.

Where to find it

Your Chapters are in the sidebar's Chapters tab, listed in the order you set. Selecting one opens it, and the editor takes over the page.

Every Chapter needs a unique title within the book.

The editor

You write in the Chapter editor. A Chapter is built from blocks: paragraphs, Headers, media, and Triggers (covered below). Your work saves as you type, and a small save indicator sits at the top. The Chapter's settings live in the side panel. Each Header has its own settings popup.

In the editor, a Chapter has its title at the top and your paragraphs below it. A Header can mark where a scene changes. A picture or video sits full width between two paragraphs. A Trigger shows as a dashed box, with one line saying what it checks and does. A Header that is hidden by default is drawn with diagonal stripes, so you can see which parts your Reader has to earn.

Chapter-level settings

The Chapter's title is the heading at the top of the editor. You type it inline, like any other Header. It can be up to 70 characters and must be unique within the book. At 70 the editor stops taking keystrokes, with no warning. Your Reader sees it as the Chapter heading.

Everything else lives in the side panel:

  • Tags: labels a Trigger or Decision Template can match on later. Chapters that share a Tag can be acted on all at once. For example, a Trigger in the Chapter where the ship lands can reveal every Chapter tagged ashore. A change by Tag only reaches Chapters and Headers after the Trigger. Earlier ones, and the Trigger's own Chapter, are skipped without a warning. So hiding the dream Chapters once your Reader wakes does nothing at all. Up to 5 Tags per Chapter, the same cap as everywhere Tags appear in the editor.
  • Hide by default: when this is on, your Reader can't reach the Chapter until a Trigger reveals it. It is for branch Chapters that should only appear after a specific decision. What a reveal does, and does not do, is on the Story Flow page. Chapter 1 can't be hidden (see below).

Block types

A Chapter is an ordered list of blocks, and blocks come in four kinds:

  • Paragraph: your story text. Each is capped at 800 characters (more on the Story Flow page). 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. You can bold and italicise inline, and you can add mentions (see below).
  • Header: three levels. The first is the Chapter title (one per Chapter, automatic). The second and third are sections and sub-sections inside the Chapter. The handbook calls both of them a Subheader. In a longer Chapter, they let a Trigger reveal one section instead of the whole Chapter. Each Header has its own settings popup (covered below).
  • Media: an image or video you upload, rendered full-width in the Chapter. The block opens your book's Media library, where you upload a file or pick one already there.
  • Trigger: how your story responds to what your Reader has done. When the Reader reaches it, it checks its conditions and runs its results. A Trigger is also the only way one of the Dynamic Components opens for the Reader. Full details on the Triggers page.

The modals

The Chapter editor has one settings window of its own: the per-Header popup. It sets whether a Header starts hidden, whether it is a writer-only section, and which Tags it carries.

A cold walk from the docks is the first sub-section of the Chapter. It is in sight from the start and tagged Ashore. This is what the window shows for most Headers in a book. Switching Hide by default on is the whole setup for a section your Reader has to earn.

The button above opens the demo. Nothing you change in it is saved.
Three Subheaders of The Spouter-Inn, one per tab. Every tab opens on a Subheader, because the Writer-only heading row only appears for Subheaders. Whatever you switch here stays in the demo.

Header settings

The per-Header settings window

Every Header has a small settings popup. A drag handle appears to the Header's left when you hover it, and Settings in its menu opens the popup. The one exception is the Chapter title at the very top: its Tags and Hide by default live in the Chapter side panel instead.

  • Hide by default: when this is on, the Header and every block under it stay hidden from your Reader until a Trigger reveals them. This is how you hold back a whole sub-section of a Chapter for a later reveal. Under a hidden Header the editor shows one line: what reveals it, such as "Hidden until Tunnel Ambush reveals it on a Failure." A Header nothing reveals says "Hidden, and nothing reveals it yet.", and no Reader reaches it. The settings window lists every rule that reveals it, and every rule that hides it again.
  • Writer-only heading: a heading your Reader never sees. It groups a stretch of paragraphs without a visible title, such as a flashback. With a Tag on it, one Many at once result can hide or reveal the whole stretch, while the Reader sees only the prose.
  • Tags: like Chapter Tags, but on this Header only. Up to 5, the same cap as everywhere Tags appear. What Header Tags are for is explained below.

For example: a sub-section held back until a good roll

The interactive tour builds this pattern in four steps. The sub-section sits under its own Subheader, say The hidden passage, with Hide by default switched on in its settings. Above it, a Trigger opens a Dice Template. That Dice Template's Success outcome has one result: reveal The hidden passage. A Reader who rolls well reads on into the passage. One who rolls badly reads past a heading that, for them, was never there.

What Header Tags are for

A Many at once result targets "every Header tagged X" in one step. Any Trigger, Decision Template, or other Dynamic Component with a results block can use it. One Trigger result like "reveal every Header tagged side-quest unlocked" can open ten sub-sections across five Chapters at once. The same goes for hiding Headers, and for adding or removing their Tags.

A precise Tag still tells you, a month from now, which Headers a "hide all flashbacks" result will affect. Chapter Tags act on whole Chapters. Header Tags act on parts of one.

Mentions

To bring a Glossary Item into your text, type @ in a paragraph. The mention picker opens. Pick a Glossary Item and the editor inserts a small pill linked to it. Two useful things follow from that:

  • Renames carry through. When you rename the Glossary Item, every mention of it in every Chapter updates. Your Reader sees the new name everywhere.
  • Reveal gating. A mention only becomes clickable once you've revealed that Glossary Item to your Reader. Mentions of items they haven't met yet look like plain text. You reveal items through Triggers and Decision Templates.

Chapter 1 is special

Your Reader starts in the first Chapter, so its Hide by default toggle is locked off. Every Reader needs a visible starting point. The other Chapter-level settings (title, Tags) work the same as on any other Chapter.

Published Chapters

Once a Chapter is published, the editor locks it. A banner at the top says so:

Published
This Chapter is published, so no change is possible. To change it, start working on an Edition from your Published page.

You can't rename it, retag it, change its visibility, edit its blocks, or delete it. In an Edition it opens while the Edition works on its part, and saves like any other. A Chapter of another part says which part it is in. Deleting one in an Edition takes it out of that Edition. The Edition can't be published while a part that's out has no Chapter left: the Publish page says so.

Once your book is published, the sidebar heads each run of Chapters with its part: Original story, an Expansion by name, or Not published yet. A Chapter's settings name its part. The part is set when the Chapter is first published and can't be changed. A Chapter written in an Edition goes at the end of the part the Edition is on, and joins that part. The Publishing page says what Readers in the middle of the book see.

Validation

A Chapter can have two kinds of problem. They behave differently, and only one of them blocks publishing.

  • A duplicate title is renamed on save, not refused. If you give a Chapter a title another Chapter in the book already uses, the save goes through. Verhaler adds a number, so it becomes "The Spouter-Inn (1)". The heading at the top of the Chapter is rewritten to match. That is the heading your Reader sees, unless you pick a different title yourself. The editor warns you as you type that it will be renamed.
  • The Chapter goes invalid when a Trigger inside it goes invalid. The cause is a broken reference, a target on the wrong side of the forward-only rule, or a Dynamic Component it opens that reveals something above it. A Chapter has no validity of its own: it takes the status of the worst Trigger inside it. A small warning icon appears on the broken Trigger, and selecting it opens the Trigger. The bad row carries the same warning, so you can go straight to the fix.

The second kind blocks publishing: the publish check refuses any book with an invalid Chapter. The first kind doesn't, because there is nothing invalid about it: the Chapter saved, under a name you did not choose.

Questions writers ask

The same questions and answers sit behind the "?" in the Header settings window.

How this fits your story

What does "Hide by default" do here?

This section and everything under it stay out of your Reader's sight until a rule reveals it. On a Fact Card, that is the Facts under the Section. In a Chapter, it is the text under the Header, up to the next Header of the same size or bigger. In the editor, the hidden stretch is striped so you can see where it ends.

For example, a Section called Secrets on The deck of the Pequod starts hidden. A Trigger in The Ship reveals it later.

How do I reveal it later?

With a Trigger in the Chapter where it should appear, or a Decision Template choice. Its result points at this section, with "Reveal or hide" set to "Reveal it". "Hide it" takes the section away again, which is rare but useful for a secret the Reader should forget after a scene.

Can I hide just one section of the Fact Card?

Yes, that is what this window is for. It opens from the Section's menu, the six dots beside it. With "Hide by default" on, the other Sections stay visible. Only the Facts under this one wait for a rule to reveal them. The whole Glossary Item has its own "Hide by default" in the side panel, for when nothing about it should show yet.

The Header settings window

What is a writer-only section?

It means two different things, depending on where it is.

On a Section of a Fact Card, or on a Header inside a Glossary Item's text, the heading and everything under it are yours alone. It suits notes to yourself, or Facts your story counts with but never shows. A Reader never gets any of it, and revealing it does nothing for them. A Trigger can still point at it and read or change the Facts under it.

On a smaller Header in a Chapter, only the heading is withheld. The paragraphs under it are published, as ordinary prose with no title over them. There it groups a stretch you can Tag, and hide or reveal in one go, without a visible title. Notes to yourself do not belong under one. Prose you want held back needs "Hide by default" instead, or a Trigger that reveals it.

It is not offered on a Chapter's top Header.

What are Tags on a section for?

Labels a rule can read, up to 5. A Trigger pointed at this section can check "Has any of", "Has all of" or "Has none of" them. In its results, it can "Add Tags" to it or "Remove Tags" from it. So a section can remember something, such as "Visited", added the first time and checked for later. A new name typed in the box makes a Tag on the spot. It is then offered everywhere Tags are.

Where is the Save button?

There is none to press. This window keeps its settings when it closes. "Done", Escape and a press outside the window all do the same thing. The page saves them with its next save.