Docs/Dynamic Components

Dice Templates

A Dice Template is a roll the Reader makes when the outcome should be uncertain. You pick the die and set which numbers count as a win or a loss. Modifiers let the Reader's stats shift the odds, and you choose what happens for each outcome. Your story can then use that roll wherever it needs one.

Where to find it

You can find Dice Templates in the sidebar, under Dynamic Components. The list shows every Dice Template in the book: its name, which die it uses, its success threshold, and whether it's valid. Add Dice Template makes a new one, and pressing a card opens it for editing.

Before you start

A roll can be built with nothing else in the book. Two things give it something to do:

  • Something hidden to reveal, or a Fact to change. A Success that reveals a Header with Hide by default on, or takes a point off a Numeric Fact, is what makes the roll matter. With no Glossary Items in the book, the Glossary Item picker in a result row is empty and says so.
  • A Calculation, if a stat should shift the odds. A Modifier's amount can be a plain number or a Calculation that reads the Reader's Facts. The Calculation button next to the amount is greyed, with the reason, until the book has one.

The template

  • Template name: the label you see in the list and the name you pick when you wire a Trigger to this roll. Required, unique per book, up to 70 characters. A descriptive name like Sneak past the watchman still makes sense in six months.
  • Description: a line or two your Reader sees under the die before they roll, so they know what is at stake. Free-form text. The field only appears when Changes the story (next) is on.
  • Die: d4, d6, d8, d10, d12, d20, or d100. A d20 suits a single dramatic roll, and a d100 a percent-style check. Defaults to d20, with Success on 12 or more.

Changes the story

One switch decides what kind of roll this is. Off: the roll changes nothing on its own. A Decision choice or a Combat Ability that rolls it decides what happens next. Opened by a Trigger, it is a roll for atmosphere. On adds the Results tab, where each outcome gets its own results. It also adds the Description field, because a roll that decides something needs setting up.

A roll can be attached to a choice, or change the story, not both
A Dice Template with Changes the story on can only be opened by a Trigger. It is greyed in the Roll a dice list on a Decision Template choice. It has Result Sets of its own, and there the choice decides what the roll does. If your roll is greyed in that list, this switch is why. The fix is to turn it off, or to build a second template for the choice.

On your Reader's screen

Two switches, under that heading in the template's own settings. Neither changes the odds, and See it as a Reader shows what each one does.

  • Dice animation: when set to Visible, the Reader presses Roll and watches the die roll across the screen. When Hidden, there is no Roll button. The roll is made as the window opens and the result appears at once, so the Description is never shown. The animation suits moments where the roll itself is part of the experience. Visible by default.
  • Target number: when set to Visible, the Reader sees the number they need, before the roll and beside the result. For example: "Success: larger than or equal to 5". When Hidden, they never see the number, only whether the roll succeeded. A hidden number builds tension, and a shown one makes the stakes clear. Visible by default.
Note
On a Decision Template choice, a roll with the animation on plays it as soon as the Reader picks that choice. The Decision Template editor says so under the picker when you attach the Dice Template.

Modifiers

Stat-driven additions to the roll

A Modifier shifts the roll in the Reader's favour or against them: a strong character is more likely to break the door down. The Modifier's value is added to (or subtracted from) the raw die before the outcome is resolved.

  • Name: what the Reader sees on the roll's Modifiers tab, beside the amount ("Sneak", "Strength", "Reputation").
  • By how much: a flat number, or a Calculation that works the number out from Facts on the Reader's character or other Glossary Items. A Calculation suits a Modifier that should depend on what has happened in the story so far.
  • What it does: Add or Subtract. Sets whether the amount raises or lowers the roll.
  • Chance it applies: the percent chance the Modifier applies on a given roll. 100, the default, means it always applies. A lower value means it sometimes does.
  • Applies: optional. With Only when... in place of Always, the Modifier only applies when its conditions hold at the moment of the roll.

A template can hold up to 10 Modifiers. The final number is the raw die plus every Modifier that applied on that roll.

Outcomes

Four outcomes the roll resolves to

After Modifiers, the final number lands in one of four outcomes:

  • Critical Success: the best outcome. Optional. Off means a normal success is enough. On gives it its own threshold. On, with conditions is for when hitting the number alone shouldn't be enough.
  • Success: the character did what they meant to. Always present.
  • Failure: they didn't. Always present.
  • Critical Failure: the worst outcome. Same three states as Critical Success: leave it off, give it its own threshold, or gate it on conditions.

Each threshold is an operator and a value, such as "equal to 1" or "larger than or equal to 5". The value field adapts to the die you picked, from 1 up to the die's maximum. The Failure row starts as "smaller than" the Success value, so the two meet. You can change it. A number that then matches neither counts as a Failure.

