153 lines
11 KiB
Markdown
153 lines
11 KiB
Markdown
# 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) :
|
|
```bash
|
|
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 |
|
|
| 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.
|
|
|
|
<details>
|
|
<summary>Solution</summary>
|
|
|
|
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. On tente l'ouverture avec la poignée (clic droit sur une molette : chiffre précédent). Le coffret contient une manette.
|
|
4. **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.
|
|
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.
|
|
|
|
</details>
|
|
|
|
## 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 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": [...] }`.
|
|
- 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, `unusable` d'un objet, indices H) sont toujours informatifs ;
|
|
- le carnet : `{ "clue": "id" }` après un message lie ce message à un indice des `clues` (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 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, 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 prop `reveal`.
|
|
- **Objet obtenu** : toute action `give` déclenche l'annonce centrale « Objet obtenu » et fait clignoter la case.
|
|
|
|
### 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`.
|