Package reference
Français · Type: reference · Audience: author, contributor · Context: engine repository, created project · Status: ready · Applies from: 4.3.0
What the engine's npm packages hold, the commands the quest-n-click package gives a game project, and how each
release checks them. scripts/pack.mjs makes them from the files git tracks; installing them is on
Install from the release archive.
The engine as a package
Since 3.9 a game does not have to live in the engine repository. The engine is packed as quest-n-click (the engine,
its pages, its tools and the quest-n-click command, the game template), create-quest-n-click
(npx create-quest-n-click) and, since 4.1.1, quest-n-click-bridge (the reference Reality Bridge). Since 4.1.9 the
connectors are a fourth package, quest-n-click-connectors, and since 4.2.1 the hosted Studio is a fifth,
quest-n-click-studio-server.
Until 4.2.4 these were web-scumm, create-web-scumm, web-scumm-bridge, web-scumm-connectors and
web-scumm-studio-server (the project was called web-scumm, D47). Through 4.2.x each release also shipped them under
their old names, and the old commands and imports (web-scumm dev, web-scumm/content) still worked, after a one-line
notice. 4.3.0 removes them: npx quest-n-click migrate renames what a game still says
(Coming from web-scumm).
None is on npm yet: each release attaches them as archives (Install from npm, once published).
quest-n-click
Contents
The tracked files under src/, tools/, studio-server/, cli/, games/_template/, public/icons/,
public/fonts/, public/og.png, the store and migration files the Studio's journal shares with the Bridge
(bridge/src/store*.ts, migrations.ts, allowlist.ts), index.html, studio.html, vite.config.ts,
tsconfig.json, requirements.txt, ops/studio/worker-requirements.lock and LICENSE. Never a game of the
repository, a test, a source documentation page or a build. Left out of tools/ as well: the asset audit, the Bridge's
cross-check and fixtures, the connectors' fuzz harness.
Entry points
The command quest-n-click (cli/quest-n-click.mjs), and five public entries: quest-n-click/content, /player,
/minigames, /testing, /reality (Public API), plus quest-n-click/cli/*. Anything else is
internal.
Dependencies
The engine's runtime dependencies (earcut, howler, navmesh, zod) and what the tools need in a game project:
Vite and vite-plugin-pwa, tsx, @typescript/typescript6 (the compiler API the tools use), @types/node,
@types/howler, Tweakpane, the MCP SDK. Tests and Playwright stay out, which is why quest-n-click doctor needs a
workaround in a created project (doctor). The package carries no lock: npm
resolves these ranges at install.
Its documentation, docs-bundle/
feature since 4.5.0
From 4.5.0 the package carries the documentation of its version, written by npm run wiki -- bundle into the prepared
folder before npm pack (never committed): index.json, md/<lang>/<id>.md, legacy/<NAME>.md, assets/ and
bundle-manifest.json with each file's sha256. Two packs of one commit give the same bytes. The MCP server of a
created project reads it (read_doc, search_docs, list_docs).
create-quest-n-click
One file, index.mjs, which runs quest-n-click create from the engine it depends on (quest-n-click at the same
version): npx create-quest-n-click my-game "My Game" once on npm.
quest-n-click-bridge
The reference Reality Bridge on its own: bridge/src bundled by esbuild into one module (src/cli.mjs, compiled since
4.1.2, so it runs on Node alone), its Datalog policies and its SQL migrations, the command quest-n-click-bridge
(init, serve, grant, rotate, revoke, doctor, compact, migrate, tenant, backup, restore). Biscuit's
WebAssembly and zod are dependencies; pg and OpenTelemetry are loaded by name only when used. It carries its
npm-shrinkwrap.json (since 4.1.19): an install resolves nothing. The Bridge's CLI.
quest-n-click-connectors
The connector SDK, the command quest-n-click-connector <email|telnet|ssh|open-badge> --config <file.json> and the four
connectors bundled into one module, with the MIME reader's worker beside it; ssh2 is a dependency. An operator's
package, run beside a Bridge, never a game's. Install it without native code:
npm install --omit=optional --ignore-scripts quest-n-click-connectors-<version>.tgz. It carries its
npm-shrinkwrap.json. Experimental (4.1.9). Connectors.
quest-n-click-studio-server
The commands quest-n-click-studio-server and quest-n-click-studio-worker, which run the server and the processing
worker of the engine installed beside it (the same version, or they stop with … runs with quest-n-click <v>, not <w>),
and the Studio's page built once. Its own dependencies are locked in its npm-shrinkwrap.json; installed from the
archive file rather than the registry, npm resolves them from their ranges (quest-n-click-studio-server deps says
which). Install from the release archive.
Commands of a created project
npx quest-n-click help lists them. The project's package.json names the usual ones as npm scripts (dev,
studio, assets, verify, build, release, preview):
| Command | What |
|---|---|
quest-n-click dev / studio | the game, the Studio |
quest-n-click assets | art and audio into public/assets |
quest-n-click verify | validate, solve, translations, lint, playtests |
quest-n-click doctor | the prerequisites: Node and Chromium required; Python, ffmpeg and WebKit optional, said when missing (4.1.6); needs a workaround in a created project (doctor) |
quest-n-click mcp | the MCP server of this game, on stdio, for an assistant (4.1.6) |
quest-n-click build | assets, verify, the build, every file of dist/ accounted for |
quest-n-click release [--commercial] | build, then the release gates: provenance lock, budgets, translations, voices, strict playtests, the proof |
quest-n-click validate, solve, lint, i18n, weight, provenance, playtests, voices, prompts, ids | each tool, with its options |
quest-n-click speedrun verify <run.wsrun> | a speedrun replayed against the game: its verdict, code and reason |
quest-n-click bridge, solve-reality | a reference Bridge for the game; a game with reality.signals proved closed |
quest-n-click preview | serve dist/ locally |
quest-n-click create <folder> ["Title"] [--engine=<spec>] | a new game project from the template |
quest-n-click migrate | bring the game's sources to the installed engine's format (Upgrade) |
They run with the project as their working folder
(WEB_SCUMM_PROJECT): the engine in
node_modules/quest-n-click is read, never written. Every option is on Command line.
How it is checked
npm run fresh-install(a CI job, when a package, template or authoring path changed): packs the engine (npm run pack), creates a game from the packed template in an empty folder outside the repository, installs the tarball, runsassets,verifyandbuild, and plays the game to its ending in Chromium. A file of the new project that names the repository fails it.npm run external-consumer(each release candidate, on Ubuntu, macOS and Windows): the candidate's own archives, never packed again, installed outside the repository: a game created on an older release and moved to them, an old save played to the ending, the documentation bundle checked against its manifest and read through a real MCP client,create-quest-n-click, the Bridge and the connectors from their archives.npm run readme-quickstart: the README's quick start, run as a reader copies it.npm run upgrade-check -- --from=<version>: a game moved from an older release to this one.scripts/studio-install-smoke.mjs: the engine and Studio Server archives installed together, a game served.
Each release attaches the five archives with their SBOMs and sums. Publishing them to npm is the maintainer's (a token, the package names): npm packages.
Related identifiers
npm run pack(node scripts/pack.mjs [--out=<dir>] [--publish-dry-run] [--build-id <id>] [--allow-dirty]), writing into.cache/packby defaultnpm run locks(the Bridge's and connectors' locks,scripts/locks/; a lock that no longer fits stopspack)- Install from the release archive, Command line, npm packages
scripts/pack.mjs,scripts/fresh-install.mjs,scripts/external-consumer.mjs