The outcomes are checked in a fixed order and the first match wins: Critical Success, then Critical Failure, then Success, then Failure. So an overlap is not a conflict: a 20 that counts as both a Critical Success and a Success is a Critical Success. A Modifier can never push the final number below 1 or past the die's maximum.

Note
A critical band set to On, with conditions only fires when the roll lands in the band and the conditions are true. It suits a critical where rolling the number shouldn't be enough on its own, such as "critical only when the Reader has the sharpened blade".

Per-outcome results

What runs for each band

The Results tab sets how the story responds to the roll. Each band has its own list of results that run when the roll lands there. A critical success can reveal a Chapter that rewards the Reader. A critical failure can take a point off a Fact such as Health. An outcome can't open another window. To lead into a Decision or a Dialogue after the roll, a result here sets a Fact, and a Trigger in the Chapter checks it.

Note
Some rolls are cosmetic, such as a flourish before a decision, or a roll where the component that started it only needs the number. Those have Changes the story off on the template, and this tab stays greyed. The die still rolls, and the component that started it decides what the outcome does.

What each result can do for a band:

  • Chapter: reveal a Chapter the Reader could not reach before, or a hidden section inside one.
  • Glossary Item: change a Fact, show or hide a character or place, adjust Tags, or restore something to its default.
  • Many at once: apply one change to every Glossary Item, Chapter, Header or Section carrying a Tag. For example, "wound every guard in the room" on a critical attack.

For example: picking a lock

Ishmael tries a locked cabin door. The template: a d20, Changes the story on, Description "The lock is old and the ship is quiet." One Modifier, named Deft hands, Add, with the amount taken from the Calculation Lockpicking (Dexterity + half Luck). Success is larger than or equal to 12, and Failure smaller than 12.

The Reader rolls a 9. Ishmael's Dexterity is 12 and his Luck 6, so the Calculation makes 12 + 3 = 15. 9 + 15 is 24, past the die's maximum, so the final number is held at 20: a Success. What flies in over the die is +11, the part of the Modifier that moved the roll. It is not the +15 you sized it at. The Modifiers tab reads Deft hands +11 (at the limit). On the Results tab, Success has one result, Reveal the Header Inside the cabin. A weaker character, with a Calculation making 2, would land on 11 and fail.

With a Modifier that size, even a roll of 1 makes 16, and Ishmael cannot fail. For a stat that should help without deciding, the Calculation can take a share of it (25% of Dexterity makes 3). A higher Success threshold works too.

What your Reader sees

A window over the page with the die in it. With the animation on, the Roll button sits in the middle of the die's own panel, with your Description under that panel. They press it, then grab the die and throw it. It tumbles, lands and shows the raw number. Each Modifier then slides in one at a time as a bare signed number, until the final number stands. The names are on the Modifiers tab, which the Reader has to tap. So a Modifier named for the moment the die lands is read by you in the window, not by them over the die.

  • The outcome shows by name: Success, Failure, or one of the criticals, with the target number beside it while Target number is Visible. A Continue button closes the window and the outcome's results run.
  • With the animation Hidden there is no Roll button and no Description. The roll is made as the window opens, and the result appears at once.
  • A roll attached to a Decision Template choice happens inside the decision's window, the moment the choice is confirmed. The choice's Result Sets read how it went.

Published templates

Once a Dice 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 Dice Template becomes invalid when something inside it references a part of your book that has since been deleted. The validator checks every reference and marks the template invalid when one no longer resolves. It usually comes down to one of these:

  • A Modifier references a deleted Calculation, Glossary Item, or Fact. Pointing the Modifier somewhere else, or removing it, fixes it.
  • A critical success or critical failure set to On, with conditions has a deleted reference in its condition list.
  • A per-outcome result points at a deleted Chapter, Header, Glossary Item, Fact, or Tag.
  • A per-outcome result is wired to a critical band you've since switched Off. The result row is orphaned until the band is on again, or its results move to another band.

The list page marks invalid templates with a warning icon and sorts them to the top. The publish check refuses any book with an invalid Dice Template. So a broken Modifier or an orphaned result row blocks the next publish until you fix it.

Before a Dice Template is deleted, a question over its window lists every Trigger, Decision Template choice and Combat Ability that still rolls it. "Keep it" changes nothing. "Delete anyway" leaves each of them marked broken until it points at another roll. The book can't be published while one is broken.

Questions writers ask

The same questions and answers sit behind the "?" in the Dice Template window.

How this fits your story

How does my Dice 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 Dice 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.

This window's own settings

What does "Changes the story" do?

Off: the roll changes nothing on its own. It is the usual choice when a Decision Template choice or a Combat Ability rolls this die and keeps its own results. Opened by a Trigger, an Off roll is for atmosphere. Your Reader rolls, sees how it went, and the story carries on the same way whatever the number was.

On makes the number matter. The Results tab, greyed until then, opens, and each outcome gets its own results. A success can reveal The Ship or change a Fact on The deck of the Pequod. A failure can do something else entirely. A roll like this is started from a Trigger in a Chapter.

