web-scumm

Build a complete point-and-click adventure with an AI, and prove it can be finished.

A SCUMM-style engine made for phones, a visual Studio to produce the game, and a pipeline that checks it, proves it and
ships it as a web game that works offline. It started as the engine of a 9-room family game, written and shipped in a
single day with an AI assistant.

Version française

New in v4.1.3 "Honest Gates": nothing in the game, everything in what guards it. The workflows read only, cancel
what a newer push supersedes, stop after a deadline, run on a named image and pin every action to a commit; the unit
suite runs once per push and the CPU-bound solver tests run every night; a tool names a coverage floor the tests
left behind, the frozen baseline says what a rewrite moves; release-check runs what CI runs; main is protected by
a ruleset and merges by pull request (CHANGELOG).

New in v4.1.2 "Reliable Bridge": the Reality Bridge after an outside review of 4.1.1, checked against the code:
proposals are taken one at a time per player (no shared sequence, one acceptance per dedupeKey); a save is bound
to its player, and one under another link is neither changed nor acknowledged; a rotation signs what waits again
under the current key and a client asks for the keys once; five minutes of clock tolerance; streams bounded and
closed on revocation; codes in memory, limits per address, a longest life for a link, "Unlink" that revokes; a
journal that survives a torn line, doctor and compact; a required signal's fallback proved by the closed witness;
mutation testing and random properties on what a signal rests on; the package web-scumm-bridge compiled, installed
and started by CI from its tarball. Nothing to change in a game (CHANGELOG).

v4.1.1 "Reality Bridge": a game can react to a fact from the world outside (an email answered, a webhook
called) without its content touching the network. A separate Bridge (web-scumm bridge, or the package
web-scumm-bridge) turns the fact into a short signed signal the game declares; the player verifies it, applies it at
most once, saves, then acknowledges; a session replays it offline; the solver proves the game without the outside,
under each scenario, and against any order of signals. Pair a game from its pause menu, try signals in the Studio's
simulated Bridge, run the sample games/signals (REALITY, REALITY-OPS).
A game without signals pays nothing.

v4.1 "Clarity": a maintenance release that makes web-scumm easier to read, review and contribute to. It
changes no gameplay and no public contract: the engine, the player and the solver are split into modules of one
responsibility each, every index access in src/ is checked, data from outside starts as unknown, the code is
formatted and linted by Biome, and the behaviour of 4.0.0 (witnesses, proofs, golden saves, the public surface) is
frozen by npm run quality:baseline. Coverage floors, property tests and mutation testing say how strong the tests
are. A newcomer starts with ARCHITECTURE and the half-hour CODE_TOUR.

v4.0 "Stable Platform": the engine is a package with a public API it promises to keep. A game lives in
its own project (web-scumm create, then npm run dev, verify, build, release), imports four entries
(web-scumm/content, /player, /minigames, /testing), and moves to a new release with web-scumm migrate: CI
creates a game on the previous release, saves in it, upgrades it and plays the old save to the end. What a release
ships is exactly its files and their licences, built from the commit CI tested and never replaced
(API, SUPPORT, PACKAGE). On the way: 3.7 made the sample
game sellable, 3.8 wrote down the field passes people still have to make (FIELD), 3.9 made the
first game outside the repository, "The Lighthouse". And for players: a double tap acts with the verb they mean
(through a door, talk to someone, look at the rest), and an item from the bag is given or used, whichever fits.

v3.6 "Production": the music director is held to budgets of its own (stems, offline, decoded audio, a
cap on what it keeps), its stem files are measured before a release, and one score hands over to another on a beat,
a bar, a phrase or a marker, through a bridge; a save keeps where the music was. The proof pools items per group of
characters who can meet, so open chains with three characters are proved where 3.5 gave up
(the measures), and random games of three
kinds are checked against the explicit search every night (counted as tried, compared and partial).

v3.5 "Score": music that follows the game. A track is cut into stems that play in sync; the mix changes
with the room, the active character or a flag, on the next bar, without a click. The proof runs on several cores
with the same result, and pools the items the characters can hand each other, so two-character games with items
moving freely are proved
(how it is measured). It is an adaptive stem mixer with
transitions, not iMUSE: no tempo changes, no branches inside a score. 3.4 "Stagecraft" brought scenes with depth:
a Canvas painter, layers, masks, lights, walk zones and stairs, the structured Studio, and a second game, "The Night
Market".

More than an engine

v4.0 in numbers

v3.6 in numbers

Measured on the release, proof cache off (BENCH.md):

The proof explores the game as the engine plays it and assumes the minigames are won. The reference game keeps each
character in their own era. When items can move freely between three characters, the search still stops before the
end, and BENCH.md says so.

What the player gets

Conversations with topics, choices and a transcript	Minigames, playable by touch or keyboard
A world map, characters who move between places	An ending that remembers what the player guessed

Nine classic verbs and a bag, dialogue, hints from a character, cutscenes and phone calls, rooms wider than the screen,
several playable characters with their own bags, scripts and events, seven minigames, an optional sealed ending,
autosave and save slots, translations, settings, touch, mouse and keyboard, and the whole game offline after the first
visit.

What the author gets

