Skip to content
quest'n'click

InstallReferenceFor authors, contributorsApplies from 4.3.0

Package reference

Cette page en françaisThis page on the GitHub wiki

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.

since 4.5.0

Its documentation, docs-bundle/

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):

CommandWhat
quest-n-click dev / studiothe game, the Studio
quest-n-click assetsart and audio into public/assets
quest-n-click verifyvalidate, solve, translations, lint, playtests
quest-n-click doctorthe 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 mcpthe MCP server of this game, on stdio, for an assistant (4.1.6)
quest-n-click buildassets, 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, idseach 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-realitya reference Bridge for the game; a game with reality.signals proved closed
quest-n-click previewserve dist/ locally
quest-n-click create <folder> ["Title"] [--engine=<spec>]a new game project from the template
quest-n-click migratebring 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, runs assets, verify and build, 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.