Documentation

Every story you make is a project. You open a project in the Engine and work in one of three views, switched from the left rail (which also carries a Muse button for the AI assistant):

• Play. Read and test your story exactly as a player will, advancing line by line and taking choices.
• Graph. The flowchart of your whole story. Every scene is a node and every jump or choice is a connection. Open a scene here to edit it.
• Assets. The media library: backgrounds, character art, items, dialogue-box designs, music, and sound.
• Muse. The built-in AI assistant that writes and edits the story and generates art and audio (see Muse).

The four words this manual uses

We use a small, consistent vocabulary. If you come from another tool you may know these by other names, but they all map onto the same four ideas, and both the editor and Muse (the AI assistant) accept your words too.

• Scene. One node of the story, a single "place" in the flow. Also called: node, passage, label, card, section, page, part.
• Statement. One item inside a scene's timeline: a line of dialogue or narration, a choice, a variable change, a jump, a sound cue, a sprite change. Also called: a beat, a step, a line.
• Route. A whole path through many scenes, usually gated by the player's state (an affection score, a flag), classically one route per love interest. A branch is the fork itself; a chapter groups scenes.
• Attribute. A story variable: a number, a flag, a piece of text the story remembers. Also called: variable, flag, stat, switch, state.

Behind the scenes, those statements are stored as a tiny, readable script. Here is a complete little story in the engine's grammar. You rarely write this by hand (the editor and Muse do), but it is the clearest way to show a story's shape:

define s = Character("Sylvie", color="#c8ffc8")
define m = Character("Me", color="#c8c8ff")

label "opening":
    scene bg-lecturehall
    "I'll never forget that day..."
    show sylvie-green-smile
    s "Hi there! How was class?"
    m "Good... I've been meaning to ask you something."
    jump "ask_her"

label "ask_her":
    m "Will you make a visual novel with me?"
    s "I'd love to!"

Play starts at your first scene (here opening); the editor decides which scene is the start, so naming a scene start has no special meaning. A scene that ends with no jump or choice (like ask_her) finishes the playthrough.

Each scene has a label, a short identifier used to jump to it. Labels are identifiers, so they cannot contain spaces; the editor normalizes any whitespace to an underscore (old_well, day-2-court).

Working with the timeline

In the script grammar a line is a speaker followed by a quoted string; the speaker is the character's short variable (from a define line). Narration is a bare quoted string:

s "Hi there! How was class?"
"I'll never forget that day."
narrator s "A voice echoes from the hall."

narrator styles a narration line as a named character (for color or box binding) while still hiding the name tag. The character must be defined first, like any speaker.

Formatting text with tags

Inline tags ride inside the quotes. The text toolbar inserts the common ones (Bold, Italic, a selection color, Insert attribute, an Instant span, a Wait marker, and a Reveal-speed span); the rest you type by hand. They all render and round-trip losslessly.

