LifePlay-Revival/Docs/Migration/16_H3_Mods_Paquets.md

# 16. H3 : assets apportés par les mods (étude, 2026-10-03)

> Depuis le lot DC3 (2026-10-07), ces scripts, `ModSources/` et `AnimSources/` sont dans le dépôt addon `LifePlay-Sandbox` (même disposition relative ; lancer depuis l'addon, `D:\Game\LifePlay-Sandbox`).

Objectif : qu'un mod apporte ses propres maillages, textures et matériaux (coiffures d'abord, puis vêtements, meubles,
animations) **sans recompiler ni recuire le jeu**. Aujourd'hui, un mod `Content/Modules/<mod>` ne contient que du texte :
tout asset doit être cuit avec le jeu (lots H1, H2).

## 1. Constats (lecture du moteur 5.5 et de la configuration du projet)

| Point | Constat | Source |
|---|---|---|
| Dossier des mods | Dans un jeu empaqueté, le gestionnaire de plugins lit **toujours** `<jeu>/Mods/` (« Always add the mods from the loose directory ») ; chaque `Mods/<Nom>/<Nom>.uplugin` devient un plugin de type `Mod` | `PluginManager.cpp`, `ReadAllPlugins` |
| Activation | un plugin `Mod` est considéré comme chargé depuis le projet : **activé par défaut** | `FPlugin::IsEnabledByDefault` |
| Paquets | pour un plugin de contenu, les paquets `Mods/<Nom>/Content/Paks/Windows/*.pak` (et leurs conteneurs IoStore `.utoc`/`.ucas`) sont **montés au démarrage** ; ses assets ont le préfixe `/<Nom>/` | `PluginManager.cpp`, montage des paquets de plugins |
| Registre d'assets | au démarrage, le registre ajoute le `AssetRegistry.bin` de chaque plugin de contenu activé : les assets du mod sont trouvables par classe et par nom (`GetAssetsByClass`, utilisé par le jeu pour vêtements, animations, meubles…) | `AssetRegistry.cpp`, `LoadPremadeAssetRegistry_Plugins` |
| Signature | aucun `DefaultCrypto.ini` : paquets non signés, non chiffrés | `Config/` |
| Shaders | `bShareMaterialShaderCode=False` : les shaders sont dans les matériaux eux-mêmes, pas de bibliothèque partagée à fournir ; une instance de matériau (`DazHair`) n'en ajoute aucun | `DefaultGame.ini` |
| Format | le jeu est cuit en conteneurs IoStore (O2) : un mod doit l'être aussi, avec le même moteur et contre la **même version cuite** du jeu | `DefaultGame.ini` |

Le mécanisme existe donc dans le moteur ; il n'a jamais été utilisé par LifePlay.

## 2. Architecture proposée

```
<jeu>/LifePlay/Mods/<Nom>/<Nom>.uplugin                       descripteur (plugin de contenu, type Mod)
<jeu>/LifePlay/Mods/<Nom>/AssetRegistry.bin                   registre des assets du mod
<jeu>/LifePlay/Mods/<Nom>/Content/Paks/Windows/<Nom>*.pak/.utoc/.ucas   assets cuits
<jeu>/LifePlay/Content/Modules/<Nom>/<Nom>.lpmod              module LifePlay (texte, comme aujourd'hui)
<jeu>/LifePlay/Content/Modules/<Nom>/Hairstyles/*.lphair      HAIRSTYLE: /<Nom>/Hairs/X.X
```

Un mod se distribue en une archive à extraire dans le dossier du jeu. Le texte reste dans `Modules` (gestionnaire de
mods, activation, données) ; les assets sont dans `Mods` (moteur). Désactiver le module retire ses coiffures
(H1) ; le paquet reste monté mais n'est plus utilisé.

**Fabrication d'un mod** (par un moddeur, avec le projet source publié) :

