Folio v1 - reference
The wiki is the spec.
Each Folio construct gets a page: parameters, canonical example, notes. The wiki is also the AI importer's reference - its contents go into the prompt, so what's written here is what the model sees.
45 pages. The sidebar groups them; placeholder rows are stubs for constructs still being built.
Narrative core
Dialogue, choices, scene flow.
- sayAttribute a dialogue line to a named character.
- narrateNarrator line - text without a speaking character.
- pausePacing event - hide the textbox and wait for a click (or auto-advance after N seconds).
- choicePlayer decision - present a list of options that branch the story.
- jumpUnconditional transfer of execution to another scene.
- whenConditionally run a body of inline steps in place; chain `else when <condition>:` arms and a final `else:` for first-match branching, or end a body with `jump` to route.
- setAssign a project variable from a bounded expression.
- callRun another scene as a subroutine, return when it finishes.
- returnPop the call stack and resume the calling scene.
- endTerminate the playthrough.
- inputAsk the reader to type a value and store it in a variable.
Stage
Backgrounds, sprites, transitions.
- bgSet the background - clears the layer, then stages a new image. Scene-scoped: the backdrop belongs to its scene and clears at the boundary.
- spriteShow a project sprite in a scene, then set its frame, move it, switch its idle motion, or hide it - every sprite is present (hidden) until shown.
- transitionBlend or fade into every change inside the block at once.
Audio
Music, sound, voice, video.
- musicControl the music channel - play or stop a background track.
- soundControl the SFX channel - play or stop a sound effect.
- voice(placeholder)Play a voice clip on the voice channel via `sound play <ref> on voice` (a dedicated auto-attach `voice` verb is planned).
- videoPlay a fullscreen cutscene, or place a video clip on the stage.
Reference
Variables, characters, scene flow at a glance.
- variablesProject state - how Folio variables are typed, declared, and referenced.
- charactersHow speakers lower into Folio. A cast member is a stable handle (`say emma:`), like a Ren'Py `Character()` variable - rename-safe. A bare quoted name (`say "Storyteller":`, optionally `#color`) is a one-off custom speaker, like a Ren'Py string-speaker line. A bare string with no speaker is `narrate`.
- scene-flowScene structure, routing arrows, and the vocabulary that moves a story between scenes.
Effects
Stage effects + text-tag grammar.
- @shakeJitter the whole frame, the backdrop, or a single sprite to punctuate impact, surprise, or shock.
- @flashPunctuate a moment with a full-stage color flash that fades back to the scene.
- @dissolveCross-fade the changes it is scoped to - one line's own `with dissolve`, or every change inside a `transition dissolve:` block. Never an effect line.
- @fadeFade the stage out to a color and hold it there - the out half only. A `transition fade:` block plays both halves around its body; `bg ... with fade` plays the reveal.
- @punchSnap the whole frame, the backdrop, or a single sprite horizontally for a single event of physical impact.
- @sprite-opacityTween a sprite's opacity by slug. Standalone, or what `sprite show`/`sprite hide ... with fade` lowers to.
- @sprite-popScale a sprite up then back to base by slug - emphasis pop, reaction beat.
- @sprite-bounceSquash-and-stretch a sprite once and settle back to base - the show-time bounce entrance as a mid-scene beat.
- @sprite-growScale a sprite in from a speck up to full size, settling on a motion curve - entrance reveal.
- @sprite-color-matrixSustained color grade on a single sprite (brightness / contrast / saturation / hue) - flashback tints, drained-to-grey, sickly casts.
- @nodDip a sprite's head down and back - a beat of agreement or acknowledgement.
- @headshakeSway a sprite's head side to side - a beat of disagreement or disbelief.
- @flinchRecoil a sprite back with a quick shrink - a startled or hurt reaction.
- @perkLift and grow a sprite slightly - a beat of sudden interest or alertness.
- @slumpSettle a sprite down with a slight lean - a beat of defeat or resignation.
- @panPan the camera (in-world layers - backdrop + sprites) to an absolute (x, y) offset from stage center.
- @zoomZoom the whole frame, the backdrop, or a single sprite to an absolute scale, pivoting on a chosen focal point.
- @kenburnsSlow camera zoom drift to a target scale - background motion behind dialogue.
- @blurApply a Pixi BlurFilter to a sprite (by slug) or the whole in-world frame.
- @color-matrixApply a Pixi ColorMatrixFilter (brightness/contrast/saturation/hue) to a sprite or the whole in-world frame.
- @particlesCustomizable persistent particles with 15 procedural presets, preset-specific style controls, wind, variance, spawn areas, and stage layering. Setting intensity=0 clears instantly and by scope, not by preset: with a sprite target it stops that sprite's streams, otherwise it stops every emitter on the stage.
- text-tagsInline formatting, motion, appearance, and pacing grammar that lives inside `say` and `narrate` string content.
- @cameraMove the camera to a full shot framing - pan, zoom, and focal point glide together on one clock with a chosen motion curve. Duration 0 cuts straight to the framing.
- @sprite-pixelateResolve a sprite from a mosaic while it fades (target by slug). What `sprite show`/`sprite hide ... with pixelate` lowers to.