A Decision Template choice cannot pick a template that is On. "Why is my template greyed out in the Decision list?" explains why.

Why is my template greyed out in the Decision list?

Because "Changes the story" is On. A Decision Template choice can only start a roll that changes nothing by itself. So a template with results is listed there greyed out, with the reason on it, and cannot be picked.

It goes by the switch, not by whether you have written any results yet. So a template with the switch On and an empty Results tab is greyed out too.

There are two ways out. The usual one is to start the roll from a Trigger in the Chapter instead. The other is "Changes the story" Off, with what it did moved into the Decision Template's own results.

Switching it Off deletes the outcome results you built here, for good. Anything you want to keep has to be moved first.

What does my Reader see?

"See it as a Reader", the button with an eye at the top of this window, draws it for you. The drawing comes from what is in here right now. So it shows every change you make, including the two below. Nothing is rolled in it, and no rule is checked.

A die, a number, and then whatever your story does next. Two rows under "On your Reader's screen" change what is on it:

Dice animation, Visible or Hidden: whether they watch the die tumble or are told the result straight away.

Target number, Visible or Hidden: whether they see the number the roll had to reach. Hiding it keeps the odds mysterious. Showing it makes the roll feel fair.

Neither changes the odds. What you set on "Win or lose" decides what counts as a success. Your Reader sees the consequences of that, but not the rules themselves.

Where did the Description field come from, and who sees it?

Your Reader does, under the die, right before they roll. It is the line that says what is at stake: "You size up the gap. Can you make the jump?" With the Dice animation Hidden, the roll happens as the window opens. There is no "before", so the line is skipped.

It only appears once "Changes the story" is On, because that is when the roll decides something. A roll for atmosphere needs no setting up. A roll that changes the story does.

How are the four outcomes decided, and what happens if two of them match?

They are checked in a fixed order, and the first match wins. The order is Critical Success, then Critical Failure, then Success, then Failure.

So when two outcomes overlap, the earlier one wins. If a 20 counts as both a Critical Success and a Success, it is a Critical Success, because that is checked first.

The two criticals are optional, and each has a three-way switch on "Win or lose". Off means it never happens. On means the number alone decides it. On, with conditions means the number has to land and your conditions have to be true. That way, a critical can be something only a prepared Reader can get.

Which die should I pick?

"Die" is how many sides it has, and it only changes how fine-grained the chances are.

A d20 (twenty sides) is the usual choice. It gives you room to say "succeeds on 12 or more" without the odds feeling arbitrary. A d100 is for when you want percentages. A d6 is for a rough, lucky-or-not moment.

Changing it after you have set your numbers only touches the ones that no longer fit. A number above the new die's top comes down to it. A Critical Success sitting at the old top follows the new top. Everything else stays where it was. So a 15 that read as "hard" on a d20 reads as "easy" on a d100 until you move it.

What is a Modifier?

A bonus or penalty added to the roll when something is true, so a prepared or well equipped character rolls higher than an unprepared one.

"+2 if the Reader has met The deck of the Pequod" is a Modifier. It is built from the same conditions as everything else. It can also take from the roll, with Subtract under "What it does".

"What it does:" is Add or Subtract. "By how much:" is the size of it, either a plain number (Number) or the answer to a Calculation you built. A Calculation lets a bonus grow with a Fact. "Chance it applies:" makes it apply only some of the time. "Applies:" decides whether it always applies (Always) or only when its conditions hold (Only when...).

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 Dice Template any more?

Four locks, and each says which one it is.

"This Dice 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 Dice 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 Dice 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 Dice 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.

The Modifiers tab says "1 open" (a 1 in a circle on a phone) and Save refuses. What is open?

A Modifier card has no Save of its own. Anything that takes you away from it keeps it. That means adding another, opening another, moving to another tab, or pressing the template's Save at the bottom. Collapse on the card folds it down to one line and keeps it too, but you never have to press it.

"1 open" counts a Modifier card that is still open. The template's Save keeps it if it is finished. A card that is not finished stops the save, and a message says what it still needs. Once the card has that, or is deleted, the template saves.

Leaving the tab with an unfinished card asks whether to go back or discard it. Nothing is thrown away without that question. A finished card, including one you reopened with the pencil, is kept.

How many results can one outcome have?

Up to 20 Result Sets on each of the four outcomes, and each set holds its own conditions and results.

Separate sets let one outcome do different things for different Readers. A success can reveal one chapter for someone who has a lantern, and another for someone who does not.

Critical Success is greyed out and says "Off under Win or lose".

The critical outcomes are optional, and yours are switched off on the "Win or lose" tab. An outcome that cannot happen cannot carry results. So the Results tab shows it as unavailable, and you cannot write something that would never run.

Once Critical Success is on there, it can be edited here.