Vibe code an escape game to see the potential
Go to file
Julien Quiaios d2b777d8d1 first commit 2026-10-24 09:46:11 -04:00
src first commit 2026-10-24 09:46:11 -04:00
tests first commit 2026-10-24 09:46:11 -04:00
.gitignore first commit 2026-10-24 09:46:11 -04:00
CLAUDE.md first commit 2026-10-24 09:46:11 -04:00
README.md first commit 2026-10-24 09:46:11 -04:00
index.html first commit 2026-10-24 09:46:11 -04:00
package-lock.json first commit 2026-10-24 09:46:11 -04:00
package.json first commit 2026-10-24 09:46:11 -04:00
tsconfig.json first commit 2026-10-24 09:46:11 -04:00
vite.config.ts first commit 2026-10-24 09:46:11 -04:00
vitest.config.ts first commit 2026-10-24 09:46:11 -04:00

README.md

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écuter localStorage.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
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 : seul le curseur change, et 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
  1. 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.
  2. 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é ».
  3. 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. Le coffret contient une manette.
  4. Mécanisme : on installe la manette sur le disjoncteur (mur ouest), puis on l'abaisse. Le plafonnier s'allume et le boîtier est sous tension.
  5. 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

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 raccourcis left, right et back gé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, et var: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": [...] }.
  • Props : l'état visuel des objets selon les conditions (visible, offset, rotation, emissive), ou selon une variable (spin : une molette tourne de step radians 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, le coffret s'ouvre quand les 4 molettes affichent le bon code.
  • 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.

Choix structurants

  • Engine ne connaît aucun rendu. Il parle à une interface View.
  • Le monde référence ses objets par leur nom. bureau.ts construit la pièce par code. Un modèle Blender exporté en .glb avec 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'appeler registerPuzzle('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

  1. Ajouter l'objet nommé dans le monde (worlds/*.ts).
  2. Lancer le jeu, appuyer sur D, cadrer la vue à la souris, puis C pour copier la caméra.
  3. Déclarer la scène et ses hotspots dans scenario.json.
  4. Mettre à jour walkthrough.json si l'enchaînement change, puis lancer npm run check et npm 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 .glb modé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.