LifePlay-Revival/Docs/Migration/08_Guide_Developpeur.md

08 — Guide du développeur (LifePlay UE 5.5)

Pour reprendre le projet : installer, compiler, empaqueter, diagnostiquer et corriger sans casser la parité avec 4.27. Architecture : 07_Architecture_5.5.md. Commandes prêtes à copier : 09_Commandes_Utiles.md. Méthode de travail obligatoire : 10_Protocole_Operations.md.

---

1. Environnement

Élément	Valeur
Moteur	Unreal Engine 5.5.4 (Launcher) : D:\Game\Launcher\Engine\UE_5.5
Compilateur	Visual Studio 2022 (D:\Game\VS2022), MSVC 14.38, SDK Windows 10.0.22621
Projet	D:\Game\LifePlay-master 5.5\LifePlay.uproject
Référence (lecture seule, jamais modifiée)	D:\Game\LifePlay-master 4.27 + build D:\Game\LifePlay_Build_427_Dev
Sauvegardes de lots	D:\Game\LifePlay_Backup_5.5\<lot>\ (hors dépôt)
Cache de données dérivées	D:\DDC (à conserver : évite des heures de recompilation de shaders)
Dépôt public	github.com/edujiro5972/LifePlay-Revival (branche main ; ue5.5-v1.1 = V1.1)

Python 3 est utile pour Tools/DiffRemplacementNoeuds.py. PowerShell 7 pour les scripts Tools/*.ps1. L'addon LifePlay-Sandbox n'est plus requis pour compiler ni lancer le jeu ; il fournit la sandbox et l'atelier de mods (module LPModTools).

2. Arborescence

Chemin	Contenu	Versionné
Source/LifePlay	runtime : compatibilité 4.27, sous-systèmes	oui
Source/LifePlayEditorTools	commandlets (éditeur)	oui
Plugins/ModdingExtra, Plugins/StreetMap	plugins du jeu (sources)	oui
Plugins/McpAutomationBridge	pilotage MCP de l'éditeur	non (outil local, jeton)
Config/	.ini du projet	oui
Content/BPs, UI, Structs, Scenes, Render, Characters	Blueprints et cartes de gameplay	oui
Content/Heavy	maillages, textures, villes (plusieurs Go)	non (archive 7z de publication)
Content/Modules	données texte du jeu (DSL, presets)	oui
Docs/Migration	cette documentation, journal, registre, relevés etat/	oui
Tools/	scripts de lot, de mesure et de diff	oui
Saved/Logs/portage	journaux de parties et de commandlets archivés	non
.mcp.json, .claude/	configuration locale d'agent (jeton)	jamais

2.1 Carte de Content/Heavy et dossiers à ne pas déplacer

Les noms de dossiers (New, New2…) viennent de l'auteur et ne disent rien de leur contenu. Ils ne sont pas renommés (audit O7, 11_Audit_Optimisation.md §16) : le jeu y construit des chemins à partir de noms lus dans les données, et les mods en dépendent.

Dossier	Contenu
Heavy/Clothes4	vêtements (940 maillages et leurs matériaux), désignés par nom dans Modules/Clothes4.txt
Heavy/New2	Furniture (meubles des .lpworld), Anims2, Daily (animations), Sound, Hairs, BDSM, Beasts, Buildings (carte de la ville)
Heavy/Daz	corps Bridget (femme) et Michael (homme) avec cheveux et pilosité, Anims, Clothes
Heavy/New3	UI (icônes, dont celles des morphs), Anims, Hairs, Tattoos, Characters/Tanlines
Heavy/New4	Anims, Hairs, Misc, Tentacles
Heavy/Backgrounds	images de fond
Heavy/StreetMap	280 villes (StreetMap) et leurs maillages (Static)
Heavy/Characters, New, New5	squelette, 37 icônes, 1 animation

Ne jamais déplacer ni renommer ces dossiers. Leurs préfixes sont écrits en texte dans les Blueprints :

• New2/Furniture (Room) ;
• Clothes4 (GI) ;
• StreetMap et StreetMap/Static (GI, UI/CityMenu) ;
• New3/Tattoos (GI) ;
• New3/Characters/Tanlines (Person) ;
• Daz/Bridget/Hairs/Pubic et Daz/Michael/hairs/other (GI, Person) ;
• New3/UI (UI/VisualMorph) ;
• Daz/Clothes (UI/Inventory_Cloth).

Content/Modules cite aussi 17 chemins complets de New2 et New3.

Pour chercher par thème plutôt que par dossier, utiliser les collections LifePlay_* du Content Browser (panneau Collections, section locale) : animations, vêtements, meubles, cheveux, icônes, villes, sons… La collection rouge LifePlay_Chemins_Fixes liste les assets à ne jamais déplacer. Après ajout d'assets, les régénérer avec Tools/BuildCollections.py (lot O7d, 11_Audit_Optimisation.md §16.5).

Coiffures et pilosité : listes décrites par les fichiers Modules/**/*.lphair (base : vin_Base/Hairstyles/vin_Base.lphair) ; ajouter une coiffure : 13_Protocole_Coiffure.md.

