Title, pause and settings screens
Lives in: screens.json
Menus and boards around the story — title, pause, settings, credits, custom galleries. Separate from the dialogue panel and from stage sprites.
Most stories
| Screen | Role | Job |
|---|---|---|
title | modal | New Game, Continue, Settings, Quit |
pause | modal (often pauses the tree) | Resume, save/load, settings, title |
settings | modal | Volume, text speed, and similar rows |
hud | hud | Pause button (and friends) while playing |
{
"defaults": { "transition_duration": 0.3 },
"title": {
"role": "modal",
"layers": [
{ "type": "background", "order": 0 },
{
"type": "menu",
"order": 10,
"buttons": [
{ "label": "New Game", "interaction": { "hooks": { "on_click": "new_game" } } },
{ "label": "Continue", "interaction": { "hooks": { "on_click": "continue" } }, "show_if": "has_autosave" }
]
}
]
}
}
Copy a working screens.json from examples/ and change labels first — Your first ten minutes.
Full map
Every allowed key in one view: screens.json file map. Layers, blocks, and actions: Screens detail.
Roles
| Role | Effect |
|---|---|
modal (default) | Full menu; blocks the world; not persistent |
hud | Stays up during play; never pauses; input passes through by default |
scene | Under characters (special boards) |
Auto HUD id comes from game.json → session.hud_screen (default "hud"; "" turns it off) — Save, Back and story end.
Layers
Each screen is a list of layers drawn in order:
type | Job |
|---|---|
background | Full-rect plate / dimmer (often click-outside → close) |
menu | Button column (title, pause, HUD) |
content | Card of blocks (text, sliders, history, save slots, …) |
sprites | Anchored UI pictures with optional hooks |
chrome | Extra controls (Close), often docked to a content card |
Open and close
| From | How |
|---|---|
| Button / hook | interaction.hooks.on_click holds the action: new_game, screen:pause, close, … |
| Story | { "type": "screen", "value": "pause" } · "show": false to remove · "mode": "replace" |
Screens stack. Top modal usually owns input; HUDs can stay underneath. Return to title clears persistent HUD strips.
show_if on buttons (and some blocks) hides them unless a condition is true — e.g. "has_autosave".
Save / load and history
Slot UI and history logs are content blocks inside your screens. Slot count is session.save_slots — Save, Back and story end. Polished slot chrome is still early — In development.
Usually you need
| Want | Do |
|---|---|
| Change title buttons | Edit screens.json → title menu labels / actions |
| Pause from HUD | HUD button "screen:pause" — Gameplay HUD |
| Open a board mid-story | screen command with that id |