LifePlay-Revival/Docs/Modding/FullGuides/Creating_Asset_Mods.md

# Creating asset mods (hairstyles, and more)

*LifePlay Revival addition (UE 5.5). Available from the first release published with its reference version (`Releases/<version>` in the full source archive), that is the release after LifePlay 2026.10.4 (V1.4).*

Text mods (scenes, actions, stats, presets...) work as before: a folder in `LifePlay/Content/Modules`, see
[Getting_Started.txt](Getting_Started.txt). This guide is about mods that bring **new 3D assets** (meshes, textures,
materials) without rebuilding the game. The first supported use is **hairstyles**.

## 1. How it works

An asset mod has two parts, installed side by side in the game folder:

```
LifePlay/Mods/<Name>/<Name>.uplugin                      plugin descriptor
LifePlay/Mods/<Name>/Content/Paks/Windows/<Name>LifePlay-Windows.pak/.utoc/.ucas   cooked assets
LifePlay/Content/Modules/<Name>/<Name>.lpmod             LifePlay module (text, as usual)
LifePlay/Content/Modules/<Name>/Hairstyles/*.lphair      hairstyle declarations
LifePlay/Content/Modules/<Name>/CREDITS.txt              credits and licenses
```

- The engine mounts every plugin found in `LifePlay/Mods/` at startup. Its assets live under `/<Name>/...`.
- The text module makes the mod visible in the **Mod Manager** (title screen, or Ctrl-M in game). The hairstyles are
  available only while the module is enabled.
- Cooked assets are tied to a game version: a mod is built against the **reference version** of a release
  (`Releases/<version>`, shipped with the full source archive) and is made for that version. Another game version
  may require rebuilding the mod.

## 2. Requirements

- Windows, Unreal Engine **5.5** (Epic Games Launcher), Visual Studio 2022 is not needed for asset mods.
- The **LifePlay Revival full source archive** of the game version you target, including `Releases/<version>/`
  (for example `Releases/2026.10.4/` for LifePlay 2026.10.4). Open `LifePlay.uproject` once to let the editor build
  its caches.
- 7-Zip (`C:\Program Files\7-Zip\7z.exe`) to package the mod.
- Assets you are **allowed to redistribute**: CC0 or CC BY (credit the author). Store licenses such as the Fab
  "Standard License" forbid redistributing the source files and are not suitable.

The scripts below are in `Tools/` and are run from a PowerShell window in the project folder. The engine path
(`D:\Game\Launcher\Engine\UE_5.5`) is set at the top of each script: adjust it if your engine is elsewhere.

## 3. Create the mod

```powershell
.\Tools\NewMod.ps1 -Name MyHairPack -Title "My Hair Pack" -Author "Me" -Hairs
```

This creates the mod sources in `ModSources/MyHairPack/`:

```
ModSources/MyHairPack/MyHairPack.uplugin     content plugin
ModSources/MyHairPack/Content/               your assets (filled by the editor or the hair pipeline)
ModSources/MyHairPack/Module/MyHairPack.lpmod
ModSources/MyHairPack/Module/CREDITS.txt
Tools/mods/MyHairPack.json                   hair pipeline configuration (with -Hairs)
```

Mod sources stay in `ModSources/`. The tools move a mod into the project's `Mods/` folder only while they work on it
(import, cook) and move it back afterwards: a plugin left in `Mods/` would be cooked into the base game.

The name is the plugin name, the asset root (`/MyHairPack/`) and the module ID: letters, digits and underscores,
starting with a letter, unique.

## 4. Add hairstyles

Hairstyles must be skinned to the Genesis 8 skeleton used by the game characters and use the game's hair material.
The hair pipeline does this for static hairstyles distributed as FBX (for example the free Pocolov hairs on Fab):
it fits the hair to the default head, transfers skin weights from the body (head, neck, chest) so long hair follows
the character without cutting through the skin, and creates `DazHair` material instances.

1. Download the hairstyle archives (zip/rar/7z with an FBX and its textures).
2. Add one entry per hairstyle in `Tools/mods/MyHairPack.json` (see `Tools/mods/lpr_hair_pocolov.json`, the 12 Pocolov
   hairstyles, for a complete example):

   ```json
   {
     "name": "MyHair01",
     "archive": "D:/Downloads/my-hair-01.zip",
     "title": "My Hair 01",
     "url": "https://source/of/the/asset",
     "author": "Original author",
     "license": "CC BY 4.0",
     "sex": "F",
     "mesh": "auto", "head": "auto", "cap_slots": "auto", "diffuse": "auto", "strands_opacity": "auto",
     "cap_opacity": "white",
     "thicken": 1
   }
   ```

3. Inspect, read the report, fix the JSON if a guess is wrong, then apply:

   ```powershell
   .\Tools\HairPipeline.ps1 -Config Tools\mods\MyHairPack.json -Step Inspect
   .\Tools\HairPipeline.ps1 -Config Tools\mods\MyHairPack.json -Step Apply
   ```

   `Apply` writes the assets to `ModSources/MyHairPack/Content/Hairs/`, one `.lphair` per hairstyle in
   `Module/Hairstyles/` and one line per hairstyle in `Module/CREDITS.txt`. To redo a hairstyle: `-Step Inspect` then
   `-Step Apply -Rebuild -Only MyHair01` (the previous version is moved to the backup folder, never deleted).

   Fitting options per hairstyle (`margin`, `scale`, `offset_z`, `offset_y`, `skin`, `gap`) and the detailed protocol
   are described (in French) in `Docs/Migration/13_Protocole_Coiffure.md`.

