CCXL: Hair Profiles (Colors)
This will show you how to use the CCXL Hair Profiles template to add your custom hair colors to Character Creator without replacing basegame options.
Summary
Published: May 17, 2025 by nutboy Last documented edit: nutboy on May 17, 2025
Wait, this is not what I want!
To learn how to make hair profiles (hair colors), go here: Custom Hair Colors
To learn to add a hairstyle to character creator, read CCXL hairs
To learn more about the character creator, check Game Components explained -> Character Creator: .inkcc
To convert an existing hairstyle to CCXL, check Convert a hair mod to hair CCXL mod
Requirements
You have hair profiles (.hp) files and/or gradient (.xbm) files ready
Wolvenkit Version: 8.16.1 Stable or newer
Step 0: Make a project
Start by making a new project in WolvenKit. Name your project.
Open your new project's root folder by clicking the yellow folder button on the top right of the project explorer:
In file explorer, open and drag the template files into your project. It will show the files in WolvenKit's project explorer. If it does not, hit the blue refresh 🔄 button next to the yellow root folder button.
Step 1: Replace template folder & file names

Next, we need to replace all placeholders of "moddername" and "modderinitial" and "modname" in the project.
Here are the full steps:
Locate the Archive section of your project explorer.

Select the first folder, then right click and click Rename (or press F2).

Change folder "moddername" to YOUR OWN modder name, and check the box "update in project files"
Change the next folder "modname_ccxl" to a unique project name for this project, and check the box "update in project files"
WolvenKit's logs will print a list of places it updated the names.
HELP!!! I goofed and didn't check the box to "update in project files!"
Don't worry. Rename your folder back to the placeholder name and do not check the update in project files box. Then, rename it again to your new replacement name.
Remember to check the box this time before confirming.
Next, find the Resources folder in project explorer, at the bottom.
Rename the following:
.xl file and .yaml - "
modderinitials_modname
" to the same as what you just named your project.the "
moddername
" folder in r6/tweaks to your modder name.
Next expand your materials folder. Inside there are a bunch of .mi files.
Rename all "modname
" file names to your mod name with "Update in project files" checked.
Do not delete the __
and suffix following (__beard
, __braid
, __brows
, etc) for any files.
Next, rename the .inkcharactercustomization files with "Update in project files" checked.
Next, rename the .inkatlas and icon .xbms with "Update in project files" checked.
Step 2: Update renamed paths in files
Open your .xl file in your text editor of choice, such as Notepad++ or Visual Studio Pro.

In WolvenKit, copy the path to the updated female (PWA) inkcharactercustomization file by hovering it and clicking the orange 🟧 button (or right click > "Copy relative path to game file").
In the xl, under customizations, delete the old path after female:
and paste in your new path.
Repeat the above steps for the male:
(PMA) inkcharactercustomization file.
Remember to save your .xl before exiting.

Open your .yaml file. Delete the old path after atlasresourcepath:
Copy the path to your renamed/updated inkatlas file and paste it into the yaml where the old path was.
Save your yaml.
Step 3: Check for broken paths
Now that you've updated a bunch of files, check to make sure nothing broke in the process.
At the top of WolvenKit's UI, go to Project > Scan File for Broken File References

It will open a window. Ignore the inkatlas if it says "none" underneath, it's not an issue.
If there are any other files listed in the window, you have broken paths.
The first file listed is the file you need to open, and the indented list of other file(s) underneath are the paths that need to be udpated.
Open any files listed and expand menus as necessary to find the incorrect file path, or right click the first header RDTDataViewModel and click "Search and Replace", searching and replacing instances of "moddername", "modderinitials", or "modname" in the project. Remember to save your files as you update any broken paths.
Repeat scanning for broken file references until the only one left is inkatlas - none.

Install your mod with WolvenKit, open your game, and open Character Customization to ensure everything still works: icons are still in the hair color list, hair colors show on the character when you select them, etc. If not, go back and check all your paths again.
Step 4: Add your hair colors (.hp) and gradients
Now that your mod's file structure is set up, delete the placeholder .hp files in the hair_profiles
folder and replace them with your own .hp files.

Make sure you've named each .hp file its own unique name.
If you are converting an old hair colors replacer mod where the names are basegame hair color names, give them new unique names.
Custom Caps & Eyebrows (Gradients)

If you are including custom gradients for the hair cap (scalp base) of hairs and eyebrow color options that match each of your colors, delete the placeholders in the cap_gradients folder and add your own.
There is not currently a full tutorial for how to make custom gradients, so here's a short and sweet version: You can find a basegame cap gradient such as by searching hh_cap_grad
in WolvenKit's asset browser, add it to your project, export as PNG, then edit it in Photoshop or an image editing program of your choice to make something close to your hair colors. Once done, convert the files back from PNG to .xbm and put them in the cap_gradients
folder.
Name each of your gradient .xbms to hh_cap_grad__color
, with "color" being the corresponding .hp color name. Make sure not to remove the extra _ betwee "grad" and your color name.
No custom gradients? No problem

First, pick a color for your roots/hair cap. It will be used by all your hair colors. My character has dark roots; I use black_carbon in this example, but you can use any
hh_cap_grad
gradient file.

