Checking your game

Four commands tell you most of what is wrong with a game before anyone plays it: validate checks the content, solve finds a way to the ending, lint reads the puzzle graph for what a player would trip on, and solve --prove proves that no player can get stuck. Then the game is played for real: by a scripted walkthrough, in a browser, on a phone, and by a person.

What you get

A game whose references all resolve, that can be finished from "New game", whose softlocks are ruled out by an exhaustive proof, and whose remaining warnings you have read and either fixed or kept on purpose. At the end, the checklist Before you share the link.

Context and versions

• The engine repository (a clone of quest-n-click, to work on the engine or its sample games): the commands are npm scripts, npm run validate. The game is GAME=<id>, otherwise config.game of package.json.
• A created project (made by npx quest-n-click create): the commands are quest-n-click subcommands, npx quest-n-click validate, and the project's scripts npm run verify, npm run build, npm run release. The game is game/.
• This page describes 4.3.0 and later (the lint's hero-looks-default arrived in 4.3.0). The status of a solver run is the same since 3.3.

Prerequisites

• The engine installed: Install from the repository or a created project (Your first game).
• A game with at least one room. The working loop is in The working loop.

Where to run the commands

On your machine, at the root of the folder:

In the engine repository, options go after -- (npm run solve -- --prove); with npx quest-n-click they follow the subcommand directly.

Steps

1. Validate the content.

   # in the engine repository
   npm run validate
   # in a created project
   npx quest-n-click validate

   copy

   Everything referenced exists, every visible thing has a Look line, texts are neither empty nor too long, flags are set and read. Exit 1 on an error. What it checks is listed in What each check looks at.

2. Find a way to the ending.

   # in the engine repository
   npm run solve
   # in a created project
   npx quest-n-click solve

   copy

   It prints ✔ The game can be finished, the path, and three warnings to read: dead ends, items obtained but never used, items never obtained (the warnings). A winning path is not a proof.

3. Lint the content.

   # in the engine repository
   npm run lint
   # in a created project
   npx quest-n-click lint

   copy

   Conditions nothing can satisfy, rules another rule hides, red herrings, hints that cannot fire, actions the solver never ran. Fix each finding, or keep it on purpose in game.ts (lint.ignore, below).

4. Prove there is no softlock.

   # in the engine repository: the global proof, the proof by chapters, every Reality world
   npm run prove:game
   # in a created project
   npx quest-n-click solve --prove

   copy

   Only a solved from --prove rules out softlocks. A truncated result proves nothing: raise the budget (Solver options).

5. Play it for real. A scripted walkthrough and the browser e2e (Prove it plays), a real phone in landscape (Testing on a phone over the LAN), then a person who has never seen the game (Playtests).

6. Go through the checklist Before you share the link.

What each check looks at

• Validated. Broken references, unreachable rooms and untranslated lines are found before anyone plays. validate checks shapes and references: everything referenced exists, every visible thing has a Look line, texts are not empty or too long, flags are set and read. It warns about rooms nothing leads to and declared exits with no way back (oneWay: true when intended). It checks each minigame's required parameters (required), the images cited in their params, every skin id (manifest images, audio sounds) and ending.scratch, and that a required Reality signal's fallback names a rule.

• Solved. The solver runs the real engine, with no second model of the content. solve asks for a witness, a path to an ending; solve --prove explores every reachable state and fails on a softlock or a truncated search. These are two different promises, and a release asks for the second (What the solver proves). solve also reports the invariants (GameDef.invariants) that became true, with their path.

• Linted. lint says what validate cannot (it checks shapes and references) and what solve does not say loudly (it answers "can it be finished"). From the puzzle graph:

  • a condition nothing sets (cond-never-true, an error);
  • a rule another rule matches first (rule-shadowed);
  • an item no rule needs (item-red-herring) or nothing gives (item-never-gained);
  • a hint that waits for something nothing sets (hint-stuck, an error), or that shares its until with an earlier hint (hint-never-fires);
  • a dead topic, choice option or listener; a choice with one option; an exit with a condition and no locked line;
  • an action that only changes what nothing live reads (action-dead, info; a flag a character's variant or a text switch reads is not counted as nothing, so the intro's choice of the hero is not reported);
  • two or more values of the hero's flag that no hero variant matches, so those heroes look like the written one (hero-looks-default, info, 4.3.0; see Heroes);
  • a target behind a walk link a condition closes, whose rule does not check that condition (walk-link-gate: the link stops the walk, never the action).

  After a solver run, also: a required signal's fallback the closed witness never plays (fallback-unplayed, a warning); a live action the witness never ran and a room it never entered (rule-never-run, room-never-reached: information with the witness, warnings with a completed --prove; a truncated proof keeps them as information and says so, it never calls anything unreachable); a live action that ran without ever changing the state (rule-no-effect, info: a topic that only talks, or a set already true). Reachability counts every try the solver made, whether or not it changed the state.

  Each finding names its room and path (the one the Studio's Rooms tab shows), its stable id, and what to do. Exit codes: 0 clean, 1 an error that is not ignored, 2 the search was truncated (--json carries status and truncated). --prove runs the exhaustive search first (slow on a big game), --static runs no solver at all, --max=<n> sets the search's budget (20 000). The Studio's Check tab shows the same list with links into Rooms; the lint MCP tool returns it as Markdown. verify:game runs it, so does CI.

• Replayed. A session is the unit of reproduction (Playtests); saves load across versions, with one frozen save per release from 3.0.0 on (State and saves).

• Accessible as far as a machine can tell. axe-core on every screen, keyboard and touch play in CI. That is not a WCAG conformance claim: screen-reader and real-device passes are a person's to make (Accessibility, Field passes).

Keeping a finding on purpose. A red herring you want, or a decorative flag (set, never read), is silenced in game.ts; the same list keeps flag-never-read:<flag> out of validate's warnings:

lint: { ignore: ['item-red-herring:rubber_chicken', 'rule-shadowed:house/on[4]'] },   // a code, `code:<id>` or `code:<room>/<path>`

ui.shareSession names the pause menu's row that sends a playtest from a phone (Playtests).

Commands

Every command below runs in the engine repository with npm run. The second column gives the created project's equivalent when there is one; "—" means the created project has none.

The game's content

The game's gates

The engine repository's own checks

In a browser (engine repository; the dev server or a production build already running at <url>)

Documentation and repository tooling (engine repository)

Prove it plays

In the engine repository, npm test runs the engine tests and the game's walkthrough: a scripted full playthrough on the real engine (tests/demo-walkthrough.test.ts for the demo). npm run e2e plays the whole game by touch in a phone-sized Chromium and saves a screenshot of every step: look at them, or have your assistant look, to catch what the solver cannot see (a character standing on a table, a line cut by the screen edge).

# in the engine repository: start the dev server, then in another terminal
npm run dev
npm run e2e -- http://localhost:5173/

npm run e2e takes the solver's path (npm run solve -- --json, its steps) and taps through it. It passes only when the solver's run is solved (its exit code, status and steps are checked) and the engine itself reports the ending (state.done): a truncated or unsolved game is a failure, never "the best path replayed anyway". games/demo/e2e.mjs is the example of a game-specific e2e script: it starts from the title screen, plays the pipes and pick minigames and the sealed ending's scratch ticket for real instead of skipping them, then checks the final card.

In CI (the engine repository's .github/workflows/ci.yml): every push to main, every tag and every pull request runs npm run build:game (the game's gates, the bundle, the spoiler and asset audits) and npm run prove:game on the sample game; the heavier jobs (the production e2e in several browsers, the keyboard and French playthroughs, a second game made from the template…) run when ci:plan says the change needs them. main deploys to Pages; a tag releases. The weekly prove workflow (Mondays, or by hand) runs prove:game, the strict playtests and the bench on a generated 100-room game. Dependabot proposes npm and Actions updates weekly, pip ones monthly (Bot PRs).

Before you share the link

• Premise, want, obstacle per room and ending fit in four lines.
• The storyboard is final, and every room text comes from it.
• Each room has one goal, 3 to 6 steps, one "aha", 8 to 15 named things.
• Every named thing has a Look line; repeated looks follow normal, normal, normal, absurd.
• Each character has 2 to 4 topics, a hug, a refuse and a distinct colour.
• Each verb has 3 to 6 fallbacks in the hero's voice. No "That doesn't work".
• Hints cover every step of every room, in order, until the ending.
• Every minigame has a reason in the story, a Skip, and lasts about 30 seconds.
• The map shows only unlocked places; news markers point to the next step.
• Every state change has a sound.
• No line over 90 characters.
• validate: no errors. solve: finished, no dead ends, no unused items. solve --prove: solved.
• Engine repository: npm test and npm run e2e pass; screenshots reviewed.
• Played start to end on a real phone, in landscape.
• Sealed ending checked with npm run check:spoilers (The sealed ending).
• Someone else played it without help (Playtests).

Then build and ship it: Build and release a game.

Expected result, and how to check it

• validate: its last line starts with ✔ [<game>] and counts the rooms, items and characters; exit 0. Warnings (⚠) do not fail it. "(images not checked: run npm run assets)" means the images were not checked.
• solve: ✔ The game can be finished and ✔ Witness solved: …, exit 0.
• solve --prove: ✔ Proof solved: the ending stays reachable from every one of the N reachable states, exit 0.
• lint: exit 0; the findings left are information, or ignored on purpose.

The exit code is the verdict: 0 passed, 1 a problem to fix, 2 the search was truncated and nothing is proved.

Common errors

Files or data changed

The checks only read your game. What they write: .cache/proofs/ (the proof cache), and the folders you name with --out. npm run e2e writes its screenshots to E2E_OUT (default /tmp/e2e). validate --report prints to the terminal; page:world and page:puzzles write their page under dist-pages/ (or --out <dir|file.html>). ids --write and provenance --lock are the exceptions that change files you commit: they are not checks, and they say so.

Recovery or going back

Nothing to undo: a check does not change the game. To start from a clean slate, delete .cache/proofs/.

References

• tools/validate.ts, tools/solve.ts, tools/lint.ts, cli/quest-n-click.mjs
• What the solver proves, Solver options, Playtests
• The Studio's Check tab, MCP tools
• npm scripts, CLIs