Install from the repository to work on the engine

To change the engine itself, its tools or its Studio, or to play its sample games from source, you work in a clone of the engine repository. To make a game of your own, you do not need it: Install from the release archive.

What you get

A clone of wanoo/quest-n-click with its development dependencies, the Python modules and Chromium installed, checked by npm run doctor, and the sample game running with npm run dev.

Context and versions

• The engine repository, on your machine. Every command runs at the root of the clone.
• main holds work not released yet. To work on a released version, check out its tag (git checkout v4.4.0).
• The repository is github.com/wanoo/quest-n-click since 4.2.5; the old github.com/wanoo/web-scumm address redirects to it.
• The whole contributor setup, with the conventions and the checks before a pull request, is Developer setup; this page is the installation only.

Prerequisites

• git, and Node.js 22.12 or newer (22.13 for the local Studio and the writing tools); nvm reads the repository's .nvmrc (Requirements).
• Python 3 (Requirements).
• Optional: ffmpeg, for sounds and the audio pipeline (Requirements).

Where to run the commands

On your machine, in the folder that will hold the clone, then at the clone's root. On Windows, in Git Bash.

Steps

1. Clone the repository and enter it:

   # in the folder that will hold the clone
   git clone https://github.com/wanoo/quest-n-click.git
   cd quest-n-click

   copy

2. Use the Node version the repository names (.nvmrc says 22: the newest Node 22 you have):

   # at the root of the clone
   nvm use
   node --version        # v22.12.0 or newer

   copy

3. Install the exact dependencies of package-lock.json, development tools included (Playwright, Vitest, Biome):

   # at the root of the clone
   npm ci

   copy

4. Install the pinned Python modules (Pillow, NumPy, SciPy):

   # at the root of the clone
   python3 -m pip install -r requirements.txt

   copy

5. Install the browser the e2e scripts and the Studio's checks drive:

   # at the root of the clone
   npx playwright install chromium

   copy

   npx playwright install webkit firefox adds the two optional browsers.

6. Check the machine:

   # at the root of the clone
   npm run doctor

   copy

7. Run the sample game. The game is chosen by GAME, else the game .cache/game links to (npm run game makes the link), else config.game in package.json, which is demo:

   # at the root of the clone
   npm run dev                 # the sample game, games/demo
   GAME=heroes npm run dev     # another game of games/

   copy

Expected result, and how to check it

npm run doctor ends with Development, asset and browser-test prerequisites are ready. (or says which optional prerequisite is missing, and exits 0 all the same); see doctor. npm run dev prints a local URL that opens the sample game. The checks to run before a change are on Before a PR.

Common errors

Symptom	Cause	Fix
npm ci refuses: the lock and package.json disagree	A local change to package.json	git checkout package.json package-lock.json, or npm install if you meant the change
✖ Playwright Chromium: browser binary missing	Step 5 not done	npx playwright install chromium
error: externally-managed-environment from pip	Your system's Python refuses global installs (PEP 668)	Use a virtual environment: python3 -m venv .venv && . .venv/bin/activate, then step 4
✖ games/<id>/index.ts not found (GAME=<id>)	GAME names no folder of games/	ls games and pick an existing id

Install troubleshooting has more.

Files or data changed

The clone; node_modules/; Playwright's browsers in its cache folder (outside the clone, shared by every project); the Python modules in your Python environment; .cache/ in the clone (the game link, the journal of the writing tools, caches), ignored by git.

Recovery or going back

Delete the clone. Playwright's browsers stay in its cache until npx playwright uninstall --all.

References

• Developer setup, Dev loop, Before a PR
• Requirements, doctor
• CONTRIBUTING.md, tools/select-game.ts (how the game is chosen)