input
After the line finishes, show a text field, write a flag, then advance. Hosted like choices (stack/free, panel/overlay, packs). Optional pattern gates confirm.
{
"id": "ask_name",
"text": "What should I call you?",
"input": {
"flag": "player_name",
"prompt": "Your name?",
"default": "Hero",
"max_length": 24,
"pattern": "^.+$",
"style": "name_entry",
"container": { "layout": { "mode": "stack", "host": "panel" } },
"field": { "layout": { "width": 480 } },
"confirm": { "label": "OK" }
},
"next": "after_name"
}
Script (before or after the line text):
:: ask_name
What is your name?
[input player_name]
:: ask_name_rich
What is your name?
[input player_name "Your name?" default "Hero" max_length 16]
:: ask_hint
What is your name?
[input player_name placeholder "Type a name…" pattern "^.+$"]
:: ask_prefill
What is your name?
[input player_name prefill "Hero" max_length 16]
:: ask_name_again
Edit your name.
[input player_name "Your name?" default "Hero" prefill_from_flag]
:: ask_age
How old are you?
[input age "Age?" pattern "^[0-9]+$"]
Put flag/prompt in the script; put free/overlay positions and rich chrome in story.json on the same node’s input (JSON merges over the script fields). Sticky pack override: input_style.
Usually you need
| Field | Type | Default | Effect |
|---|---|---|---|
flag | string | — | Destination flag (required) |
prompt | string | "" | Label above the field |
default | string | "" | Ghost text; empty Enter/OK uses this when there is no seed |
placeholder | string | "" | Ghost hint only (never submitted); used when default is empty |
prefill | string | "" | Editable text already in the field |
prefill_from_flag | bool | false | If the flag exists, seed from it (wins over prefill) |
max_length | number ≥ 1 | 32 | Clamp on submit |
pattern | string | — | Regular expression; fail keeps the field open (no flag write). Prefer ^…$ |
Ghost and seed
| Non-empty keys | Ghost in the field | Empty Enter/OK |
|---|---|---|
neither default nor placeholder | (none) | "" |
default only | default | default (when no seed) |
placeholder only | placeholder | "" |
| both | default wins | default (when no seed) |
| Seed source | Editable text | Clear field then Enter/OK |
|---|---|---|
| none | empty | see table above |
prefill | that string | "" (does not fall back to default) |
prefill_from_flag and flag exists | flag value (wins over prefill) | "" |
default, placeholder, and prefill support {flag} like dialogue lines (one pass). A flag seed from prefill_from_flag is used as stored.
All fields
| Field | Type | Default | Effect |
|---|---|---|---|
flag | string | — | Required |
prompt | string | "" | Prompt label |
default | string | "" | Ghost + empty-Enter fallback when no seed |
placeholder | string | "" | Ghost hint only |
prefill | string | "" | Authored editable seed |
prefill_from_flag | bool | false | Seed from existing flag when present |
max_length | number ≥ 1 | 32 | Clamp |
pattern | string | — | Confirm gate |
style | string | — | Pack under themes/ |
source | string | — | Compose pack (container / field / confirm / style) |
container | object | — | Host layout (same shape as choice containers) |
field | object | — | Text-field chrome / layout |
confirm | object | — | Confirm button (label, visible, layout) |
Timing and keys
- Appears after the line finishes. If the same node also has
choices, choices are shown instead. - Enter / Confirm → submit (strip + empty→
defaultwhen no seed + clamp;patternmay reject). - Esc → submit
""(nodefaultsubstitution). Ifpatternrejects empty, stay open. Pause does not open while the field is up. - Continue / Back are blocked while the field is open.
- After Back to this node, the field shows again with the same ghost/seed rules (
prefill_from_flaguses the flag if it is still set). - Confirm label:
confirm.label(defaultOK). Hide the button withconfirm.visible: false— Enter / Esc still work.
Validation
Encode rules in pattern (e.g. ^.{3,}$, ^[0-9]+$). Invalid pattern → warn and accept. Fail keeps the field open. Use jump_if for checks regex cannot express. Keep default / prefill values pattern-safe if you use pattern.
Precedence (chrome)
Node input.style → sticky input_style → layout.text_input.style → code fallbacks (no pack file required).
At show: node input overlays layout.text_input. Packs: Text input packs.
Save
The flag is written only after a successful confirm. Sticky input_style is session chrome.