Skip to content
quest'n'click

StudioHow-toFor authorsApplies from 4.2.1

Storyboard

Cette page en françaisThis page on the GitHub wiki

The Storyboard tab edits storyboard.json, the script of the game, board by board and panel by panel, shows each panel the way the game would stage it, and says what of it the game already does.

What you get

A games/<id>/storyboard.json written by the Studio, each panel previewed as a frame, a coverage badge on every board and panel, and, if you want, a storyboard.md to read or share.

Context and versions

The local Studio, in the engine repository or a created project; the demo Studio too (its edits stay in the browser). True from 4.2.1. Why the storyboard is the source of truth, and how it relates to the content: The storyboard, source of truth.

Prerequisites

Where to run the commands

In the browser, on the Studio's Storyboard tab. The optional command line export runs in the engine repository.

Steps

  1. Boards. On the left, the boards (title, room, goal), with move up, move down, add and delete.
  1. The selected board, in the middle: title, id, room ("Open in Rooms" switches to that room), goal, exit, its arrival lines, then its panels as cards in play order. A panel has a title, an id, the player action that triggers it, and lines with a speaker chooser (the game's characters, hero, action, stage) and sfx chips taken from the game's audio.sfx. Per line: move, delete, "+ line". Per card: move, duplicate, delete. Then the board's hints (ordered), the talk topics per character (topic and lines) and the optional reactions (action and lines).
  1. The frame, on the right: the selected panel composed like a storyboard frame, with the room's decor, the portraits of the panel's speakers (the one speaking highlighted), the current line in the game's speech style (the speaker's colour; step through the lines, or click one in the script below), the action as the game's sentence bar, and the sfx. Under it, the notes about this panel (about = the panel id) and a box to add one (Notes).
  1. Save. Every edit stays in memory until Save (or Ctrl/Cmd+S while the tab is shown) writes the whole document. "● Unsaved changes" shows until then, and leaving the page asks first. Save refuses duplicate or empty panel ids, because notes hang on them. An unchanged storyboard is not rewritten; a changed one is written compactly (what fits on 120 columns stays on one line).
  1. Read the coverage. After every load and save, the saved storyboard is checked against the content (src/engine/tools/coverage.ts): a badge on each board and panel, ✓ everything is in the game, ~ partly, ✗ something is missing, ? prose. Under a panel, the list of what is not there yet: an action no rule answers, a line the game does not say, a sound not in audio.sfx. The bar shows the overall score. The same check is in the Check tab ("Storyboard coverage") and is the storyboard_coverage MCP tool.

  1. Export Markdown writes games/<id>/storyboard.md from the saved file; it offers to save first. The same text comes from the command line:

    # in the engine repository
npm run page:storyboard -- --md

Expected result, and how to check it

"● Unsaved changes" disappears after Save; git diff games/<id>/storyboard.json shows your change; the badges turn ✓ as the content catches up with the script.

Common errors

SymptomCauseFix
Save refused: a panel id is empty or used twiceNotes hang on panel idsGive each panel a unique id
A banner says the file changed on diskAn AI, an editor or git wrote itReload, or save knowingly over it
Export Markdown answers 404No storyboard.json saved yetSave first
✗ under a panelThe game does not do it yetWrite the rule, line or sound it names

Files or data changed

games/<id>/storyboard.json; games/<id>/storyboard.md on export; games/<id>/notes.json for panel notes.

Recovery or going back

The header's Undo does not cover the storyboard (nor the notes): a Save is a journal operation, but not an undoable one. Go back with git: git checkout -- games/<id>/storyboard.json.

References