Adding direction to a script scene
Lives in: story/script.txt + story/story.json
Keep dialogue and flow in the script. Put precise staging in a direction entry with the same id.
Name the scene
:: park
HANA:
Watch the meter.
-> after
The :: park name is the link. Without a stable id, the direction file cannot find the moment.
Add a patch
story/story.json is a list of objects. Each object matches one script moment:
[
{
"id": "park",
"commands": [
{
"type": "obj",
"object": "meter",
"instance_id": "score_meter",
"show": true,
"x": 16,
"y": 16
}
]
}
]
How merge works
| Rule | Effect |
|---|---|
Match by id | Direction entry attaches to that script moment |
| Most fields | Direction replaces what the script had |
commands | Direction commands are appended after script brackets |
| Fields you omit | Script values stay |
So the line and HANA: stay in the script; the meter object is only in the direction file.
A worked meter / flag bind lives in the presentation examples under examples/ (search for story.json next to a script.txt).
When commands run
| When | Where you put them |
|---|---|
| Start of the moment | Script brackets, or commands in the direction entry |
| Middle of the text | Mid-line […] → {@cN} + flow_commands, or write those fields in direction / data |
| Leave the moment | exit_commands / exit_delay — fade or cleanup on the way out |
Everyday timing stays in the script: Pacing. Use direction when the mid-line or leave action is too heavy for a bracket. Batches and indexing: Command flow.
Choices and other overlays
You can also replace or flesh out choices, panel fields, auto, and similar on the matched id. Prefer replacing only what you must; leave speakers and text in the script when they are already clear.
Usually you need
| Want | Do |
|---|---|
| Extra staging on one beat | { "id": "…", "commands": [ … ] } |
| Keep script stage too | Rely on append — do not duplicate every [bg] |
| Whole new text | Put text in the direction entry (it replaces the script text) |
| Every command’s fields | Commands |