Content/Saves reçoit les sauvegardes des joueurs : il doit exister, mais reste vide dans le dépôt et l'archive. Les parties de test de l'éditeur ont été déplacées vers D:\Game\LifePlay_Backup_5.5\O7\Content_Saves (lot O7a).

3. Compiler

$UE   = 'D:\Game\Launcher\Engine\UE_5.5\Engine'
$Proj = 'D:\Game\LifePlay-master 5.5\LifePlay.uproject'
& "$UE\Build\BatchFiles\Build.bat" LifePlayEditor Win64 Development -Project="$Proj" -WaitMutex

• Fermer l'éditeur avant : avec Live Coding actif, UBT refuse de compiler (« Unable to build while Live Coding is active »).
• Le module d'outils est compilé avec bUseUnity=false (des fichiers concaténés entreraient en collision) : une inclusion manquante se voit immédiatement.
• Critère : 0 erreur, aucun nouvel avertissement.

4. Empaqueter

& "$UE\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="$Proj" -platform=Win64 `
  -clientconfig=Development -build -cook -iterate -stage -archive `
  -archivedirectory=D:\Game\LifePlay_Build_5.5_<nom> -unattended -utf8output -nop4

• Depuis le lot O2 le contenu est en conteneurs IoStore (UsePakFile, bUseIoStore, bCompressed dans DefaultGame.ini). Modules reste en fichiers nus.
• -clientconfig=Shipping pour une version distribuable (ne journalise pas) ; Development pour toute mesure. Builds de plongée : Tools\BuildDebug.ps1 (18_Build_Debug.md), jamais -nodebuginfo.
• Contrôle T-PKG-01 : ≥ 8 555 .uasset sous Windows/LifePlay/Content (8 561 attendus).
• Le résultat est dans <archivedirectory>\Windows\LifePlay.exe.

Builds conservées (2026-10-02) :

• LifePlay_Build_427_Dev : référence 4.27 journalisée ;
• LifePlay_Build_5.5_Shipping : V1.1, version publiée précédente ;
• LifePlay_Build_5.5_Shipping_V1.2 : V1.2, distribution ;
• LifePlay_Build_5.5_Dev_V1.2 : Development de la V1.2, référence pour les comparaisons ;
• LifePlay_Build_5.5_ERR038 : en test.

Les builds intermédiaires supprimées ont leurs journaux, mesures et parties sauvegardées dans D:\Game\LifePlay_Backup_5.5\builds_supprimees\ ; elles se reconstruisent depuis leur tag git.

5. Commandlets (Source/LifePlayEditorTools)

Lancement commun : UnrealEditor-Cmd.exe "<projet>" -run=<Nom> <options> -unattended -nopause -nosplash (ou Tools\RunCommandlet.ps1, qui archive le journal). L'éditeur graphique doit être fermé pour une commandlet qui écrit des assets.

5.1 Analyse (lecture seule)

Commandlet	Options	Usage
LPDumpFunction	-BP=<nom> [-Fn=<fonction>] [-Pins] [-Exec]	graphe d'une fonction Blueprint ; identique sur 4.27 et 5.5 pour comparer
LPDumpAssets	-List=<fichier> ou -Dirs=/Game/A,/Game/B ; -Out=<fichier>	photographie complète de paquets (propriétés non par défaut, broches et liaisons) pour diff avant/après
LPDumpComponents	-BP=<nom> ou -Map=<carte> -Filter=<texte> ; [-All]	composants et propriétés modifiées ; révèle les changements de valeurs par défaut
LPDumpWidgetTree	-BP=<widget> ou -BP=*	arbre UMG et propriétés de slot
LPDumpCDO	-Class=/Game/BPs/GI.GI_C -Out=<f> -Props=A,B	valeurs par défaut d'une classe (tableaux et maps)
LPDumpSave	-File=<.sav> -Out=<f> [-Props=A,B]	contenu d'une sauvegarde
LPCheckMeshAssignment	—	nœuds d'affectation de maillage et broches orphelines (T-LOAD-02)
LPCheckStreetMap	[-CSV=<f>] [-Path=/Game/…] [-Verbose]	contenu des 280 villes
LPCheckMeshes	-Path=/Game/… -CSV=<f>	LOD, sommets, triangles, dimensions des maillages statiques
LPTestStringCompat	—	compare LPStringCompat à une transcription de FString::Find 4.27

5.2 Correction de graphes (toujours -DryRun d'abord)

Commandlet	Correctif	Cible
LPFixAssetRegistryNodes	CX-B00	GetAssetByObjectPath → version pure
LPFixAssetRegistryPins	CX-B01	GetAssetsByClass : classe perdue
LPFixEditableTextBoxFont	CX-B02	broche Font → TextStyle.Font
LPFixOrphanBoundEvents	CX-B04	événements On Clicked sans widget
LPFixParseIntoArray	CX-B08	ParseIntoArray → LPStringCompat
LPFixButtonPadding	CX-B09	marges UButton → valeurs UE4
LPFixSkeletalMeshGet	CX-B10	Get SkeletalMesh → LPMeshCompat
LPFixNavRandomPoint	CX-B11	GetRandomPointInNavigableRadius → helper pur
LPFixStringSearch	CX-B12	Contains/Split/FindSubstring → LPStringCompat
LPFixDeprecatedNodes	(R-03/R-04 d'origine)	ne plus utiliser

Toutes réappliquées à l'état actuel, elles ne trouvent plus rien (idempotentes).

5.3 Cartes et paquets

Commandlet	Options	Usage
LPFixZeroScaleActors	[-Fix "-Scale=0.1"]	composantes d'échelle nulles (CX-B03) ; guillemets obligatoires sous PowerShell
LPConvertAtmosphericFog	-Map=<carte> [-DryRun]	AtmosphericFog → SkyAtmosphere (L7d)
LPFixSceneCapture	-Map -Actor -From "-Offset=x,y,z" [-DryRun]	racine et position d'une SceneCapture2D (L7j)
LPResavePackages	-List=<fichier> [-DryRun]	réenregistrement UE5 sans modification (CX-B07)

6. Écrire un correctif

6.1 Choisir la forme

Situation	Forme	Exemple
Une fonction moteur appelée par des Blueprints a changé de comportement	fonction C++ de compatibilité (mêmes broches) + commandlet de rebranchement	LPStringCompat + LPFixStringSearch
Une fonction moteur est devenue impure	enrobage pur	LPNavigationHelpers
Un défaut visible, sans changement de Blueprint souhaité	UGameInstanceSubsystem + FTSTicker, lecture des propriétés de GI par réflexion	LPOutdoorRoomSubsystem, LPSecondScreenSubsystem
Une valeur par défaut du moteur a changé	commandlet qui réécrit uniquement les composantes égales au nouveau défaut	LPFixButtonPadding
Une carte mal construite	commandlet -Map= avec vérification et sauvegarde conditionnelle	LPFixSceneCapture

Préférer le sous-système quand c'est possible : aucun asset modifié, retour arrière = retirer deux fichiers.

6.2 Commandlet de rebranchement : exigences

Modèle : LPFixNavRandomPointCommandlet.cpp (puis LPFixStringSearch, sa généralisation).

1. Trouver les nœuds par classe et fonction exactes ; compter (le -DryRun doit donner le nombre attendu).
2. Relever avant modification, pour chaque broche : liaisons et valeur par défaut.
3. Créer le nouveau nœud au même emplacement, reporter broche par broche, par nom.
4. Comparer après : tout écart, broche sans équivalent, cible self reliée ou nœud impur → nœud laissé en l'état, Blueprint non sauvegardé.
5. Recompiler puis sauvegarder les seuls Blueprints entièrement corrects.

Contrôle indépendant : LPDumpAssets avant/après puis python Tools/DiffRemplacementNoeuds.py avant.txt apres.txt <profil> (profils L7a, L7b, CX-B12 ; ajouter un profil pour un nouveau correctif). Le diff ne doit montrer que les nœuds remplacés.

6.3 Sous-système : modèle

void UMonSubsystem::Initialize(FSubsystemCollectionBase& C)
{ Super::Initialize(C); TickHandle = FTSTicker::GetCoreTicker().AddTicker(FTickerDelegate::CreateUObject(this, &UMonSubsystem::Tick)); }
void UMonSubsystem::Deinitialize() { FTSTicker::GetCoreTicker().RemoveTicker(TickHandle); Super::Deinitialize(); }

• Lire une variable Blueprint de GI : FindPropertyByName + CastField<FObjectPropertyBase>.
• Rechercher un acteur de carte par GetFName() : les étiquettes d'acteur n'existent pas en Shipping.
• Ne jamais défaire un état que le sous-système n'a pas lui-même posé (voir HiddenCeiling).
• Ne pas utiliser LogLifePlay.GetCategoryName() : en Shipping la catégorie est un FNoLoggingCategory.

7. Diagnostiquer

1. Le défaut existe-t-il en 4.27 ? dans le build précédent ? Demander avant toute analyse (10_Protocole_Operations.md §3).
2. Mesurer sur une build Development empaquetée, jamais avec UnrealEditor.exe -game.
3. Comparer 4.27 et 5.5 sur un parcours identique (nouvelle partie, vitesse normale, mêmes lieux) avec Tools\LogStats.ps1 -Compare.
4. Pour un état d'exécution (positions, variables), utiliser les options -LPDump* et -LPTrace* (09_Commandes_Utiles.md §4) dans un fichier .bat placé à côté de l'exécutable, que l'utilisateur lance à la place de LifePlay.exe.
5. Pour une mesure de performance (à-coups, mémoire, non-régression) : build empaquetée via Tools\BuildDebug.ps1 et sessions A/B/C (18_Build_Debug.md). Pas UnrealEditor.exe -game pour des millisecondes comparables à O0.
6. Pour un graphe : LPDumpFunction sur les deux arbres, puis diff.
7. Pour un écart de comportement du moteur : lire les sources moteur 4.27 et 5.5 sur les cas limites ; en faire un test (LPTestStringCompat).

Inspection en direct : avec l'éditeur ouvert et le serveur MCP lancé (McpAutomationBridge, port 3000), l'agent peut lire acteurs et propriétés de la carte. Usage en lecture seule recommandé ; toute modification passe par une commandlet versionnée.

8. Publier

• Compte GitHub edujiro5972 (vérifier gh auth status : un autre compte est aussi connecté).
• Identité de commit : edujiro5972 <336072401+edujiro5972@users.noreply.github.com>.
• Jamais publiés : adresse e-mail personnelle, .mcp.json, .claude/, Plugins/McpAutomationBridge, tout SecurityToken, Content/Heavy, binaires, *.png, *.7z, *.mp4 (règles du .gitignore d'origine ; pas de LFS).
• Version complète : archive 7z des sources et du contenu (D:\Game\LifePlay_Publication), avec empreinte SHA-256 publiée dans le README.
• Tags : v1.0, v1.1 ; un tag <lot>-valide par lot validé en jeu.