Choices (story node)

A choice menu on a dialogue node. Script > lines compile into this object. Full presentation keys live here — the opening sketch is just the idea.

"choices": {
  "shuffle": false,
  "show_numbers": true,
  "style": "choice_button",
  "items": [
    {
      "text": "Take the key",
      "target": "vault",
      "set": { "has_key": true },
      "commands": [{ "type": "sfx", "value": "pickup" }]
    },
    { "text": "Leave", "target": "NEXT" }
  ]
}

Script sugar:

> Help her. -> help_branch
> Stay back. -> skip_branch
> Continue

Per-item set / commands are Mode B (JSON) only — not Mode A > sugar.

Usually you need

Key	Type	Default	Effect
`items`	array	—	Required. Choice entries
`style`	string or `{ "source" }`	game / `choice_style`	Button pack → `themes/<name>.json`
`shuffle`	bool	from `layout.choices` → `false`	Deterministic reshuffle. Forbidden when `mode` is `free`
`show_numbers`	bool	from layout → `true`	Prefix `N.` on captions
`container`	object	`{}`	Group layout / plate / host
`item`	object	`{}`	Defaults merged into every item

That covers stacked button menus. Floating sprite picks and full chrome are below.

All group keys

Key	Type	Default	Effect
`items`	array of objects	—	Choice entries
`container`	object	`{}`	Group presentation — container
`item`	object	`{}`	Defaults for each item root (`layout`, `style`, `interaction`, …)
`style`	string or `{ "source" }`	see precedence	Button element pack name. Empty `""` falls through to game
`source`	string	—	Pack compose → `themes/<name>.json`. Marks group pack-backed (sprite inheritance)
`shuffle`	bool	layout → `false`	Display shuffle. Forbidden with `free`
`show_numbers`	bool	layout → `true`	Number labels
`timer`	object	—	Optional countdown — Timed choices

Not allowed on the group root: gap (use container.layout.gap or layout.choices.gap), top-level layout / transition / shader / audio / interaction (those live under container).

Style name precedence (button groups): node choices.style → active choice_style → layout.choices.style. See Styling model.

Timed choices

Optional choices.timer starts when the menu is shown. A player pick cancels it. On timeout, either jump elsewhere or auto-pick an item (that item’s set / commands run).

"choices": {
  "timer": { "seconds": 8, "on_end": "too_slow" },
  "items": [
    { "text": "Defuse", "target": "safe" },
    { "text": "Run", "target": "hall" }
  ]
}

Auto-pick (uses the chosen item’s body):

"timer": { "seconds": 5, "on_end": { "pick": 0 } }

Key	Type	Default	Effect
`seconds`	number > 0	—	Required
`on_end`	string or `{ "pick": int }` or `{ "pick_id": string }`	—	Timeout jump, or auto-pick by source index / item `id`
`id`	string	`__choice_<node_id>`	Timer id (saved with the session)

Mode B only — no Mode A sugar for choices.timer. Background timers use the timer command.

Container

Allowed roots: layout, style, transition, shader, audio, interaction, source.

`container.layout`

Key	Type	Default	Effect
`mode`	`"stack"` \| `"free"`	`"stack"`	Stack = vertical list; free = absolute item `x`/`y`
`host`	`"panel"` \| `"overlay"`	`"panel"`	Sit in the panel choice slot vs full-screen overlay
`render_mode`	`"button"` \| `"sprite"`	`"button"`	Group-wide. Sprite uses item `style.sprite` faces
`anchor_h`	`"left"` \| `"center"` \| `"right"`	overlay: `"left"`	Overlay horizontal anchor
`anchor_v`	`"top"` \| `"center"` \| `"bottom"`	overlay: `"top"`	Overlay vertical anchor
`offset_x` / `offset_y`	number	`0`	Nudge the host
`x` / `y`	number	—	Absolute group position when used
`width` / `height`	number ≥ 0	—	Group plate size only (not items)
`min_width` / `min_height` / `max_width` / `max_height`	number ≥ 0	—	Plate clamps
`padding`	`{ left, top, right, bottom }`	`0`	Plate padding
`gap`	number ≥ 0	from `layout.choices.gap`	Stack item separation. Forbidden in `free`

Free vs stack

Rule	`stack`	`free`
Item placement	VBox + `align_h`	Absolute `x` / `y`
`container.layout.gap`	Allowed	Forbidden
`shuffle`	Allowed	Forbidden
Item `align_h`	Allowed	Forbidden
Item `x` / `y`	Forbidden	Allowed

Key	Type	Effect
`source`	string	Pack pull for the plate
`bg_color`	color string	Plate fill
`bg_texture`	texture spec	Plate texture
`border_color`	color string	Border colour
`border_width`	number	Border width
`corner_radius`	number	Corner radius
`layout` / `shader` / `interaction`	object	Nested same shapes as container roots

`container.transition`

Key	Type	Effect
`kind`	transition kind	Default kind
`duration`	number ≥ 0	Seconds
`on_show` / `on_hide`	transition kind	Enter / exit
`transition` / `transition_in` / `transition_out`	transition kind	Legacy aliases
`transition_duration`	number ≥ 0	Legacy duration

Kinds: instant, fade, slide_up, slide_down, slide_left, slide_right. Group-scoped only — not copied onto items. on_hide plays for host: "overlay"; a host: "panel" group leaves with the line change so the plate never keeps the old choice height. See Transitions.

`container.audio`

Key	Type	Effect
`on_show` / `on_hide`	string (sfx name)	Group show / hide sound

