CCXL: Hairs
Last updated
Last updated
Published: Jan 20 2025 by manavortex and Last documented edit: Jan 18-20 2025 by manavortex, , 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
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 overwrite 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
As you do not need any .ent files in your CCXL hair project, delete them now.
Thanks to ArchiveXL magic, your .app file needs only one appearance. All other appearances will be extrapolated from it!
You have two choices - you can either adjust your existing .app file, or use the example mod's.
Make sure to delete everything in partsValues, since the .ent file it was pointing at is gone now
Check that your hair components and paths are correct (you can use File Validation to help you)
You can use any of the existing base game hair colours, as long as the definition itself is valid.
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, 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 are generated as follows:
The tutorial hair has only two materials, and three material entries (@context, @long, @cap):
Now, let's look at the materials themselves.
The first material is special:
It does not have a base material
It needs one value entry for every dynamic material (see below)
All of its values must be of the type CpuNameU64. You can create one as follows:
The parameter names must be named SomethingBaseMaterial, where Something must correspond with the names of the other materials with an uppercase letter (in our example, @long and @cap)
The parameter value points at the .mi file in the project
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.
If your hair is using base game materials, you can use the baseMaterial from inside the .mi file, use it as the baseMaterial in your .mesh's material, and delete the file.
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.
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.
This entry must be nameless, or it will overwrite the basegame switcher!
link: Targets one of the headGroups entries
names: Contains the headGroup's options
hairstyle_cyberwareThis entry defines the hairstyle for cyberware_01.
gameUiAppearanceInfosFrom 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.
