EN Contribute Developer Setup

Developer setup

Français · Type: tutorial · Audience: contributor · Context: engine repository · Status: ready · Applies from: 4.4.0

From an empty folder to an engine repository whose checks run on your machine. About fifteen minutes, most of it downloads.

What you will build

A clone of wanoo/quest-n-click with its dependencies, the Python image modules, a Playwright Chromium, and a report from npm run doctor with no required item missing. At the end the sample game runs in your browser and the unit suite passes.

This page is for working on the engine. To make a game with a released engine, create a project instead (Your first game); to install from the repository without contributing, see Install from the repository.

What you need

• Git.
• Node.js 22.12 or newer (package.json engines: >=22.12). The repository's .nvmrc says 22, so nvm use takes the newest 22 you have installed: make sure it is at least 22.12. The Studio, the tools that write a game and the Reality Bridge on SQLite need 22.13 or newer (node:sqlite).
• Python 3 with the modules of requirements.txt (Pillow 13.0.0, NumPy 2.4.6, SciPy 1.18.1): the asset tests and npm run assets use them. CI uses Python 3.12.
• ffmpeg (optional): audio authoring, and validate --release, which measures the music stems with ffprobe.
• About 2 GB of disk for node_modules and the browsers.

The exact versions per system are in Requirements.

Steps

Every command below runs in a terminal, in the engine repository once it is cloned.

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

   You see the repository's folders: src/, games/, tools/, tests/, wiki/…

2. Select Node. With nvm:

   # in the engine repository
   nvm use
   node --version

   node --version prints v22.12.0 or newer. Without nvm, install a Node 22 LTS from nodejs.org.

3. Install the dependencies exactly as the lockfile says.

   # in the engine repository
   npm ci

   It ends without error and creates node_modules/. Use npm ci, not npm install: the lockfile is part of what CI checks.

4. Install the Python image modules.

   # in the engine repository
   python3 -m pip install -r requirements.txt

   A virtual environment works too; the tools call python3, so activate it before running them.

5. Install a browser for the end-to-end tests.

   # in the engine repository
   npx playwright install chromium

   Chromium is required (the e2e and the Studio's checks use it). WebKit and Firefox are optional: npx playwright install webkit firefox adds them, for the rows CI runs in those browsers.

6. Ask the doctor.

   # in the engine repository
   npm run doctor

   Each line is ✔ (present), ○ (optional and missing) or ✖ (required and missing), with the command that fixes it, for instance Run: python3 -m pip install -r requirements.txt or Run: npx playwright install chromium. It checks Node (major version 22 or more), Python 3, the image modules, ffmpeg, the three Playwright browsers, and Ed25519 and Biscuit for the Reality Bridge. Only a required item fails the report: Python, ffmpeg, WebKit and Firefox are optional for daily work. npm run doctor -- --release makes Python, its modules and ffmpeg required, as npm run release-check needs them. The doctor never installs anything.

7. Run the unit suite and the sample game.

   # in the engine repository
   npm test
   npm run dev

   npm test runs the unit suite (test:node: every test file but the heavy solver tests and the two asset tests). npm run dev serves the sample game, "The Pantry Key", at http://localhost:5173/: open it in a phone-sized window.

8. Pick another game when you need one. The current game is, in this order: the GAME environment variable, the game the link .cache/game points to, package.json "config": { "game" }, then demo.

   # in the engine repository
   GAME=reference npm run dev        # this command only
   GAME=heroes npm run game          # moves the .cache/game link: later commands use heroes
   GAME=demo npm run game            # back to the sample game

   The bundled games are demo, reference ("The Night Market"), heroes, signals and _template (the model npm run new-game copies). npm run dev, npm run check and npm run build run npm run game first, so the link follows GAME when it is set.

Limit · windows-posix On Windows the unit suite runs without the few test files that assume POSIX (file modes, / in paths, the shell's tools, the connectors' Telnet and SSH tests, the Studio Server's processing worker): CI's windows job names them. See Requirements.

What you learned

• The repository's tools are npm scripts; npm scripts lists them all.
• npm run doctor says what is missing and how to fix it: doctor.
• The current game is chosen by GAME, a link, then package.json.

Where to go next

• The dev loop: change, check, look.
• Architecture and the Code tour.
• Before a pull request.

---

Edit the source of this page · Report an error