1. créer un plugin de contenu dans `Mods/<Nom>` du projet ;
2. y importer ses assets (coiffures : `Tools/HairPipeline.ps1` avec `folder` = `/<Nom>/Hairs`) ;
3. cuire **ce seul plugin** en DLC contre la version publiée du jeu :
   `RunUAT BuildCookRun ... -cook -stage -pak -iostore -dlcname=<Nom> -basedonreleaseversion=2026.10.4` ;
4. assembler l'archive du mod (plugin cuit + module texte).

**Côté jeu** : rien à recompiler pour le montage. À ajuster :

- `LPHairstyleSubsystem` : contrôle d'une coiffure par le registre (déjà) avec repli sur
  `FPackageName::DoesPackageExist` si le registre du mod manquait ;
- **version de référence** : chaque publication doit produire `Releases/<version>/Windows/` (option
  `-createreleaseversion=<version>` du build de distribution) et la livrer avec les sources ; un mod est cuit contre
  elle. Pour la V1.4 publiée, elle se recrée par une cuisson incrémentale (contenu inchangé depuis le tag `v1.4`).

## 3. Risques et inconnues à lever par un prototype

| Risque | Conséquence | Vérification |
|---|---|---|
| Cuisson DLC dans ce projet (plugin dans `Mods/`, `-basedonreleaseversion`) | outil des moddeurs inutilisable | cuisson d'un mod d'essai |
| Compatibilité du conteneur IoStore du mod avec celui du jeu publié | mod non chargé, ou plantage au chargement | montage dans une copie du build Shipping V1.4 |
| Références du mod vers le jeu (squelette Genesis, matériau `DazHair`) | coiffure sans matériau ou sans squelette | contrôle visuel en jeu |
| Mod cuit contre une version, joué avec une autre | incompatibilités si les assets référencés changent | règle : un mod indique la version du jeu ; les assets de base référencés (squelettes, matériaux maîtres) ne sont plus renommés |
| Taille de `Releases/<version>` à livrer avec les sources | dépôt alourdi | mesure ; hors git si volumineux (archive des sources seulement) |
| Mods malveillants | un paquet ne contient que des assets cuits (pas de code) ; les plugins de code ne sont pas chargés dans un jeu Shipping sans binaire compatible | rien à faire au-delà de l'avertissement |

## 4. Lots proposés

| Lot | Contenu | Sortie |
|---|---|---|
| **H3a, prototype** | version de référence `Releases/2026.10.4` ; mod d'essai `LPHairSample` (une coiffure Pocolov non encore intégrée, ex. Pocolov 05/07) ; cuisson DLC ; installation dans une **copie** du build Shipping V1.4 | coiffure du mod visible et fonctionnelle en jeu, sans recuire le jeu |
| **H3b, outillage** | `Tools/BuildMod.ps1` (squelette de plugin, cuisson DLC, archive du mod) ; option `HairPipeline` vers `/<Nom>/` ; repli `DoesPackageExist` dans le sous-système | un mod de coiffures en une commande |
| **H3c, documentation moddeurs** | guide (anglais) : créer, cuire, distribuer, compatibilité de version ; intégration de la création de `Releases/<version>` au protocole de publication | guide publié avec la version suivante |

## 5. Prototype H3a (2026-10-03) : résultats

Validé en jeu le 2026-10-03 : la coiffure Pocolov 05, apportée par un mod cuit à part, est chargée par le jeu publié
sans recuisson du jeu ; décocher le mod la retire.

| Étape | Résultat |
|---|---|
| Version de référence | `-createreleaseversion=2026.10.4` (build Shipping, cuisson incrémentale) : `Releases/2026.10.4/Windows` ; paquets **identiques octet pour octet** à ceux du V1.4 publié. Taille : **1,3 Go** (copie complète des paquets du jeu, à livrer aux moddeurs : H3c) |
| Mod d'essai | plugin `LPHairSample` (`CanContainContent`), coiffure importée par `Tools/HairPipeline.ps1 -Config Tools/mods/LPHairSample.json` dans `/LPHairSample/Hairs` ; dépendances : ses assets et `/Game/Heavy/Daz/Bridget/Hairs/DazHair` |
| Cuisson DLC | `-dlcname=<chemin du .uplugin> -basedonreleaseversion=2026.10.4` : 6 paquets, 0 erreur, 0 avertissement ; `LPHairSampleLifePlay-Windows.pak/.utoc/.ucas` (≈ 337 Ko) ; le `.pak` contient le `AssetRegistry.bin` du mod |
| Installation | `<jeu>/LifePlay/Mods/LPHairSample/` (`.uplugin` + `Content/Paks/Windows/*`) et `<jeu>/LifePlay/Content/Modules/LPHairSample/` (`.lpmod`, `.lphair`, `CREDITS.txt`) |
| Compatibilité | mod cuit contre 2026.10.4, chargé aussi par le build UI15b (menu principal modifié depuis) |

