Aller au contenu
quest'n'click

InstallerGuidePour auteursS'applique de 4.2.5

Installer depuis l'archive de la release

This page in EnglishCette page sur le wiki GitHub

Le moteur n'est pas encore sur npm (Installer depuis npm, une fois publié). Chaque release GitHub le joint sous forme d'archive, quest-n-click-<version>.tgz, et c'est avec cette archive qu'on crée et qu'on fait tourner un jeu aujourd'hui.

Ce que vous obtenez

Un projet de jeu à vous, hors du dépôt du moteur : un lieu, un héros et des images provisoires, le moteur installé depuis l'archive de la release sous node_modules/quest-n-click, jouable dans votre navigateur avec npm run dev.

Contexte et versions

  • Un projet créé, sur votre machine. Rien ici ne demande un clone du dépôt du moteur.
  • Depuis la 4.2.5, les fichiers de la release s'appellent quest-n-click-…. Avant la 4.2.5, c'était web-scumm-… (Venir de web-scumm).
  • Les commandes ci-dessous sont le démarrage rapide du README. Chaque candidat de release les lance comme un lecteur les copie, dans un dossier vide hors du dépôt, sur sa propre archive (scripts/readme-quickstart.mjs) ; après le tag, --published vérifie que l'URL répond et que ses octets correspondent au SHA256SUMS de la release.

Prérequis

Où lancer les commandes

Sur votre machine, dans un terminal, depuis le dossier qui contiendra le nouveau projet (create crée lui-même le dossier du projet). Toutes les commandes après cd my-game tournent dans le projet créé. Sous Windows, utilisez Git Bash.

Étapes

  1. Nommez l'archive de la release voulue. Le modèle d'URL est https://github.com/wanoo/quest-n-click/releases/download/v<version>/quest-n-click-<version>.tgz :

    # dans le dossier qui contiendra le projet
T=https://github.com/wanoo/quest-n-click/releases/download/v4.4.0/quest-n-click-4.4.0.tgz

  1. Créez le projet depuis cette archive. --package=$T lance la commande quest-n-click de l'archive ; --engine=$T inscrit la même archive comme dépendance du projet :

    # dans le dossier qui contiendra le projet
npx --package=$T quest-n-click create my-game "Mon jeu" --engine=$T

    create <dossier> ["Titre"] refuse un dossier qui existe et n'est pas vide. L'id du jeu est le nom du dossier en minuscules, mots séparés par des tirets ; le titre vaut ce nom par défaut.

  1. Installez le moteur dans le projet :

    cd my-game
npm install

  1. Installez les modules Python dont les outils d'images ont besoin, depuis le fichier que porte le paquet du moteur :

    # dans le projet créé
python3 -m pip install -r node_modules/quest-n-click/requirements.txt

  1. Préparez les images, puis jouez :

    # dans le projet créé
npm run assets && npm run dev

    Ouvrez l'URL qu'affiche dev. En paysage sur un téléphone, le jeu se joue comme pour les joueurs (le serveur de développement n'écoute que sur votre machine ; Tester sur un téléphone du réseau l'ouvre au réseau local). ?edit=start dans l'URL ouvre l'éditeur de placement sur le lieu start.

  1. Quand vous avez changé quelque chose, vérifiez le jeu et construisez-le :

    # dans le projet créé
npm run verify
npm run build

    npm run build écrit dist/, un site statique que n'importe quel hébergement sert (Construire et publier).

Pour vérifier l'archive avant de la lancer, téléchargez-la avec les sommes de la release et installez depuis le fichier :

# dans le dossier qui contiendra le projet
gh release download v4.4.0 --repo wanoo/quest-n-click -p 'quest-n-click-4.4.0.tgz' -p 'quest-n-click-v4.4.0-SHA256SUMS'
shasum -a 256 -c --ignore-missing quest-n-click-v4.4.0-SHA256SUMS
npx --package=./quest-n-click-4.4.0.tgz quest-n-click create my-game "Mon jeu" --engine=file:../quest-n-click-4.4.0.tgz

Le chemin file: se lit depuis le dossier du projet, d'où le ../. shasum affiche quest-n-click-4.4.0.tgz: OK quand les octets sont ceux que liste la release (vérifié le 23 octobre 2026 avec la v4.4.0).

Résultat attendu, et comment le vérifier

create se termine par :