A `.lphair` file can also be written by hand for a hairstyle made another way (see
[explanation.lphair](../ShortGuides/explanation.lphair)):

```
HAIRSTYLE: /MyHairPack/Hairs/MyHair01.MyHair01
SEX: F
DAZ: true
```

## 4b. Mod metadata

The first three lines of `<Name>.lpmod` are read **by position** by the game and must stay first, in this order:
`MODULE_UNIQUEID`, `MODULE_NAME`, `MODULE_AUTHOR`. The other lines are free; the Mod Manager shows the whole file in its
detail panel, so every line below is visible to players.

| Key | Written by | Meaning |
|---|---|---|
| `MODULE_VERSION` | you (`NewMod.ps1 -ModVersion`, default 1.0) | version of the mod; also in the archive name and the plugin `VersionName` |
| `MODULE_CREATED` | `NewMod.ps1` | creation date (YYYY-MM-DD) |
| `MODULE_LICENSE` | you (`-License`) | license of the mod as a whole (each asset's license stays in `CREDITS.txt`) |
| `MODULE_AUTHOR_LINK` | you (`-AuthorLink`) | author page; also the plugin `CreatedByURL` |
| `MODULE_PRICE` | you (`-Price`, default Free) | information only, the game sells nothing. A non-free mod is refused by `BuildMod.ps1` if `CREDITS.txt` mentions a non-commercial or store license (`NC`, `Standard License`, `Personal`) |
| `MODULE_DEFAULT_ENABLED` | you | `true`: enabled the first time the game finds it; otherwise a new mod starts disabled |
| `MODULE_PACKAGED` | `BuildMod.ps1` (shipped copy only) | packaging date |
| `MODULE_GAME_VERSION` | `BuildMod.ps1` (shipped copy only) | game version the assets were cooked for. If an **enabled** mod declares another version than the game, the game shows a "Mod version warning" window (once per session) |

## 5. Edit the mod in the editor

```powershell
.\Tools\EditMod.ps1 -Name MyHairPack
```

Opens the editor with the mod mounted: its assets appear in the Content Browser under **MyHairPack Content**
(`/MyHairPack/`). Close the editor to move the mod back to `ModSources/`. Keep every asset of the mod inside
`/MyHairPack/`; referencing game assets (skeletons, the `DazHair` material...) is fine, modifying them is not
(changes to game assets are not shipped by the mod).

## 6. Build and test

```powershell
.\Tools\BuildMod.ps1 -Name MyHairPack -Install <test game folder>\Windows
```

`BuildMod.ps1`:

1. checks the plugin, the module and the reference version (`Releases/<version>`, version read from
   `Config/DefaultGame.ini`, or `-Version`);
2. cooks only the mod against the reference version (log in `Saved/Logs/portage/mods/`);
3. checks that the cooked container holds nothing outside `Mods/MyHairPack/` (no game asset is shipped);
4. builds `MyHairPack-for-LifePlay-<version>.zip` (with an install README) in `D:\Game\LifePlay_Publication\Mods`
   (`-Out` to change it);
5. with `-Install`, copies the mod into a test game (the folder that contains `LifePlay.exe`).

Then start the game, open **Mod Manager** on the title screen, enable the mod, close the manager and start or load a
game: the new hairstyles are at the end of the hairstyle list (for the sex declared in `SEX`).

## 7. Distribute

Share the zip. Players extract it into the game folder (the one that contains `LifePlay.exe`), merging the `LifePlay`
folder, then enable the mod in the Mod Manager. To uninstall, they delete `LifePlay/Mods/<Name>` and
`LifePlay/Content/Modules/<Name>`. Always say which LifePlay version the mod was built for, and keep the credits of
every asset in `CREDITS.txt`.

## 8. Troubleshooting

| Symptom | Cause, fix |
|---|---|
| The mod is not listed in the Mod Manager | `LifePlay/Content/Modules/<Name>/<Name>.lpmod` missing, or `MODULE_UNIQUEID` different from the folder name |
| The mod is listed but the hairstyle does not appear | module not enabled; `HAIRSTYLE` path wrong (`/<Name>/Hairs/<Asset>.<Asset>`); `LifePlay/Mods/<Name>/Content/Paks/Windows` missing; wrong `SEX` |
| `Mods\<Name> existe deja` when running a tool | a previous run was interrupted: move `Mods/<Name>` back to `ModSources/<Name>` by hand |
| `Version de reference absente` | the source archive lacks `Releases/<version>`: use the source archive of the targeted game version |
| `Autres plugins dans Mods\` | another mod is still mounted: move it back to `ModSources/` |
| The hairstyle cuts through the shoulders or floats | adjust `gap`, `margin`, `offset_z`, `offset_y` and rebuild the hairstyle |