11 KiB
Escape Game
Escape game point & click façon Myst, en 3D temps réel avec three.js et des caméras fixes. On passe d'un point de vue à l'autre par un mouvement de caméra.
Le moteur est piloté par les données : tout le contenu d'un chapitre (points de vue, objets cliquables, inventaire, énigmes, indices, animations) tient dans un scenario.json. Le décor 3D est un « monde » dont les objets sont nommés.
Jouer
- Sans rien installer : double-cliquer sur
dist/index.html. Le jeu tient dans ce seul fichier. - En développement (Node 20.19+ requis) :
npm install npm run dev # serveur avec rechargement à chaud npm run build # régénère dist/index.html - Petite config : ajouter
?quality=lowà l'URL, ou exécuterlocalStorage.setItem('escape-game:quality','low')dans la console. Ce mode désactive les ombres et le bloom, et rend en pleine résolution simple.
Commandes
| Action | Contrôle |
|---|---|
| Examiner / zoomer | clic sur un élément (le curseur change et l'objet est surligné) |
| Tourner à gauche ou à droite | flèches sur les bords gauche et droit de l'écran |
| Reculer | flèche en bas de l'écran, clic droit ou Échap |
| Utiliser un objet | clic sur l'objet dans l'inventaire, puis sur la cible |
| Combiner deux objets | clic sur un objet de l'inventaire, puis sur un autre objet de l'inventaire |
| Fermer un message | clic n'importe où (ou Échap) |
| Carnet d'indices | bouton Carnet ou C ; « Noter dans le carnet » sous les messages qui révèlent un indice |
| Indice progressif | bouton Indice ou H |
| Mode debug | D : caméra libre (glisser = orbiter, molette = zoom). Affiche l'objet visé et le point 3D. C copie le point de vue en JSON "camera" |
La partie est sauvegardée automatiquement dans le navigateur (bouton « Continuer » dans le menu).
Difficulté (au lancement d'une partie) :
- Facile : les objets interactifs s'entourent d'un contour doré et affichent leur nom au survol ;
- Difficile : aucun indice visuel sur les objets (ni contour, ni nom, ni changement de curseur). Seules les flèches de navigation restent indiquées.
Le chapitre 1 : le bureau du professeur
Cinq énigmes enchaînées, pour 15 à 20 minutes de jeu. Attention, la solution est détaillée ci-dessous.
Solution
- Combinaison : une lampe UV dans les tiroirs gauches du bureau, des piles dans le vase. On combine les deux dans l'inventaire pour obtenir une lampe UV allumée.
- Déchiffrement : on éclaire le tableau avec la lampe UV pour révéler un message. On l'ouvre, puis on tourne la roue de César jusqu'au décalage 7 : « Le coffre s'ouvre à l'heure où le temps s'est arrêté ».
- Cadenas à molettes, en bas de la bibliothèque : l'horloge est arrêtée à 10 h 40, le code est donc 1-0-4-0. On tente l'ouverture avec la poignée (clic droit sur une molette : chiffre précédent). Le coffret contient une manette.
- Mécanisme : on installe la manette sur le disjoncteur (mur ouest), puis on la relève. Le plafonnier s'allume et le boîtier est sous tension.
- Code couleur : les chiffres 1 (jaune, dans le tableau), 2 (rouge, sur un livre), 3 (bleu, au mur nord) et 4 (vert, près de la porte) donnent la combinaison du boîtier. Elle ouvre le tiroir secret du bureau, qui contient la clé de la porte.
Tests
| Commande | Durée | Ce qu'elle vérifie |
|---|---|---|
npm test |
~1 s | Moteur et scénarios sans navigateur : références, cohérence logique, paramètres des mini-jeux, et la solution de référence (walkthrough.json) rejouée jusqu'à la victoire |
npm run check |
~5 s | Typage + npm test + build |
npm run smoke |
~1 min | Rejoue la solution avec de vrais clics dans le jeu 3D construit (mode ?test=1) : objets 3D introuvables, zones masquées, erreurs console, écran de victoire, et aucun shader ni texture préparé en cours de partie (sinon, à-coups) |
Options du smoke test : npm run smoke -- --shots (une capture par scène dans tests/shots/), --hard, --chapter chapitre1, --headed. Il a besoin de Playwright (npm i -D playwright && npx playwright install chromium).
La cohérence logique (src/engine/scenarioAnalysis.ts) détecte notamment :
- un drapeau testé mais jamais levé (faute de frappe) ;
- un objet jamais donné ou qui ne sert à rien ;
- une variable jamais modifiée ;
- une énigme impossible à ouvrir ;
- une scène inaccessible ;
- l'absence de condition de victoire.
Chaque chapitre a sa solution de référence dans walkthrough.json, une suite d'étapes comme { "click": "desk" }, { "use": "key", "on": "lock" }, { "combine": [a, b] } ou { "solve": "cipher" }, chacune avec des vérifications expect optionnelles. Si on modifie l'enchaînement des énigmes, il faut mettre ce fichier à jour.
Mode test du rendu : dist/index.html?test=1 passe en basse qualité, sans animation de caméra ni d'objets.
Architecture
src/
engine/
types.ts format JSON d'un scénario
state.ts état de partie, conditions, sauvegarde
Engine.ts logique : interactions, actions, indices (aucun rendu)
BaseRenderer.ts UI : HUD, inventaire, messages, mini-jeux, flèches, debug
three/ThreeRenderer.ts rendu 3D : caméras, raycast, surlignage, objets animés
scenarioLoader.ts chargement et validation des références
scenarioAnalysis.ts cohérence logique d'un scénario
walkthrough.ts rejoue une solution de référence sans rendu
cursors.ts curseurs (examiner, prendre, flèches...)
audio.ts bruitages synthétisés (provisoires)
puzzles/
registry.ts contrat d'un mini-jeu
colorCode.ts mini-jeu « code couleur »
caesar.ts mini-jeu « roue de César »
worlds/
bureau.ts la pièce 3D construite par code (objets nommés)
textures.ts textures procédurales (canvas)
scenarios/
chapitre1/ scenario.json, walkthrough.json, images/ (icônes)
tests/
engine.test.ts mécaniques du moteur (variables, déclencheurs, combinaisons...)
scenarios.test.ts contrôles de tous les chapitres + solution de référence
smoke.cjs partie complète dans le navigateur (Playwright)
Le format du scénario
- Scène : un point de vue,
"camera": { "position", "target", "fov" }. Les raccourcisleft,rightetbackgénèrent les flèches de navigation. - Zone cliquable :
"object": "nomObjet", le nom d'un objet du monde 3D. L'objet le plus précis l'emporte : cliquer sur la serrure, qui fait partie de la porte, déclenche la zone « serrure ». - Conditions :
flag:x,item:x,selected:x,solved:x, etvar:x=3(également!=,>=,<=,>,<), avec!pour la négation. - Actions :
{ "goto" },{ "message" },{ "setFlag" },{ "give" },{ "remove" },{ "puzzle" },{ "sound" },{ "win" };- les variables :
{ "add": "molette1", "mod": 10 }et{ "set": "x", "value": 0 }; - les conditionnelles :
{ "if": [...], "then": [...], "else": [...] }. - les messages : par défaut, une observation (en difficile, le joueur peut la noter au carnet) ;
{ "message": "…", "info": true }pour un retour d'action ou une consigne, jamais notable. Les messages du moteur (intro, « ne sert à rien », combinaison ratée,unusabled'un objet, indices H) sont toujours informatifs ; - le carnet :
{ "clue": "id" }après un message lie ce message à un indice desclues(noté d'office en facile).
- Props : l'état visuel des objets selon les conditions (
visible,offset,rotation,emissive), ou selon une variable (spin: une molette tourne destepradians par unité). Tout est animé : tiroir qui coulisse, porte qui s'ouvre, molettes, voyants, plafonnier. - Déclencheurs (
triggers) : des actions exécutées une seule fois, dès que leurs conditions deviennent vraies. Par exemple, un déclic quand un mécanisme se débloque. - Combinaisons (
combinations) : deux objets d'inventaire et les actions à exécuter quand on les combine. - Variables initiales (
vars) : par exemple, la position de départ des molettes. - Indices (
clues) : textes que le joueur peut noter dans son carnet. L'action{ "clue": "id" }, placée après un message, ajoute le bouton « Noter dans le carnet ». - Lampe UV (
uvLight) : objet qui, tenu en main, projette un halo sous la souris. Les surfaces en encre invisible (invisibleInk()dans le monde) n'apparaissent que dans ce halo, jusqu'à leur révélation par la propreveal. - Objet obtenu : toute action
givedéclenche l'annonce centrale « Objet obtenu » et fait clignoter la case.
Choix structurants
Enginene connaît aucun rendu. Il parle à une interfaceView.- Le monde référence ses objets par leur nom.
bureau.tsconstruit la pièce par code. Un modèle Blender exporté en.glbavec les mêmes noms d'objets pourrait le remplacer sans toucher au scénario. - Le rendu se fait à la demande. On ne redessine que pendant un mouvement ou après un changement, ce qui laisse le GPU au repos le reste du temps.
- Des zones invisibles agrandissent les petites cibles. Ces zones (clé, chiffre peint dans le tableau) vivent sur un calque à part : le raycast les voit, la caméra non.
- Deux familles d'énigmes. Les mécanismes dans le décor (molettes, disjoncteur) se font uniquement en JSON, avec les variables, les props et les déclencheurs. Les mini-jeux en surimpression (
colorCode,caesar) sont des types réutilisables paramétrés en JSON. Pour créer un nouveau type, il suffit d'appelerregisterPuzzle('monType', factory). - Le validateur signale en console les références cassées : scène, objet d'inventaire, puzzle, image, ou objet 3D introuvable.
Ajouter du contenu
- Ajouter l'objet nommé dans le monde (
worlds/*.ts). - Lancer le jeu, appuyer sur
D, cadrer la vue à la souris, puisCpour copier la caméra. - Déclarer la scène et ses
hotspotsdansscenario.json. - Mettre à jour
walkthrough.jsonsi l'enchaînement change, puis lancernpm run checketnpm run smoke.
Un nouveau dossier dans src/scenarios/ apparaît automatiquement comme nouveau chapitre dans le menu.
Pistes suivantes
- Faire jouer la pièce complète à quelques testeurs pour équilibrer les indices et la difficulté.
- Trancher entre web et Godot.
- Charger un
.glbmodélisé dans Blender à la place du monde procédural. - Ajouter d'autres types de mini-jeux : taquin, ordre de symboles, mécanismes plus riches.
- Ajouter de vrais sons et une musique d'ambiance.
- Empaqueter en application desktop (Electron ou Tauri), avec Steam en ligne de mire.
- Construire l'éditeur de niveaux sur le format
types.ts.