Rooms: the real engine, a placement editor on top, every line editable in place	Storyboard: the story panel by panel, checked against the game
Assets: every sheet and cell, where it is used, the prompt to make it	Check: the validator and the solver, run again after every save

The puzzle graph shows what each item, flag and room leads to. With Critical path on, what does not lead to the
end fades. With Heat, the rules the solver went through most turn red. The Studio also has a Play tab with a rule
explainer and session replay, shared notes with the AI, and an Assistant that works with any model.

Make your own game

Needs Node 22+, Python 3 for the art tools (pip install -r requirements.txt) and ffmpeg for sound.

In its own project (3.9, PACKAGE): the engine installs from a release's tarball (npm
publishing to come, then npx create-web-scumm my-game):

T=https://github.com/wanoo/web-scumm/releases/download/v4.1.3/web-scumm-4.1.3.tgz
npx --package=$T web-scumm create my-game "My Game" --engine=$T
cd my-game && npm install
npm run assets && npm run dev        # then npm run verify, npm run build, npm run release

In this repository, beside the sample games:

npm install
npm run doctor                       # checks Node, Python modules, ffmpeg and the test browsers
npm run new-game my-game "My Game"   # games/my-game from the template, set as the current game
npm run assets                       # prepares the placeholder art
npm run studio                       # the Studio: rooms, story, assets, checks, play

Then, before anyone plays it:

npm run verify:game   # validation, a path to the ending, chapters, translations, lint, playtests
npm run prove:game    # every reachable state: softlocks and truncation fail
npm run build         # tests, bundle and audits, into dist/ for any static host

npm run dev plays your game on this computer, npm run dev:lan on your phone. Write the story in
storyboard.json first, then the rooms with CONTENT_GUIDE open.
WORKFLOW is the whole method, step by step.

How a game is written

Everything is data: rooms, props with states, characters, items, rules, topics, hints, scripts, events. There is no
code in the content, so every tool can read it, check it and play it.

export const garden: RoomDef = {
  id: 'garden', name: 'The garden', decor: 'garden',
  props: { tank: { name: 'water tank', states: { full: 'tank_full', empty: 'tank_empty' } } },
  actors: { grandpa: { char: 'grandpa' } },
  exits: { back_door: { name: 'back door', to: 'house', entry: 'garden' } },
  on: [
    { verb: 'use', a: 'pipe', b: 'tank', if: '!tank_drained',
      do: [{ minigame: 'pipes', params: { /* see games/demo */ } }, { lose: 'pipe' }, { set: 'tank_drained' }, { prop: ['tank', 'empty'] }] },
  ],
  talk: { grandpa: [{ topic: 'Where is the key?', if: '!tank_drained', do: [{ say: ['grandpa', 'It fell in the tank. Plop.'] }] }] },
  hints: [{ until: 'tank_drained', lines: ['Use the pipe on the water tank.'] }],
};

A rule is a verb, a target, a condition and a list of commands. CLASSICS writes twenty famous
mechanics of the genre with it: insult sword fighting, a nurse on patrol, a tree planted in the past.

Why an AI can really work on it

• The content is declarative, so an assistant reads and writes it like any other file.
• Every operation is a command, and the same operations are MCP tools for Claude Code, Cursor, Codex, Gemini CLI or
  any MCP client (MCP). The Studio's Assistant gives them to any model.
• After each change the assistant can validate, solve, replay and take a screenshot, so it sees its own mistakes.
• Every result stays reviewable by a person, in the Studio and in Git. CLAUDE.md and AGENTS.md hold the rules.

Art and sound

npm run prompts writes ready-to-paste image prompts for every character sheet, object, background and piece of
furniture, all in one style. npm run assets cuts the generated sheets into sprites (PROMPTS).
npm run audio arranges a MIDI for Mega Drive chips and renders the sound effects from the same palette
(AUDIO).

Documentation

Every page also exists in French under docs/fr/. docs/dev/ holds the log of the work with the other assistant.

Releases

Current release: v4.1.3 "Honest Gates": the CI made
trustworthy before the refactorings (read-only workflows pinned to commits, the unit suite once per push, the heavy
solver tests nightly, coverage and baseline ratchets, a ruleset on main), on 4.1.2's reliable Bridge. The
story from v1.3 to v4.1 is in the ROADMAP, every change in the CHANGELOG.

Repository map

src/engine/      core (the DSL, the engine), tools (validate, solve, lint, i18n…), dom (the renderer), minigames
games/demo/      the sample game: rooms, layouts, art, audio, locales, storyboard
games/_template/ copied by npm run new-game
tools/           the commands, the Studio, the MCP server, the art pipeline
scripts/         the browser tests, the sealed ending, new-game, the README screenshots
docs/en docs/fr  the documentation; docs/dev: the work log

The images of this page come from the production bundle and the Studio, taken by npm run docs:screenshots.

Licences

Code: MIT. Sample artwork, sound effects and theme: CC BY 4.0 (attribution "Wano"); the theme is Tchaikovsky's Swan
Lake (public domain), written out and arranged for the project, so the sample game passes npm run verify:commercial
(3.7). Fonts: SIL OFL. See CREDITS.md.