Command flow
When enter, mid-line, and exit command batches run on a dialogue node. Shared idea: Command flow (concept).
{
"id": "park",
"text": "Hello.{@c1} Nice day.",
"commands": [{ "type": "bg", "value": "street" }],
"flow_commands": [[{ "type": "sfx", "value": "click" }]],
"exit_commands": [{ "type": "char", "name": "hana", "show": false }],
"exit_delay": 0.5,
"next": "after"
}
Usually you need
| Surface | Type | Effect |
|---|---|---|
commands | array of commands | Run on enter (after set) |
flow_commands | array of batches | {@cN} runs batch N-1 while typing |
exit_commands | array of commands | Run on leave (advance or choice) |
exit_delay | number ≥ 0 | Seconds after exit_commands, before next node |
{@cN} | text tag | Trigger flow batch (1-based) |
Lifecycle order
| Step | What runs |
|---|---|
| 1 | Node set flags |
| 2 | Enter commands (top → bottom) |
| 3 | Line display / typing |
| 4 | Each {@cN} → that flow_commands batch (typing does not pause) |
| 5 | Continue / auto-advance / choice pick |
| 6 | exit_commands |
| 7 | exit_delay wait (if > 0) |
| 8 | Enter next node (next, choice target, or end) |
Leave also runs when the player picks a choice (exit, then the branch node).
Batch fields
| Key | Type | Default | Effect |
|---|---|---|---|
commands | array | — | Enter batch; omitted = no enter commands |
flow_commands | array | — | Each element is a command array (a batch) |
exit_commands | array | — | Leave batch |
exit_delay | number ≥ 0 | 0 | Wait after exit batch before advancing |
set | object | — | Flags applied on enter, before commands |
Related node timing (not command batches): auto / [auto N] — Node fields, Typing.
flow_commands shape
| Rule | Detail |
|---|---|
| Outer array | Slots indexed by {@cN} |
| Each slot | A command array (may hold several commands) |
{@c1} | flow_commands[0] |
| Missing slot | Warning; no run |
| Script sugar | Mid-line […] appends a one-command batch and inserts {@cN} |
"flow_commands": [
[{ "type": "sfx", "value": "click" }],
[
{ "type": "char", "name": "hana", "expression": "happy" },
{ "type": "sfx", "value": "whoosh" }
]
]
Text: "A.{@c1} B.{@c2} C."
Script forms
| Construct | Maps to |
|---|---|
[bg …] before spoken text | Enter commands |
[…] after text has started | New flow_commands slot + {@cN} in assembled text |
[exit: …] | Append to exit_commands |
[exit_delay N] | exit_delay |
[flag = …] | set (not a command) |
-> target | next (not a command) |
Full script map: script.txt syntax.
jump and batches
| Rule | Detail |
|---|---|
| When | After the current batch finishes |
| Winner | First jump / effective jump_if in that batch |
Enter jump | Leaves before the rest of the line plays |
Flow jump | Stops further typing on that line; transfers immediately |
Exit jump | Skips normal advance / choice target after the exit batch |
Linear next | Not a command — use only outside batches |
jump · jump_if · call · return.
Command meta when
| Field | Type | Effect |
|---|---|---|
when | expression | Skip that command if falsy / eval error; rest of batch continues |
JSON / Mode B overlay only — no [when …] in script.txt. Same expression language as next_if / expressions.
vs other conditionals
| Tool | Job |
|---|---|
Choice rules.show_if / disable_if | Menu option visibility / enable |
next_if / jump_if | Where the story goes |
Command when | Run or skip that side effect |
Cases
Conditional chrome (mutually exclusive packs):
{ "type": "choice_style", "profile": "choice_plain", "when": "chose_skin == \"plain\"" }
{ "type": "choice_style", "profile": "choice_button", "when": "chose_skin == \"textured\"" }
Conditional SFX / character / flags:
{ "type": "sfx", "value": "alarm", "when": "bomb_armed" }
{ "type": "char", "name": "rival", "show": true, "when": "rival_present" }
{ "type": "set_flag", "values": { "hint": true }, "when": "score < 3" }
Stop a timer only if it was armed (exit_commands or enter batch):
{ "type": "timer", "id": "bomb", "action": "stop", "when": "bomb_armed" }
Pick-item commands use the same meta (after item set, before target):
{
"text": "Take",
"target": "NEXT",
"commands": [
{ "type": "sfx", "value": "pickup", "when": "!quiet_mode" }
]
}
Mode B
Overlay commands are appended after script enter commands. Other batch keys follow normal overlay replace rules. Mode B.
Save note
During exit_delay (after exit commands, before the next node), a save uses the pre-exit snapshot so reload does not land mid-teardown. Save and session.
Related
- Command flow (concept) · Node fields · Flow tags
- script.txt syntax · Command API pages under sidebar Command API