LifePlay-Revival/Docs/Migration/19_Plan_Outillage_Debug.md

19 — Plan d'outillage debug (pilotage)

Plan de lot révisé (game manager + senior). Procédure opérationnelle et mesures : 18_Build_Debug.md. Skill agent : .cursor/skills/lifeplay-debug-build/. Protocole lots : 10_Protocole_Operations.md.

État : gates I0–I6 mesurés (voir §4 et relevés dans 18). Prochain lot d'optimisation proposé : G6 (pas O10 en premier) — décision dans 18 § mesures.

---

1. Brief production (game manager)

Mission

Livrer une capacité de mesure reproductible (pipeline + preuves), pas une optimisation joueur. Après ce lot, l'équipe peut décider quoi corriger (G6 à-coups, O10 physique) avec des chiffres, pas au feeling.

Succès (Definition of Done globale)

Le lot est terminé seulement si :

1. Un tiers (ou un agent futur) peut packager DebugGame/Development et lancer sessions A/B/C sans scripts hors dépôt.
2. Trois jeux de preuves archivés (Dbg-I4, Dbg-I5, Dbg-I6) sous D:\Game\LifePlay_Backup_5.5\.
3. Une note chiffrée classe les priorités suivantes (G6 vs O10 vs autre) — décision, pas encore le fix.
4. Shipping inchangé en comportement joueur (IncludeDebugFiles=False, pas de coût runtime Shipping).
5. Skill + 18_Build_Debug.md alignés sur le livré.

Hors scope (explicitement)

Inclus	Exclu jusqu'à preuves I4–I6
Scripts packaging / lanceurs / collecte	Optimisation GI / timers / async load
Sous-système debug non-Shipping	Refonte collisions ville / LOD / morphs
Doc + skill	Montée UE 5.8 (préparer seulement la portabilité)
Mesure G6 / Physics	Intégration Tracy / Optick / ASAN / ImGui
Outils gratuits documentés	Builds Shipping « debug » pour joueurs

Priorité joueur (pourquoi ce lot)

Signal existant (O0/O9)	Impact ressenti	Ce lot livre
À-coups GameThread (G6)	Stutters irréguliers	Preuve nommée → backlog fix priorisé
Physics ~463 Mo (O0) ; ~172 Mo session B post-O9	Risque machines modestes	Chiffre Physics + CVD → backlog O10
Régime 16,7 ms	OK aujourd'hui	Garde-fou non-régression (I6)

Règle produit : ne pas ouvrir un lot d'optimisation tant que I4 (hitches) et I5 (mémoire) n'ont pas leurs gates verts.

Effort et dépendances (ordre de grandeur)

Phase	Effort estimé	Qui	Dépendance
I0 skill	15 min	Agent	—
I1 scripts + 1er cook DebugGame	0,5–1 j (+ cook long)	Agent ; cook machine	UE 5.5, Content/Heavy dispo
I2 C++ + compile / smoke	0,5 j	Agent	I1 ou Editor Development pour smoke
I3 doc + sync skill	0,25 j	Agent	I1–I2 stabilisés
I4 / I5 / I6 playtests	3× ~20–30 min jeu + analyse	Utilisateur joue ; agent archive/analyse	Builds prêtes

Chemin critique : temps de cook DebugGame + disponibilité playtest humain.

Risques production

Risque	Impact	Mitigation
Cook DebugGame très long / échec	Bloque I1	Smoke I2 en Editor d'abord ; -SkipBuild / iterate ; un seul cook DebugGame pour I4–I5
Confusion DebugGame vs Dev sur les ms	Fausses régressions	Dual-build documenté ; I6 = Development only vs O0
Instrumentation fuit dans Shipping	Perf / logs joueur	#if !UE_BUILD_SHIPPING strict ; pas de changement DefaultGame.ini Shipping
Scope creep « on corrige GI tout de suite »	Lot interminable	Hors scope ; nouveau lot après I6
Trace Insights trop lourde	Machine saturée (déjà vu O9)	Trace courte ciblée ; channels limités ; bookmarks
Playtest non standard	Mesures incomparables	Scénario O0 figé 15 min ; même type de save

