escape_game/CLAUDE.md

4.1 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.

Mode économe (par défaut)

Objectif : préserver les tokens de l'utilisateur. Le jugement visuel et les tests en jeu, c'est lui qui les fait.

  • Une session par fonctionnalité. Le contexte utile est dans ce fichier, dans le README et dans la note du projet : ne pas relire tout le code, seulement les fichiers concernés.
  • Vérification de ma part : uniquement npm run check. Pas de npm run smoke, pas de captures d'écran, pas de navigateur, sauf demande explicite de l'utilisateur.
  • Après chaque modification, dire précisément quoi tester en jeu (scène, action, résultat attendu). L'utilisateur teste avec npm run dev sur sa machine et remonte les problèmes, avec une capture si besoin.
  • Pas d'envoi de build dist/ : l'utilisateur lance npm run dev lui-même.
  • Modifications ciblées (Edit, sed, petits scripts) plutôt que la réécriture de fichiers entiers ; lire seulement les portions utiles des gros fichiers (bureau.ts, ThreeRenderer.ts).
  • Réponses courtes. La note du projet n'est mise à jour que si une décision change.
  • Commit une fois npm run check vert. Pour un changement qui touche la 3D ou l'interface, attendre le retour de l'utilisateur. Push : c'est l'utilisateur qui le fait (le SSH sortant est bloqué depuis la VM).

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.