# 09 — Commandes utiles

> Toutes les commandes se lancent depuis la racine du dépôt de travail, sous PowerShell 7. Explications :
> `08_Guide_Developpeur.md`. Règles et leçons (référence, V1) : `10_Protocole_Operations.md` ; méthode actuelle : skill `lp-lot` et `32_Organisation_Agents.md`.
>
> **Atelier de mods (DC3, 2026-10-07)** : `BuildMod`, `NewMod`, `EditMod`, `HairPipeline`, `AnimPipeline`, `DeliverAnims`, `ModSource` et les lanceurs sandbox se lancent depuis `D:\Game\LifePlay-Sandbox` (`.\Tools\...`), avec `-GameRoot` facultatif (défaut : `[Workshop] GameRoot` de `Config\LPSandbox.ini` de l'addon) ; `ModSources\`, `AnimSources\` et `Tools\{anim,hairs,mods}` y sont aussi. Dans ce document, les chemins `.\Tools\<script de mod>` et `<projet>/Tools/Hair*.py` s'entendent donc dans l'addon.

```powershell
. .\Tools\Engine.ps1                 # point unique du moteur : $LPEngineRoot, $LPEngineVersion, $LPProject, $LPBuildRoot
$UE   = $LPEngineRoot                # version lue dans LifePlay.uproject ; $env:LP_ENGINE_ROOT la surcharge
$Cmd  = "$UE\Binaries\Win64\UnrealEditor-Cmd.exe"
$Proj = $LPProject
```

**Piège PowerShell** : un argument contenant une virgule ou un point après `=` doit être placé entre
guillemets (`"-Offset=0,-10000000,0"`, `"-Scale=0.1"`), sinon il est découpé et la commandlet reçoit une
valeur fausse.

## 1. État et intégrité

```powershell
git status; git log --oneline -5; git tag --list '*-valide'    # où en est-on
.\Tools\CheckIntegrity.ps1 -Modules -Env                       # données, environnement ; -Modules contre la référence figée (créée par -InitRef, SKIP si absente)
.\Tools\AssetHeaders.ps1                                       # 0 paquet UE4 attendu (8563/8563 UE5)
```

## 2. Compilation et build

```powershell
& "$UE\Build\BatchFiles\Build.bat" LifePlayEditor Win64 Development -Project="$Proj" -WaitMutex
& "$UE\Build\BatchFiles\Build.bat" LifePlay Win64 Shipping -Project="$Proj" -WaitMutex

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

# Mesure (DebugGame ou Development) : PDB conserves, lanceurs deposes a cote de LifePlay.exe
.\Tools\BuildDebug.ps1
.\Tools\BuildDebug.ps1 -Config Development
.\Tools\CollectDebugArtifacts.ps1 -Lot <lot> -BuildDir "${LPBuildRoot}_DebugGame" -Session A
.\Tools\SummarizeDebugCsv.ps1 -Csv <dossier CSV>

(Get-ChildItem "${LPBuildRoot}_<nom>\Windows\LifePlay\Content" -Recurse -Filter *.uasset).Count   # T-PKG-01 ≥ 8555
```

**Compiler sans l'addon `LifePlay-Sandbox`** : possible (DC2/DC4) ; UBT affiche `AdditionalPluginDirectory …\LifePlay-Sandbox\Plugins not found` (avertissement, sans effet). Piège : après une compilation sans l'addon, UBT réutilise `Intermediate\Build\Win64d\LifePlayEditor\Development\Makefile.bin` (et `…\LifePlay\Development\…`) sans les modules de l'addon quand celui-ci revient : les sources de l'addon ne sont plus recompilées malgré un code 0. Déplacer ces `Makefile.bin` (pas supprimer) avant de recompiler avec l'addon.

## 3. Commandlets

```powershell
# Générique, journal archivé par lot
.\Tools\RunCommandlet.ps1 -Lot <lot> -Commandlet CompileAllBlueprints
.\Tools\RunCommandlet.ps1 -Lot <lot> -Commandlet LPResavePackages -Args '-List=<liste.txt> -DryRun'

# Directement
& $Cmd $Proj -run=CompileAllBlueprints -unattended -nopause                     # T-LOAD-01
& $Cmd $Proj -run=LPCheckMeshAssignment -unattended -nopause                    # T-LOAD-02
& $Cmd $Proj -run=LPDumpFunction -BP=GI -Fn=GeneratePerson -Pins -unattended -nopause
& $Cmd $Proj -run=LPDumpAssets -List=<liste.txt> -Out=<photo.txt> -unattended -nopause
& $Cmd $Proj -run=LPDumpComponents -Map=/Game/Scenes/CentralLondon -Filter=SecondScreen -unattended -nopause
& $Cmd $Proj -run=LPDumpSave "-File=Saved\SaveGames\1.sav" -Out=<f.txt> -unattended -nopause
& $Cmd $Proj -run=LPCheckStreetMap -CSV=Docs/Migration/etat/<projet>/<lot>/<lot>_streetmap.csv -unattended -nopause
& $Cmd $Proj -run=Cook -TargetPlatform=Windows -unattended                      # T-LOAD-05

# Coiffure : import FBX, conversion, matériaux (protocole complet : 13_Protocole_Coiffure.md)
& $Cmd $Proj -run=pythonscript "-script=<projet>/Tools/HairImportFbx.py fbx=<f.fbx> dest=/Game/Heavy/New5/Hairs/_Work" -unattended -nopause
# exige l'addon LifePlay-Sandbox (module LPModTools) ; sans lui : « LPHairFromStaticMeshCommandlet looked like a commandlet, but we could not find the class »
& $Cmd $Proj -run=LPHairFromStaticMesh -Static=<maillage> -FitHead=<tete> -Out=/Game/Heavy/New5/Hairs/<Nom> -DryRun -unattended -nopause
& $Cmd $Proj -run=pythonscript "-script=<projet>/Tools/HairMaterials.py mesh=/Game/Heavy/New5/Hairs/<Nom> diffuse=<f> strands_opacity=<f> cap_opacity=white cap=<emplacement>" -unattended -nopause

# Gestionnaire de mods sur l'écran titre (UI15, 17_Mods_Ecran_Titre.md)
& $Cmd $Proj -run=LPTitleModManager -DryRun -unattended -nopause

# Mod d'assets (H3, 16_H3_Mods_Paquets.md §5-6) : sources dans ModSources\<Nom>, cuisson et archive en une commande
.\Tools\BuildMod.ps1 -Name <Nom> [-Install <jeu>\Windows]
.\Tools\BuildMod.ps1 -Name <Nom> -Retarget bake [-RetargetOnly]
.\Tools\BuildMod.ps1 -Target sandbox -Open
.\Tools\BuildMod.ps1 -Target game -Open
# Détail (version de référence puis cuisson DLC, toujours via cmd /c ou un .cmd : la version serait coupée)
# cmd /c '"$UE\Build\BatchFiles\RunUAT.bat" BuildCookRun ... -createreleaseversion=2026.10.4 ...'
# cmd /c '"$UE\Build\BatchFiles\RunUAT.bat" BuildCookRun ... -cook -stage -pak -iostore -compressed -dlcname="<projet>\Mods\<Nom>\<Nom>.uplugin" -basedonreleaseversion=2026.10.4 ...'

# Collections thématiques de l'éditeur (O7d), essai à blanc puis écriture
& $Cmd $Proj -run=pythonscript "-script=$($Proj | Split-Path)/Tools/BuildCollections.py -dryrun" -unattended -nopause
& $Cmd $Proj -run=pythonscript "-script=$($Proj | Split-Path)/Tools/BuildCollections.py" -unattended -nopause

# Diff indépendant d'un rebranchement de nœuds
python Tools\DiffRemplacementNoeuds.py <avant.txt> <apres.txt> CX-B12
```

### Sandbox Pair / Mesure (plugin `LPSandbox`, addon sibling)

Prérequis : clone `LifePlay-Sandbox` à côté du jeu, pin et liaison décrits dans `Docs/21_Sandbox_Addon.md` (`AdditionalPluginDirectories`, `../LifePlay-Sandbox/Plugins`).

```powershell
# Lanceurs (GameMode addon : /Script/LPSandbox.LPPairSandboxGameMode)
.\Tools\debug\LifePlay_pair_sandbox.bat          # Pair ou Interaction via le menu
.\Tools\debug\LifePlay_interaction_sandbox.bat   # même entrée (alias historique)
.\Tools\debug\LifePlay_measure_sandbox.bat       # écrit Saved\sandbox_mode.txt = Mesure

# Cible des clips sandbox vs jeu (LPAnimRedirect)
.\Tools\BuildMod.ps1 -Target sandbox -Open
.\Tools\BuildMod.ps1 -Target game -Open
```

Sorties du mode Mesure (relatif à `Saved/`) : `Measurement/retarget_pose_<Corps>.txt`, `Measurement/tour.csv`, `Measurement/tour/`, `Measurement/vignettes/`, `Measurement/planches/`, etc. (`Config/LPSandbox.ini`, clé `MeasureOutputRoot`).

Chaîne d'animations headless (module `LPModTools` de l'addon `LifePlay-Sandbox`, lot DC2 ; sans l'addon : « LPAnimEvalCommandlet looked like a commandlet, but we could not find the class ») :

```powershell
# Évaluation courte (1 clip) — archivage journal : RunCommandlet.ps1
& $Cmd $Proj -run=LPAnimEval "-Clips=Idle_Loop" "-Instants=1" `
  "-Out=Saved/AnimPipeline/quaternius" -unattended -nopause

.\Tools\RunCommandlet.ps1 -Lot AP4 -Commandlet LPAnimEval `
  -Args '-Out=Saved/AnimPipeline/quaternius'

& $Cmd $Proj -run=LPAnimTwist "-ClipDir=/Game/Quaternius/UAL" -unattended -nopause
& $Cmd $Proj -run=LPAnimCatalog "-Livraison=Saved/AnimPipeline/quaternius/livraison.json" -unattended -nopause

python Tools\anim\RapportControles.py Saved\AnimPipeline\quaternius
```

Réimport scripté d'un correctif (photo, simulation comptée, application, diff, compilation). Les commandlets de
correction `LPFix*` et `LPConvertAtmosphericFog` sont **retirés en U2 (historique git, tag `U2-avant`)** ; le script
reste pour un futur correctif de graphe :

```powershell
.\Tools\ReimportCorrectif.ps1 -Id <id> -Commandlet <commandlet de correction> `
  -Assets Content\UI\<A>.uasset,Content\UI\<B>.uasset `
  -Graphs <A>:EventGraph,<B>:EventGraph -ExpectPattern '<motif du journal>' -ExpectCount <n>
```

## 4. Options de diagnostic du jeu (build Development)

À passer à `LifePlay.exe`, de préférence dans un `.bat` à côté de l'exécutable :
`start "" "%~dp0LifePlay.exe" <options>`. Toutes inactives par défaut. Résultats dans
`Windows\LifePlay\Saved\Logs\LifePlay.log`, catégorie `LogLifePlay`.

| Option | Effet |
|---|---|
| `-LogCmds="LogModdingExtra Verbose"` | trace de chaque `LoadTxt`/`SaveTxt`/`GetAllFilesFromFolder` (comparaison A/B avec le build de référence 5.5) |
| `-LPDumpVars=A,B` | valeur des variables `A`, `B` de `GI` au démarrage et à la fin (tableaux : un élément par ligne) |
| `-LPTraceScriptEx=<texte>` | à chaque exception de script dont le message contient `<texte>` : fonction, offset, variables locales |
| `-LPTraceLocals=x,y` | ne relever que les variables locales dont le nom contient `x` ou `y` |
| `-LPTraceFunctions=F1,F2` | ne relever que les exceptions levées dans ces fonctions |
| `-LPTraceDepth=N` | relever aussi les N cadres appelants |
| `-LPTraceGIVars=A,B` | relever aussi ces variables de `GI` |
| `-LPTraceMax=N` | nombre maximal de relevés (3 par défaut) |
| `-LPDumpPaths=a.b.c,…` | chemins à relever, depuis `GI` (ex. `Room.WallT.RelativeLocation`) |
| `-LPDumpOnLog=<texte>` | relevé quand une ligne du journal contient `<texte>` (au plus une fois toutes les 5 s) |
| `-LPDumpDelay=S` | délai avant ce relevé (1,5 s par défaut ; le lieu se charge en arrière-plan) |
| `-LPDumpMax=N` | nombre maximal de relevés sur motif (20 par défaut) |
| `-LPDumpEvery=S` | relevé périodique toutes les S secondes |
| `-LPHitchLog` | journal des à-coups (`LPDebug hitch`), non-Shipping, inactif sans ce flag |
| `-LPHitchMs=N` | seuil des à-coups en ms (50 par défaut) |
| `-LPCollisionLog` | suit la collision du monde joué (échantillon toutes les 2 s, dump dès qu'un trimesh a des triangles). Pas au `ExecCmds` de démarrage |

Commandes console : `LifePlay.LogSummary` (bilan de session à la demande) ;
`LifePlay.MemSnapshot`, `LifePlay.CollisionDump`, `LifePlay.Bookmark`, `LifePlay.HitchSummary`
(non-Shipping, `18_Build_Debug.md`).

Lanceurs de session, déposés par `BuildDebug.ps1` à côté de `LifePlay.exe` :
`LifePlay_debug_sessionA_insights.bat`, `LifePlay_debug_sessionB_mem.bat`,
`LifePlay_debug_sessionC_profil.bat`, `LifePlay_debug_bugs.bat`, `LifePlay_debug_gpu.bat`,
`LifePlay_debug_collision.bat`.

Ne jamais lancer le CSV avec `-csvCaptureFrames` (arrêt avant l'init du RHI). Session C :
`-ExecCmds="csvprofile repeat=20, csvprofile frames=9000"`.

Exemple (mesure L7l, `LifePlay_releve_L7l.bat`) :

```bat
start "" "%~dp0LifePlay.exe" -LPDumpEvery=5 -LPDumpPaths=CurrentAmenity,Room.RootComponent.RelativeScale3D,Room.WallT.RelativeLocation,PlayerCharacter.CapsuleComponent.RelativeLocation
```

## 5. Journaux

```powershell
.\Tools\LogStats.ps1 <journal>                                   # compteurs, signatures les plus fréquentes
.\Tools\LogStats.ps1 -Compare <journal 5.5>, <journal 5.8>       # A/B normalisé par personnage
Select-String <journal> -Pattern '===== LifePlay'                # résumé de démarrage et bilan
Copy-Item <build>\Windows\LifePlay\Saved\Logs\LifePlay.log Saved\Logs\portage\<lot>_<objet>_<date>.log   # archiver
```

Journal du build de référence 5.5 validé : `Saved\Logs\LifePlay.log` sous `D:\Game\LifePlay_Build_5.5_DC4\Windows\LifePlay`.

## 6. Sauvegarde et retour arrière

```powershell
git tag <lot>-avant
.\Tools\Snapshot.ps1 -Lot <lot> -Path Content\BPs\GI.uasset, Content\Scenes\CentralLondon.umap
.\Tools\Snapshot.ps1 -Lot <lot> -Path Content\UI -Recurse

.\Tools\Restore.ps1 -Lot <lot> -WhatIf                           # simuler
.\Tools\Restore.ps1 -Lot <lot>                                   # restaurer (les versions remplacées sont conservées)
.\Tools\Restore.ps1 -Lot <lot> -Only Content\BPs\GI.uasset       # un seul fichier
git checkout <lot>-avant -- Source Config                        # code et configuration
```

## 7. Publication

```powershell
gh auth status                                  # compte actif : edujiro5972
git config user.name; git config user.email     # edujiro5972 / 336072401+edujiro5972@users.noreply.github.com
git push origin main <tag>
Get-FileHash <archive.7z> -Algorithm SHA256     # empreinte à publier dans le README
```

Liste de contrôle d'une publication (depuis H3c, `16_H3_Mods_Paquets.md` §7) :

```powershell
# 1. Version : Config\DefaultGame.ini, ProjectVersion=<annee>.<mois>.<compteur de publication> (ex. 2026.10.5)
# 2. Aucun mod monté dans le projet (il serait cuit avec le jeu)
. .\Tools\ModSource.ps1; Get-StrayMods (Get-Location)                         # doit être vide
# 3. Build de distribution ET version de référence, dans un dossier neuf (via cmd /c : la version serait coupée)
cmd /c '"<UE>\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="<projet>\LifePlay.uproject" -platform=Win64 -clientconfig=Shipping -build -cook -iterate -stage -pak -iostore -compressed -createreleaseversion=<version> -archive -archivedirectory=<$LPBuildRoot>_Shipping_V<x.y> -nodebuginfo -unattended -utf8output -nop4'
# 4. Contrôle : Releases\<version>\Windows\AssetRegistry.bin présent ; paquets identiques à ceux du build
Get-FileHash Releases\<version>\Windows\LifePlay-Windows.utoc, <build>\Windows\LifePlay\Content\Paks\LifePlay-Windows.utoc
# 5. Releases\ ne garde que la version publiée (les précédentes vers LifePlay_Backup_5.5\Releases) : l'archive des
#    sources la contient (≈ 1,3 Go) ; exclure aussi les produits de cuisson des mods : -x!ModSources\*\Saved
# 6. (zips de mods d'assets : produits par LifePlay-Sandbox\Tools\BuildMod.ps1, lancé depuis D:\Game\LifePlay-Sandbox)
# 6. Mods officiels recuits contre la nouvelle version : .\Tools\BuildMod.ps1 -Name lpr_hair_pocolov
#    Modules livrés à part : Tools\modules\next.json (essentiels : vin_Base, vin_VanillaRealistic ; lp_Revival retiré en H3d)
#    Un zip par module (15_Modules_Optionnels.md §5), dans un même dossier que les mods d'assets ; diffusion sur Discord :
#    .\Tools\SplitModules.ps1 -Build <build neuf> -Config Tools\modules\next.json -Out D:\Game\LifePlay_Publication  (version à renseigner)
#    .\Tools\BuildMod.ps1 -Name lpr_hair_pocolov -Out D:\Game\LifePlay_Publication\Modules_<version>
# 7. README : section de la version avec le lien vers Docs/Modding/FullGuides/Creating_Asset_Mods.md
```