How to read a scene · The Velan Codex

Every scene has the same fields:

Where: the location id (Data/Locations/<id>.json), and the marker or area in it.
When: the story gate: quest stage or flags, written as the when condition the location JSON will hold.
Who: the characters present.
What happens: 2–6 sentences.
Player does: move, talk, choose, cast, fight or learn.
Content to make: Yarn node titles, encounter ids, fragments and spells, items, and the flags and quest stages it sets.
Art and audio: models, props, VFX and music.
Screens used.

Conventions the scenes follow, all from the game as built (Docs/Writing/Dialogue.md):

Story state is integer flags, saved with the game; a flag never set reads 0. A stage flag never goes backwards: every set_flag on a stage is guarded with <<if flag(...) < n>>.
Node titles are <Act>_<Place>_<Beat> (Prologue_Steps_Lesson), so the Act 1 nodes are Act1_…. Each act's Yarn lives in Data/Dialogue/<Act>/.
Scene markers: Spawn_ (where the player arrives), Exit_ (a way out, with its sign), Event_ (a thing to tap or walk into), Mark_ (where an actor stands), Cam_ (a camera angle for <<camera>>). The overworld's walk-in markers are Walk_n; Act 1 adds Road_n.
Gates (VEL-53): interactables and triggers take if, unless, once and when; locations take actors and enter. A when uses the same JSON as a quest's completeWhen.
Screens are named as the game names them today: Title, Dialogue box, Choices, Tap prompt (the verb button: "Talk", "Go in", "Trace"), Exit sign, Quest log, Pause menu, Spell book, Cast prompt (<<prompt_cast>>), Trace lesson (<<learn_spell>>), Battle HUD, Battle result. New screens Act 1 needs are marked (Idea).