`container.interaction`

Key	Type	Effect
`focusable`	bool	Group focus hint
`hooks`	object	`on_show`, `on_hide` → action payloads
`hooks_override`	object	Override or clear hook payloads

Not copied onto items.

`container.shader`

Key	Type	Default	Effect
`name`	string	—	Shader stem
`params`	object	`{}`	Uniforms
`target`	`"bg"` \| `"full"`	`"bg"`	Apply target
`pass`	`"direct"` \| `"subviewport"`	`"subviewport"`	`full` + `direct` forbidden
`margin`	number or sides object	`0`	Expand host

`container.source`

String pack ref; deep-merged under the container.

Items

Each entry in items:

Key	Type	Default	Effect
`id`	string	`""`	Stable id (unique in the node); used by animate / `choice_item:…`
`text`	string	—	Caption. Need `text` or `text_key`
`text_key`	string	—	Catalog key (Localization)
`target`	string or omit	`NEXT`	Jump target — targets
`set`	object	—	Flags applied on pick before navigating (same as node `set`)
`commands`	array	—	Commands run after `set`, before enter `target`. No `jump` / `call` / `return` / story `input` — use `target` to navigate. Meta `when` skips individual pick commands the same as enter batches
`rules`	object	visible + enabled	Visibility
`layout`	object	from `item` / game	Item layout
`style`	object	from `item` / game	Item style
`transition`	object	—	Item enter / focus / confirm FX
`shader`	object	—	Same shader shape as container
`audio`	object	—	`on_focus` / `on_confirm` sfx names (prefer `on_confirm` for a one-off pick sound)
`interaction`	object	focusable true	Hooks, hotkey, hit_test
`state_visual`	object	—	Per-state look / animation
`source`	string	—	Per-item pack compose
`debug`	any	—	Passthrough

On pick

Menu node exit_commands (if any)
Item set
Item commands
Enter target → that node’s set → its enter commands

Omit target (or "NEXT") to continue to the next node after the menu. For a loop that re-shows the same menu without re-typing a line, use a menu-only node (empty text + choices) and point target back at that node — not at a say+choices node.

Rules

Key	Type	Effect
`show_if`	expression string	Hidden when falsy
`disable_if`	expression string	Shown but disabled when truthy

Item layout

Key	Type	Mode	Effect
`align_h`	`"left"` \| `"center"` \| `"right"`	stack only	Horizontal align
`x` / `y`	number	free only	Absolute position
`width` / `height`	number ≥ 0	both	Item size; omit in sprite for native face size
`rotation_degrees`	number	both	Rotation

Item style

Key	Type	Effect
`source`	string	Element pack pull
`text_color`	color string	Caption colour (sprite packs often transparent)
`icon` / `hover_icon` / `pressed_icon` / `focus_icon`	path string	Glyph + text; ignored when sprite theme applies
`icon_max_width`	number	Icon width cap
`sprite`	object	Only when group `render_mode` is `"sprite"`

`style.sprite`

Key	Type	Effect
`normal` / `hover` / `focus` / `pressed` / `disabled`	texture spec	State faces
`scale_mode`	`"stretch"` \| `"fit"` \| `"cover"` \| `"keep"`	Face scaling

Item transition

Key	Type	Effect
`kind` / `duration`	kind / number ≥ 0	Defaults
`on_show` / `on_focus` / `on_confirm`	transition kind	Event kinds

Item interaction

Key	Type	Default	Effect
`hotkey`	string	—	Custom action; not reserved (`choice_1`…`choice_5`, `choice_prev` / `next` / `cycle` / `confirm`, `dialogue_advance`); unique per node
`focusable`	bool	`true`	Focus eligibility
`hit_test`	`"rect"` \| `"alpha"` \| `"polygon"`	`"rect"`	Hit mode; `alpha` / `polygon` need sprite render
`hooks`	object	—	`on_show`, `on_focus`, `on_blur`, `on_confirm`, `on_hover_enter`, `on_hover_exit`
`hooks_override`	object	—	Override or clear payloads

Item `state_visual`

Key	Type	Effect
`normal` / `hover` / `focus` / `pressed` / `disabled`	entry object	Per-state look
`fallback_order`	string[]	Resolve order

Entry keys: source, shader (null to clear — unlike shader_params, which is kept when present), shader_params, animation or animations (not both). Animation keys: preset, property, to, from, duration (> 0), ease, trans, relative.

Targets

Keyword	Resolves to
`NEXT`	Node `next`, else next array node
`END`	Story end (`null`)
`START`	Pack entry node (`start` by default), else the first moment in the file

Omitted target = NEXT. Resolved at load. Avoid node ids named NEXT / END / START (keyword wins; warning). Name your opening moment :: start when New Game and START should agree — Scenes and jumps.

Sprite vs button inheritance

Condition	Inherits from `layout.choices`
`render_mode: "sprite"` without `choices.source`	No button chrome — author `container` + item `style.sprite` on the node
Sprite with `choices.source`	Pack supplies chrome; pack `item` is the item base
Either	`shuffle` / `show_numbers` / `gap` fallbacks still apply if unset on the node

Example pack: examples/example-05-ui-and-polish/themes/choice_yes_no.json (free + sprite + overlay).

Guide: Choices, Free choices, State visual, Styling model
Project defaults: layout.choices
Pack files: Choice packs
Runtime pack switch: choice_style
Start path: Choices and flags

VN-Mikro 0.1.0