Scenes and jumps

Lives in: story/script.txt

Name moments and move between them so the story can branch and meet again.

Name a scene

:: park
HANA:
We're here.

:: park sets this moment’s id to park. Use letters, numbers, and underscores. Every jump target must match an id (or the special end).

If you omit ::, the player still builds a moment — it just has no stable name to jump to. Named scenes are how you build routes.

Where New Game starts

New Game looks for a moment named start (JSON: "id": "start"). In the script that is:

:: start
[bg street fade 0.5]
HANA:
Good morning.

You can omit :: start. The player then uses the first moment in the file. Small examples do that on purpose. Name it when you care about a stable entry (saves, jumps to START, or a pack that sets a different entry).

For several stories in one project, each pack can set its own entry id with stories[].start — Several stories.

Jump

-> park

alone on a line (or after text in some setups) sets where to go when this moment finishes. Common pattern:

HANA:
Let's go.
-> park

End the story

-> END

Ends play (then credits / title follow your session settings — Save, Back and story end).

Branch and merge

:: choice
> Left path. -> left
> Right path. -> right

:: left
HANA:
Left.
-> after

:: right
HANA:
Right.
-> after

:: after
HANA:
Both roads meet here.

Both branches jump to the same after moment. That is how routes rejoin.

Visit a beat and come back

For a reusable insert (a menu of facts, a short cutaway), use call and return:

[call encyclopedia]

…and at the end of that scene:

[return]

call remembers where you were; return goes back. Prefer plain -> for normal story flow; reserve call/return for side visits.

Conditional jump

[if helped -> thank_you]

If the expression is true, go there instead of the normal next moment. Expressions use flag names and && / || / ! — Choices and memory.

Order tips

• Give every important moment a :: id early — renaming later can break old saves.
• Keep merge points (:: after) obvious in the file.
• One -> per moment for the default exit; choices carry their own targets.

Usually you need

Next

Choices and memory

Try examples/example-02-choices-and-flags/story/script.txt.