Published: Jan 20 2025 by and Last documented edit: Feb 16 2025 by , , , , and
This page will tell you how to use ArchiveXL to add hair to the character creator.
To learn more about the character creator, check Game Components explained -> Character Creator: .inkcc
To convert an existing hair mod to CCXL, check Convert a hair mod to hair CCXL mod
You have downloaded the example project from Nexus
If you would rather understand what you're doing, please skip to Step 1: Deleting .ent files!
Download example project
Add your .mesh file to the project
Copy the appearances, materialEntries, and localMaterialDefinitions from the template mesh
Overwrite it with your own
Overwrite the .rig and the .animgraph with your own, if you have them
Adjust .app file entry
If you're not using base game textures: Change files paths in the .mi
Rename the .xl file
Change translation key in the .json file to something unique for your mod
Change translation entries in the .inkcharactercustomization file
Custompath everything — do not publish anything that still contains tutorial files!
Profit
We will be moving backwards through the files: starting at the bottom, and working our way to the top (the character creation and the .xl control file).
Start by downloading the example project from Nexus
Unpack the source folder into the root of your existing hair project so that it merges with yours
Move any .mesh, .animgraph, and .rig files from your original hair to your_modder_name\ccxl\your_first_addition\meshes
If you don't have any .ent files, you're good!
If you do have them, delete them now – we don't need them in our CCXL projects.
Thanks to ArchiveXL magic, your .app file needs only one appearance. All other appearances will be extrapolated from it!
You can use any of the existing base game hair colours, as long as the definition itself is valid.
The template file has three .app files – one of them is for your hair's default appearance, one is for the cyberware_01 appearance, and one is for the first person hair.
If you do not have a cyberware_01 appearance, you can delete this file and adjust the file path under Step 6: The .incharactercustomization file
If you want to add more meshes/rigs to the template .app (for example from uuhv4), you can duplicate the entSkinnedMeshComponent and the matching entAnimatedComponent from the context menu.
File Validation can help you making sure that your hair components and paths are correct.
This section will explain how ArchiveXL works its magic to pick all the right hair colours and -textures from three entries and a piece of duct tape.
If you are converting an existing hair mod, you probably already have these files.
In this case, copy appearances, materialEntries, and localMaterialInstances from the template file to your existing hair mesh.
We'll now go through everything step by step.
As you can see, you only need a single appearance — ArchiveXL will generate all the rest.
If your hair mesh is set up differently from the template file, you need to adjust the chunk materials here!
In our example, the first submesh uses the material @long, and the second one the material @cap.
The names must be set as follows:
The tutorial hair has only two materials, and three material entries (@context, @long, @cap):
You can define more materials here if you need them (please note the box below)
You have to use the exact material names that ArchiveXL is expecting, or extra hair colours won't work.
Now, let's look at the materials themselves.
This is not actually a material instance – instead, this is where you register your mesh file's material properties for ArchiveXL's character creator extensions.
Please note the following:
It does not have a base material
Each value points at one .mi file in the project
All of its values must be of the type CpuNameU64. You can create one as follows:
You need to create one entry for every type of material that you want ArchiveXL to expand.
If your hair is using a material multiple times (e.g. long, long, cap), you still create only one LongBaseMaterial value.
This material defines the hair cards. It points at the .mi file in your project, where the hair's textures are defined.
All ResourcePaths must have Soft flags for this to work, including the baseMaterial! (see screenshot)
Since the dynamic context does not transfer to the .mi, we need to set the HairProfile here.
The {material} placeholder in the file entry will be replaced with the chunk mask name from the appearance (e.g. black_carbon).
This material defines the hair cap (the stubbles on the scalp). It points at the .mi file in your project, where the scalp's textures are defined.
Since the dynamic context does not transfer to the .mi, we need to set the GradientMap here. Omitting this will lead to the hair cap looking way darker than it's supposed to.
The .mi file and the @context are required for ArchiveXL character creator extensions. Without a .mi file, you won't have e.g. extra hair colours (e.g. Hair Profiles CCXL)
With the exception of the hair cap, the .mi file is a completely normal material tempate file (link not necessary for understanding this guide).
The hair cap base material is included within ArchiveXL. If you aren't using one, you don't need to know any of this — just move all properties without dynamic properties from the .mesh file into your .mi.
Open the included .json file, and make sure to change the entries according to your needs.
There are two translation entries, because this tutorial assumes that you want to name the cyberware_01 variant differently.
For an explanation of what is what, keep reading.
femaleVariant
Your First Hair
maleVariant
leave it blank
If no value is found, then femaleVariant acts as default
primaryKey
0
Will be generated by ArchiveXL, leave it alone
secondaryKey
UI-Customization-your_first_hair
Used in the .inkcharactercustomization file to set your hair's entry name
incharactercustomization fileHere is where everything connects to each other.
For more information about this, see .inkcharactercustomization: CC options
Open the file, we will look at the entries now.
These entries create character creator additions, while the CustomizationOptions define them (think of a materialDefinition and a materialInstance in a .mesh file).
Let's take a look at the headCustomizationOptions. The first to entries of the type gameuiSwitcherInfo add our new hair to Cyberpunk's character creator menu, so that they show up when you scroll through the hairs.
If you're only using one hairstyle mesh, keep this entry nameless, or it will overwrite the Character Creator: .inkcc's base switcher!
link: Targets one of the headGroups entries
names: Contains the headGroup's options
If you want to use a different mesh when cyberware_01 is enabled, you will have to cut "hairstyle" from the link in the first entry and instead put it in name to have two visibly distinct meshes. Otherwise you'll only have one mesh visible.
hairstyle_cyberwareThis entry defines the hairstyle for cyberware_01.
gameUiAppearanceInfosThe template inkcc has three gameUiAppearanceInfos, one for your hair, one for the cyberware_01 variant, and one for FPP.
If you do not have an extra appearance for cyberware_01, you can re-use the default hair .app file.
Make sure to adjust the paths to your corresponding .app file:
From your project's resource directory, open the .archive.xl file that you created in the previous guide. Add the following lines at the bottom (make sure that there are no leading spaces):
Now it's time to custompath your project.
On some versions of WolvenKit, you might encounter an issue where a file like .inkcharcustomization fails to apply the custom path, in that case you'll have to open the file and copy relative path of your .apps
It's recommended to look in the Log view and check if there's an error in a renaming custompaths in files.
Most likely, you screwed up the names of your material definitions. They must be exactly as ArchiveXL expects them to be. Go back to 3.2 Material definitions and double-check everything.
This happens due to having a different localizedName forcyberware_hairstyle switcher that's inside the.inkcc file. For exampleUI-Customization-your_first_hair in the blank switcher, and UI-Customization-your_first_hair_cyberware in the cyberware_hairstyle switcher.
If you want to have a unique hairstyle mesh when cyberware_01 is enabled refer to 6.2 gameUiSwitcherInfos, specifically the hint about link and name.
To understand appearances, you can check 3d objects: .mesh files-> . This is not necessary to complete the guide, though!
To understand material definitions, you can check 3d objects: .mesh files -> . This is not necessary to complete the guide, though!
For a full list, see ArchiveXL: Character Creator additions ->
To understand materials, you can check 3d objects: .mesh files -> . This is not necessary to complete the guide, though!
For a full list, see ArchiveXL: Character Creator additions ->
For more information on this, see .inkcharactercustomization: CC options -> . This is not necessary for the purpose of this guide!
This page will tell you how to use ArchiveXL to add body tattoos to the character creator
To learn more about the character creator, check Game Components explained -> Character Creator: .inkcc
If you want to create a tattoo first, check out For V - Creating Custom Skins - Tattoos - Scars Textures
You have a
You have downloaded the example project from Nexus, and merged it with your project's source folder
We recommend that you use the suggested paths, as the template is configured to load files from there, then rename files at the very end once everything works.
If you ignore this advice, you're making things needlessly difficult for yourself.
In this tutorial, we will create an overlay mesh from a base game body mesh, which you can get from the .
If you want to create an overlay from a modded body, use the instead.
You can look up all mesh paths in Cheat Sheet: Body
This is the path to acquire the gender you want to work on for vanilla V.
For the tutorial, I will take male V's right arm:
ArchiveXL will do the heavy lifting, but if we leave the body mesh where it is right now, you will break the player body. For that reason, you need to rename the mesh file (you can use Wolvenkit's rename menu - hotkey: f2).
For this tutorial, we'll put it in the following path (where the template files expect it):
This tutorial will not go into details about this process, but you need to
Slightly inflate the mesh so that it doesn't clip with the body (you can use a shrinkwrap modifier for this)
Import back into your project (check the link in the first bullet point)
In this section, we will configure your .mesh file to load the texture(s) via the included .mi.
The textures are inside the textures folder. They are loaded by the .mi file.
If you want to tweak the parameters, make sure to edit this file (we will look at it in more detail later).
You can learn more about meshes and materials on the 3d objects: .mesh files page, and about .mi files under Re-using materials: .mi.
This is not necessary for the purpose of this tutorial.
Open your .mesh file in Wolvenkit
Create or edit a materialEntry:
Set the name to your_tattoo
Set isLocalInstance to true (check the box)
Create or edit a local material instance:
If your mesh does not have preloadLocalMaterialInstances, use localInstances.materials instead.
Set baseMaterial to your_modder_name\ccxl\your_tattoo\textures\your_tattoo.mi
(the relative path to the .mi file)
Create or edit an appearance: the chunkMaterials need to point at your_tattoo.
As this is a template project, the .app is already configured. Since you moved the .mesh to your_modder_name\ccxl\your_tattoo\models\your_tattoo_pma.mesh, you don't need to change anything here:
Now, use dynamic renaming feature and rename your files.
Since our imported mesh is named as your_tattoo_pma, the dynamic renaming feature will allow you to rename it to whatever you want. If you ignored our advice, have fun correcting all those entries one by one:
You can use the dynamic renaming feature (check the box) to safely move all the files in your project.
Change the localizedName entry to something globally unique – call it something like UI-customization_yourmoddername_my-first-tattoo.
If you end up using the same translation key as somebody else, the game might show either entry, and you probably don't want that.
This works the same as in CCXL: Hairs -> Step 5: The translation entry
This entry defines what the game will display instead of UI-customization_yourmoddername_my-first-tattoo (as defined in our .inkcharcustomization file).
FemaleVariant is used as default, so you can leave the male variant empty.
Open the .archive.xl on your project's directory. Here, double-check the paths and make sure that they point at the relative paths of your files.
Note: If you want to do for only one gender, just delete either male or female from the .xl and make sure to pick the mesh path to load the one you want if you want either of the genders. Adapting a tattoo is usually pretty easy! Why not make your mod for both genders?
How to add new items to the character creator
Published: Jan 19 2025 by and IslandDancer Last documented edit: Jan 19 2025 by and IslandDancer
This page groups the individual CCXL addition guides. For a full explanation of the structure, see CCXL: Hairs.
To learn more about the character creator, check Game Components explained -> Character Creator: .inkcc
The full list of hair style materials as supported by CCXL extension:
@beard
BeardBaseMaterial
@braid
BraidBaseMaterial
@cap
CapBaseMaterial
@cap01
CapBaseMaterial
@curls
CurlsBaseMaterial
@dread
DreadBaseMaterial
@long
LongBaseMaterial
@short
ShortBaseMaterial
@brows
BrowsBaseMaterial
@lashes
LashesBaseMaterial
While @cap01 falls back to CapBaseMaterial, this is how you can define an extra hair cap texture for cyberware_01.