Commandes :

```powershell
cmd /c '"<UE>\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="<projet>" -platform=Win64 -clientconfig=Shipping -build -cook -iterate -stage -pak -iostore -compressed -createreleaseversion=2026.10.4 -archive -archivedirectory=<dossier> -nodebuginfo -unattended -utf8output -nop4'
cmd /c '"<UE>\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="<projet>" -platform=Win64 -clientconfig=Shipping -cook -stage -pak -iostore -compressed -dlcname="<projet>\Mods\LPHairSample\LPHairSample.uplugin" -basedonreleaseversion=2026.10.4 -nodebuginfo -unattended -utf8output -nop4'
```

Enseignements :

- **Version en argument** : appelé directement depuis PowerShell, `-createreleaseversion=2026.10.4` est coupé en
  `2026` et `.10.4` (version `2026` créée, déplacée vers `LifePlay_Backup_5.5\H3a`) : passer par `cmd /c '…'`.
- **Sources des mods hors du jeu de base** : un plugin dans `<projet>/Mods/` est un plugin Mod chargé par l'éditeur et
  cuit avec le jeu ; un module dans `Content/Modules/` est livré avec le jeu. Les sources du mod d'essai sont donc dans
  `ModSources/LPHairSample/` (`.uplugin`, `Content/` non versionné, `Module/` texte) ; pour la cuisson DLC, le plugin est
  placé temporairement dans `Mods/` (H3b : `Tools/BuildMod.ps1`). Les builds de test H3a/UI15 ont été faits avec les
  sources sorties du projet ; vérifié : aucun asset `/LPHairSample/` dans les paquets du jeu.
- **Activation des modules** (défaut de H1, présent en V1.4) : pour le jeu (`GI.IsModEnabled`, gestionnaire de mods), un
  module absent de `GI.ModEnableds` est inactif ; `LPHairstyleSubsystem` le croyait actif (coiffure du mod présente,
  mod décoché). Corrigé : même règle que le jeu ; nouvelle clé `.lpmod` `MODULE_DEFAULT_ENABLED: true`, qui ajoute
  le module coché à la liste des mods s'il n'y figure pas (`lp_Revival`, livré avec le jeu).
- **Gestionnaire de mods** : accessible seulement en partie ; entrée ajoutée sur l'écran titre (lot UI15,
  [17_Mods_Ecran_Titre.md](17_Mods_Ecran_Titre.md)).
- `Tools/HairPipeline.ps1` accepte un dossier de plugin (`/<Plugin>/...` → `Mods/<Plugin>/Content/...`) et un fichier
  de crédits propre au mod (`credits`) ; `Tools/HairMaterials.py` contrôle les dépendances par chemin de paquet.
