quest'n'click 4.5.0 · r1

Built for quest'n'click 4.5.0, revision r1. Whether it is published, and which one is current, is recorded at publication.json.

Working with an AI

Français · Type: how-to · Audience: author · Context: engine repository, created project · Status: ready · Applies from: 4.2.5

quest'n'click is built to be written with an AI assistant: the game is data, every step has a tool that says whether it is right, and the human sees each change in the Studio. This page gives the method, the MCP server that hands the Studio's operations to any assistant, a typical session, the documentation search an agent uses, and how to split a big game between sub-agents.

What you get

An assistant (Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI, or an agent you wrote) that reads and edits your game the way the Studio does, checks its own work with the validator, the solver, the lint and the tests, and asks you through the notes when it should not guess. You watch the result live in npm run studio.

Context and versions

Prerequisites

Where to run the commands

On your machine, in the engine repository (or in the created project). The MCP client starts the server itself, with the repository as its working folder; you start the Studio in another terminal to watch.

The method

This is the method that produced the first game built with this engine: a 9-room, 15-character family adventure, written and shipped in a single day by one person working with Claude Code. Each step has a tool in this repository, and each step ends with something the author can validate on a phone before the next one starts.

StepWhat the AI doesWhat you validatePage
1. Story first, as datawrites games/<id>/storyboard.json (skill /storyboard)the story, the lines, the hintsThe storyboard
2. The storyboard on a pagenpm run page:storyboard, published so you annotate from a phoneyour notes under each panelReview pages
3. The artnpm run prompts, one prompt per sheetthe sheets you generateImages
4. Cut, key, reviewtools/cut-sheet.py, npm run page:reviewkeep / redo / unused per cellImages
5. The roomsone file per room (skill /new-room), then validate and solve—Rooms
6. Placementnever types coordinates: asks youyou drag in the Studio, ?edit=<room> or the placement pageGeometry
7. Prove it playsnpm test, npm run e2e, looks at the screenshotsa playthrough on your phoneChecking your game
8. Shipnpm run buildthe link you sendBuild and release a game

