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. 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

.\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):

   {
     "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:

   .\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):

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

.\Tools\EditMod.ps1 -Name MyHairPack

Opens the editor with the mod mounted: its assets appear in the Content Browser under MyHairPack Content (/MyHairPack/). Plugin content is hidden by default: in the Content Browser settings (gear icon), tick Show Plugin Content. The search box matches asset names, not folder names (search MyHair, not 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

.\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