Stage directions

A stage direction is a beat that changes the stage instead of the text. Insert one with the toolbar, with the / menu (type /st), or by converting the current beat with Ctrl+Alt+S. The beat's first control is the action type, and the rest of the row changes to match it.

Thirteen action types exist. Nothing else is a stage direction.

Every direction

Every direction, whatever its type, also carries parallel.

prop and inspect have a page of their own: Props. The rest are below.

Parameter details

preset offers wide, two-shot, close-up, over-shoulder. A preset the runtime does not recognize is ignored, and the previous shot stays up.

expression is a select when the character's VRM told us its expression names at upload, with a custom… entry that opens free text. A character whose names we do not have gets the six VRM standard presets: happy, angry, sad, relaxed, surprised, neutral. Capitalization matters, because these are the names the model registers. An unknown name is silently ignored, and a character below the VRM avatar tier has no expressions at all.

clip is either a clip name from an animation asset's parsed catalog or the id of a clip asset you picked directly. The clip picker offers names.

gain is the authored volume, 0 to 1. Leave it empty for the default of 1. What the reader hears is your gain multiplied by their volume slider and by any fade currently running, so moving a slider mid-fade does not fight the fade.

fadeMs is a fade-in on play and a fade-out on stop. Empty means no fade.

loop on music and sfx overrides the channel default. Music loops unless you turn it off; sound effects do not loop unless you turn it on.

The asset slot on music, sfx, cutaway, prop and inspect accepts either a literal asset or a binding: the name of a declared text variable holding an asset id. set theme = "m-storm" earlier in the story, then bind the music direction to theme, and the story picks its own track. The binding is resolved when the direction runs. Anything unresolvable (unset, not text, not a real asset) plays nothing rather than erroring. See Variables.

Parallel, and the Hold

parallel is the single most important control on the beat, and it is off by default.

Off, the direction is a Hold. The runtime rests on the direction beat, runs the op, and only moves to the next beat when the op's own work has finished. A non-parallel video cutaway therefore gates the script until the clip ends, with no wait beat and no duration for you to guess. A non-parallel move gates it until the character arrives, and a non-parallel inspect until the reader puts the prop down.

On, the direction fires and the script keeps going. This is how you play music under a line, or run an animation while a character talks over it.

Directions that only change persistent state (face, prop, light, weather, camera, expression) have nothing to wait for and release at once, so leaving parallel off on them costs nothing.

Moving cast

move is how a character enters, exits or crosses. to is one of the five marks or offstage; there are no coordinates. gait is walk, jog, run or cut.

stage  move  Mira  to center  walk

The three moving gaits play the library's walk, jog and sprint loops while the character travels, and stop on arrival. Travel time is distance divided by gait speed, wall-clock, so a paused render loop cannot stall the Hold; the character covers the ground on that same clock and lands as the Hold releases. cut teleports, and so does every gait for a reader with reduce motion on.

Footsteps come with the walk. A travelling character lands one step per stride, at the cadence its gait implies: about two a second at a walk, three at a run. There is nothing to author, no asset to upload and no direction to write. The steps ride the reader's sound-effects slider and the scene's reverb, an sfx stop does not stop them, and a cut (or any gait under reduce motion) covers the ground in no time and so lands none.

Entrances and exits. offstage is a wing just past the edge of the wide shot, on the side nearest the character's mark. A character who is not in the scene's staging header and is moved to a mark walks in from that wing; a character moved to offstage walks out through it and is no longer drawn. Nothing else is needed for an entrance.

stage  move  Kai   to left      jog      (enters from the left wing)
line   Kai   Sorry. The bridge was out.
stage  move  Kai   to offstage  run      (and leaves again)

then face. A move may carry an arrival facing, applied the moment the walk ends. Without it the character keeps whatever facing they had.

stage  move  Mira  to center  walk  then face Kai

A move ends any looping animation on that character (locomotion replaces the idle). Placements set by move last for the scene and are replaced by the next scene's staging header, exactly like a header placement.

Facing

face turns a character on the spot. toward is another cast member, camera, or away. Every character starts facing the camera.

stage  face  Mira  toward Kai
stage  face  Kai   toward away

Facing a member who was never staged reads as facing the camera. A member who walked offstage is faced toward the wing they left by.

Looping an animation

animation plays its clip once and returns to idle. Tick loop and the clip becomes that character's resting idle instead, until a later clip on the same character or a move replaces it, or the scene changes.

stage  animation  Mira  Sitting_Idle_Loop  loop

The built-in library carries posture and locomotion loops (Sitting_Idle_Loop, Push_Loop, Walk_Loop and others) that only make sense looped. Uploaded clip assets loop the same way.

Framing one character

camera has an optional target. Left empty, the shot follows the speaker as described in The virtual stage. Name a member and the preset frames them instead, whoever is talking, until the next camera direction or the next scene.

stage  camera  close-up  on Mira