You can find it by searching: base\characters\common\hair\textures\cap_gradiants\hh_cap_grad__black_carbon.xbm
In WolvenKit's asset browser. Double click to add it to project.

Delete the template gradients by highlighting and right click deleting them.

Drag the black carbon gradient .xbm into your empty cap_gradients mod folder, then delete the empty base folder from your project.

Hover the black carbon file with your mouse, use the orange button to copy the path (or right click > Copy relative path).
In the materials folder, open your .mi file ending in
_cap
(NOT_cap_mask)
)

Expand values section, click GradientMap. In the window on the right side, paste the path to your black carbon gradient into the DepotPath box.
Change Flags to default, then save.

Next we need to update our InkCC files so we don't add basegame black carbon as an eyebrow option more than once.
Open both the PWA and PMA inkcc files.

Expand the last gameuiAppearanceInfo entry in each inkcc. The uiSlot near the bottom will read
eyebrows_color.
Right click gameuiAppearanceInfo for the eyebrows_color entry, and right click Delete Item in Array/Buffer.

Delete this in each inkcc file, both PMA and PWA.
Save your files.
Step 5: Replace placeholder hair color names in files
Now that we have new hair colors, we replace the old names in all the other files.
Find & Replace color names
Right click your
patch.mesh
, and click "Convert to json". It will put the converted .json in your RAW folder section of the project explorer.Convert the inkatlas, and PWA/PMA inkcharcustomization files to .json
Open your .json files and your .yaml in a text editor such as Visual Studio Code or Notepad++ and CTRL+F
In the search box, type the name of the first placeholder color (you can use the .yaml as reference if needed.) In the replace box, put the name of your first hair color. It must be the same name as your .hp files and same as the suffix of the gradient .xbms.
Save your file. Tab to the next .json. Run the search and replace again. Save, repeat for the last json.
If you had less colors than placeholders, open your files after converting back from .json.
(optional) Delete extra placeholders
In each of the files, you can highlight everything that you want to keep, and right click > "Delete all but selection in array/buffer" and it will delete the extra placeholders.
Placeholders will be found in the following locations in each file:
.mesh - list of appearances
.inkcharcustomization files - in each appearance's definitions section. (There are up to 3 appearance sections in the PWA file and 4 in the PMA file whose definitions list you'd have to expand and delete extra placeholders from.)
.inkatlas - parts sections
.yaml - you must open in a text editor and delete the entire line of a placeholder you no longer need, including the - and any indents/spaces on that line.
At this point, you can install and see if your new colors show in the character creator in game.
If a hair color shows up pure black or blonde instead of the color it should be, you've made a typo somewhere.
Step 6: Add Custom Icons
Icons for character creator are 160px by 160px with an additional, smaller 1080p version for the mini icon preview in the CC menu.
You are welcome to edit the template .xbms in a photo editing program of your choice. In WolvenKit, at the top, go to "Tools > Export Tool" and select the icons .xbms. It will convert them to PNGs in your RAW folder, which you can edit, save over, then go to "Tools > Import Tool" to import them back to .xbm
I recommend making a folder of your icon PNGs, with each named exactly like your .hp colors. Use the icon python script to generate a brand new inkatlas. Name your new inkatlas exactly the same as your placeholder inkatlas, delete the placeholders and make sure your icon .xbms paths are correct in the inkatlas file.
If you've never made custom icons or used inkatlases before, check out these articles first:
Step 7: OptionsIcons - Connect icons to Character Creator
Open your .yaml file.

On the first line, you'll see there's one instance of "
modderinitials_modname
" that we never replaced. Update it to your name and mod name, save the file.Next, we need to update our inkcc files to match this change so it knows which icons to use. Open one of your .inkcharcustomization files.
Expand
headCustomizationOptions
, then expand the firstgameuiAppearanceInfo
, and expanddefinitions
.Click your first color. It will open a panel on the right, where you'll see a section called "
icon:
" It may be empty, but it might readOptionsIcons.modderinitials_modname_bleached_aqua
(or some other color)Copy and paste the first line of our .yaml into this
icon:
section. Then change$(color)
to the color name you have open.Click through each color in the definitions list, and update the
icon:
section, replacing$(color)
with the corresponding color each time. Save your inkcharcustomization file.Next, highlight all definitions you just updated. Right click > Copy from array buffer

Collapse this first
gameuiAppearanceInfo
section, then expand the next one underneath.Right click definitions, click "Clear Array/Buffer". (if it doesn't allow you to clear, expand the definitions list, highlight all the definitions, and right click clear array/buffer that way)

Once cleared, right click definitions again, paste selection into array buffer.

Repeat those steps for the remaining
gameuiAppearanceInfo
definitions lists.Then, repeat again with the other inkcharcustomization file.
Step 8: Test your finished mod
Install your mod, and check in game that icons are working.
You have successfully added new colors to character creator!
Troubleshooting
My icons are black!
double check that your OptionsIcons in each definitions entry correctly matches the format in the first line of your yaml, and that all your color names are exactly the same, with the same underscore placements, etc.
double check that your .xbms are pathed correctly in the inkatlas
double check that your inkatlas "parts" listed are named the same as all hair color names listed in your .yaml
My hair is black or blonde!
you've messed up the name of an appearance in your mesh or did not update the paths to the .mi files in your mesh
Last updated