escape_game/CLAUDE.md

2.8 KiB

Consignes pour Claude : projet Escape Game

Escape game point & click 3D (three.js, caméras fixes), piloté par src/scenarios/<chapitre>/scenario.json. Voir le README pour le format.

Versionnage Git (règle n° 1)

Le dépôt de référence est le dossier de l'utilisateur (D:\Code\claude\escape_game, branche main, remote origin en SSH).

  • Avant toute modification, lancer git status :
    • si l'arbre est propre, on commence ;
    • si des changements sont en cours et que la demande est un fix ou un ajustement de la fonctionnalité ou du bug en cours, on continue sur ces changements ;
    • sinon, on ne commence pas : on signale les changements en cours et on demande de les versionner (commit) ou de les abandonner.
  • Une modification = un commit, avec un message en français au format type: résumé. Types : feat, fix, perf, refactor, test, docs, chore.
  • Avant de commiter : npm run check doit être vert, et npm run smoke aussi si la 3D, le rendu ou l'UI ont changé.
  • Essais risqués : sur une branche dédiée essai/<nom>, pour revenir facilement en arrière.
  • Interdit sans accord explicite : git push, ainsi que toute réécriture d'historique (reset --hard, rebase, push --force).
  • dist/ n'est pas versionné : il se régénère avec npm run build.

Vérifier une modification (du plus rapide au plus lent)

  1. npm run check (~5 s) : typage, tests de logique, build. À lancer après chaque modification.
  2. npm run smoke (~1 min) : la solution de référence rejouée avec de vrais clics 3D. À lancer seulement si la modification touche le monde 3D (src/worlds/), le rendu, les caméras ou l'UI.
  3. Captures ciblées : npm run smoke -- --shots, puis regarder seulement les vues concernées dans tests/shots/.

Règles

  • Ne jamais rejouer une partie à la main avec des scripts ad hoc : passer par walkthrough.json et tests/smoke.cjs.
  • En environnement sans GPU, toujours utiliser ?test=1 (pas d'animation, basse qualité). Le rendu 3D est très lent en logiciel.
  • Délais d'attente courts (smoke : 20 s par action) : un test bloqué est un test en échec.
  • Si l'enchaînement des énigmes change, mettre à jour walkthrough.json dans le même changement.
  • Un nouveau type de mini-jeu doit avoir un contrôle dans tests/scenarios.test.ts (checkPuzzle) et une résolution dans tests/smoke.cjs.
  • Le jugement visuel final (lumière, ombres, fluidité) revient à l'utilisateur, sur sa machine.
  • Performance : tout est préparé au chargement par ThreeRenderer.warmUp() (shaders, textures, géométries). Une lumière pilotée par les props s'éteint (intensité 0) au lieu d'être masquée, car changer le nombre de lumières recompile tous les shaders. Le smoke test échoue si un shader ou une texture est préparé en cours de partie.