• {b}...{/b} bold, {i}...{/i} italic, {u}...{/u} underline, {s}...{/s} strikethrough.
• {color=#ff005d}...{/color} color, {size=40}...{/size} size, {font=mono}...{/font} font (typed by hand, no toolbar button).
• ${name} inserts the value of an attribute (great after an input).
• {w} waits for a click; {w=1.5} mid-line pauses the reveal 1.5s then continues, and at the very end of a line auto-advances after 1.5s with no click. {nw} auto-advances immediately; {p} is a paragraph break.

s "Wait... {w}you mean {b}right now{/b}?"
s "Hello, ${name}. {color=#66d4db}Welcome back.{/color}"

In the grammar, a menu is a header and one line per option:

menu:
  "Ask her right away." -> "rightaway"
  "Ask her later." -> "later"

An option line can carry, in order: per-choice art (img / hover), a show condition (if), a jump target (->), an activate sound (~), and an assignment ($):

menu:
  "Confess." if love >= 3 -> "good_end" $ confessed = 1
  "Say nothing." -> "later"

• An unset attribute reads as the number 0 (which is falsy), so you rarely need to initialize anything. not seen_well is true before seen_well is ever set.
• Change one with a set statement. In the script grammar a set is written with a $ prefix: $ love += 1, $ route = "moon", $ unlocked = true.
• Values can be numbers, text, or true/false. Conditions accept keyword or symbol operators interchangeably (and/&&, or/||, not/!), and a single = in a condition means equality.

Persistent attributes

Most attributes reset each playthrough. Flag one as persistent (the ∞toggle on its pill) and its value survives across playthroughs for that signed-in player: for gallery unlocks, New Game+ carryover, or "you've seen this ending" flags.

Conditioned lines and jumps (the cheapest branch)

mia "You came! I knew you would." if love >= 3
mia "Oh. It's you." if love < 3
jump "true_end" if confessed = 1

A line with a failing condition is silently skipped. A conditioned jump is taken only when its condition holds. Per-line guards have no implied else, so write the exact complement yourself.

Blocks: if / elif / else

When an arm needs more than one statement (a line plus an attribute change, say), use a block:

if love >= 3:
    $ trust += 1
    s "I was hoping you'd ask."
elif love >= 1:
    s "Oh, sure, okay."
else:
    s "...maybe another time."

Keep blocks balanced (the editor renders them as a connected chain with editable condition chips). Play falls out of the taken arm to the statements after the block, so branches converge for free.

Asking the player for text: input

input name "What's your name?"
m "Nice to meet you, ${name}."

inputstores the player's text in an attribute; recall it with ${name} in any later line.

Compound conditions

Join comparisons with and / or / not, and group with parentheses:

jump "true_end" if (love >= 3 and brave) or route = "moon"

Loops: while

A whileblock repeats its body while a condition holds (handy for “ask until they get it right” prompts). Make sure the body stops on a player-facing line or changes the condition; a runaway loop is capped at 100,000 statements and ends the scene rather than freezing.

while answer != "rosebud":
    input answer "The password?"
    "Wrong." if answer != "rosebud"

• Stat-gated reaction (one alt line per tier) → a chain of conditioned lines.
• Route dispatch (one point fans out by state) → a stack of conditioned jumps, always ending with one unconditioned jump so play never falls off the end.
• Hub-and-spoke(visit places in any order, exit when done) → a menu of options gated on "not seen yet", each spoke setting its flag and jumping back.
• Counters & thresholds(points across chapters) → increment with an option's $ clause, gate the payoff with a compound condition.
• Convergence (branches share an ending) → end every branch with jump to one shared scene; never duplicate the shared content.

jump "moon_route" if route = "moon"
jump "sun_route" if route = "sun"
jump "common_route"

Backgrounds

A backgroundstatement swaps the stage's backdrop. In the grammar it's scene followed by the background asset name:

scene bg-lecturehall
scene bg-meadow with dissolve 600

The asset name is a bare identifier (no quotes); a transition rides on a with <kind> <ms> suffix where the duration is in milliseconds.

Sprites

A show statement puts a character on stage; hide removes them. Position, zoom, mirror, and paint depth are all clauses, but you usually set them by dragging and resizing the sprite on the stage.

show sylvie-green-smile
show sylvie-green-smile at 0.3,0.5 zoom 0.9
show sylvie-green-smile behind eileen
hide sylvie

• at X,Y sets the position as a fraction of the stage from 0 to 1 (0.5,0.5 is centered).
• zoom N sets scale; mirror flips horizontally.
• zorder N / behind tag set paint depth, so a sprite can sit in front of or behind another. The editor exposes this as the selected sprite's Send behind / Bring in front buttons.

Background transitions

The background stage chip has a transition dropdown (Cut, Dissolve, Wipe, Slide, Iris, Fade) plus separate pills for the transition time, a fade color (when Fade is chosen), a filter, and a shake. In the grammar the transition is a with suffix and the time is in milliseconds:

• Dissolve: the new background crossfades in. scene bg with dissolve 600.
• Fade: the stage dips through a color and reveals the new background from it. scene bg with fade 500 color #000000.
• Shake: a one-shot whole-stage punch (hpunch horizontal, vpunch vertical). scene bg-club shake hpunch.

Sprite entrance effects

A showcan carry an entrance effect, set from the sprite's effect chip: fade (fade in), hop, shake, bounce, movein-left, and movein-right.

scene bg-club shake hpunch
show sylvie-green-surprised effect bounce

play music "illurock" fadein=1000
play sound "door-creak"

There are two channels, chosen by the cue: music (one looping track, last cue wins) and sound (one-shot effects). Audio names are quoted; the params are key=value in milliseconds (fadein=1000). There is no stop keyword: to stop the music, add a music cue with no track in the audio-cue panel.

What you can change

• Geometry:the box's position and size on the stage (drag to move/resize) and its corner radius.
• Fill: a solid or gradient background, opacity, blur, an optional top feather (revealed by the Fade toggle), or a full box image (upload the say-window art and stretch it behind the text).
• Text: font, size, line spacing, a Center alignment toggle, and color; the dialogue asset editor adds a Bold toggle. (Paragraph gap and text outline are theme tokens Muse or an import can set, but they have no editor control yet.)
• Choice buttons: fill color and opacity, idle and hover text color, text size, weight, caption alignment, corner radius, gap, padding, columns, a shared button-image skin, and per-option art.
• Name tag: its position, background, color, and radius.

The title (main) menu

The quick menu

The in-play row of controls (back, history, skip, auto, save, quick save/load, preferences) is configured on the Quick tab: its actions, labels, colors, font, position, and optional per-action art. You can also hide it entirely.

• Advance by clicking the stage or pressing Space, Enter, or the right arrow; take a choice by clicking an option.
• Back (or the left arrow) rolls the story backward; the quick menu also offers history, skip (fast-forward seen text), and auto (hands-free advance).
• Save / Load keeps multiple named slots, while Quick Save / Quick Load use one rolling slot (the latest overwrites the previous).
• Preferences control text speed, auto speed, skip options, fullscreen, and music/sound volume.

• Each scene is a node; each jump or choice is a connection between nodes.
• Create a scene by double-clicking the empty canvas; open one by double-clicking its node.
• The attributes panel (top-left) adds, renames, and removes your story variables; Auto-arrange (top-right) tidies the layout. The graph stays in sync with the playable editor.

• Backgrounds: full-frame scene art, set with the scene statement (drag onto the stage).
• Sprites(characters & items): cut-out art shown with show. Generated characters are auto-background-removed so they composite cleanly on any background.
• Dialogue boxes: reusable say-window designs (see Dialogue-box themes).
• Audio: music tracks and sound effects, played by a sound cue.
• Video: uploaded clips for cutscene or looping backgrounds.

Editing an image never overwrites it: it makes a new variant and keeps the original, so an asset is really a small stack of versions you can pick between.

Muse can:

• Write and edit the story: add, rewrite, move, or delete scenes and statements; build choices and branches; set jumps; create characters and attributes.
• Make art and audio: generate new images or sound, and edit an existing image into a variant.
• Style and configure: restyle the dialogue box and set up the title screen.
• Drive the editor: open a scene, switch views, or start a preview, so you can watch her work.

Muse is context-aware: she knows which scene you have open and which asset you have selected, so "add a line here" or "make it brighter" just works on the thing you're looking at. She speaks your vocabulary too. Call a scene a node or a passage, an attribute a flag or a stat, and she maps it.

Statements

Background clauses (after scene)

Show clauses (after show)

Conditions & inline tags

Our script grammar is Ren'Py-flavored, so most lines look nearly identical. The main differences: scene labels are quoted (label "start":) and the word scene here means a graph node, while a background change is the scene statement.