LifePlay-Revival/Docs/Migration/18_Build_Debug.md

18 — Build debug (mesure, pas optimisation)

Capacité de mesure reproductible après l'audit O0. Le Shipping joueur ne change pas (IncludeDebugFiles=False dans Config/DefaultGame.ini, aucun coût runtime : le sous-système est compilé vide en Shipping). Skill agent : .cursor/skills/lifeplay-debug-build/. Plan de pilotage du lot : 19_Plan_Outillage_Debug.md.

1. Deux builds

Config	Rôle	Comparer les ms absolues
Development	Baseline chiffrée, session C, non-régression vs O0	Oui
DebugGame	Plongée (checks, PDB, sessions A et B)	Non — ratios, signatures, piles
Shipping	Joueurs	Hors sujet

Ne pas reconstruire DebugGame à chaque itération. Itérer dans l'éditeur ou en Development ; reconstruire DebugGame seulement quand les checks, les PDB ou un outil externe l'exigent.

2. Empaqueter

.\Tools\BuildDebug.ps1 [-Config DebugGame|Development] [-ArchiveDir <chemin>] [-UE <moteur>] [-SkipBuild]

• Config par défaut : DebugGame.
• Archives : D:\Game\LifePlay_Build_5.5_DebugGame ou D:\Game\LifePlay_Build_5.5_Development.
• Jamais -nodebuginfo. Le PDB Binaries\Win64\*Win64-<Config>.pdb est recopié dans Windows\LifePlay\Binaries\Win64 parce que IncludeDebugFiles reste False (le Shipping lancé depuis l'éditeur ne doit pas embarquer les PDB).
• Cuisson alignée sur le projet actuel (lot O2) : -pak -iostore -compressed. Modules reste en fichiers nus via DefaultGame.ini.
• Après l'archive, les lanceurs Tools/debug/*.bat sont copiés à côté de Windows\LifePlay.exe.

Journal UAT : Saved\Logs\portage\BuildDebug_<config>_<horodatage>.log.

3. Lanceurs

Scénario unique (O0 §5, environ 15 min) : partie avancée → carte de la ville → intérieur peuplé → extérieur peuplé → scène à plusieurs personnages → quitter normalement.

Session	Build	Lanceur	But
A	DebugGame	LifePlay_debug_sessionA_insights.bat	À-coups / travail de GI (G6)
B	DebugGame	LifePlay_debug_sessionB_mem.bat	Fuites, physique, collisions
C	Development	LifePlay_debug_sessionC_profil.bat	Non-régression CSV + LLM

Auxiliaires, hors chemin critique : LifePlay_debug_bugs.bat, LifePlay_debug_gpu.bat (PIX ou RGP, jamais les deux), LifePlay_debug_collision.bat. LifePlay_debug_ui.bat ouvre une fenêtre pour cocher ces options (le canal memory reste décoché ; -csvCaptureFrames n'est pas proposé). Le .ps1 du même nom doit rester à côté du .bat.

Flags des sessions :

Lanceur	Ligne de commande
A	-trace=cpu,frame,bookmark,loadtime,memory -statnamedevents -tracefile=<Saved>/Profiling/SessionA.utrace -LPHitchLog
B	-llm -llmcsv -LPCollisionLog -ExecCmds="LifePlay.MemSnapshot, p.Chaos.StartVDRecording"
C	-csvGpuStats -llm -llmcsv -ExecCmds="csvprofile repeat=20, csvprofile frames=9000"
bugs	-LogCmds="LogModdingExtra Verbose"
gpu	-d3d12 (PIX). RGP : attacher au processus, sans ce lanceur
collision	-LPCollisionLog -ExecCmds="p.Chaos.StartVDRecording, show collision"
ui	fenêtre : les mêmes options, une par une

Piège CSV. Ne jamais passer -csvCaptureFrames. La capture démarre avant l'initialisation du RHI et le moteur s'arrête (IsRayTracingAllowed() may only be called once RHI is initialized). La session C démarre le CSV par -ExecCmds, après le rendu. Mesurer un jeu empaqueté, pas UnrealEditor.exe -game, pour les chiffres comparables à O0.

4. Collecte

.\Tools\CollectDebugArtifacts.ps1 -Lot <lot> -BuildDir <archive> -Session A|B|C|bugs|gpu|collision

Destination : D:\Game\LifePlay_Backup_5.5\<lot>\Session<session>\ (journaux, CSV, LLM, .utrace, MemReport, Profiling\LPDebug, enregistrements ChaosVD). Le script échoue si rien n'est copié.

Résumé CSV (session C) :

.\Tools\SummarizeDebugCsv.ps1 -Csv <dossier ou fichier CSV>

Médiane FrameTime, images > 50 ms et > 100 ms. Référence O0 (build L7cdj, 36 004 images) : médiane 16,7 ms ; 159 images > 50 ms ; 112 images > 100 ms ; physique Chaos environ 463 Mo.

5. Runtime non-Shipping

ULPDebugSubsystem (UGameInstanceSubsystem), derrière #if !UE_BUILD_SHIPPING.

Entrée	Effet
-LPHitchLog	Journal des images ≥ seuil. Sans ce flag, aucun relevé d'image
-LPHitchMs=N	Seuil en millisecondes (50 par défaut)
-LPCollisionLog	Échantillon toutes les 2 s, dump dès qu'un trimesh a des triangles, avec l'acteur qui le porte. Inactif sans ce flag
LifePlay.Bookmark <texte>	TRACE_BOOKMARK et ligne LPDebug bookmark :
LifePlay.MemSnapshot	Saved/Profiling/LPDebug/MemSnapshot_*.txt + memreport
LifePlay.CollisionDump	CollisionDump_*.txt immédiat (console). Le suivi automatique est -LPCollisionLog, pas cette commande au démarrage
LifePlay.HitchSummary	Bilan courant (LPDebug hitch : N hitch(s) en …)

Un bilan est aussi écrit à 2 minutes et à la fermeture quand -LPHitchLog est actif. Ligne de hitch : LPDebug hitch : <ms> ms (seuil <seuil>) #<n>.

Événements nommés Insights (macro TRACE_CPUPROFILER_EVENT_SCOPE, canal CPU ; en 5.5 il n'y a pas de macro publique SCOPED_NAMED_EVENT) : LoadTxt, LPDataCache (TryGet), LPDataCache_LoadAll. Ils sont vides en Shipping (CPUPROFILERTRACE_ENABLED est 0).

ChaosVD est limité à l'éditeur dans LifePlay.uproject. En jeu empaqueté, si p.Chaos.StartVDRecording n'existe pas, LifePlay.CollisionDump est la preuve collision. Pour un enregistrement CVD, ouvrir l'éditeur et attacher le débogueur visuel Chaos au processus, ou jouer en PIE.

Options déjà en place, inchangées : -LPDump*, -LPTrace*, -LPNoDataCache, -LPDataCacheVerify, console LifePlay.LogSummary et ModdingExtra.LoadTxtStats.

6. Gates

Étape	Vert seulement si
Build	UAT code 0, LifePlay.exe, 6 lanceurs à côté, PDB du projet présents
Hitch	Au moins une ligne LPDebug hitch :, ou 0 hitch(s) après ≥ 2 min
Signet	Ligne LPDebug bookmark :
Mémoire	Fichier MemSnapshot_*.txt non vide
Session A	.utrace ouvrable, signets alignés sur les hitches, 3 à 5 causes avec ms ou %
Session B	Physique en Mo, MemReport ou snapshot, CVD ou CollisionDump, delta mémoire
Session C	Au moins une tranche de 9 000 images, LLM, médiane ≤ 17 ms (±1) ou écart expliqué, images > 100 ms comparées à O0 (112). Jouer sans -LPHitchLog

Preuves attendues : Dbg-I4, Dbg-I5, Dbg-I6 sous D:\Game\LifePlay_Backup_5.5\.

7. Agent

- [ ] Development pour les chiffres, DebugGame pour la plongée
- [ ] BuildDebug.ps1 si l'archive n'existe pas ou si le C++ a changé
- [ ] Une session (A, B ou C), pas un lanceur unique
- [ ] CollectDebugArtifacts.ps1
- [ ] Insights / SummarizeDebugCsv / ChaosVD selon la session
- [ ] Rien de Tracy, Optick, ASAN, ImGui

Outils et URLs : .cursor/skills/lifeplay-debug-build/reference.md. Priorité : Unreal Insights → CSV/LLM → ChaosVD → RenderDoc / PIX / suite Radeon / µProf / diagnostics Visual Studio. Écartés : Tracy, Optick, Superluminal, ASAN, Nsight par défaut (machine AMD).

8. Mesures du 2026-10-04 et décision

Build DebugGame : D:\Game\LifePlay_Build_5.5_DebugGame (UAT 243 s). Preuves : D:\Game\LifePlay_Backup_5.5\Dbg-I4 et Dbg-I5. Les millisecondes DebugGame ne se comparent pas à O0.

Session A (G6)

Trace CPU courte ouvrable (SessionA_cpu.utrace, 252 Mo, export Dbg-I4\GameThreadTimers.txt) : 5 388 images, 32 à-coups ≥ 50 ms, max 2 389 ms. La trace avec canal memory (SessionA.utrace, 6,4 Go, 89 à-coups en 350 s, max 6,7 s) a saturé Insights (51 Gio / 63). Les signets TRACE_BOOKMARK sont émis dans la même fonction que chaque ligne LPDebug hitch ; le max 2,35 s des timers FTimerManager et ExecuteUbergraph_City est le même à-coup que le journal (2 389 ms).

Temps inclus GameThread, budget de travail GameEngine Tick = 14,42 s (l'attente de cadence, 69,6 s, est à part) :

Cause	Inclus	Part du tick moteur	Max une fois
ExecuteUbergraph_GI	5,34 s	37 %	2,35 s
FTimerManager	3,39 s	24 %	2,35 s
ExecuteUbergraph_City	2,51 s	17 %	2,35 s
ExecuteUbergraph_Person	1,73 s	12 %	0,30 s
PopulateRaws	1,26 s	9 %	1,26 s
Actions latentes Blueprint	1,03 s	7 %	0,30 s
LoadTxt	5,5 ms	—	0,2 ms
LPDataCache	2,6 ms	—	0,2 ms

LoadTxt n'est pas la source des à-coups. Le pic de 2,35 s est le graphe de GI / City déclenché par le gestionnaire de minuteries.

Session B (physique)

LLM, fin de chargement de CentralLondon (textures 651 Mo, proche des 624 Mo d'O0) :

Poste	Début	Fin
Physics	6,3 Mo	171,6 Mo
Physics/ChaosTrimesh	—	87,6 Mo
TrackedTotal	843 Mo	1 888 Mo

Delta physique +165 Mo. p.Chaos.StartVDRecording a écrit ChaosVD-20261004_130550.utrace (172 Mo). Le CollisionDump du ExecCmds de démarrage compte 23 primitives et 1 trimesh, sans dire qui le porte. Le détail est au §10. MemReport et MemSnapshot_20261004_130550.txt sont dans Dbg-I5\SessionB.

Les 463 Mo d'O0 ne se retrouvent pas : les collisions décoratives ont été retirées en O9. La physique reste le second poste derrière les textures, plus le premier.

Session C (Development, sans -LPHitchLog)

Build D:\Game\LifePlay_Build_5.5_Development (UAT 127 s). Une tranche complète : Profile(20261004_131659).csv, 9 000 images. Preuves : Dbg-I6\SessionC.

Mesure	Cette tranche	O0 (36 004 images)
Médiane temps d'image	16,66 ms	16,7 ms
Médiane thread de jeu	3,57 ms	3,9 à 4,4 ms
Images > 50 ms	52 (0,58 %)	159 (0,44 %)
Images > 100 ms	23 (0,26 %)	112 (0,31 %)

La médiane tient le plafond de 60 images/s (≤ 17 ms). Le taux d'images > 100 ms n'est pas plus haut qu'en O0. Le parcours n'est pas les 15 minutes du scénario O0 (démarrage puis CentralLondon), donc le décompte brut 23 contre 112 ne se compare pas tel quel. LLM en fin de cette tranche : textures 605 Mo, physique 89 Mo (la session B, plus longue, monte à 172 Mo).

Décision

Prochain lot d'optimisation : G6, pas O10 en premier. O10 reste un lot mémoire (trimesh ~88 Mo en session B), après G6. Le sous-système debug, journal d'à-coups éteint, ne déplace pas la médiane Development. La trace Development du §9 nomme la feuille : ce n'est pas le graphe GI qu'il faut réécrire.

9. Trace Development courte (G6, 2026-10-04)

Build déjà en place : D:\Game\LifePlay_Build_5.5_Development. Trace Windows\LifePlay\Saved\Profiling\G6Dev.utrace (464 Mo), canaux cpu,frame,bookmark,loadtime, sans memory, avec -LPHitchLog. Durée 184 s, arrêt après le premier à-coup > 500 ms. Copies : D:\Game\LifePlay_Backup_5.5\Dbg-G6.

Un seul à-coup > 500 ms : 3 621 ms à l'image du clic Continuer (DelayedStart, 3,583 s). Le minuteur de 2 s qui rappelle DelayedStart dure ~13 µs. Aucun FTimerManager_Tick > 200 ms : le 654 ms de l'image 3137 (CSV I6) n'est pas reproduit sur ce démarrage automatique.

Feuille CPU, temps exclusif dans cette image (export ExportTimerCallees, thread de jeu) : FindCenterOfPolygon 0,350 s exclusif / 0,742 s inclus, 49 425 appels (centre de la boîte englobante, pas le centroïde). Array_Get est plus haut en exclusif (0,536 s) mais c'est un opcode de la machine virtuelle, pas une fonction. PopulateRaws et ExecuteUbergraph_City restent des contenants (exclusif négligeable).

Lecture des ~164 Mo (CSV I6, image 395, colonnes exclusives vides) : le canal loadtime nomme /Game/Heavy/StreetMap/Static/CentralLondon et /Game/Heavy/StreetMap/CentralLondon. Disque chaud, l'attente synchrone de cette trace est 0,325 s (GetAsset × 2 → MainThreadWaitingOnAsyncLoadingThread).

Deux lots, baseline = la tranche I6 (médiane 16,66 ms, une image à 6,2 s, une image TimerManager à 654 ms) :

• CHG-115 : FindCenterOfPolygon en C++, quatre appels de GI rebranchés. Pas de réécriture du graphe, pas de décalage des minuteries.
• CHG-116 : préchargement async de ces deux paquets à l'init de l'instance de jeu. Séparé du correctif de la feuille.

Cuisson Development du 2026-10-04 14:26 (BuildDebug_Development_20261004-142617.log, UAT 148 s) contient les deux lots. Partie 14:31–14:46, quittée normalement, sans -LPHitchLog et sans CSV (journal archivé Dbg-G6p\SessionC). Preload ville : demande envoyee dès l'init. Aucune erreur FindCenterOfPolygon. L'image du clic Continuer (StreetMap BeginPlay, puis PopulateRaws) s'étale sur 1 017 ms de journal, contre 3 621 ms avant ces lots. Une autre image, à 14:33:02 (entrée « Central London » / pièce street), s'étale sur 1 171 ms. Ce ne sont pas des temps CSV : la médiane 16,66 ms et le rythme d'O0 restent à remesurer avec le lanceur de la session C.

10. Rapport collisions (2026-10-04)

Les capsules des PNJ ne sont pas les 88 Mo. Un seul trimesh les explique, et le dump de démarrage ne nomme pas son acteur. -LPCollisionLog (CHG-117) est dans la cuisson de 15:16. La partie de 15:19 ne l'a pas activé : LifePlay.exe a été lancé sans ce switch.

Preuve	Ce qu'elle montre
Dbg-I5\SessionB\Profiling\LPDebug\CollisionDump_20261004_130550.txt	Monde CentralLondon, 23 primitives dont 12 Person_C, 6 Room_C, 2 StreetMap_Static_C, 1 StaticMeshActor. 1 trimesh unique, 3 formes simples, 0 corps simulé. Pas de nombre de triangles ni d'acteur porteur.
Dbg-I5\SessionB\Profiling\LLM\LLM_Pid12232_2026.10.04-13.05.50_Windows.csv	402 échantillons. Maximum : physique 176,7 Mo, trimesh 93,5 Mo, ChaosUpdate 83,0 Mo, convexes 0,11 Mo. Dès l'échantillon 17 le trimesh est déjà à 79,3 Mo.
Dbg-I5\SessionB\Profiling\ChaosVD-20261004_130550.utrace (180 Mo)	Enregistrement présent, non ouvert : il ne nomme pas le maillage.
Dbg-I6\SessionC\Profiling\CSV\Profile(20261004_131659).csv	Development, 9 000 images, médiane 16,66 ms. Image 395 : 6 218 ms et 164 Mo lus. Image 3137 : 664 ms dans TimerManager.
Dbg-G6p\SessionC\Profiling\G6Dev.utrace (464 Mo ; original dans le Saved du build Development)	Canaux cpu,frame,bookmark,loadtime. Image Continuer 3 621 ms. Feuille FindCenterOfPolygon 0,350 s exclusif. Paquets /Game/Heavy/StreetMap/Static/CentralLondon et /Game/Heavy/StreetMap/CentralLondon.
Dbg-G6p\SessionC\Logs\LifePlay.log	Partie 14:31–14:46 avec CHG-115/116. Préchargement envoyé. Image Continuer 1 017 ms de journal. Entrée dans la ville 1 171 ms. Pas de relevé de collision (lanceur sans -LPCollisionLog).

Lecture. Les 12 capsules de PNJ sont des formes simples : les convexes du LLM culminent à 0,11 Mo. Le trimesh (93 Mo) et ChaosUpdate (83 Mo) apparaissent ensemble et font l'essentiel des 177 Mo de physique. Le dump de la même session ne voit qu'un trimesh, donc ce poste est un maillage complexe unique, parmi StreetMap_Static_C, Room_C ou le StaticMeshActor, pas une capsule de personnage. StreetMap sait construire cette collision (UseComplexAsSimple, profil BlockAll) ; le défaut du composant est de ne pas la générer, et le dump ne dit pas si l'instance de la ville l'a fait.

Le CVD et le dump de démarrage ne suffisent pas à désigner l'acteur. Le suivi -LPCollisionLog écrit CollisionTrack_*.txt (une ligne toutes les 2 s) et un CollisionDump_*.txt dès que des triangles sont comptés, avec la classe, l'acteur et le composant. Les lanceurs LifePlay_debug_sessionB_mem.bat et LifePlay_debug_collision.bat passent ce switch et ne lancent plus LifePlay.CollisionDump dans le ExecCmds de démarrage.

Partie de la cuisson 15:16, 15:19–15:27, sortie normale (Dbg-G6r\LifePlay.log). Lignes au démarrage : LPDebug collision : inactif, Preload ville : demande envoyee, aucune erreur FindCenterOfPolygon. Une image, à 15:20:00, s'étale sur 3 152 ms de journal : StreetMap BeginPlay, puis les fichiers de monde, puis « Central London », puis le domicile (home test310 UpdateWall) et un clic. Environ 2 s de cette image n'ont presque pas de lignes. Ce n'est pas un temps CSV. Le porteur du trimesh reste non nommé tant que la partie n'est pas lancée par LifePlay_debug_collision.bat.

Partie 15:37–15:50 avec -LPCollisionLog (réglage Collisions du lanceur). Sortie normale. 382 échantillons, 4 dumps, maximum 1 206 768 triangles (Dbg-G6s). À 7 s, le porteur est nommé :

Triangles	Acteur	Composant	Profil
1 084 249	StreetMap_Static	CentralLondon	BlockAllDynamic
122 469	Room_C_0 (au pic, 61 primitives)	meubles fnt_new*, lampes ls_lamp*	Custom
0	84 Person_C	une capsule CollisionCylinder partagée	Custom

Le maillage de rue porte 90 % des triangles de collision. Les PNJ n'en ont aucun. Preuve : CollisionDump_20261004_153727.txt. En fin de partie il reste 1 143 395 triangles. L'enregistrement ChaosVD (299 Mo) est dans le Saved du build.