Construire et publier un jeu

npm run build fait d'un jeu un dossier statique, dist/, que n'importe quel hébergeur web sait servir : le jeu, ses assets, son service worker et ses licences. Une construction de release ajoute les contrôles qu'un jeu doit passer avant que des gens y jouent : provenance verrouillée, budgets, traductions, voix, playtests et preuve exhaustive. Cette page dit ce que vérifie chaque commande, dans quel dossier elle se lance, et quoi regarder avant d'envoyer le lien.

Ce que vous obtenez

Un dossier dist/, vérifié fichier par fichier, prêt à téléverser : une application web installable (PWA) qui se joue hors ligne après la première visite, dont chaque fichier est recensé avec sa licence dans dist/licenses/.

Contexte et versions

Le même jeu se construit à deux endroits, avec des commandes différentes :

La page vaut à partir de la 4.2.5, quand la commande est devenue quest-n-click (avant, web-scumm). Le projet créé et ses commandes build et release existent depuis la 3.9.0 ; npm start est un lanceur Node depuis la 4.1.8.

Prérequis

• Node 22.12 ou plus récent, le projet installé (npm install dans un projet créé, npm ci dans le dépôt du moteur). Voir Prérequis.
• Python 3 avec les paquets de requirements.txt (Pillow d'abord) : npm run assets transforme art/ et audio/ en public/assets, et le build d'un projet créé le lance à chaque fois. Dans un projet créé, le fichier est node_modules/quest-n-click/requirements.txt.
• ffmpeg quand le jeu a des sons, des musiques ou des vidéos à encoder, et pour une release quand le jeu déclare une musique en stems (validate --release les mesure avec ffprobe).
• Un jeu qui passe ses vérifications : Vérifier son jeu. La construction les relance et s'arrête à la première qui échoue.

Où lancer les commandes

• « Dans le projet créé » : le dossier fait par quest-n-click create, celui qui contient game/ et package.json.
• « Dans le dépôt du moteur » : le clone de wanoo/quest-n-click. Le jeu construit est celui que nomme GAME, sinon celui choisi par npm run game, sinon package.json → config.game, sinon demo.

Étapes

1. Préparer les assets quand des images ou des sons ont changé.

   # dans le dépôt du moteur (public/assets y est commité : commitez ce que la commande écrit)
   npm run assets

   copy

   Dans un projet créé, public/assets n'est pas commité (son .gitignore le liste) et npm run build lance assets lui-même.

2. Construire.

   # dans le projet créé
   npm run build

   copy

   Elle enchaîne, et s'arrête au premier échec : assets ; verify (validation, solveur, état des traductions, lint, playtests) ; la construction Vite dans dist/ ; puis le contrôle que chaque fichier de dist/ est recensé.

   # dans le dépôt du moteur
   npm run build

   copy

   Elle lance check (types, tests Node) puis build:game : verify:game (validation, solveur, solveur par chapitre, variantes, état des traductions, lint, playtests), la construction Vite, verify:dist, check:spoilers et audit:assets.

3. Passer les contrôles de release avant une sortie publique.

   # dans le projet créé
   npm run release                 # ou : npm run release -- --commercial

   copy

   release lance assets, verify et la construction, puis : validate --release (le verrou de provenance, les placeholders, les ids), weight --release (ce qu'un téléphone télécharge, face aux assetBudgets du jeu), i18n status, voices check --release, playtests --strict, solve --prove (chaque état atteignable), solve-reality, et avec --commercial validate --commercial --errors (aucune exception, aucun placeholder, aucune licence non commerciale) ; enfin le contrôle de dist/.

   # dans le dépôt du moteur
   npm run verify:release          # ou : npm run verify:commercial
   npm run prove:game

   copy

   Les images du modèle sont des placeholders : une release les refuse tant que chaque fichier n'est pas remplacé, relu et verrouillé (npx quest-n-click provenance --lock dans un projet créé, npm run provenance -- --lock dans le dépôt du moteur). Voir Provenance des assets.

4. Sceller la fin, seulement pour un jeu à fin scellée, dans le dépôt du moteur : sceller la vraie issue, construire, commiter, puis déployer. Toute la procédure est dans La fin scellée.

   # dans le dépôt du moteur, games/<id>/private/ending.config.ts rempli
   npm run seal -- --outcome=<key>
   npm run build

   copy

5. Téléverser dist/ chez un hébergeur statique (section suivante), puis jouer la version en ligne.

   # dans le dépôt du moteur : joue le jeu déployé jusqu'à la fin, dans un navigateur à taille de téléphone
   node scripts/e2e.mjs https://<votre-site>/

   copy

   scripts/e2e.mjs n'existe que dans le dépôt du moteur ; dans un projet créé, jouez le site en ligne à la main jusqu'à la fin.

Ce que livre la construction

npm run build vérifie les types (dans le dépôt du moteur), lance les tests, assemble et audite le résultat. On obtient une PWA :

• le service worker met en cache l'application de base (code, styles, la page, les polices de la page, les icônes) dès l'installation ;
• les images et les sons sont mis en cache au premier usage, et le moteur réchauffe en tâche de fond le lieu courant, les lieux à une sortie et leur audio ;
• par défaut (GameDef.offline: 'full'), il télécharge ensuite le reste du jeu pendant les temps morts, si bien que le jeu entier se joue hors ligne après la première visite ; avec offline: 'nearby', un lieu jamais visité ni réchauffé peut encore demander le réseau. Les lieux ne sont jamais tous téléchargés avant que le jeu démarre : la première visite reste légère.

Le menu pause dit au joueur si le jeu entier est en cache. Le détail est dans Sous-chemin, cache et service worker.

Chaque construction finit par retirer de dist/assets les fichiers qui ne sont pas à ce jeu et par écrire dist/licenses/ : la LICENSE du moteur, LICENSE-ASSETS, CREDITS.md tiré de la provenance du jeu, THIRD_PARTY_NOTICES.txt et assets-manifest.json (pour chaque fichier : chemin, auteur, source, licence, SHA-256 et statut). Le contrôle qui suit refuse tout autre fichier dans dist/, ainsi qu'un fichier verrouillé ou une notice qui manque.

Déployer

dist/ est statique : n'importe quel hébergeur statique le sert.

• GitHub Pages : un workflow construit avec BASE_PATH=/<dépôt>/ et déploie dist/. Pour un projet créé, qui n'a pas de workflow, copiez celui de Publier sur GitHub Pages.
• Clever Cloud : une application Node qui construit au déploiement et sert dist/ ; voir Le jeu statique sur Clever Cloud.
• Netlify, Cloudflare Pages, nginx, un bucket… : Autres hébergeurs statiques.

Sous un sous-chemin (https://<utilisateur>.github.io/<dépôt>/), construisez avec BASE_PATH=/<dépôt>/ ; à la racine d'un domaine, pas de BASE_PATH. Tous les chemins (scripts, styles, manifeste, icônes, service worker, fichier de la fin scellée) le suivent :

# dans le projet créé ou le dépôt du moteur : la même construction que Pages, en local
BASE_PATH=/my-repo/ npm run build

Ce qui casse sous un sous-chemin, avec le cache ou avec un site à moitié téléversé : Sous-chemin, cache et service worker, déploiement incomplet, retour arrière.

Dans le dépôt du moteur, games/<id>/private/ (photos, planches brutes, configuration de la fin scellée) n'est jamais envoyé : .gitignore l'exclut, et rien de ce dossier n'est copié dans dist/. Le .gitignore d'un projet créé ne liste que node_modules, dist, .cache et public/assets : gardez les fichiers privés hors de game/, ou ajoutez-les-y.

Résultat attendu, et comment le vérifier

• La commande se termine sans erreur et dist/ contient index.html, sw.js, manifest.webmanifest, assets/, icons/, fonts/ et licenses/.
• npm run preview le sert sur http://127.0.0.1:4173/ : jouez-y avant de téléverser.
• Après le téléversement, jouez le site en ligne jusqu'à la fin sur un vrai téléphone, en paysage ; ouvrez le menu pause et attendez « complete » sur sa ligne « Offline » (ou sa traduction) avant de tester hors ligne.
• Les dernières vérifications avant de partager le lien (un vrai téléphone, quelqu'un d'autre qui joue sans aide, la fin scellée) sont dans Vérifier son jeu.

Erreurs fréquentes

Fichiers ou données modifiés

• dist/ : vidé et réécrit à chaque construction (non commité).
• public/assets/ et .cache/refs.json : écrits par assets (commités dans le dépôt du moteur, pas dans un projet créé).
• games/<id>/data/ (dépôt du moteur) : le fichier de la fin scellée, écrit par seal.
• Rien dans node_modules/quest-n-click : le moteur est lu, jamais écrit.

Revenir en arrière

Une construction ne change rien qu'on ne puisse reconstruire : supprimez dist/ et relancez-la. Pour remettre en ligne une version précédente, déployez la construction d'un commit précédent ; ce que font alors les caches et les sauvegardes des joueurs est dans Retour arrière.

Références

• cli/quest-n-click.mjs : ce que lancent build et release dans un projet créé.
• package.json : build, build:game, verify:release, verify:commercial, prove:game, start dans le dépôt du moteur ; scripts/start.mjs.
• tools/dist.ts : ce que dist/ peut contenir ; tools/validate.ts : les contrôles de release et commerciaux.
• vite.config.ts : la construction et le service worker.
• Scripts npm, Le paquet.