FolioTier 1

scene-flow

Scene structure, routing arrows, and the vocabulary that moves a story between scenes.

Reference page — scene flow isn't a verb. This page collects the shape of a Folio scene file and the routing vocabulary that connects scenes together.

Scene file shape

Every scene starts with a header — label <id> "<title>" — followed by a next -> <target> that names the scene the runtime falls through to after the last block runs. Everything between them is the scene body.

label kitchen-morning "Kitchen, morning"
next -> hallway-meet

bg bg-kitchen-morning
say "Emma": "Morning, sleepyhead."

Scene IDs are kebab-case (kitchen-morning); the importer rewrites Ren'Py's snake_case labels (kitchen_morning) at import time. The title is a quoted display name surfaced in the node editor and the migration report — it never appears in the player runtime.

Routing vocabulary

Folio names every routing arrow with ->. Five verbs participate in scene-level routing:

| Verb | Form | What it does | |---|---|---| | next | next -> <target> | Implicit fall-through after the last block in a scene | | jump | jump <target> | Unconditional transfer — never returns | | call | call <target> | Jump-with-return — the called scene runs, then return brings execution back | | if | if <cond> -> <a> else -> <b> | Two-way branch on a state expression | | choice | option "<label>" -> <target> (per child line) | Player-driven branch — each option carries its own arrow |

Each routing target is a scene ID or the literal end. There is no "fall through to the next definition in file order" — every transfer is named.

End-points

Two verbs end execution explicitly:

  • end — terminates the story branch. The player runtime treats this as a "you reached an ending" marker.
  • return — pops a call frame. Returning from the top-level scene is equivalent to end.

next -> end and option "..." -> end are common — they mark a branch terminus without a named exit scene.

Conditional tails

Most verbs (including the routing ones) carry an optional if <cond> tail. A conditional jump if <cond> is a common shorthand for the two-way if <cond> -> <jump-target> else -> <fallthrough> shape when the false target is the next block in source order. Use the explicit two-arrow if for clarity in the node editor; reserve the tail form for narrow guards on side-effecting verbs (set love = love + 1 if emma-route).

Importer translation

The Ren'Py shapes lower predictably:

| Ren'Py | Folio | |---|---| | label scene_one:
... | label scene-one "Scene one"
next -> ... | | jump scene_two | jump scene-two | | call scene_subroutine
return | call scene-subroutine
(implicit return in callee scene) | | menu:
"Pick":
jump branch_a | choice:
option "Pick" -> branch-a | | if love >= 5:
jump good_route
else:
jump neutral_route | if love >= 5 -> good-route else -> neutral-route |

Menus with embedded code (Python in option bodies, set between options, non-jump terminal lines) lower into a choice plus a small per-option scene that runs the body before the routing — these surface in the migration report's per-fragment review.

See also

  • jump — unconditional transfer
  • call — jump-with-return
  • if — conditional branch with named targets
  • choice — player-driven branch
  • return — pop a call frame
  • end — terminate a branch