Decision Templates
Where to find it
You can find Decision Templates in the sidebar, under Dynamic Components. The list shows every decision in this book: its heading, how many choices it offers, its Description, and whether it's currently valid. Add Decision Template creates a new one. Pressing a card opens it in the editor.
Before you start
A decision with nothing to change is only a question. Two things make its results worth having, and neither is required to open the window:
- A Glossary Item with a Fact or two. A Fact is a value on a Glossary Item's Fact Card: a number such as Coins, or a True or False value such as Has a room. A result changes one, and a prerequisite reads one. With no Glossary Items in the book, the Glossary Item picker in a result row is empty and says so.
- A Chapter or Header with Hide by default on. A result can only reveal something that is hidden. So the branch a choice opens has to exist, and be hidden, before the choice can point at it.
The modals
The list on the left starts with General Settings, then every choice in the order your Reader sees them. Whatever you pick in the list opens on the right. General Settings holds the heading, the Description, the line above the choices and the picture. A choice holds what happens when the Reader picks it (Results). If it should not always be offered, it also holds who gets to see it (Prerequisites). Add a choice sits under the list.
See it as a Reader, the button with an eye at the top of the window, draws the decision as your Reader meets it. A note under each choice says when it is offered and what it does. Opened from a choice, the drawing puts a ring around that choice.
A new template: one choice called Choice 1 and nothing set. Pressing the choice opens it. Its Prerequisites tab is greyed until Only offer this choice when... is on. Roll a dice offers the one roll in the sample book that changes nothing by itself.
The template
The template has four settings at the top of the list, in General Settings. The choices come after them.
- Heading the Reader sees: the heading over the window when the decision opens. It is also the name you see in the list, and the one you pick when you point a Trigger at this decision. Required, unique per book, up to 70 characters. A new template opens as "What do you do?".
- Description: a line or two your Reader sees under the picture and above the choices, such as scene-setting. Optional, up to 250 characters.
- Line above the choices: a switch for one more line of your own, in bold, right above the choices. For example "Which path?" or "Whose side are you on?". The line goes in Title above the choices, which appears under the switch. Up to 30 characters. Off shows nothing there.
- Media: one optional image or video from your Media library, shown at the top of the decision above the Description and the choices. Choose from gallery picks it, Change media swaps it, Clear removes it.
Choices
A decision has one to ten choices. Each is a button your Reader can press, and each one holds:
- Choice name: the words on the button. It's rich text, so italics, bold and
@-mentions of Glossary Items work the same as in Chapter text. Your Reader can tap a mention to look it up. Up to 70 characters. - Icon: a small picture on the button, in a colour you pick. Default keeps the plain seal. A choice that rolls a dice shows a die instead.
- Only offer this choice when...: a switch for a choice that should only be offered when certain rules hold. The Prerequisites section below explains the rules. Turning it off again asks before the rules are removed.
- Roll a dice: a switch that attaches one Dice Template to the choice. The dice rolls inside the decision, before the choice's results run. It suits a choice that is an attempt, where the dice decides whether it succeeds. A Dice Template with Changes the story on is greyed in the list. It has Result Sets of its own, and here the choice decides what the roll does. With that switch off in the Dice Template, it can be attached here. If the attached roll shows its rolling animation, the window says so. Your Reader then watches the die tumble before the results land. Dice animation, in the Dice Template's own settings, turns that off.
Prerequisites
The Prerequisites tab
A choice can be limited to Readers who meet certain rules. For example, they carry the right item, they've met the right character, their strength is above some number, or a particular Chapter has been revealed. The tab opens once Only offer this choice when... is on. Each rule checks one thing. A choice can have up to ten rules, and all of them must hold. Leaving the tab or opening something else in the list keeps the rules.
Under When the rules below fail you choose what the Reader sees:
- Hide the choice: the choice is hidden. The Reader never knows it existed.
- Show the choice, but the Reader can't pick it: the choice still appears in the list, greyed out, and cannot be pressed. It lets the Reader see a choice they can't take yet.
Prerequisites can't check the choice's own dice roll, because the roll happens after the Reader picks the choice. The roll's outcome is checked on the choice's Result Sets instead. A set can run only when the roll succeeds, or only when it fails.
Results
The Results tab
When the Reader picks the choice, every Result Set whose conditions hold runs, top to bottom. A choice holds up to ten sets. A set on Always runs every time. One on Only when... runs when its conditions hold, such as the dice roll being a Success. Each row in a set changes one of:
- Chapter: reveal a Chapter, or a specific Header inside one, that the Reader couldn't reach before. A reveal opens the path, and the Reader still reads their way there. The Chapter they did not pick stays hidden. The Story Flow page draws it. The forward-only rule for Triggers applies here too. A reveal must point past the Trigger that opens this decision. A backward reveal makes that Trigger invalid.
- Glossary Item: change a character, place, or item. You can set or reset a Fact, add or remove a Tag, or raise or lower a number by a flat amount or a percentage. You can also reveal the item to the Reader, or hide it again. It works on a specific Glossary Item, or on Reader. Reader means whoever your Reader is playing as (a Character with Playable on).
- Many at once: apply one change to every Glossary Item, Chapter, Header, or section carrying a Tag. It turns one sweeping change, like alerting every guard in the castle, into a single result.
For example: a bed for the night
Ishmael arrives at the Spouter-Inn with 30 Coins and Peter Coffin has one room. As a Decision Template with three choices, each written the way the window lays it out:
- "Pay for a room". Only offer this choice when... Ishmael's Coins is more than 1. When the rules fail, it shows greyed, so a broke Reader sees what they cannot afford. Results, in one set that always runs: Subtract 2 from Ishmael's Coins, then Reveal the Header A room upstairs in The Spouter-Inn.
- "Sleep in the stable". No prerequisites. One result: Reveal the Header A night in the stable.
- "Try the back door". Roll a dice on, with the template A test of nerve (d20) attached, and two Result Sets. One runs Only when... the dice roll is Success and reveals the room upstairs without paying. The other runs Only when... the dice roll is Failure and sets Ishmael's Caught sneaking to True, for a Trigger further on to find.
Both Headers start with Hide by default on. The Reader picks once, one Header appears in their Chapter, and the story reads on into it.
How a decision reaches the Reader
A decision reaches the Reader only through a Trigger, placed in the Chapter where the choice should happen. In the Trigger's results, the decision sits under Dynamic Component, then Decision Templates. When the Reader gets there and the Trigger's conditions are met, the decision opens. The Reader picks a choice, its Result Sets run, and the story continues.
The same template can be opened from any number of Triggers and Chapters. After you save, the window says this too.
What your Reader sees
A window over the page, headed with the line from Heading the Reader sees. Inside it, from the top: the picture or video from Media, if you picked one. Then your Description, if you wrote one, and the line from Line above the choices, if that is on. Last comes one button per choice, each with its icon. A choice whose prerequisites fail is either missing or greyed, as you chose.
- A first tap picks a choice, and a second tap confirms it. A choice with Roll a dice on then throws the die inside the same window, before its results run.
- The window has no close button. Your Reader can minimize it and read back over what came before. They cannot read past the spot where it opened until they make a choice. Then its results run and the story goes on.
The heading is also the decision's name in your list, and it is the line your Reader reads.
Published templates
Once a Decision Template is published, it locks. Its card in the list shows a lock and no longer opens. Duplicate, which appears when you hover over the card, makes a copy with (Copy) added to the name, and the copy can be edited.
The published one changes in an Edition, started from your Published page. There it opens while the Edition works on the part it was published with, and your change goes out with the Edition when you publish it. The Publishing page says what Readers in the middle of the book see.
Validation
A Decision Template can have two kinds of problem, and both block publishing until they are fixed.
- The template's image or video has since been deleted from your gallery. The Media row is marked. Save stays greyed until you pick a new one, or press Dismiss to go without one. Then the template can be saved again.
- The template goes invalid when one of its choices relies on something that has since been deleted. That can be a Glossary Item, a Chapter, a Fact or a Tag, in a prerequisite or a result. The list page flags the template with a warning icon and sorts it to the top. In the window, the broken choice is marked with a warning where it sits in the list. Next choice to fix, above the list, opens it.
Either way the publish check rejects the book until the template is valid again.
Before a Decision Template is deleted, a question over its window lists the Triggers that still open it. A Trigger is the only thing that can open one, so that list is everything that uses it. "Keep it" changes nothing. "Delete anyway" leaves each of them marked broken until it opens something else. The book can't be published while one is broken.
Questions writers ask
The same questions and answers sit behind the "?" in the Decision Template window.
How this fits your story
How does my Decision Template actually reach my Reader?
It does not, on its own. Building it here only makes it available. Something in the story has to start it.
That something is almost always a Trigger. A Trigger is an invisible checkpoint inside a Chapter, added from the "+" menu in the editor like any other block. When your Reader reaches that line, the Trigger checks what they have done so far. It can then open this Decision Template.
A Trade Screen and a Dice Template each have one more way in. A reply in a Dialogue Template can open a Trade Screen from its own results. That is how a conversation leads into a shop. A Decision Template choice or a Combat Ability can roll a Dice Template with its "Roll a dice:" switch.
No other result opens a Dynamic Component. A choice, a dice outcome or a combat's outcome sets a Fact instead, and a Trigger that checks it does the rest.
So it is built here. Its Trigger goes in the Chapter where it should happen (The Ship, for instance), at the moment you want it.
What is the difference between a condition and a result?
A condition, under "When", is a question about what your Reader has already done. A result, under "Then", is a change that happens once the answer is yes.
"Has the Reader seen The Ship?" is a condition. "Reveal The Ship" is a result. The same thing can appear on either side, which makes them easy to mix up. One asks about it, and the other changes it.
Both are built the same way, in the same order, everywhere in Verhaler. First comes what the row is about, then what to ask or what to do.
If I add several conditions, do all of them have to be true?
All of them. Rows are only ever joined with And. There is no "Or" anywhere in the builder.
"Either of these" takes two separate Result Sets, each with one condition and the same result.
Up to 10 conditions in one group.
What is the first box in a row, the one that asks what should be checked or changed?
It picks what the row is about.
In a condition, that is a Chapter or a Glossary Item. The dice roll and an Emotion are offered too, where the window you are in allows it.
In a result, it is the thing you want to change: a Chapter, a Glossary Item, or many of them at once ("Many at once"). Where the window you are in allows it, it can also be a Dynamic Component to open.
The boxes after it narrow down what you picked, so they only make sense once the first one is filled.
Can one result put several Items in a bag, or take them out?
Yes. A "Put in" on a Container Fact can name up to 200 Items, each with its own amount.
A "Take out" of one Item takes the amount it names. A "Take out" of several takes all of each.
What is the difference between "The whole Chapter" and one of its Headers, or "The item itself" and one of its Facts?
The whole thing, not one of its parts.
The Ship with "The whole Chapter" means the Chapter itself. A Header instead means only that part. On a Glossary Item, "The item itself" means the item, as against one of its Facts or one section of its page. When the row is about the Reader, the same choice reads "The Reader themselves".
When there is nothing inside to choose from, that box is not shown at all. The whole thing is the only answer, so it is taken for you.
Why did my result disappear after I saved?
A set whose result row was never filled in is not saved. Under Always, a Trigger says "Nothing to save yet. Pick at least one result first". It says "A few of these are still empty, so nothing was saved yet" under Only when... instead. Elsewhere, the empty set is quietly dropped when you save the window. That is the usual reason a result seems to vanish after saving.
What do "Always" and "Only when..." mean?
They decide whether the results need conditions at all.
Always: the results happen every time, and there is no "When" block to fill. Only when...: they happen only when every condition under "When" is true. The one that is pressed in is the one you are in.
What does revealing or hiding something do to my Reader?
Chapters, Headers and Glossary Items can start out hidden, and stay out of your Reader's reach until something reveals them.
A reveal result on The Ship lets them get to it. A hide takes it away again. The condition "is revealed" asks about that same state. That is how one part of your story can depend on another having happened.
Where do I say what happens when a choice is picked?
On the choice's Results tab. Pressing the choice's row opens it. Each Result Set is a bundle of changes, up to 10 per choice. Every set whose conditions hold runs the moment your Reader confirms the choice. A set can reveal The Ship, change Dexterity, add a Tag, or do several of these at once.
A set on "Always" runs every time. A set on "Only when..." depends on what your Reader has done, or on the dice roll if the choice rolls one.
Can a choice open a dice roll, a combat or a shop directly?
Only the dice roll. A choice with "Roll a dice:" set to Yes rolls the Dice Template picked under it. A Result Set here cannot open another Dynamic Component.
A combat or a shop takes two steps. The choice sets a Fact on a Glossary Item. A Trigger that checks that Fact then opens the Combat Template or the Trade Screen.
How do I make a result depend on whether the roll succeeded?
On the Results tab, a Result Set on "Only when..." can be about "The dice roll". It then checks for Success, Failure, Critical Success or Critical Failure. "The dice roll" is offered only once "Roll a dice:" is Yes above and a Dice Template is picked.
So one choice carries both endings. One set runs only on a Success and reveals The Ship. Another runs only on a Failure and does something else. A set left on "Always" runs whatever the roll.
Critical Success and Critical Failure appear greyed out when the Dice Template you attached has them switched off. Once they are on in that template, they can be picked here.
A prerequisite cannot check the roll. The roll happens after your Reader picks the choice, so a rule for whether the choice is offered never sees it. "The dice roll" belongs on a Result Set instead.
This window's own settings
What does my Reader see?
A window headed with the line from "Heading the Reader sees:". At the top inside it are the picture or video from "Media:" and your Description, if you added them. Below those is the line from "Line above the choices:", if that is on. Last comes one button per choice, each with its icon. "See it as a Reader", the button with an eye at the top of this window, draws it from what is in here right now.
A first tap picks a choice, and a second tap confirms it. A Decision Template is a fork in the road, and the Result Sets on the picked choice are what happens next. The window has no close button. Your Reader can minimize it and look back over the story. They cannot read past the spot where it opened until they choose.
"Choice name:" is the words on the button. Your Reader sees it, so it works best as what they are choosing to do.
What does "Line above the choices" do?
Yes puts one more line of your own right above the choices, in bold, under the Description. It suits a question such as "Which door?" over three doors. The line goes in "Title above the choices:", which appears under the switch. No shows nothing there, even if a title is still typed in.
It is separate from the heading. "Heading the Reader sees:" is the window's title and is always shown. This line sits inside the window, next to the buttons.
Can a choice make my Reader roll for it?
Yes. A choice with "Roll a dice:" set to Yes rolls the template picked under "Dice Template:". Your Reader presses the button, and the roll happens inside the decision. The outcome decides which of your Result Sets apply. The button shows a die instead of the icon you picked.
Only some templates can be picked there. A Dice Template with "Changes the story" On is greyed out here, with the reason on it. It has Result Sets of its own, and here the choice decides what the roll does. Templates with "Changes the story" Off are the ones you can attach.
If every roll in the list is greyed out, that is why. The way round it is a Dice Template that only rolls, with the consequences put here instead. An empty list means the book has no Dice Templates yet.
A note under "Dice Template:" says the die tumbles every time. Why?
That Dice Template has "Dice animation:" set to Visible, so your Reader watches the die tumble every time they pick this choice. Setting "Dice animation:" to Hidden in that Dice Template gives an instant result. The note only appears under a template that animates. The row's own help is its label: pressing the underlined words opens it.
What are Prerequisites, and what does my Reader see when they are not met?
Rules on the choice itself, not on its results. They say what must already be true before this choice is offered at all. "Has met The deck of the Pequod" is a prerequisite. With "Only offer this choice when...:" set to Yes, the Prerequisites tab opens. On No, the choice is always offered.
You choose what happens when the rules fail, under "When the rules below fail:":
Hide the choice: your Reader never knows it was there. It suits a secret.
Show the choice, but the Reader can't pick it: they see the locked door, greyed and unpressable. It suits showing them what they missed, which is often the more interesting choice.
What is the "Icon:" picker on a choice for?
A small picture on that choice's button, shown to your Reader, in the colour you pick next to it. "Default" keeps the plain seal every choice starts with.
A choice with "Roll a dice:" on shows a die instead, and your pick comes back when you switch the roll off.
Can I mention a character in a choice's text?
Yes. Typing @ in "Choice name:" offers your Glossary Items to pick from. The pick shows as a highlighted name on the button. Your Reader can tap it to open that Glossary Item. The decision waits, minimized, until they come back to it.
A choice your Reader cannot pick (greyed by its prerequisites) cannot be tapped at all, mention included.
When something looks wrong
"Add another" has stopped doing anything. Why?
You have reached a cap. One group holds up to 10 conditions, and one Result Set holds up to 10 results.
More Result Sets can carry more, each with its own conditions and results.
Why can't I edit this Decision Template any more?
Four locks, and each says which one it is.
"This Decision Template is published, so no change is possible." It changes in an Edition, started from your Published page. A locked card in the list will not open at all. "Duplicate", the copy icon that appears when you hover over the card, makes a copy you can change, and your Readers keep the original.
"This Decision Template is your draft for the next Expansion." An Edition is open, and what you wrote before it waits until it is published or discarded.
"This Decision Template is part of the original story." Or of an Expansion: the lock names the part. An Edition works on one part at a time. "Work on another part" with Switch, in the banner at the top of the page, moves it there.
A lock on the whole book. The banner at the top of the page says why, and its button leads to where the book opens again.
What happens if I delete a Decision Template something else is using?
Nothing silently breaks. Before it goes, a question over the window lists what still uses it, a Trigger that opens it included. "Keep it" changes nothing, and "Delete anyway" deletes it. Each of those then shows as broken, with a warning icon on it, until you pick something else there or remove it. The book can't be published while one is broken.
A delete can't be undone.
How do I check that any of this works?
In a Reading Simulation, by reading past the point where it should happen.
The sidebar's Trigger Log lists every Trigger you passed. "What it checked and changed", under a Trigger in the log, shows each condition marked Passed or Failed, and each result Applied or Skipped. That tells you whether the problem is your condition or your result.
It says another Decision Template is already called that.
Every Decision Template in a book needs its own heading. The heading is also how you tell them apart in the list and in a Trigger. That is why a new one opens as "What do you do?", and a second one as "What do you do? (2)".
Save goes through once this one has a heading of its own. The question your Reader is being asked makes a good one, and so does the moment it happens at.
"Add a choice" has gone grey.
A Decision Template holds up to 10 choices, and you are at the cap. It also needs at least one: the bin on the last choice refuses.
The cap is also a hint. 10 buttons is already a lot to read at once. Two decisions in a row often land better than one with everything in it.
The Prerequisites tab is greyed out.
It says "This choice is always offered. This tab opens once 'Only offer this choice when...' above is Yes." That switch sits above the tabs. Once it is on, the tab opens and you land on it.
Setting it back to No removes the rules you wrote. It asks first, and there is no undo once they are gone.
The Results tab says "(1 open)", or shows a small 1. What does that mean?
A Result Set is still being edited: its card is open. The number is how many are open, counting the empty card a fresh choice starts on. On a phone, it is a small number on the tab instead of "(1 open)".
Opening another choice or General Settings, "Save Decision Template" and the other tab all look after them. A finished card is kept on the way, and an empty one is dropped. A half-built one stays open, and you are asked whether to keep editing or discard it. Nothing you filled in is thrown away without asking.
"Save Decision Template" is greyed out.
Either nothing has changed since the last save, or the picture or video this decision showed was deleted from your gallery. That can happen when it is deleted from somewhere else.
In the second case, the Media row is marked. Save comes back once you pick another, or press Dismiss to go without one.