Story Markup

Everything that makes cards into a story is stored as tags on the cards themselves. Story Map and the Story Inspector write these tags for you. This page is for reading them, and for writing stories by hand.

Story tags go on a card’s last line, together with its other metadata, as described in The FlowBoard file format. A value that contains spaces is quoted: ::#label/"The long road".

A minimal story

## Reference

* ::#vn/character/mara/"Mara"

## Act 1

* The road forks under a grey sky.
  Mara: I should choose before the rain.
  ::#story ::#type/start ::#id/S0 ::#label/Crossroads
* Which way?
  ::#story ::#type/choice ::#id/S1 ::#from/S0 ::#label/Choose
* The forest.
  ::#story ::#type/ending ::#id/E_F ::#from/S1 ::#label/Forest
* The city.
  ::#story ::#type/ending ::#id/E_C ::#from/S1 ::#label/City

Story structure

Tag	Meaning
::#story	The card is part of the story that readers see
::#author-only	A planning card inside the story structure that readers never see
::#type/<type>	The card’s type: start, scene, choice, ending, note, merge (shown as Rejoin) or alt (shown as Alternate)
::#story/start	The story starts here. Can be combined with any type.
::#id/<id>	A name other cards use to refer to this one. It must be unique in the whole story.
::#from/<id>	This card follows the card with that ID. Repeat it when several paths lead here.
::#label/<text>	A short label. On a card after a Choice, it’s also the option’s default text.
::#route/<name>	The route (path) the card belongs to. The default is main.
::#merge/<route>	After this card, the route continues in the named route
::#choice/"<key>"/"<id>"/"<text>"	On a Choice card: one option, with its key, the ID of the scene it leads to, and the text the reader clicks. The Story Inspector writes these.
::#story/flow/explicit	The card continues only through its explicit connections

Story cards without ::#from follow the previous story card of the same route, in card order. A Choice’s options are either written as ::#choice/… tags, or given by the cards that name the Choice in their ::#from.

Characters, backgrounds and sound files

Declarations belong on cards in a board’s Reference column. They apply to the whole story.

Tag	Declares
::#vn/character/<id>/"<Name>"	A character. Optionally add /<alias> as the character’s short name in the Ren’Py script.
::#vn/asset/bg/<id>/"<file>"	A background image
::#vn/asset/sprite/<character>/<expression>/"<file>"	A character image for one expression
::#vn/var/<name>/<value>	A variable and its starting value: a number, true/false, or "text"
::#vn/transform/<name>/"<spec>"	A named position you can use like left or right

Images embedded in the Reference column are also recognized by their file names: bg_forest.jpg becomes the background bg_forest, and char_alice_happy.png becomes Alice’s happy expression. Files in folders named backgrounds and characters work the same way.

Scenes

These tags run in order when a scene begins:

Tag	Effect
::#vn/scene/<background>	Sets the background and empties the stage, like scene in Ren’Py. Show characters after it.
::#vn/show/<character>/<expression>/<position>	Shows a character. Positions: left, center (the default), right, centered, topcenter, or a named transform.
::#vn/show/<character>/<expression>/<position>/flip	Shows the character mirrored left to right. /vflip turns them upside down; /flip/vflip does both.
::#vn/hide/<character>	Takes a character off stage
::#vn/clear	Hides all characters and keeps the background
::#vn/play/<channel>/"<file>"	Plays audio on the music, sound or voice channel. Add /loop, /noloop, /fadein=<seconds> or /volume=<0–1> as needed.
::#vn/stop/<channel>	Stops a channel. Add /fadeout=<seconds> to fade out.

Music loops and continues into later scenes until it’s changed or stopped. Sound and voice play once.

Each ::#vn/show describes the character completely. A show without /flip shows them unmirrored, even if an earlier scene flipped them. Play Mode and the Ren’Py and Ink exports all follow these rules, so what you test is what the game shows.

Dialogue and text

In the card’s text, Name: line is dialogue by a declared character. The name can be the character’s display name or its ID. Every other line is narration. **bold**, *italic*, <u>underline</u> and ~~strikethrough~~ are shown in Play Mode and exported to Ren’Py.

Variables and logic

Tag	Effect
::#vn/set/"<name> <op> <expression>"	Changes a variable when the scene begins. Operators: =, +=, -=, *=, /=.
::#vn/if/"<condition>"	The scene can only be entered while the condition is true
::#vn/while/<id>/"<condition>"	After this scene, return to the scene <id> for as long as the condition is true

Expressions use numbers, true/false, quoted text, and variable names, with + - * / %, the comparisons == != < <= > >=, and and, or, not. For example: ::#vn/set/"trust += 1" or ::#vn/if/"trust >= 3 and has_key".

::#vn/if goes on the scene that is entered. After a Choice, the option leading there only appears while the condition is true. After a Scene with several next scenes, the first scene whose condition is true is taken, in card order, and a scene without ::#vn/if is the default.

A loop must eventually end: change a variable on each pass, so that the condition becomes false.

In text, [name] shows a variable’s current value.

Groups share their tags

A group whose group card carries story tags passes them to its cards: ::#story, ::#route, ::#type, ::#vn/scene and ::#vn/show. Identity and logic stay on each card: ::#id, ::#from, ::#label, and ::#vn/set, ::#vn/if and ::#vn/while. The group card itself is never played. A card can override what it inherits, for example with a different ::#vn/show.

The group’s ::#vn/scene runs again on every card in the group, and a scene empties the stage. A character that one card adds with its own ::#vn/show is therefore gone on the next card. Put characters who stay for the whole group on the group card. A card with its own ::#vn/scene replaces the group’s background, and the group’s characters still appear.

Game engine code

Code for one target goes into fenced blocks in the card’s text:

Block	Goes to
```renpy or ```python, or a line starting with $	The Ren’Py script only
```ink	The Ink script only

On a story card, the code becomes part of that scene. On a Reference column card, it’s placed outside any scene, as general setup code for the script.

Play Mode’s RenPy preview doesn’t run Ren’Py code. If a branch depends on a Ren’Py condition that FlowBoard can’t evaluate, the preview pauses there with a notice. The Ink engine plays the exported Ink script, so your ink blocks do run there.

Files and exports

Tag	Effect
::#renpy/file/<path>	On any card of a board: the Ren’Py file that board is exported to, such as chapters/ch1.rpy. The Ink export uses the same name with .ink.
::#include/"<path>.md"	Includes another FlowBoard document when you play or export. See Combine several files.

Prefix

vn is the default prefix for scene, sound and variable tags. A document can use a different prefix in its frontmatter (play_mode.namespace). The tags then start with that prefix instead.