Gouvernance

• Protocole lots : 10_Protocole_Operations.md (tag, snapshot, journal).
• Skill obligatoire : .cursor/skills/lifeplay-debug-build/.
• Go / No-Go à chaque gate In : critères verts ou stop + re-mesure.
• Commit : uniquement si demandé ; un sous-lot = un objectif mesuré.

---

2. Brief technique (senior gameplay / engine)

Principes

1. Zero cost Shipping — tout debug derrière !UE_BUILD_SHIPPING ; flags CLI opt-in.
2. Réutiliser ULPSessionLogSubsystem patterns (FParse, FAutoConsoleCommand, FName categories).
3. Pas de modification Blueprint GI dans ce lot — C++ subsystem + ModdingExtra hotspots only.
4. DebugGame rare — un cook pour plongée ; itération code en Editor/Development.
5. Portable 5.8 — Insights/ChaosVD/CSV + attach process ; pas de plugin profiler tiers.

Architecture cible

flowchart TB
  subgraph mgmt [DoD_produit]
    Proof[Preuves_A_B_C]
    Decision[Priorite_G6_vs_O10]
  end
  subgraph pipe [Pipeline]
    BuildPs[BuildDebug.ps1]
    Bats[Tools/debug_bats]
    Collect[CollectDebugArtifacts.ps1]
  end
  subgraph runtime [Runtime_non_Shipping]
    LPDebug[ULPDebugSubsystem]
    Named[SCOPED_NAMED_EVENT_LoadTxt_Cache]
    SessLog[ULPSessionLogSubsystem_existant]
  end
  BuildPs --> Bats
  Bats --> LPDebug
  Bats --> SessLog
  Named --> Insights[UnrealInsights]
  LPDebug --> Insights
  Bats --> Collect
  Collect --> Proof
  Proof --> Decision

Dual-build

Config	Rôle	Comparer ms absolus
Development	Baseline chiffrée / I6 vs O0	Oui
DebugGame	Plongée I2/I4/I5 (checks, PDB)	Non
Shipping	Joueurs	Hors lot

Livrables techniques

