When the script is not enough
Lives in: story/script.txt and (when needed) story/story.json
Most of a game stays in the script: speakers, lines, jumps, choices, and short stage directions. Add a direction file only when a moment needs more than brackets can say cleanly.
What the script is good at
| Job | In the script |
|---|---|
| Who speaks, what they say | HANA:, lines, (silent), joints |
| Simple stage | [bg …], [hana left], [bgm …] |
| Flow | :: id, ->, >, [if …] |
| Pacing | {@w}, {@cps=…}, [auto …], mid-line […] / {@cN} |
That is enough for a whole first draft — Writing your story.
When brackets get awkward
Reach for story/story.json when you need things like:
- An object or widget tied to a flag (a meter, a lamp)
- Choice menus with custom layout or look packs in detail
- Dense animation, shaders, or panel chrome on one beat
- A command that should run only if a condition is true (
when) - Something that sticks for the session, or lasts only this moment (
apply)
If you can say it in one clear bracket line, keep it in the script.
Three ways to work
| Way | Files | Use when |
|---|---|---|
| Script only | script.txt | Most games, most moments |
| Script + direction | script.txt + story.json | Dialogue in the script; heavy staging in data |
| Data only | story.json alone | Rare — whole story as data entries |
With script + direction, each direction entry matches a scene by id (the same name as :: park). Dialogue and jumps stay in the script; the data file adds or overrides what that moment needs.
Start in the script
- Write and play the scene as script.
- Give important moments a stable
:: id. - Only then add a
story.jsonpatch for the moments that need it.
Next: see one moment in both shapes — The same beat as data.