Docs/Dynamic Components

Dialogue Templates

A Dialogue Template is a conversation between your Reader and one character. The character speaks, your Reader picks a reply, the character answers that reply, and so on down a tree you write line by line. A reply can change the story on the way: reveal something, change a Fact, or move how the character feels. You build the conversation once, and any Trigger in the book can open it.

Where to find it

You can find Dialogue Templates in the sidebar, under Dynamic Components. The list shows every conversation in this book: name, line and Emotion counts, and validity. Add Dialogue Template creates a new one. Pressing a card opens it in the editor.

Before you start

A conversation can be written with nothing else in the book. Two things make it better:

  • Someone to talk to. A Character or Creature Glossary Item, ideally with a main image. Then the bar at the top of the conversation shows a face and a name. The picker under Who the Reader talks to lists only Characters and Creatures. With none in the book, it is empty and says so.
  • A Fact for a feeling to land in. Emotions last for one conversation only. A reply can write the feeling to a Numeric Fact on the character, such as Trust. The next conversation, and the rest of the book, can read that Fact.

The template

  • Template name: the label shown in the list and in any Trigger that opens this conversation. Required, up to 70 characters. A name you'll still recognise later helps: "Queequeg, first meeting at the Spouter-Inn" is clearer than "dialogue 3".
  • Show the title: when on, the template name is a heading at the top of the conversation. Off keeps the focus on the character.
  • Media: one optional picture or video from your Media library, shown full width above the character's line. A reply's Change Media result swaps it for another as the conversation moves, so a scene can change while they talk.

Who the Reader talks to

Who the Reader talks to is the character of the conversation: a Character or Creature Glossary Item from your book. Its name and its main image appear in the bar across the top of the conversation, so the Reader can see who's speaking. With no main image, the bar shows the first letter of the name. The main image is set on the Glossary Item's own page.

It is optional, and a template has at most one. The whole conversation is with that character. Clear, beside the box, takes the character off again.

Lines and replies

The conversation tree

A conversation alternates. The character says a line, and under it you write up to five replies the Reader can pick from. Under each reply you write the character's next line, then its own replies, and so on. A conversation holds up to 20 lines in all.