Livrable	Contenu clé
Tools/BuildDebug.ps1	-Config DebugGame|Development, pas -nodebuginfo, stage des bats
Tools/CollectDebugArtifacts.ps1	-Lot -BuildDir -Session → backup
Tools/debug/*.bat	Sessions A/B/C + bugs/gpu/collision
ULPDebugSubsystem	Hitch + bookmark + MemSnapshot + CollisionDump
Named events	LoadTxt, LPDataCache
18_Build_Debug.md	Procédure + mesures + Agent/skill

Sessions de capture

Scénario unique (O0 §5, ~15 min) : save avancée → carte → intérieur → extérieur → multi-PNJ → quit.

Session	Build	Gate métier
A	DebugGame	Top contributeurs hitch chiffrés
B	DebugGame	Physics Mo + CVD ou dump collision
C	Development	Non-régression vs O0 (médiane ~16,7 ms)

Auxiliaires hors chemin critique : bugs / gpu (PIX ou RGP) / collision.

Stack outils (gratuite, pas de trial)

Insights + Memory Insights, CSV/LLM, ChaosVD, RenderDoc, PIX, Radeon RGP/RMV, µProf, VS Diagnostics.
Écartés : Tracy, Optick, ASAN, Superluminal, Nsight par défaut (machine AMD).

Détail : .cursor/skills/lifeplay-debug-build/reference.md.

Pièges techniques connus

• Jamais -csvCaptureFrames (crash RHI).
• Mesurer packaged, pas Editor -game, pour I6.
• Shipping NO_LOGGING — ne pas s'y fier pour l'analyse.
• Traces Insights lourdes : rester court + bookmarks.
• I6 sans -LPHitchLog (overhead off by default).

---

3. Skills (obligatoire agent)

Skill	Usage
SKILL.md	Lire avant tout code (I0)
reference.md	Flags, chemins, mapping symptôme→outil

Ne pas diverger (mega-lanceur, Tracy, rebuild DebugGame systématique) sans maj skill + ce plan.

---

4. Planning itératif mesurable

Règle de sortie

On ne quitte In que si tous les critères de mesure sont verts.
Code sans artefact / impression en jeu = rouge.
Rouge → corriger → re-mesurer. Pas de skip vers In+1.

flowchart LR
  I0[I0] --> I1[I1]
  I1 --> G1{Gate}
  G1 -->|non| I1
  G1 -->|oui| I2[I2]
  I2 --> G2{Gate}
  G2 -->|non| I2
  G2 -->|oui| I3[I3]
  I3 --> G3{Gate}
  G3 -->|non| I3
  G3 -->|oui| I4[I4]
  I4 --> G4{Gate}
  G4 -->|non| I4
  G4 -->|oui| I5[I5]
  I5 --> G5{Gate}
  G5 -->|non| I5
  G5 -->|oui| I6[I6]
  I6 --> G6{Gate}
  G6 -->|non| I6
  G6 -->|oui| DoD[DoD_lot]

Statut des gates

Itération	Objectif	Gate (résumé)	Statut
I0	Skill	Procédure partagée	Fait
I1	Pipeline scripts	Build + Collect smoke	Fait
I2	ULPDebugSubsystem	Hitch / bookmark / MemSnapshot	Fait
I3	Doc 18 + skill sync	Doc = réalité	Fait
I4	Session A	utrace + hitches chiffrés G6	Fait — voir 18
I5	Session B	Physics Mo + CVD	Fait — voir 18
I6	Session C vs O0	Médiane ≤ 17 ms, hitches	Fait — voir 18

Détail des itérations

I0 — Alignement

• Owner : Agent
• Mesure : skill lu ; scope hors Tracy/mega-lanceur confirmé

I1 — Pipeline (P0 technique)

• Livrables : BuildDebug.ps1, CollectDebugArtifacts.ps1, bats
• Gate : UAT DebugGame OK + exe + bats staged + Collect smoke → backup non vide

I2 — Runtime debug (P0 technique)

• Livrables : ULPDebugSubsystem + named events ; Shipping-safe
• Gate : compile clean ; hitch log ; Bookmark ; MemSnapshot non vide

I3 — Doc / skill = réalité

• Gate : noms bats/flags identiques doc↔skill↔Tools ; section Agent ; piège CSV documenté

I4 — Mesure G6 hitches (P0 produit)

• Owner : Utilisateur (jeu) + Agent (analyse)
• Gate : .utrace ; bookmarks/hitch alignés ; top contributeurs avec ms/% ; Collect OK
• Livrable décision : causes candidates classées

I5 — Mesure Physics / fuites (P0 produit)

• Gate : Physics Mo ; MemReport ; CVD ou CollisionDump ; delta mémoire ; Collect OK

I6 — Non-régression Development

• Gate : CSV ≥1×9000 frames ; LLM ; tableau vs O0 ; médiane ≤17 ms (±1) ou écart causé ; Collect OK
• Sans -LPHitchLog

Après DoD

Lots suivants (chacun avec baseline avant/après) :

1. Fix G6 (étalement ExecuteUbergraph_GI / City, PopulateRaws) — priorité décidée en I4/I6
2. O10 collisions / trimesh — après G6
3. Montée 5.8 — réutiliser cette pipeline

---

5. Critères d'acceptation (checklist manager)

• Aucun changement comportement Shipping joueur
• Scripts versionnés ; plus de dépendance à LifePlay_profil_O0.bat hors repo
• I4 + I5 + I6 verts avec backups
• Décision écrite G6 vs O10 (priorité prochain lot) — dans 18_Build_Debug.md
• Skill + doc 18 synchronisés
• Temps cook / playtest consigné au journal (Journal_Modifications.md) si publication du lot

---

6. Ordre d'exécution (référence)

1. I0 skill
2. I1 scripts ; cook DebugGame
3. I2 C++ ; recook DebugGame si besoin
4. I3 doc + sync skill
5. I4 → gate → I5 → gate → I6 → gate
6. Revue DoD + proposition du prochain lot d'optimisation