my-game: "Mon jeu" created (quest-n-click https://github.com/wanoo/quest-n-click/releases/download/v4.4.0/quest-n-click-4.4.0.tgz).
Next:
  cd my-game
  npm install
  npm run assets && npm run dev

Dans le projet, npx quest-n-click help affiche quest-n-click 4.4.0: an engine for point-and-click games in the browser et la liste des commandes. npm run dev montre le lieu du modèle avec son héros ; npm run verify se termine sans erreur (validation, solveur, état des traductions, lint, playtests).

Erreurs fréquentes

SymptômeCauseCorrection
npm error 404 Not Found - GET https://registry.npmjs.org/quest-n-click à npm installLe projet a été créé sans --engine=$T : sa dépendance vaut ^<version>, cherchée sur npm, où le moteur n'est pas publiéRecréez-le avec --engine=$T, ou lancez npm install $T dans le projet
my-game exists and is not emptycreate n'écrit jamais dans un dossier qui contient des fichiersChoisissez un autre nom de dossier, ou videz-le
npm warn EBADENGINE Unsupported engineNode plus ancien que 22.12Installez Node 22.12 ou plus récent (Prérequis)
npm run assets échoue sur import PILLes modules Python manquentÉtape 4
warning: missing images: … après assetsLe contenu cite une image dont le fichier n'est pas dans game/artAjoutez le fichier, ou corrigez le nom (Images)
npx quest-n-click doctor s'arrête sur Cannot find package 'playwright'doctor importe Playwright, que le paquet du moteur n'apporte pasDépannage de l'installation

Fichiers ou données modifiés

create n'écrit que le nouveau dossier :

CheminQuoi
game/le jeu : game.ts, rooms/, cast.ts, items.ts, rules.ts, layout/, locales/, art/, audio/, provenance.json
public/les icônes de la page, son image d'aperçu, la police complète ; public/assets est écrit par npm run assets (pas commité)
dist/le build, avec licenses/ (npm run build)
package.jsonles scripts dev, studio, assets, verify, build, release, preview, qui appellent chacun quest-n-click, et le moteur comme seule dépendance
tsconfig.json@engine/* pointe dans node_modules/quest-n-click/src/engine, quest-n-click/* dans son API publique
.gitignore, README.mdnode_modules, dist, .cache, public/assets ignorés ; les commandes ci-dessus

Les images du modèle sont provisoires, dessinées à partir de formes (tools/placeholder-art.py) : game/provenance.json le dit, et npm run release les refuse tant que chaque fichier n'est pas remplacé et revu (npx quest-n-click provenance --lock). L'organisation complète d'un projet est dans Organisation d'un projet.

npm install ajoute node_modules/ et package-lock.json ; npm run assets écrit public/assets/ et .cache/, et met à jour game/assets.gen.json (les tailles en pixels des images préparées). Les commandes tournent avec le projet comme dossier de travail (WEB_SCUMM_PROJECT) : le moteur dans node_modules/quest-n-click est lu, jamais écrit. Hors du projet, seuls le cache de npm et les modules Python de l'étape 4 changent.

Reprise ou retour arrière

Supprimez le dossier du projet : rien d'autre n'a été écrit pour lui. Pour changer de version du moteur plus tard, voir Mettre à jour.

S'applique de 4.2.5 à …, depuis 4.2.1

Les autres archives d'une release

Une release joint cinq archives npm, toutes à la même version (la liste de la v4.4.0, lue le 23 octobre 2026) : quest-n-click-<version>.tgz (le moteur), create-quest-n-click-<version>.tgz (npx create-quest-n-click, une fois sur npm), quest-n-click-bridge-<version>.tgz (le Reality Bridge de référence, Installer et lancer le Bridge), quest-n-click-connectors-<version>.tgz (les connecteurs, ceux d'un opérateur, jamais d'un jeu) et, depuis la 4.2.1, quest-n-click-studio-server-<version>.tgz. Le contenu de chacune est dans la Référence du paquet.

L'archive du Studio Server contient les deux commandes quest-n-click-studio-server et quest-n-click-studio-worker, la page du Studio déjà construite, et ses propres dépendances (OpenID Connect, JWT, Postgres). Leurs versions sont verrouillées dans son npm-shrinkwrap.json et son SBOM ; npm lit ce verrou quand il installe depuis le registre, pas depuis un fichier d'archive, où pg prend le dernier 8.x que permet sa plage (quest-n-click-studio-server deps dit lequel). Elle fait tourner le serveur du moteur installé à côté, qui doit être de la même version :

# sur la machine du serveur, dans un dossier vide pour l'installation
npm install quest-n-click-<version>.tgz quest-n-click-studio-server-<version>.tgz
npx quest-n-click-studio-server import ./my-game --config studio.config.json
npx quest-n-click-studio-server serve --config studio.config.json
npx quest-n-click-studio-worker          # sur la machine du worker, avec WORKER_PUBLIC_KEY et WORKER_INSTANCE

Un worker installé depuis les archives prépare aussi les assets (depuis la 4.2.3) : son hook de build installe le verrou que porte le paquet du moteur, depuis le dossier du worker, où le worker cherche les paquets (WORKER_PYTHON_PATH pour les mettre ailleurs) : CC_POST_BUILD_HOOK=python3 -m pip install --target .python --require-hashes --only-binary=:all: -r node_modules/quest-n-click/ops/studio/worker-requirements.lock. Le verrou vaut pour CPython 3.13 sous Linux x86_64, glibc 2.28 ou plus récente (le runtime natif de Clever Cloud) ; une autre plateforme le refait (son en-tête dit comment). En 4.2.2, il fallait un worker déployé depuis le dépôt.

L'archive du moteur apporte Vite et tsx, dont le worker a besoin pour exécuter le code du jeu et construire ses prévisualisations (le Studio lui-même ne fait plus tourner Vite, depuis la 4.2.2). Mettez dans publicDir les assets préparés de votre jeu (public/ de son dépôt) : celui du moteur ne contient que ses icônes et sa police. Le candidat de chaque release installe ces deux archives dans un dossier vide et y sert un jeu, ses dépendances trouvées que npm les remonte ou les imbrique (scripts/studio-install-smoke.mjs). Le déploiement est décrit dans Premier déploiement sur Clever Cloud.

Références