Each line holds:

  • What the character says: the character's words on this turn, shown in a speech bubble above the replies. A long turn can be several bubbles, up to 15, each up to 200 characters. The plus beside the numbered tabs adds one. The Reader taps Continue through them, and the replies come after the last. Nothing runs between two bubbles. A change halfway through a long turn takes two lines, with a reply such as "Go on"between them. A reply with nothing under it has no such field, and says so. Picking it ends the conversation, so there is no moment for an answer. To give the character the last word, their line needs one more reply under it, such as "Nod and leave", and that reply ends it.
  • Replies: what the Reader can say back, up to 170 characters each. Each reply has its own prerequisites (whether it's offered) and its own results (what happens when the Reader picks it).
  • Prerequisites, behind Only offer this reply when..., decide whether a reply is offered. They can check a Fact, an item the Reader carries, whether a Glossary Item has been revealed, or an Emotion's score. For example: "only offer this reply if Trust is above 5". When the rules fail, you choose whether the reply is hidden or greyed out.
  • Results are what picking the reply does. A result can reveal a Glossary Item or a Chapter section, change a Fact or an Emotion, swap the picture, or open a Trade Screen. A Trade Screen is the only Dynamic Component a reply can open. Two results steer the conversation itself. Go back to the previous line takes the Reader up one step, so they can pick again. End the conversation closes it from a reply that has lines under it.
  • Grey out once picked: on by default. Once the Reader has picked this reply, it greys out and can't be picked again. Off suits a question worth asking twice, like an innkeeper the Reader can talk to on every visit.

For example: Asking the innkeeper for a room

Ishmael wants a bed. Coffin has half of one. The whole conversation, as the tree on the window's left would show it:

Coffin"Rooms? I have one bed left, and a harpooneer in it."The opening line: What the character says, at the top of the tree.
Reply"Any other rooms at all?"A reply. Its own What the character says is Coffin's answer below.
Coffin"Not unless you count the bench by the fire."
Reply"The bench will do."Nothing under it, so picking it ends the conversation. Its result reveals the Header A night by the fire.
Reply"Who is the harpooneer?"Result: Add 1 to Trust. Coffin likes a man who asks.
Coffin"A quiet sort. Pays on time. Sells heads on Sundays."
Reply"Then I will share the bed."Only offer this reply when... Trust is more than 5. Greyed until the Reader has asked about him first.
Reply"Let me think about it."Result: Go back to the previous line, so the Reader can ask the other question.
In the window this is six lines: the opening one and five replies. The two replies that lead on also hold Coffin's answer. Every indent is one more level down the tree on the window's left.

"Who is the harpooneer?" raises Trust, and "Then I will share the bed" is only offered once Trust is above 5. So the order the Reader asks in matters. "Let me think about it" goes back a step, so a Reader who asked about the harpooneer first can still ask about rooms. The two ways out each reveal a different hidden Header.

Emotions

Named feelings a reply can read and write

A template can have up to five Emotions, such as Trust, Anger, Fear, Affection, or whatever fits the character. Each one has a name of up to 25 characters and a score from 0 to 10 that starts at 5. It can also have a short description. The description is for the Reader: they see it when they hover the Emotion's badge. A reply's prerequisite can read the score, as in "Trust above 5". A reply's result can write it: add, subtract or reset points, or take the change from a Calculation.

Note
Emotions last for this conversation only and reset when it ends. The rest of the book can't read them. A feeling carries forward when a reply's result writes it to a Numeric Fact on the character's Glossary Item. Emotions themselves always start at 5 out of 10, so the next conversation cannot inherit them. It can read that Fact in a prerequisite instead, and offer different replies.

What your Reader sees

A window over the page. Across the top runs a bar with the character's picture and name, if you set a character, and one badge per Emotion. Below it, the picture or video fills the width, if you set one. Then comes the character's line in a speech bubble. A line of several bubbles shows one at a time, with a Continue button under it, and the replies come after the last. Last is one button per reply, in the order you listed them, each with its icon.

  • A first tap picks a reply, and a second tap confirms it. The character's answer replaces the bubble, the next replies replace the buttons, and the badges move as Emotions change. Hovering a badge shows the score and your description.
  • A reply that goes back, ends the conversation or opens a shop shows that action's own icon, not the one you picked.
  • A reply whose rules fail is missing or greyed, as you chose on its Prerequisites tab. A reply they already picked is greyed while Grey out once picked is on.

The window holds the page: the Reader can minimize it and look back, but they read on only once the conversation has ended.

See it as a Reader, the button with an eye at the top of the window, draws all this on your own conversation. It starts from the line you have open, with the bar, the picture, the bubble and the buttons. A note under each reply says where it goes and when it is offered. Nothing is checked or run there, so every reply is shown and the badges stay where they start. Back returns you to the same place in the window. Edit this line opens the line on screen.

Published templates

Once a Dialogue 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 Dialogue Template can be invalid for several reasons:

  • The character it talks to points at a Glossary Item that has since been deleted. Picking another character, or pressing Clear, makes the template valid again.
  • A reply's prerequisite or a result points at a Glossary Item, Fact, Tag, Calculation, or Emotion that has since been deleted. Deleting an Emotion from the Emotions tab flags every reply that used it. Renaming one is safe, because the rules follow the name. The fix goes in the reply that shows the warning.
  • The picture was deleted from your Media library, here or in a reply's Change Media result. The row stays marked until another picture is picked or the row is cleared.
  • A reply has Only offer this reply when... switched on but no rules written. Writing the rules, or turning the switch off, fixes it.
  • Two Result Sets on the same reply clash, with no conditions to separate them. Either both open a Dynamic Component, or both steer the conversation (one goes back to the previous line, the other ends it). Only one of each can run when the reply is picked. Conditions on the sets, or removing one, fix it.

The list page marks invalid templates with a warning icon and sorts them to the top. The publish check rejects any book with an invalid conversation, so a broken template blocks the next publish until you fix it.

Before a Dialogue Template is deleted, a question over its window lists the Triggers that still open 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 Dialogue Template window.

How this fits your story

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

How do I add the lines my Reader can say back, and how does a reply lead to more?

In two places, whichever suits. "Add a reply" sits under the line you have open in the tree on the left. The line's own "Replies" tab has the same button, with the list of replies to edit in place. Each reply is one thing your Reader can say. A line can offer up to five, and a conversation holds twenty lines in all.

Opening a reply, in the tree or from its row on the "Replies" tab, lets you carry on from it. Whatever you add under it is what your Reader can say next. Every reply can grow its own replies, as deep as the conversation needs. The tree on the left shows all of it at once, each reply indented under the line it answers.

A reply with nothing under it ends the conversation when it is picked. The exception is a reply with a result that goes back a step or opens a Trade Screen. An ending nobody meant to write is usually a reply somebody forgot to continue.

What are Emotions for?

A score this conversation keeps, so it can remember how your Reader has been behaving in it. They live on the "Emotions" tab. Each starts at 5 out of 10 when the conversation opens.

A reply's results raise or lower one. A kind answer adds to Trust, and a threat takes from it. Another reply's prerequisites then check it, so a line can be offered only once Trust is high enough. Together, the two let a character react to how they have been treated across the whole conversation.

They belong to this conversation, not to the book. Something the whole story remembers belongs in a Fact on The deck of the Pequod instead.

Rules find an Emotion by its name, and renaming one renames them too, so a rename never breaks a rule.

What does my Reader see, exactly?

A bar across the top with the character's picture and name, if you set a character, and one badge per Emotion. Under it is the picture or video, if you set one, filling the width. Then comes the character's line in a speech bubble, or one bubble at a time with a Continue button when the line has several. Last is one button per reply, in the order you listed them, each with its icon.

A reply that goes back, ends the conversation, or opens a shop shows that action's own icon instead of the one you picked. A reply whose rules fail is hidden or greyed, as you chose on its Prerequisites tab. Hovering a badge shows the Emotion's score and its description.

"See it as a Reader", the button with an eye at the top of the window, draws all of that from your own conversation. It starts from the line you have open. A note under each reply says where it goes and when it is offered. It is only a drawing, so rules are not checked. Every reply is shown, and the badges stay where they start. Back, or Escape, returns you to where you were.

Can a reply open a shop?

Yes, with a result on the reply: Dynamic Component, then Trade Screens, then the screen. Your Reader sees a basket on that reply. Picking it saves the conversation and opens the shop on top. When the shop closes, the conversation comes back where it was, on the line that reply answered.

Inside a conversation, a Trade Screen is the only kind of Dynamic Component a reply can open. Anything else waits until the conversation ends, when a Trigger in the Chapter can take over.

This window's own settings

Where do I write what the character says?

In "What the character says:", at the top of whichever line you have open. The line you start on is the opening line, the one the character says before your Reader has done anything.

A long turn can be several bubbles. The numbered tabs above the box hold them, and the plus beside them adds one, up to 15. Your Reader taps Continue through them, and the replies come after the last.

"What the Reader says:" is the opposite: the words your Reader says back, on a reply. So a conversation takes turns. The character says a line, and your Reader picks one of the replies you offer. The character then answers whichever reply they picked.

A reply with nothing under it has no field for the character's answer, and says so. Picking it ends the conversation, so there is no moment for an answer. The field appears once the reply has a reply of its own under it.

Who is the character my Reader talks to, and do I have to pick one?

"Who the Reader talks to", on the "Overview" tab: a Character or Creature Glossary Item. Their name and picture come from that item, and the picture is its Main image. So a later change to the portrait there shows up here too. "Clear" beside the box takes the character off again.

You do not have to set one. A conversation with no character suits a voice with no face, such as a narrator or a voice through a door.

If the list is empty, it says so: you have no Characters or Creatures yet. One made in the Glossary tab shows up here.

What does "Grey out once picked" do?

Once your Reader has picked this line, it stays on screen but they cannot pick it again for the rest of the conversation. It is on by default.

Off suits a line worth asking twice, such as "Tell me again about the fire". On suits anything that would be strange to repeat.

How do I let my Reader go back and pick something else?

With a "Go back to the previous line" result on the reply. Picking that reply takes your Reader back up one step instead of onwards. The result is greyed on a reply to the opening line, since there is nothing earlier to go back to.

That makes a conversation people can explore. A handful of questions each loop back, and one reply that does not is the way out.

The reply's icon follows a rule too. A line that goes back, ends the conversation, or opens a Trade Screen shows that action's own icon. It replaces the icon you picked.

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

Four locks, and each says which one it is.

"This Dialogue 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 Dialogue 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 Dialogue 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 Dialogue 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 Prerequisites or Results tab is greyed out.

Each greyed tab says why when you hover it, and what turns it on.

On a reply, Prerequisites is greyed while the reply is always offered. With "Only offer this reply when..." set to Yes, the tab opens on the rules.

On the opening line, both are greyed. It is always spoken, so it has no rules for when it is offered. And it only speaks, so what happens next is set on each reply underneath it.

There is a warning icon and the button says "Next reply to fix".

Something in the conversation is unfinished. The tree on the left marks every line it is waiting on. "Next reply to fix", at the top of the tree, walks you to them one at a time, until nothing is marked.

The usual causes are a half-built condition or result, or a "Change Media" result whose picture or video was deleted from your gallery. The warning clears once it is finished or removed.