Content blocks

Blocks inside a content layer (or nested scroll).

"blocks": [
  { "type": "heading", "text": "Audio" },
  { "bind": "bgm", "label": "Music", "label_key": "screen.settings.bgm_volume", "min": 0, "max": 1, "step": 0.05 },
  { "bind": "locale", "label": "Language", "label_key": "screen.settings.language", "style": "locale_button", "active_style": "locale_button_active" },
  { "type": "separator" },
  {
    "type": "table",
    "columns": [30, 70],
    "rows": [
      [
        { "type": "text", "text": "Go" },
        { "type": "button_row", "buttons": [{ "label": "A", "interaction": { "hooks": { "on_click": "close" } } }] }
      ]
    ]
  }
]

Usually you need

Type / shape	Role
`heading` / `text`	Copy
`bind`	Preference row — Widget bindings
`slider` / `toggle`	Free controls with hooks (not prefs)
`button` / `button_row`	Actions
`table`	Multi-row percent columns
`history`	Backlog log
`save_slots`	Manual save/load slot grid
`separator`	Rule — separator

Common fields

Key	Type	Effect
`type`	string	Block kind (required unless `bind` is set)
`bind`	string	Preference id — no `type` when set
`id`	string	Locale merge / identity
`style`	string pack	Element pack sugar
`source`	string	Pack compose
`show_if`	expression	Visibility
`interaction`	object	Hooks
`state_visual`	object	Per-state look

Types

`bind` (preference)

Key	Type	Effect
`bind`	string	Known preference id (`master`, `locale`, …)
`label` / `label_key`	string	When set → settings row (label \| control); omit → full-width control. Labels accept BBCode (`[b]`, `[color=…]`, …)
format / min / max / step / suffix	—	Slider display (when kind is slider)
`style` / `active_style`	pack ids	Locale chips

Do not set type on bind blocks; only listed keys are allowed.

`heading` / `text` / `link`

Key	Type	Effect
`text` / `text_key`	string	Copy. `text` blocks accept BBCode; `heading` is plain

`separator` / `spacer`

Theme separator supplies colour/height for separator. spacer is empty space (optional size fields via style/layout).

`image`

Key	Type	Effect
image path / texture fields	—	Displayed image
`align`	string	`left` \| `center` \| `right`

`button`

Key	Type	Effect
`label` / `label_key`	string	Caption
icon fields	path	Glyphs
`interaction.hooks`	object	Typically `on_click`

`button_row`

Key	Type	Effect
`buttons`	array	Explicit row buttons (required)
`style`	pack id	Default button pack
`align_h`	string	`left` \| `center` \| `right` (default `center`)

`slider` / `toggle` (free UI)

Key	Type	Effect
`label` / `label_key`	string	When set → settings-style row; omit → full width. Labels accept BBCode
`interaction.hooks`	object	Require `on_change` and/or `on_commit`
`min` / `max` / `step` / format fields	—	Slider only

Only listed keys are allowed — use bind for preferences.

`table`

Key	Type	Default	Effect
`columns`	number[2..6]	—	Percent weights; must sum to 100
`rows`	array of cell arrays	—	Each row length = `columns.length`
`align_h`	string or array	`left`	Cell default; array = per column
`align_v`	string	`center`	`top` \| `center` \| `bottom`
`spacing` / `row_gap`	int	—	Gaps

Cells are normal blocks (text, bind unlabeled, free controls, …). No nested table or scroll. Bind/slider/toggle inside cells must omit label/label_key (put copy in an adjacent cell). Empty {} or null = spacer. Cell blocks may override align_h / align_v.

`history`

Key	Type	Effect
`max_items`	int	Cap
`show_speaker` / `speaker_on_own_line` / `reverse_order`	bool	Layout
`empty_text` / `empty_text_key`	string	Empty state
colours / sizes / `item_separator`	—	Look

No interaction.hooks / state_visual on history.

`save_slots`

Early — not final UX. The slot grid works; layout, labels, and comfort (filters, previews, per-story views) are not polished yet.

Slot grid for opt-in save / load screens. Clicks emit save_slot:N or load_slot:N.

Key	Type	Default	Effect
`mode`	`"save"` \| `"load"`	`"save"`	Save writes a slot; load opens occupied compatible slots
`columns`	int	`3`	Buttons per row (1–6)
`style`	string	`"menu_button"`	Button theme prefix
`empty_label` / `empty_label_key`	string	`Slot {n} — Empty`	Empty cell; `{n}` = slot number (literal token, not a story flag)
`occupied_label` / `occupied_label_key`	string	`Slot {n} — {node}`	Occupied; `{n}`, `{node}`, and (multi-story) `{story}` / `{story_title}`
`spacing` / `row_gap`	int	`10`	Gaps

Slot count comes from session.save_slots (see Save and session). Empty load cells are disabled. No built-in save / load screens ship — build them yourself with this block, then point menus at screen:save / screen:load (immediate "save" / "load" stay slot 1).

`scroll`

Key	Type	Effect
`blocks`	array	Nested blocks (no nested `scroll`)
`height` or `height_percent`	number	Window height
`min_height` / `max_height` / `separation`	number	Clamps / gap

Widget bindings · Actions and hooks · Named button packs · Theme: card · settings_layout.

Keyboard shortcuts

VN-Mikro 0.1.0