Skip to content
quest'n'click

CreateExplanationFor authorsApplies from 4.3.0

Content principles and the identity contract

Cette page en françaisThis page on the GitHub wiki

Why a quest'n'click game is written as data, why its geometry lives in a separate file, and why everything a save remembers carries a stable id.

Writing the game content

This page and the other "Create a game" pages are for whoever writes the story: the rooms, the lines, the puzzles. They describe the format the engine reads. You never need to touch the engine (src/engine/): the whole game lives in one folder, games/<id>/ in the engine repository, game/ in a project made with quest-n-click create (layout of both).

The full types, with their comments, are in src/engine/core/types.ts, which re-exports the files of src/engine/core/types/ (split by subject in 4.1.0). Your editor offers them as autocomplete. The generated DSL reference lists every command and condition.

These pages replace the old docs/en/CONTENT_GUIDE.md, split by question. Since the 4.5 switch-over, that old file is a transition page: it keeps every old anchor, each old heading links to its new destinations here, and a fallback link to blob/v4.4.0/docs/en/CONTENT_GUIDE.md always works.

The principles

  1. Content, not code. The content is made of data: objects, lists, texts. No functions. That is what lets the engine check the game on its own (npm run validate) and prove it can be finished (npm run solve).
  2. Logic on one side, geometry on the other. You write what happens in rooms/<room>.ts. Where things are (clickable rectangles, character positions, the walkable area) lives in layout/<room>.json, placed with the mouse in the placement editor (npm run dev, then ?edit=<room>) or in the Studio. You never type coordinates by hand, except for a one-off scripted move (geometry).
  3. Nothing is a dead end. Every action gets a response. With no written reaction, the engine answers with the game's fallback responses (reactions).
  4. Logical coordinates. A backdrop measures 640 × 400, origin top-left. A character is placed by its feet.

The v3 identity contract

New games set schemaVersion: 3 in game.ts (the template does). Anything whose execution position survives in a save has an explicit, unique id: every Rule, TalkTopic, Choice, EventRule, and every once, nth, cycle or random block. A ScriptDef already has an id and adds one stepIds entry per top-level command. The validator rejects a v3 game with a missing or duplicate id (… requires a stable "id" in schema v3, duplicate stable id "…", schema v3 script needs one stable step id per command). Reordering content or translating a text therefore does not change the meaning of a save.

schemaVersion: 3,
// …
{ id: 'open.pantry', verb: 'open', a: 'pantry', do: […] }
{ id: 'ask.key', topic: 'Where is the key?', do: […] }
{ once: […], id: 'arrival.first' }
{ id: 'clock', stepIds: ['wait', 'chime'], do: [{ wait: 1000 }, { sfx: 'chime' }] }

Lines can carry ids too ({ say: [...], id }, { id, text } in a list): translations and voice clips then follow the id, not the line's position (npm run ids -- --lines).

npm run ids -- --write --map writes those ids into an existing game, with the migration step its saves need; how to rename an id later without breaking saves is on state and saves. compileGame(source) (src/engine/core/define.ts) clones and normalises the authoring source once; a v3 result is frozen, so a tool that tries to change it fails at once. The engine, the validator, the solver, the replay and the puzzle tools all consume that same compiled representation. Read the v2 → v3 upgrade notes before converting an existing game.

Why

A game has to be checked, saved, translated, compared between two revisions, edited by the Studio and an assistant, and proved finishable by a machine. A function inside the content can do none of that: no tool can read what it does without running it. Data can be read by all of them. The solver even runs the real engine on that data, so what it proves, a player can do (what the solver proves).

Geometry is apart because it is edited differently (with the mouse, against the picture) and changes for different reasons (a new backdrop moves every rectangle, not a single rule).

Alternatives set aside

  • Scripts in a general-purpose language (callbacks in the content): flexible, but the validator, the solver, the Studio and the translation tools would lose sight of the game.
  • Ids by position (the schema 2 rule: a topic is <room>.<actor>.<index>): no work for the author, but inserting a topic or translating a text shifted what an old save meant. Schema 3 made the ids explicit.

Trade-offs

Some ideas take a custom command instead of three lines of code, and the DSL grows slowly, one primitive per real need. Writing ids is extra work; npm run ids -- --write does most of it.

Decisions and ADRs