- Relancer `HairMaterials.py` sur une coiffure dont les textures existent déjà dans un plugin fait planter la commandlet
  (boîte de dialogue de remplacement à l'import) : à traiter en H3b.

## 6. Outillage H3b (2026-10-03)

Validé en jeu le 2026-10-03 (build `LifePlay_Build_5.5_H3b`, mod installé par l'outil).

Organisation d'un mod d'assets :

```
ModSources/<Nom>/<Nom>.uplugin     plugin de contenu (versionné)
ModSources/<Nom>/Content/          assets du mod (non versionnés, comme Content/Heavy)
ModSources/<Nom>/Module/           module LifePlay en texte : <Nom>.lpmod (MODULE_UNIQUEID = <Nom>),
                                   Hairstyles/*.lphair, CREDITS.txt (versionnés)
```

`<projet>/Mods/` reste vide : `Tools/ModSource.ps1` y déplace le mod le temps d'un travail (import, cuisson) puis le
remet dans `ModSources/` (déplacements seulement). Le build du jeu de base ne contient donc rien des mods sans
manipulation (vérifié : aucun asset `/LPHairSample/`, ni `Mods/`, ni module dans le build H3b).

Fabrication :

```powershell
.\Tools\HairPipeline.ps1 -Config Tools\mods\<Nom>.json -Step Inspect   # "mod": "<Nom>", "folder": "/<Nom>/Hairs"
.\Tools\HairPipeline.ps1 -Config Tools\mods\<Nom>.json -Step Apply
.\Tools\BuildMod.ps1 -Name <Nom> [-Version 2026.10.4] [-Out D:\Game\LifePlay_Publication\Mods] [-Install <jeu>\Windows]
```

`BuildMod.ps1` : contrôles (plugin, module, version de référence `Releases/<version>`, aucun autre plugin dans `Mods/`),
cuisson DLC par un `.cmd` écrit à côté du journal (`Saved/Logs/portage/mods/`), contrôle du conteneur (toutes les
entrées sous `Mods/<Nom>/`), assemblage `<Nom>-for-LifePlay-<version>` (`LifePlay/Mods/<Nom>`,
`LifePlay/Content/Modules/<Nom>`, `README.txt` bilingue), archive `.zip` testée ; un assemblage précédent est déplacé
(`precedent_<date>`). Mod d'essai : `LPHairSample-for-LifePlay-2026.10.4.zip`, 334 Ko, 8 fichiers.

Corrections du lot :

- `Tools/HairMaterials.py` : dans un plugin, le registre d'assets de la commandlet ne connaît pas encore les assets
  existants (`does_asset_exist` faux) ; la création d'un matériau existant ouvrait une boîte de dialogue et plantait
  (`Assertion failed: IsValid()`). Analyse synchrone du dossier au départ ; texture déjà importée depuis la même
  source réutilisée (autre source dans un plugin : refus, `-Rebuild`).
- `HairPipeline.ps1 -Rebuild` d'un mod déplace aussi les textures vers la sauvegarde ; une reconstruction demande une
  nouvelle inspection (les maillages de travail sont rangés dans la sauvegarde après chaque application).
- `LPHairstyleSubsystem` : coiffure de mod absente du registre d'assets acceptée si son paquet existe
  (`FPackageName::DoesPackageExist`, avertissement).
- `BuildMod.ps1` : `cmd /c` avec guillemets imbriqués échoue depuis PowerShell (« syntaxe du nom de fichier
  incorrecte ») ; d'où le fichier `.cmd`.

## 7. Documentation et publication (H3c, 2026-10-03)

- Guide des moddeurs (anglais, avec les guides d'origine de Vinfamy) :
  `Docs/Modding/FullGuides/Creating_Asset_Mods.md` (fonctionnement, prérequis, création, coiffures, éditeur, cuisson et
  essai, diffusion, dépannage) ; `Docs/Modding/ShortGuides/explanation.lphair` (format `.lphair`) ;
  `explanation.lpmod` complété (`MODULE_DEFAULT_ENABLED`).
- Outils des moddeurs : `Tools/NewMod.ps1` (squelette `ModSources/<Nom>` : `.uplugin`, `Module/<Nom>.lpmod`,
  `CREDITS.txt`, et avec `-Hairs` `Tools/mods/<Nom>.json`), `Tools/EditMod.ps1` (éditeur ouvert avec le mod monté,
  remis en place à la fermeture). Essai de `NewMod.ps1` sur un mod jetable `H3cTest` (déplacé vers
  `LifePlay_Backup_5.5\H3c`) : fichiers conformes, nom déjà pris refusé.
- Publication : la version de référence fait partie de chaque publication (`10_Protocole_Operations.md` §6, liste de
  contrôle `09_Commandes_Utiles.md` §7). L'archive des sources V1.4 publiée ne la contient pas : les mods d'assets
  sont donc possibles pour les moddeurs à partir de la publication suivante (la V1.4 reste jouable avec des mods cuits
  ici contre `Releases/2026.10.4`).
- Ne pas faire de build complet destiné à la publication sans recréer la version de référence correspondante.

## 8. Métadonnées, avertissement de version et paquet Pocolov (H3d, 2026-10-03)

Validé en jeu le 2026-10-03 (build `LifePlay_Build_5.5_H3d`).

- **Lecture des `.lpmod` par le jeu** (vérifiée dans `GI`) : seules les lignes 1 à 3 sont lues, **par position**
  (`MODULE_UNIQUEID`, `MODULE_NAME`, `MODULE_AUTHOR`) ; le gestionnaire de mods affiche le fichier entier
  (`ModuleTick.FullString`). Toute ligne ajoutée après la troisième est donc sans risque et visible des joueurs.
- **Clés ajoutées** : `MODULE_VERSION`, `MODULE_CREATED`, `MODULE_LICENSE`, `MODULE_AUTHOR_LINK`, `MODULE_PRICE`
  (écrites par `Tools/NewMod.ps1`), `MODULE_PACKAGED`, `MODULE_GAME_VERSION` (écrites par `Tools/BuildMod.ps1` dans la
  copie livrée). `BuildMod.ps1` contrôle l'ordre des trois premières lignes, reporte la version et le lien de l'auteur
  dans le `.uplugin` livré (`VersionName`, `CreatedByURL`), nomme l'archive `<Nom>-<version>-for-LifePlay-<jeu>.zip`
  et refuse un mod payant dont `CREDITS.txt` cite une licence non commerciale ou de magasin.
- **Avertissement** : `ULPModInfoSubsystem` (C++, `Source/LifePlay`) lit les `.lpmod` et, toutes les 2 s, compare le
  `MODULE_GAME_VERSION` des modules **actifs** à `ProjectVersion` ; un écart ouvre une fenêtre Slate « Mod version
  warning » (indépendante des Blueprints, aussi sur l'écran titre), une fois par module et par session. Testé avec un
  module texte déclaré pour 2026.9.1 (déplacé ensuite vers `LifePlay_Backup_5.5\H3d`). Métadonnées accessibles aux
  Blueprints : `GetModuleMetadata(Module, Key)`.
- **Paquet `lpr_hair_pocolov` 1.0** : sur 192 produits Pocolov (Fab), les 12 coiffures CC BY (03, 05, 06, 07, 09, 10,
  11, 13, 14, 15, 16, 17) ; exclus : 5 coiffures payantes (licence standard Fab : redistribution interdite), vêtements
  « Avatall » (autre squelette), objets, armes, véhicules. Configuration `Tools/mods/lpr_hair_pocolov.json` (réglages
  HAIRS1 repris ; détection identique aux choix validés). Pocolov 07, 09, 10, 13, 14 téléchargées (CC BY 4.0, accord du
  2026-10-03). La Pocolov 09 a sa calotte en maillage séparé, non convertie : rendu jugé correct en jeu.
  `MODULE_DEFAULT_ENABLED: true` (les sauvegardes qui utilisaient les anciennes coiffures du jeu les retrouvent dès que
  le paquet est installé). Archive `lpr_hair_pocolov-1.0-for-LifePlay-2026.10.4.zip` (3,8 Mo, 70 paquets cuits).
- **Jeu de base allégé** : les 6 Pocolov de `/Game/Heavy/New5/Hairs` et le module `lp_Revival` sont retirés du jeu
  (déplacés vers `LifePlay_Backup_5.5\H3d\retires`), leurs crédits passent dans le `CREDITS.txt` du paquet ; le mod
  d'essai `LPHairSample` est retiré (même dossier). Modules essentiels de la prochaine publication :
  `Tools/modules/next.json`.