A target in the wings, or never staged, is ignored and the speaker frames the shot as usual.

Moving the camera

A camera direction cuts to its preset. Set move and the shot travels there instead, over the duration you type in over ms. Leave the duration empty and a move takes 1200 ms, which is what the placeholder shows.

stage  camera  close-up  on Mira  move dolly-in  over 1600

Leave move empty and the direction cuts, which is what every camera direction did before this field existed. The lens stays aimed at the subject through the whole move, so what travels is the angle they are seen from, not them.

A move with parallel off is a Hold, exactly like a walk: the script rests on the beat until the camera lands, and the next line arrives after the push finishes. Turn parallel on to run a slow crane under dialogue.

Where the move ends is where the shot stays, held as an offset on the framing until the next camera direction or the next scene. A dolly-in stays pushed in. The travel is solved against the framing the preset lands on, so the same move reads the same on a narrow pane as on a wide one, and a camera direction with a move replaces the header's push-in for the rest of the scene.

The camera's breath (Handheld) stands down while a move is travelling and fades back in once it lands, so a dolly is clean. A reader with reduce motion on lands the move at once instead of watching it.

Light

light swaps the stage's lighting rig: key, fill, rim, sky, fog and exposure together. The six presets are day (the default rig), dusk, night, candle, neon and storm. The rig fades to the new preset over about a second; reduce motion snaps it.

stage  light  night

Lights belong to the stage, not the environment, so a preset looks the same on every set. It stays up across beats and goes back to day on scene entry.

Weather

weather puts a particle layer over the stage: rain, snow, petals, embers or fog, or none to clear it. Like light it persists across beats and is cleared on scene entry.

stage  weather  rain

Weather is dropped entirely on the low quality tier, so never make a plot point depend on the reader seeing it.

Cutaways

A cutaway covers the stage with full-screen media. Beats, dialogue, choices, and the HUD keep rendering on top of it, always. That is not a style preference: choices baked into a video clip would break saves, conditions, timed choices, and everything else the engine does with a choice.

One direction covers both flavors. Point it at an image asset and you get a visual-novel CG. Point it at a video asset and you get an FMV clip. The runtime reads which from the asset itself.

Three behaviors to plan around:

It persists. A cutaway stays up across beats and across scene edges until you end it or show a different one. Chains of video scenes never flash the stage between clips. It also suppresses the fade-in a scene's enter setting would otherwise play.

It holds its last frame. A non-parallel video that reaches its end does not disappear. The frame stays painted, and the choice renders over it. The gun is still in your face while you decide.

Saves resume at its start. A save made mid-clip resumes at the beginning of the cutaway, not at the frame you left. There is no seek guarantee. Music follows the same rule: a save restores the track from its start, at the volume you authored.

There is no trim and no in/out timing on the op. If you need a clip to run for eight seconds, cut the clip to eight seconds.

Effects

shake jitters the camera briefly and decays to nothing. flash is a single screen flash.

letterbox is a toggle, not a switch you set. Each letterbox direction flips the bars: one to bring them in, a second one later to take them away. Scene entry clears them, so a scene you enter with bars up from the previous scene starts clean. Both facts are easy to trip over. If your bars stay up for the rest of the chapter, you are missing the second direction.

Audio in practice

There is one music slot. A new music play replaces whatever was playing, fading the outgoing track out if the new direction names a fadeMs. Stops fade too, with the same field.

Sound effects stack. Each sfx play starts another element, one-shots clean themselves up when they finish, and sfx stop stops all of them at once. There is no way to stop one named effect.

The scene's ambient loop is not an sfx direction and is not affected by sfx stop. It lives in the staging header, along with the room every effect and voice is heard in.

Music ducks under dialogue, and you do not have to ask. While a character speaks, the music bus drops to 40% of its gain over 200 ms and comes back the same way when the line ends. A recorded voice line ducks deeper still and holds for the clip's own length; a typed line holds for as long as the text takes to reveal. Unvoiced narration, a line with no speaker, does not duck at all.

Two fields on the music direction change that, and both belong to the cue rather than to the story:

• duck is what the bus drops to, 0 to 1. 0 is silence under a line, 1 switches the duck off for this cue. Empty is the default dip.
• duck ms is how long the dip and the recovery take. Empty is 200 ms.

Sound effects never duck. An effect is what plays over the dialogue, so there is nothing for it to make room for.

Where to see the result

The editor's stage viewport previews the stage at your caret: the camera preset and target, every placement, facing, looping idle, prop, light preset and weather the script has set up to that point, plus any one-shot animation on the beat you are actually sitting on. It reads the script linearly, so it does not descend into a choice's inline body and does not evaluate conditions, and a prop bound to a variable is skipped because the preview cannot know its value. Music, sound effects, screen effects, and cutaways are not part of that preview, because none of them are persistent stage state. To hear and see the whole thing, including a walk, open Preview.