Adding new items: files from scratch

How to set up the folder structure from scratch

TL;DR: If you can't be arsed doing this by yourself, find a template project with one working item (female rigged) here. (But in this case: Why are you reading this page?)

This guide deals with finding the correct files for an ArchiveXL item addition. For an explanation of the file structure, see the corresponding wiki page.

Overview:

File in modded dir	was originally copied from
rootentity.ent	base\gameplay\items\equipment\underwear\player_underwear_item.ent
appearance.app	base\gameplay\items\equipment\underwear\appearances\player_underwear_item_appearances.app
mesh_entity.ent ⚠ Check the red hint box ⚠	base\characters\garment\player_equipment\torso\t1_080_pwa_tank__judy.ent
my_mesh.mesh	base\characters\garment\gang_monk\torso\t2_135_jacket__monk_shirt\t2_135_wa_jacket__monk_shirt.mesh
my_tshirt_factory.csv	base\gameplay\factories\items\clothing.csv
translation_strings.json	base\localization\en-us\onscreens\onscreens.json
preview_icons.inkatlas	base\gameplay\gui\common\icons\items\item_icons6.inkatlas
preview_icons.xbm	base\gameplay\gui\common\icons\items\item_icons6.xbm
tutorial_my_custom_tshirt.archive.xl	Wolvenkit -> New File -> ArchiveXL
tutorial_my_custom_tshirt.yaml	Wolvenkit -> New File -> TweakXL

For mesh_entity.ent, your entity file needs to correspond to your item's body part. If you put a shirt in an entity file for shoes, it will deform badly once you put it on. You can find the entity files in base\characters\garment\player_equipment, where they are sorted in subfolders by body part (e.g. torso, legs, feet).

You also need to grab a player .ent file rather than an NPC one

It is good practice to keep local copies of everything that you change (=> custompathing) instead of overwriting files under base. This makes sure that no other mods will overwrite your changes.

ℹ Only keep files under base if you are okay with them being overwritten!

Optional, but very recommended: Clean out obsolete entries

1. Open the file translation_strings.json in WolvenKit. Expand the array root and then the array entries. Delete all entries but one.

2. Open the file my_shirt_factory.csv in WolvenKit. In compiledData, delete all entries but one. In data, delete everything - these will get autogenerated.

3. Open the file root_entity.ent.

   Expand the list appearances. Delete all entries but the first (most likely default).

4. Open the file my_custom_shirt.app. Expand the list appearances. Delete all entries but default.

5. Open the file mesh_entity.ent Select resolvedDependencies and delete all the entries. (We don't need Judy's top anymore.)

6. Make a back-up copy of your t1_custom_shirt.mesh, then open it.

   1. Expand the first appearances at the top of the file. Open the appearance default and check which material is linked in the chunkMaterials array.

Now is a good time for a backup.