The rules an agent follows are those of AGENTS.md: content is data; logic in rooms/*.ts, geometry in layout/*.json; the storyboard changes first, then the room; after any content change, npm run validate && npm run solve && npm test with the output reported, not summed up; a screenshot looked at after any visual change; never delete an asset; a note in notes.json rather than a guess.

Steps

  1. Start the Studio, so you see what the agent changes.

    # in the engine repository, on your machine (created project: npm run studio)
npm run studio

  1. Connect your client to the MCP server. The command it runs is:

    # in the engine repository: what the client starts, over stdio
npm run -s mcp

    # in a created project: what the client starts, over stdio
npx quest-n-click mcp

    Keep -s (silent): without it, npm prints its > quest-n-click mcp banner on stdout, which carries the protocol only, and strict clients reject it. The server's own logs go to stderr; it says [quest-n-click mcp] ready: game "<id>" (<folder>) there. The per-client blocks are in Local MCP: setting up each client.

  1. Ask for the work, and let the agent run a session like the one below.
  1. Answer the agent in the Studio's Notes tab, or by editing the storyboard. It reads you back with get_notes.

What the MCP server is

npm run mcp starts a Model Context Protocol server over stdio, named quest-n-click, that exposes the Studio's operations (studio-server/src/ops/core.ts) as tools. Any MCP client then reads and edits a game exactly as the Studio does, and the human sees the result live in npm run studio, which watches the files.

Limit · screenshot-needs-dev-server screenshot renders through a running dev server (npm run studio or npm run dev, at WEB_SCUMM_DEV_URL, default http://localhost:5173/) and Playwright; without them it says why it is unavailable. A tool whose ability the backend lacks is not offered at all.

An AI without MCP

It still works. The AI edits the files; the Studio reloads (it watches them); the human sees the result and answers in Notes or in the Storyboard; the AI reads games/<id>/notes.json back. Git carries the history.

A typical session

  1. Learn the game and the format: list_rooms, get_storyboard, get_notes, and the documentation (below: search_docs then read_doc { id, section }; or, whole, read_doc { name: "CONTENT_GUIDE" }).
  2. Edit: set_storyboard first, then set_text / add_entity in the rooms.
  3. Check: validate, solve, lint, run_tests; screenshot if the human runs the Studio.
  4. Ask: add_note for anything the human must decide or place; read their answer with get_notes. Notes with task: true are requests the human wrote from the Studio's Assistant: the agent does them, then answers with add_note on the same about.

Finding the answer in the documentation

Applies from 4.5.0 · feature since 4.5.0

An agent does not need to read whole pages. search_docs { query } searches the pages of this wiki, in English or French: titles and questions first, then aliases, keywords and identifiers (a DSL command, an npm script, an HTTP code such as 423), then section headings, then section text. Accents and case do not matter, and the glossary adds the other language's words. Each result is id#section, with its title, type, context, versions and an excerpt: read it with read_doc { id, section } (lang en or fr, at most 20,000 characters per answer by default, a cursor for the rest). version leaves out what does not apply to that version. list_docs lists the pages by audience, context, type, language or state. With no confident match, search_docs gives an empty list and the index pages to try.

read_doc { name } still returns one of the eight historical pages whole: CONTENT_GUIDE, ENGINE, TOOLS, STUDIO, WORKFLOW, AUDIO, UPGRADING, CLASSICS. Give name or id, not both.

Publish a page and read the annotations back (Claude Code)

The review pages (npm run page:storyboard, page:review, page:placement) let the author annotate from a phone. With Claude Code:

  1. Build the page, then publish it with the Artifact tool, declaring the database: capabilities: { db: {} }. Republish to the same URL after each regeneration (same file path in the same session, or pass url): the database is kept across versions.
  2. Send the link to the author. Only people with edit rights (Contributor or more) can write.
  3. Read the annotations with the ArtifactData tool, action: "list", on the artifact's url:
    • storyboard: collection notes; answer by writing rewrites/<panel id> with { "text": "…" } (set);
    • review: collection decide; list the redo cells with their notes, one regeneration prompt per sheet;
    • placement: collection layouts; save the documents to a JSON file and import them.
  4. If the author used a plain file instead, they send the exported JSON: same content, read it directly.

The pages themselves: Review pages.

Working with sub-agents

For a game of several rooms, split the work into packages that an orchestrator hands to sub-agents: engine changes, content per group of rooms, assets, minigames, QA. The plan we used is the Production template; in the engine repository, the /production-plan skill fills it from the storyboard. Each package ends with validate + solve + tests + screenshots.

Expected result, and how to check it

The client lists the quest-n-click server with its tools. Ask it to call list_rooms: it answers with the game's id, title, hero, rooms, characters and items. An edit it makes shows in the Studio as soon as the file is written, and validate returns { ok, errors, warnings, ms }.

Common errors

SymptomCauseFix
The client says the server's output is not valid JSON, or drops the connection at startnpm run mcp without -s: npm's banner went to stdoutUse npm run -s mcp in the client's configuration
The agent edits another game than the one open in the StudioGAME differs between the two, or config.game changedGive the same GAME=<id> to the client's env and to the Studio
screenshot answers that it is unavailableNo dev server at WEB_SCUMM_DEV_URL, or Playwright's Chromium is not installedStart npm run studio; npx playwright install chromium
read_doc answers "give either name … or id, not both"Both name and id, or neitherGive one
read_doc { id } answers that reading by id needs the documentation of wiki/The backend it runs on has no documentation setRead the page on the wiki, or use name
An edit is taken back after the writeset_value validates the game after the write and undoes an edit that adds an errorRead the error it returns, fix the value

Files or data changed

What the tools write: games/<id>/rooms/<room>.ts (set_text, set_value, add_entity), games/<id>/layout/<room>.json (set_layout, add_entity), games/<id>/storyboard.json (set_storyboard), games/<id>/notes.json (add_note), the game file for its objectives (set_value on @game). screenshot writes a PNG under .cache/studio/. The other tools read only. Commit small, and review the diff the agent made.

Recovery or going back

Every write is a file change in your working copy: git diff shows it and git restore <file> takes it back.

References

Edit the source of this page · Report an error