285 lines
11 KiB
Markdown
285 lines
11 KiB
Markdown
# 19 — Plan d'outillage debug (pilotage)
|
||
|
||
> Plan de lot révisé (game manager + senior). Procédure opérationnelle et mesures :
|
||
> [`18_Build_Debug.md`](18_Build_Debug.md). Skill agent :
|
||
> [`.cursor/skills/lifeplay-debug-build/`](../../.cursor/skills/lifeplay-debug-build/).
|
||
> Protocole lots : [`10_Protocole_Operations.md`](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`](10_Protocole_Operations.md) (tag, snapshot, journal).
|
||
- Skill obligatoire : [`.cursor/skills/lifeplay-debug-build/`](../../.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
|
||
|
||
```mermaid
|
||
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`](../../Tools/BuildDebug.ps1) | `-Config DebugGame\|Development`, pas `-nodebuginfo`, stage des bats |
|
||
| [`Tools/CollectDebugArtifacts.ps1`](../../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`](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`](../../.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`](../../.cursor/skills/lifeplay-debug-build/SKILL.md) | Lire **avant** tout code (I0) |
|
||
| [`reference.md`](../../.cursor/skills/lifeplay-debug-build/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.
|
||
|
||
```mermaid
|
||
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)
|
||
|
||
- [x] Aucun changement comportement Shipping joueur
|
||
- [x] Scripts versionnés ; plus de dépendance à `LifePlay_profil_O0.bat` hors repo
|
||
- [x] I4 + I5 + I6 verts avec backups
|
||
- [x] Décision écrite G6 vs O10 (priorité prochain lot) — dans [`18_Build_Debug.md`](18_Build_Debug.md)
|
||
- [x] 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
|