Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

screens.json — file map

Optional defaults, then screen ids you choose — any names you need. title, pause, settings, and hud are common starters, not a closed list. Every screen uses the same shape (documented below under the example id title). Copy from examples/ and change labels first.

The whole file

Keys with { … } open below. Linked names jump to that section. Grey notes say what each key does. Under each section, Keys lists type, If omitted, allowed values, and a short note.

{
  "defaults": { … },  // shared enter/exit fade for every screen that does not set its own
  "title": { … },     // example id only — use any name (`pause`, `credits`, `gallery`, …); every screen uses this shape
  "…": { … }          // any other screen ids you invent — same shape
}

defaults

Shared enter/exit fade for every screen that does not set its own.

{
  "defaults": {                 // shared enter/exit fade for every screen that does not set its own
    "transition_in": "fade",    // how screens appear
    "transition_out": "fade",   // how screens leave
    "transition_duration": 0.3  // fade/slide length
  }
}

Keys

transition_in enum
If omitted instant
Values instant · fade · slide_up · slide_down · slide_left · slide_right
Enter transition kind when a screen does not set its own.
transition_out enum
If omitted instant
Values instant · fade · slide_up · slide_down · slide_left · slide_right
Exit transition kind when a screen does not set its own.
transition_duration number
If omitted 0
Values seconds
Seconds for enter/exit when a screen does not set its own duration. 0 = instant.

Learn more: defaults

title

Example id only — use any name (pause, credits, gallery, …); every screen uses this shape.

{
  "title": {                                  // example id only — use any name (`pause`, `credits`, `gallery`, …); every screen uses this shape
    "role": "modal",                          // how the screen sits in the world
    "layers": [ {                             // ordered plates drawn bottom → top (required)
      "type": "menu",                         // what this layer is
      "order": 10,                            // draw order
      "layout": {"host": "screen", "anchor_h": "center", "anchor_v": "center"},  // where the layer sits
      "style": {"bg_color": "#101018"},       // look of this layer
      "buttons": [ {                          // menu layer only — the button column
        "label": "New Game",                  // caption
        "label_key": "screen.title.new_game",  // translated caption
        "interaction": {"hooks": {"on_click": "new_game"}},  // what the button does
        "show_if": "has_autosave",            // when to show
        "icon": "sprites/ico-pause.png"       // optional glyph
      } ],
      "blocks": [ {                           // content layer only — rows inside the card
        "type": "heading",                    // block kind
        "bind": "bgm",                        // settings preference id
        "label": "Music",                     // row caption
        "text": "Audio",                      // copy for heading/text
        "interaction": {"hooks": {"on_click": "close"}}  // hooks for buttons/controls
      } ],
      "items": [ {                            // sprites layer only — UI pictures
        "image": "ui/logo.png",               // picture path
        "interaction": {"hooks": {"on_click": "close"}}  // click / hover hooks
      } ],
      "interaction": {"hooks": {"on_click": "close"}},  // layer hooks (background / chrome)
      "modulate": "#ffffff",                  // layer tint
      "scale": 1.0                            // layer scale
    } ],
    "pauses_tree": false,                     // pause the game while open
    "transition_in": "fade",                  // this screen's enter
    "transition_out": "fade",                 // this screen's exit
    "transition_duration": 0.3,               // this screen's fade length
    "interaction": {},                        // screen-level hooks
    "shader": {},                             // screen shader
    "action_context": "",                     // hook allowlist context
    "modulate": "#ffffff",                    // whole-screen tint
    "scale": 1.0,                             // whole-screen scale
    "plane": "",                              // draw plane override
    "persistent": false,                      // stay when others stack
    "input_passthrough": false                // clicks pass empty areas
  }
}

Keys

role enum
If omitted modal
Values modal · hud · scene
modal = full menu (default). hud = stays up during play. scene = under characters.
layers[].type enum
If omitted required on each layer
Values background · menu · content · sprites · chrome
background plate · menu button column · content card of blocks · sprites UI pictures · chrome extra controls (e.g. Close).
layers[].order number
If omitted draw order 0
Higher draws above. Also used when merging locale overlays.
layers[].layout object
If omitted theme / type defaults
Placement. Menu often uses host: screen or panel (dock to dialogue box).
layers[].style object
If omitted theme defaults
Colours / textures for the plate. May include source pack compose.
layers[].buttons[].label string
If omitted empty / icon-only
Button text. Prefer label_key when translating.
layers[].buttons[].label_key string
If omitted use label
Catalog key for the caption.
layers[].buttons[].interaction object
If omitted required for a working button
hooks.on_click is a verb string (new_game, close, screen:pause), a command object, or an array of those.
layers[].buttons[].show_if string
If omitted always show
Hide unless a condition is true (e.g. has_autosave for Continue).
layers[].buttons[].icon path
If omitted text-only button
Image path for an icon button (common on HUD).
layers[].blocks[].type enum
If omitted required unless bind is set
Values heading · text · separator · link · spacer · image · button · button_row · slider · toggle · history · save_slots · scroll · table
Omit type when using preference bind instead. Common: heading, bind (as field), history, save_slots.
layers[].blocks[].bind string
If omitted not a preference row
Values master · bgm · sfx · typing_enabled · typing_speed_scale · auto_advance_default · locale · …
Preference row (volume, language, …). Do not set type when bind is set.
layers[].blocks[].label string
If omitted full-width control / no caption
When set with bind, builds a settings row (label | control).
layers[].blocks[].text string
If omitted use text_key or none
text / heading body. text accepts BBCode.
layers[].blocks[].interaction object
If omitted none
Same action payload shapes as menu buttons.
layers[].items[].image path
If omitted depends on sprite kind
For kind: image sprites.
layers[].items[].interaction object
If omitted decorative only
Optional interaction on a UI sprite.
layers[].interaction object
If omitted none
Background often uses on_click: close for click-outside. Chrome uses the same hook shape.
layers[].modulate color
If omitted no tint
Colour multiply for the whole layer.
layers[].scale number
If omitted 1
Scale for the layer (number or [x,y]).
pauses_tree bool
If omitted false
Values true · false
When true, the story/world pauses (typical for pause). HUD screens never pause.
transition_in enum
If omitted use defaults
Values instant · fade · slide_up · slide_down · slide_left · slide_right
Overrides defaults.transition_in for this screen only.
transition_out enum
If omitted use defaults
Values instant · fade · slide_up · slide_down · slide_left · slide_right
Overrides defaults.transition_out.
transition_duration number
If omitted use defaults
Values seconds
Overrides defaults.transition_duration.
interaction object
If omitted none
Rare. Prefer hooks on layers / buttons.
shader object
If omitted none
Optional fullscreen/bg shader while this screen is up — [Shaders](../../polish/shaders.md).
action_context string
If omitted from role / built-in
Advanced: which action policy context this screen uses.
modulate color
If omitted no tint
Colour multiply for the screen root.
scale number
If omitted 1
Scale for the screen root.
plane string
If omitted from role
Advanced. Prefer role.
persistent bool
If omitted from role (hud is persistent)
Advanced. HUD role already implies persistence.
input_passthrough bool
If omitted from role (hud passes through)
Advanced. HUD role passes input through empty space by default.

Learn more: title