# CCXL: Hairs

## Summary

Published: Jan 20 2025 by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention") and [island\_dancer](https://app.gitbook.com/u/s8gktWvqEZWGRxQIsePwOnEI2Mo2 "mention")\
Last documented edit: March 01 2026 by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention")

This page will tell you how to use ArchiveXL to add hair to the character creator.

### Wait, this is not what I want!

* To learn more about the character creator, check [files-and-what-they-do](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do "mention") -> [character-creator](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/character-creator "mention")
* To convert an existing hair mod to CCXL, check [convert-a-hair-mod-to-hair-ccxl-mod](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/npcs/guides-all-about-hair/convert-a-hair-mod-to-hair-ccxl-mod "mention")

## Requirements

You have downloaded the example project from [Nexus](https://www.nexusmods.com/cyberpunk2077/mods/19228)

## TL;DR

If you would rather understand what you're doing, please skip to [#step-1-deleting-.ent-files](#step-1-deleting-.ent-files "mention")!

1. Download example project
2. Add your `.mesh` file to the project
3. Copy the `appearances`, `materialEntries`, and `localMaterialBuffer.materials` from the template mesh
4. Overwrite it with your own
5. Overwrite the `.rig` and the `.animgraph` with your own, if you have them
6. Adjust `.app` file entry
7. If you're not using base game textures: Change files paths in the `.mi`
8. Rename the `.xl` file
9. Change translation key in the `.json` file to something unique for your mod
10. Change translation entries in the `.inkcharactercustomization` file
11. Custompath everything — do not publish anything that still contains tutorial files!
12. Profit

## Let's go!

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

1. Start by downloading the example project from [Nexus](https://www.nexusmods.com/cyberpunk2077/mods/19228)
2. Unpack the `source` folder into the root of your existing hair project so that it merges with yours
3. Move any `.mesh`, `.animgraph`, and `.rig` files from your original hair to `your_modder_name\ccxl\your_first_addition\meshes`

## Step 0: Deleting empty meshes

Starting with 8.16.2, Wolvenkit has the menu option `Project` -> `Clean up` -> `Delete empty meshes`. This will delete placeholder files from your hair mod.

## Step 1: Deleting .ent files

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.

## Step 2: Adjusting the .app file

<details>

<summary>If you are converting an existing mod with an .app file</summary>

It is often easier to convert the existing file and replace the template mod's `.app` with it, especially when you are using more than one hair mesh.

1. **Delete** all but the first appearance.
2. `partsValues` are unused and should be left blank.
3. `partsOverrides` are not used by hairstyles in the basegame, but ArchiveXL does use them to generate/expand appearances in .app and to unambiguously resolve `meshAppearance` per component per `appearanceAppearanceDefinition`.
4. ArchiveXL has fallback behavior in the event `partsOverrides` are missing. It will try to recognize which components are meshes that require `meshAppearance` to be set, but it it can make incorrect assumptions in complex cases involving many components. Best practice is therefore to add `componentOverrides` and set `componentName` and `meshAppearance` but leave `depotPaths` blank.

</details>

### Your .app should look like this:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-2916ba77fa53f066c39e49d8c6554f3e9ac2ddd7%2Fccxl_mesh_file_02.png?alt=media" alt=""><figcaption></figcaption></figure>

## Your .app partsOverrides should look like this:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-8710bb5a3bce78aa98cb1482a8624f343b3ed538%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Wait, I'm missing meshes!

If you have more than one .mesh file, for every additional mesh, complete the following steps:

1. Duplicate the `entAnimatedComponent`
   1. Change the `rig` 's depot path to the relative path of the corresponding .rig file
   2. Change the `graph's` depot path to relative path of the corresponding .animgraph file
   3. Change the `name` so that it's unique (add `_pt_1` at the end or number it)
2. Duplicate the `entSkinnedMeshComponent`
   1. change the depot path to point it at your extra mesh
   2. Select `parentTransform` and change the `bindName` to your `entAnimatedComponent`'s name (step 1c above)
   3. Select `skinning` and change the `bindName` to your `entAnimatedComponent`'s name (step 1c above)
   4. Change the `name` to be unique
3. Duplicate the `appearancePartComponentOverrides` in `partsOverrides`
   1. change the `componentName` to your new `entSkinnedMeshComponent` 's name from step 2
   2. repeat this step for each new meshComponent you add
4. Optional: Component uniqueness
   1. If you are running into issues, you can assign unique `id`s to all of your components. Go through them one by one, select their `id` attribute, and select "`Generate new CRUID`" from the context menu.

### My hair mesh is not animated

If one or more of your hair meshes do not have physics (i.e. lacks a corresponding rig + animgraph and has no "dangle" bones), you can follow these steps:

1. Delete the `entAnimatedComponent` "hair\_dangle" corresponding to this mesh by right clicking on it and selecting "Delete Item in Array/Buffer"
2. Expand the `entSkinnedMeshComponent` for the mesh and change the following:
   1. Under `parentTransform`, change the `bindName` to `root`
   2. Under `skinning`, change the `bindName` to `root`

Once done, the .app should look like this:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2F1rt4qK0yPB3pao3WGMt8%2Fnophys-app.png?alt=media&#x26;token=bafa8ce7-f2db-4f27-bf96-d1693fc114da" alt=""><figcaption></figcaption></figure>

### How does this work?

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-.inkcharactercustomization-file](#step-6-the-.inkcharactercustomization-file "mention")

{% hint style="info" %}
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.
{% endhint %}

{% hint style="info" %}
File Validation can help you making sure that your hair components and paths are correct.
{% endhint %}

## Step 3: The .mesh files

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.

{% hint style="info" %}
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.
{% endhint %}

We'll now go through everything step by step.

### 3.1 Appearances

{% hint style="info" %}
To understand appearances, you can check [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files "mention")-> [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files#step-1-appearances](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files#step-1-appearances "mention"). This is not necessary to complete the guide, though!
{% endhint %}

As you can see, you only need a single appearance — ArchiveXL will generate all the rest.

{% hint style="warning" %}
If your hair mesh is set up differently from the template file, you need to adjust the chunk materials here!
{% endhint %}

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-7785d5485bf3a8506fad650712cf49910048032f%2Fccxl_mesh_file_01.png?alt=media" alt=""><figcaption></figcaption></figure>

In our example, the first submesh uses the material `@long`, and the second one the material `@cap`.

The names must be set as follows:

```
<name_of_appearance>@<name_of_material> => black_carbon@long
```

### 3.2 Material definitions

{% hint style="info" %}
To understand material definitions, you can check [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files "mention") -> [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files#step-2-material-registry](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files#step-2-material-registry "mention"). This is not necessary to complete the guide, though!
{% endhint %}

The tutorial hair has only two materials, and three material entries (`@context`, `@long`, `@cap`):

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-d785743690b1ca7c1a582f3d93da00bdf0d91065%2Fccxl_mesh_file_02.png?alt=media" alt=""><figcaption></figcaption></figure>

You can define more materials here if you need them (please note the box below)

{% hint style="warning" %}
You have to use the exact material names that ArchiveXL is expecting, or extra hair colours won't work.

For a full list, see [ccxl-theory-scopes-and-extensions](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-character-creator-additions/ccxl-theory-scopes-and-extensions "mention") -> [#hair-materials](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/ccxl-theory-scopes-and-extensions#hair-materials "mention")
{% endhint %}

Now, let's look at the materials themselves.

### 3.3 Materials

You have to repeat this step for every mesh file in your project. Be careful, as different meshes may use different texture sets. In this case, you need an extra `.mi` file for them.

{% hint style="info" %}
To understand materials, you can check [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files "mention") -> [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files#step-3-material-definition](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files#step-3-material-definition "mention"). This is not necessary to complete the guide, though!
{% endhint %}

{% hint style="info" %}
You can read more about @context and appearance extrapolation under [#material-colour-extensions](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/ccxl-theory-scopes-and-extensions#material-colour-extensions "mention"). This is not necessary to complete the guide, though.
{% endhint %}

#### @context

This is a blank container for storing contextual parameters. This is not a functioning material instance.

You can use contextual parameters in any mesh by creating a blank material named `@context` .

Please note the following:

* It should always be the first `materialEntries`. That is, it should always be index position 0.
* `baseMaterial` should always be *null*.
* In `values` you then create a key whose value is a string of type `CpuNameU64`.
* If you wish to use basegame materials as is, this string may be any context BaseMaterial in PlayerCustomizationHairFix.xl. e.g.:

```yaml
  context:
    LongBaseMaterial: base\characters\common\hair\textures\hair_profiles\_master__long_bright.mi
    CapBaseMaterial: archive_xl\characters\common\hair\textures\hair_profiles\hh_025_ma__pompadour_cap.mi
```

* You can find all of the fix xl configs in "Cyberpunk 2077\red4ext\plugins\ArchiveXL\Bundle\\". Do not modify these files in any way, as they are required for CCXL hair implemention to function correctly.
* If you wish to change basegame materials (e.g. path to custom hair textures), then your @context string will be a path to one of the external material instance ( `.mi` ) files in the project.
* You can create a contextual parameter by doing the following:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-fcda2e9d0aa7e64f9d7566ab1366157fc4655551%2Fccxl_mesh_file_04.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
You need to create **one** entry for every type of material that you want ArchiveXL to expand.

For a full list, see [ccxl-theory-scopes-and-extensions](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-character-creator-additions/ccxl-theory-scopes-and-extensions "mention")-> [#hair-materials](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/ccxl-theory-scopes-and-extensions#hair-materials "mention")
{% endhint %}

{% hint style="warning" %}
If your hair is using a material multiple times (e.g. long, long, cap), you still create **only one** LongBaseMaterial value.
{% endhint %}

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-66561f8c223a37c9169078bf98ba66041df176a4%2Fccxl_mesh_material_context.png?alt=media" alt=""><figcaption></figcaption></figure>

#### @long

This material defines the hair cards. It points at the `.mi` file in your project, where the hair's textures are defined.

{% hint style="warning" %}
All ResourcePaths must have `Soft` flags for this to work, including the `baseMaterial`! (see screenshot)
{% endhint %}

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

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-5781e894a5aa62ba80fbd1a63fbfc8be3e25a905%2Fccxl_mesh_file_05.png?alt=media" alt=""><figcaption></figcaption></figure>

#### @cap

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.

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-ccf94a8fd0fecac003b6004c8c5a712b5aa62669%2Fccxl_mesh_file_06.png?alt=media" alt=""><figcaption></figcaption></figure>

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.

## Step 4: The .mi files

{% hint style="info" %}
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](https://www.nexusmods.com/cyberpunk2077/mods/19115))
{% endhint %}

With the exception of the hair cap, the .mi file is a completely normal [material template file](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/materials/re-using-materials-.mi) (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`.

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-c0cedd80a26c0fdd0adde0e5ee335f669ce50a2a%2Fccxl_mi_file.png?alt=media" alt=""><figcaption></figcaption></figure>

## Step 5: The translation entry

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.

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-3d23e4ae10debf46b9cedfabac4e273e3e23ae94%2Fccxl_json_01.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="187">key</th><th width="238.5">value</th><th>explanation</th></tr></thead><tbody><tr><td><code>femaleVariant</code></td><td><code>Your First Hair</code></td><td></td></tr><tr><td><code>maleVariant</code></td><td><em>leave it blank</em></td><td>If no value is found, then <code>femaleVariant</code> acts as default</td></tr><tr><td><code>primaryKey</code></td><td>0</td><td>Will be generated by ArchiveXL, leave it alone</td></tr><tr><td><code>secondaryKey</code></td><td><code>UI-Customization-your_first_hair</code></td><td>Used in the <code>.inkcharactercustomization</code> file to set your hair's entry name</td></tr></tbody></table>

## Step 6: The .`inkcharactercustomization` file

Here is where everything connects to each other.

{% hint style="info" %}
For more information about this, see [.inkcharactercustomization-cc-options](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/character-creator/.inkcharactercustomization-cc-options "mention")
{% endhint %}

Open the file, we will look at the entries now.

### 6.1 headGroups

These entries **create** character creator additions, while the CustomizationOptions **define** them (think of a materialDefinition and a materialInstance in a `.mesh` file).

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-a8716c3a27463cff5c1895d0d4872faba95360e8%2Fccxl_inkcc_headgroups.png?alt=media" alt=""><figcaption></figcaption></figure>

### 6.2 gameUiSwitcherInfos

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.

#### The first entry

{% hint style="danger" %}
If you're only using one hairstyle mesh, keep this entry nameless, or it will overwrite the [character-creator](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/character-creator "mention")'s base [switcher](https://wiki.redmodding.org/cyberpunk-2077-modding/files-and-what-they-do/file-formats/character-creator#the-switcher)!
{% endhint %}

* **link**: Targets one of the `headGroups` entries
* **names**: Contains the `headGroup`'s `options`

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-5708e4f0c9e216c02a15b470ad2a075ab027bb6a%2Fccxl_inkcc_2.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
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.
{% endhint %}

#### The second entry: `hairstyle_cyberware`

This entry defines the hairstyle for `cyberware_01`.

### 6.3 `gameUiAppearanceInfo`s

{% hint style="info" %}
For more information on this, see [.inkcharactercustomization-cc-options](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/character-creator/.inkcharactercustomization-cc-options "mention") -> [#gameuiappearanceinfo](https://wiki.redmodding.org/cyberpunk-2077-modding/files-and-what-they-do/file-formats/character-creator/.inkcharactercustomization-cc-options#gameuiappearanceinfo "mention"). This is not necessary for the purpose of this guide!
{% endhint %}

The template inkcc has three `gameUiAppearanceInfo`s, 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:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-5e86eb1aedfa0d1b05ea78dc1e35cce78fa3ac4b%2Fccxl_inkccfile_1.png?alt=media" alt=""><figcaption></figcaption></figure>

## Step 7: The .xl 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):

```yaml
customizations:
  female: your_modder_name\ccxl\your_first_addition\_pwa.inkcharcustomization
localization:
  onscreens:
    en-us: your_modder_name\ccxl\your_first_addition\localization\your_first_hair_wa__local.json
resource:
  scope:
    player_wa_hair.app:
      - your_modder_name\ccxl\your_first_addition\appearances\your_first_hair_wa.app
      - your_modder_name\ccxl\your_first_addition\appearances\your_first_hair_wa_cyberware.app
      - your_modder_name\ccxl\your_first_addition\appearances\fpp\your_first_hair_wa_fpp.app
    player_wa_hair.mesh:
      - your_modder_name\ccxl\your_first_addition\meshes\your_first_hair_wa.mesh
      - your_modder_name\ccxl\your_first_addition\meshes\your_first_hair_wa_cyberware.mesh
```

<details>

<summary>TODO: What does this do?</summary>

It just works. Adjust the paths!

</details>

## Step 8: Renaming and moving

Now it's time to [custompath](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/custompathing-assets) your project.

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-81e93992aebc458c016253460c95f72864281f8b%2Fccxl_custompathing.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
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.
{% endhint %}

## Troubleshooting

### Hair colour extensions (modded hair colors) don't work on my hair!

Most likely, you screwed up the names of your material definitions. They must be **exactly** as ArchiveXL expects them to be.\
Go back to [#id-3.2-material-definitions](#id-3.2-material-definitions "mention") and double-check everything.

Otherwise, check that your `componentsOverride` in the `partsOverrides` of the `.app` is correctly named. (see [#your-.app-partsoverrides-should-look-like-this](#your-.app-partsoverrides-should-look-like-this "mention"))

If that doesn't help, check the log (see [#my-hair-is-always-black](#my-hair-is-always-black "mention"))

### My hair colour doesn't change at all!

* If it's an extra mesh, check your `.xl` file and make sure that all files are part of the correct scopes.
* Check if material patching/expansion worked: Search the [ArchiveXL log](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-users/user-guide-troubleshooting/finding-and-reading-log-files#a-list-of-framework-logfiles) for the name of the broken hair mesh. Most likely, there is a warning or an error that you can fix.
* In your `.app` file(s), check the `partsOverrides`. Make sure that the component names are correct, and that the appearance is the same as the one you assigned in the `components` array.

### I have duplicate entry in hairstyles options!

This happens due to having a different `localizedName` for`cyberware_hairstyle` switcher that's inside the`.inkcc` file. For example`UI-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 [#id-6.2-gameuiswitcherinfos](#id-6.2-gameuiswitcherinfos "mention"), specifically the hint about `link` and `name`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-character-creator-additions/ccxl-hairs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.