# BIG EGG — directives opérationnelles Ce fichier est chargé dans le contexte des agents. Il reste volontairement court : les récits, historiques et règles spécialisées sont dans les documents référencés à la fin. Lire ce fichier **une fois par fil de travail**, pas à chaque message. Après une compaction, ne le relire que si son contenu n'est plus présent dans le résumé ou s'il a changé sur disque. Langue de travail : français. Identifiants et commentaires de code : anglais, comme le code existant. ## 1. Projet actif - Travailler uniquement dans `big-egg-3d/`. - `big-egg/` est une référence 2D en lecture seule. - Racine : `E:\GDRIVE\SERVEUR ET PRODUCTION WEB\2025\REBIRTH\BIG EGG`. - Godot : `C:\Users\ELR17\Downloads\Godot_v4.7.1-stable_win64.exe\Godot_v4.7.1-stable_win64_console.exe`. - Dépôt Git **local** depuis le 17/09/2026, pour `big-egg-3d/` seulement. Sa base vit hors de Drive et le `.git` du projet n'est qu'un pointeur : ne jamais le convertir en dossier synchronisé. Aucun dépôt distant, aucun push. Décision et règles de relève : `big-egg-3d/AGENTS.md`; commandes : `big-egg-3d/tools/dev/README.md`. - Préserver les modifications existantes et ne jamais tuer l'éditeur Godot ouvert par l'utilisateur. - **Le dépôt est le filet de sécurité.** Tout ce qui compte y est suivi, y compris `data/game_data_master.json` et `draft.json`. Avant un chantier risqué — schéma, données maîtres, refonte multi-système — faire un **commit de point de reprise**, pas une copie de dossier. - **Ne pas faire de copie complète de `big-egg-3d/`.** Elle recopie `big-egg-3d/_backups/`, qui pèse à lui seul plus de 7 Go : une telle copie atteint 8,5 Go pour 800 Mo de projet réel, et déclenche des heures de synchronisation Drive. Mesuré le 22/09/2026, directive corrigée en conséquence — elle datait d'avant le dépôt. - **Sauvegarde hebdomadaire complète** (décision du 30/09/2026) : au moins une par semaine, avec un rapport des travaux depuis la précédente dans `big-egg-3d/docs/rapports/`. Seule voie : `dev.py backup`, qui archive hors Drive sans `_backups/` et copie l'historique Git sur Drive. `dev.py resume` signale quand elle est due : la proposer à l'auteur. Procédure : `big-egg-3d/tools/dev/README.md`. - Ce que le dépôt ne couvre pas est listé dans `.gitignore` : `_backups/`, `.godot/`, `/exports/`, `tools/dev/runs/`, `tools/meshy/meshy_output/` et les journaux. Rien d'irremplaçable. - Le vrai risque restant n'est pas la panne mais **une commande git destructrice** sur les données d'auteur, qui édite en parallèle dans son navigateur. La parade est une copie ciblée des deux fichiers de données dans le scratchpad avant toute migration, jamais un miroir du projet. ## 2. Lecture progressive — ne pas charger tout le projet Inspecter les fichiers réels, mais ne lire que les références nécessaires : | Tâche | Référence à ouvrir | |---|---| | Nouvelle fonction débloquée par un meuble | `docs/contrat-deblocage-meubles.md` | | Variables, statistiques, effets | `docs/architecture-variables.html` | | Donjon, salles, dimensions | `docs/architecture-donjon.html` | | Brigade et employés | `docs/architecture-employes.html` | | Visuels et sprites | `docs/architecture-visuels.html` | | Génération PixelLab | `docs/pipeline-pixellab.md` | | Pont 3D | `big-egg-3d/LISEZMOI-3D.md` | | Sons, musique, ambiance | `big-egg-3d/docs/systeme-audio.md` | | Capacités spéciales des monstres | `big-egg-3d/docs/capacites-speciales.md` | | Touches, menus, pause, Retour, menu neuf | `big-egg-3d/docs/mapping-touches.md` | | Carte du resto, ajout auto, cadenas d'ingrédient | `big-egg-3d/docs/carte-et-cadenas.md` | | Ancienne décision à rouvrir | `docs/journal-conception.md`, section ciblée | | Passe narrative dans Déroulé (questionnaire, cartes) | `big-egg-3d/docs/passe-narrative-deroule.md` (skill `/passe-deroule`) | | « Billet N » (ou « ligne N »), bug ou idée de l'auteur (outil Chantiers) | section 8 ci-dessous | L'ancienne version complète de ces directives est conservée dans `docs/directives-detaillees-archive-20260828.md`. C'est une archive de recherche, pas une lecture obligatoire. Utiliser `rg` pour trouver la section pertinente. ## 3. Validation proportionnée Une validation finale suffit. Pendant l'implémentation, lancer seulement le contrôle le plus petit qui éclaire l'erreur en cours. Ne pas relancer une suite verte après une modification qui ne touche ni le code ni les données testées. | Niveau | Changement | Validation finale | |---|---|---| | 0 | documentation, commentaires, sauvegarde | aucune | | 1 | script local sans règle ni donnée | contrôle unique de la zone | | 2 | règle, entité, interaction, texte | `smoke_test` + contrôle distinct de la zone | | 3 | schéma, maître JSON, autoload, `project.godot`, outil | contrôles réellement touchés, puis batterie complète si l'impact est transversal | Dédupliquer : si le contrôle de zone est déjà `smoke_test`, « smoke + zone » signifie **un seul smoke test**. Plusieurs fichiers déjà modifiés dans le dossier ne justifient pas de tester leurs zones si le chantier courant ne les touche pas. | Zone | Contrôle | |---|---| | règles du jeu, restaurant, clients, économie, donjon | `smoke_test` | | pont 3D, avatars, caméra, attaques, butin affiché | `bridge_3d_check` | | menu, changement de scène, clavier/manette | `bridge_3d_flow_check` | | persistance à travers un changement de scène | `upgrade_return_smoke` | | outil de données JS | test JS ciblé du même domaine | | validation/publication PHP | test PHP ciblé | | formes 3D | `mirror_test.php` | Commandes Godot, depuis la racine : ```powershell $godot = 'C:\Users\ELR17\Downloads\Godot_v4.7.1-stable_win64.exe\Godot_v4.7.1-stable_win64_console.exe' & $godot --headless --path 'big-egg-3d' 'res://scenes/main/smoke_test.tscn' & $godot --headless --path 'big-egg-3d' 'res://scenes/main/upgrade_return_smoke.tscn' --quit-after 3 & $godot --headless --path 'big-egg-3d' 'res://scenes/main/bridge_3d_check.tscn' & $godot --headless --path 'big-egg-3d' 'res://scenes/main/bridge_3d_flow_check.tscn' ``` - Préférer `python tools/dev/dev.py check --area ...` depuis `big-egg-3d/`. Les commandes brutes ci-dessus lisent **et réécrivent** la vraie sauvegarde du joueur; le runner donne à chaque contrôle son propre `APPDATA`, et signale une erreur repérée dans les logs même si le test imprime « OK » et sort avec zéro. - Un test neuf doit échouer une fois avec la régression réintroduite, puis passer après restauration. Faire ce rouge/vert **une seule fois à sa création**. - Un échec isolé de physique sensible au timing se confirme par une seconde exécution. Les autres échecs ne se relancent pas sans changement explicatif. - Le smoke test normal prend environ 6 à 10 secondes. - Le parse éditeur complet n'est pas un prérequis systématique. Les scènes de contrôle parsèrent déjà leurs dépendances. ### Éditeur headless et MCP Ne jamais lancer `godot --headless --editor` pendant qu'un éditeur graphique du même projet sert le MCP. Le toolkit utilisait le même registre et le même jeton, ce qui forçait ensuite une désactivation/réactivation manuelle. Le plugin local ignore désormais les éditeurs headless pour empêcher ce conflit. Un parse éditeur complet est réservé à un nouveau `class_name`, un autoload, une scène non couverte ou un niveau 3. Éditeur graphique fermé : le lancer en headless. Éditeur graphique ouvert : ses diagnostics LSP/MCP, puisque le headless `--editor` est alors interdit (voir plus haut). ```powershell & $godot --headless --editor --path 'big-egg-3d' --quit ``` **Headless/CLI d'abord** (directive du 30/09/2026) : quand le MCP n'est pas indispensable, passer par `dev.py`, une scène de contrôle headless ou un script CLI. Le MCP reste pour ce que seule une session vivante montre : capture, clic, état d'une scène ouverte, diagnostics quand le headless `--editor` est interdit. Après une commande headless ordinaire, ne pas « réparer » le MCP sans preuve de panne. Un seul contrôle suffit : listener éditeur, entrée de registre et connexion cliente. Ne recourir à l'automatisation de l'interface que si un appel MCP réel échoue après ces vérifications. ## 4. Discipline de contexte et de sortie - Utiliser `rg` ciblé. Exclure par défaut `_backups/`, `big-egg/`, `.godot/`, `node_modules/`, les addons tiers et les fichiers binaires/SVG volumineux. - Ne jamais imprimer un arbre ou un gros fichier entier quand un motif ou une plage de lignes suffit. - Borner les sorties de commandes et sélectionner les champs nécessaires avant `ConvertTo-Json`. - PowerShell : ne jamais sérialiser directement la sortie enrichie de `Get-Content`, `Get-Item`, `Get-Process` ou `Get-CimInstance`. Convertir le contenu en `[string]` et appliquer `Select-Object` aux objets. Une sérialisation accidentelle de métadonnées de fournisseur peut produire des dizaines de Mo. - Pour un diagnostic MCP, afficher les ports/PID/états, pas les objets système complets ni le catalogue de 112 outils. - Ne pas prendre de captures d'écran de l'éditeur pour naviguer si le MCP ou une vérification TCP donne déjà la réponse. ## 5. MCP Godot Les deux `.mcp.json` sont intentionnels : - `/.mcp.json` sert les agents lancés à la racine et fixe le chemin du projet; - `/big-egg-3d/.mcp.json` sert Claude lancé directement dans le projet. Ne pas en supprimer un. Le serveur expose 36 outils initiaux et garde 78 outils en groupes à la demande : ne découvrir/activer que le groupe nécessaire. Le package est épinglé à la version du plugin pour éviter une résolution npm et une mise à jour implicite pendant une session. ## 6. Invariants d'architecture essentiels - La logique 2D est l'autorité; le pont 3D ne décide d'aucune règle. `1 px = 1` unité. Un visuel ne décide jamais de la collision. - Les données d'auteur vivent dans `data/game_data_master.json`. Les valeurs calculées ont un résolveur, pas un setter. Les modificateurs sont la vérité; les valeurs finales ne se mutent pas directement. - Effets : `set -> add -> multiply`, couches `flat`, `scaling`, `global`, `override`, sources nommées (`upgrade:`, `run:`, `test:`, etc.). - Textes affichés : identifiant `Loc`, jamais nouveau littéral livré en dur. - Persistance : portées `run`, `dimension`, `meta`; `GameState.end_run()` et `complete_dimension()` sont les seuls passages structurants. - Restaurant : quatre états d'ouverture indépendants (salle/comptoir). Un rideau ne se relève jamais seul. Fermé, le trottoir continue de vivre. - Interactions : faces utilisables, teinte dorée semi-transparente sur l'objet entier; aucun tapis ni rectangle au sol. Exception : un passage (édicule, trappe, escalier) n'allume que sa porte, repérée par le nom de ses pièces (`PASSAGE_DOOR_PARTS` du pont). `Player.current_target` reste la source unique du HUD et des actions continues. - Plan de salle : `RestaurantElement` + `apply_layout()` sont l'autorité des positions, rotations, collisions et présences. Aucun meuble déplaçable ne doit dépendre d'une position codée en dur. - Fonction portée par un meuble : chaîne obligatoire `upgrade -> modificateur flat/add -> statistique *_count -> max_count_variable -> restaurant_element_open_count()`. Ne jamais écrire un effet vers `restaurant_elements`. - Donjon : une salle est l'unité écrite; un seul axe de défilement, étendue au plus `2.0`; une salle de boss ne défile pas. - `project.godot` doit rester en LF et être modifié avec prudence. Un éditeur Godot d'une autre version ne doit jamais ouvrir le projet. - Le dossier est synchronisé par Google Drive : devant une régression inexplicable, regarder d'abord `git diff` et `git log`, puis `_backups/` si la piste remonte avant le dépôt. ## 7. Méthode ### Processus d'une demande — « méthode ELR » (directive du 30/09/2026) Quand l'auteur dit « méthode ELR », c'est ce processus, sans exception de seuil (nommé ainsi le 14/10/2026). Toute demande qui modifie du code, des données ou des outils suit quatre temps. Une question, une explication ou une retouche de texte d'une ligne reçoit une réponse directe. 1. **Synthèse** : reformuler ce que j'ai compris de la demande. 2. **Analyse** : projet, paramètres de la demande, faisabilité, meilleure implémentation, processus touchés et enjeux, étapes, décisions à prendre. C'est une liste de points à examiner, pas un gabarit : un point sans question n'apparaît pas. Les décisions passent par le questionnaire à choix (`AskUserQuestion`), avec une option recommandée. 3. **Échange** : l'auteur discute ou modifie les choix. 4. **Exécution**, selon le contexte et les réponses. Des réponses qui confirment le plan valent feu vert. Une réponse qui le change sur le fond, ou une nuance qui ouvre une nouvelle question, fait représenter le plan avant d'exécuter. ### Tests délégués à un sous-agent Quand c'est possible sans fausser le résultat, confier l'**exécution** des tests à un sous-agent moins coûteux. Juger d'abord si cela vaut son coût fixe de démarrage. Un smoke test isolé de 10 secondes se lance soi-même. Une batterie longue ou une sortie volumineuse à trier vont au sous-agent. - Modèle selon le test : Haiku pour une batterie qui passe d'habitude, Sonnet quand des échecs sont attendus et qu'il faut les trier. - Le sous-agent lance `dev.py check`, lit les logs et rapporte. Il ne modifie jamais le code ni les données. Lui transmettre les échecs connus et la règle de relance des assertions instables. - Relire soi-même le verdict dans `report.json` avant de le rapporter. - Restent à l'agent principal : le rouge/vert d'un test neuf (il réintroduit la régression) et le diagnostic d'un échec. ### Règles - Diagnostiquer avant de modifier; une demande d'explication seule n'autorise pas une correction de code. - Une correction demandée inclut l'implémentation et la validation proportionnée. - Tester le geste réellement accessible au joueur, pas seulement une fonction interne. - Isoler l'état persistant des tests; ne jamais appeler `complete_dimension()` au milieu du smoke test. - `smoke_test` part de la **vraie sauvegarde du joueur et la réécrit**. Deux exécutions séparées par une partie ne sont donc pas comparables : un état de partie avancé fait tomber tout un groupe de contrôles de cuisine sans qu'aucun code n'ait bougé. Passer par `dev.py check`, qui isole l'état. - Rapporter le résultat, les tests réellement lancés et toute limite restante, sans raconter chaque commande intermédiaire. ## 8. Suivi des bugs et idées (outil Chantiers) L'auteur tient ses bugs et ses idées dans l'outil local Chantiers, qui a remplacé le Google Sheet le 14/10/2026 (billet 84). « Le billet N » désigne une fiche de cet outil (billet 98, 15/10/2026) ; « la ligne N », « le ticket N », « le suivi » et « le Sheet » restent compris. Le numéro N est l'ancien numéro de ligne du Sheet, permanent et jamais réattribué. - Page : http://localhost:8080/BIG%20EGG/big-egg-3d/tools/chantiers/ (bouton Chantiers ↗ du gestionnaire). Mode d'emploi : `tools/chantiers/README.md`. - Données : `tools/chantiers/data/chantiers.json` (suivi par Git; jamais de `git checkout` dessus). Champs : date, type (`BUG`, `idée à implémenter`, `idée à faire eventuellement`, `idée possible`), priority 1-5 (1 = urgent), status (`À Faire`, `En développement`, `Bloqué`, `Backlog`, `Terminé`), zone, details, notes, history. Les listes valides sont dans `settings`; l'auteur les modifie dans la page. - Lire : `cli.php show N` ou `rg -A 9 '"id": N,' tools/chantiers/data/chantiers.json`. Écrire : toujours par `cli.php`, signé `--by "agent billet N"`, avec le PHP de WAMP : `/c/wamp64/bin/php/php8.4.0/php.exe -n tools/chantiers/cli.php help`. - Titre facultatif (`set N title=…`). Pièces jointes de l'auteur (captures, fichiers) : `show N` donne leurs chemins absolus, les images s'ouvrent avec Read; `attach N ` / `detach N `. Rangées dans `data/attachments//`, hors Git : une pièce retirée est perdue. - Relire la fiche avant d'y travailler : l'auteur réécrit souvent ses détails. Une demande de simple analyse n'autorise aucune modification de code. - Début du travail : `set N status="En développement"`. Billet terminé, committé et testé : `set N status=Terminé` sans demander, et une `note` avec le hash du commit. Commits : « Billet N : … », puis « Chantiers : billet N terminé » pour le suivi. Nouvelle idée demandée par l'auteur : `add` (date du jour et numéro suivant automatiques). - Remue-méninges : vue « Idées » (ancien onglet « Idées abstraites »), une idée par carte, par thème; un thème renvoie à la fiche qui porte son état (Clients spéciaux → 51, Capacités spéciales → 59). Ajouter : `cli.php idea-add`. Jamais de vue dérivée (feuille de route, synthèse) sans demande. - Le Google Sheet « SUIVI BUG IDÉEs BIG EGG » est une archive figée : ne plus le lire ni l'écrire.