Summary

OK, so what is this?

ArchiveXL (nexus | github) is one of the core frameworks of Cyberpunk 2077 modding. Together with TweakXL, It allows you to add things to the game, such as

• equipment and weapons

• photo mode poses

• world sectors (deletions and additions)

• custom lipsync maps

• If you want to look up garment appearance slots: The princess is in another castle. Check Different equipment slots instead.

This page will document how to set item properties via tags & suffixes (the vanilla way), or via dynamic switching (new, cool, version >= 1.5).

Let's dive right in.

Variants and suffixes

What are variants, what do I need them for?

When adding items, you will normally offer multiple mesh appearances (variants), for example, the same shirt in black, white, and red. This is what you're modding for, after all: making cool things.

And what are suffixes?

On top of having different colours, you also have different circumstances – for example camera states: not even Johnny Silverhand wears his sunglasses in first person perspective.

CDPR deals with this by using suffixes, which are tedious to use. psiberx has since created a better system (dynamic appearances or conditions), which are much easier to use.

For more detail on this, please see the sub-page ArchiveXL: Suffixes and Substitutions

Tags

Tags are a way to add extra information to entities or appearances. They are defined on their own sub-page: ArchiveXL: Tags

Dynamic appearances

If you have ever tried to make ten colour variants of an item for two body genders with four different states of feet, then you're familiar with the struggle. Version 1.5.0 of ArchiveXL solves this problem by introducing dynamic variants, allowing you to define rules to hook up your yaml straight to the mesh entity. picking components and even appearances dynamically.

• For a tutorial about this, check ItemAdditions: Dynamic Appearances

Dynamic Appearances: the diagram

Here's an overview of how the dynamic variants work. By comparison, this is the old diagram. Especially for items with many appearances, the new way is much faster.

In any of the files you modded, check your components:

Does any of them have a type that's called something with morphtargetComponent?

Yes: Add a tag with the exact name of your body in this component's tag array (for our example, NewBody)

No: Add a new component (of any type) and give it the following name: Body:NewBody

If you can't make it work

The files below have been confirmed to work — make the changes stated above to each of them:

base\characters\common\player_base_bodies\appearances\l0_000_base__cs_flat.app
base\characters\common\player_base_bodies\appearances\l0_000_base__full.app
base\characters\common\player_base_bodies\appearances\l0_000_base_fpp__cs_flat.app
base\characters\common\player_base_bodies\appearances\l0_000_base_fpp__full.app 

The following .app files are used to register Body Tags for Male V:

base\characters\common\player_base_bodies\appearances\t0_000_base__full.app
base\characters\common\player_base_bodies\appearances\t0_000_base__full_censored.app
base\characters\common\player_base_bodies\appearances\t0_000_fpp__full.app
base\characters\common\player_base_bodies\appearances\t0_000_fpp__full_censored.app

Test

After packing your project, check if the body tag registers by running the CET command.

If yes, you're good to go!

If not and you have used a component, check if it's added to the playerPuppet, either via CET:

print(GetPlayer():FindComponentByName("Body:NewBody"))

or via RedHotTools:

Summary

Published: ??? by manavortex Last documented update: Feb 18 2024 by manavortex

This page will teach you about conditional appearance switching in Cyberpunk and give you an overview of existing suffixes and substitutions.

Wait, that's not what I want!

• For a hands-on guide to Adding new items, check the corresponding pages in the Modding Guides section

• Dynamic appearances have their own guide (see ItemAdditions: Dynamic Appearances)

• There is an own page for Influencing other items

• To conditionally hide items or parts of items, check Influencing other items or ArchiveXL: Tags (especially the section about Root entity tags)

Why are suffixes?

Sometimes, you want to load different meshes/appearances under different circumstances. Before ArchiveXL 1.5, the only way to do that were suffixes — registering them in the .yaml, then adding one appearance for each variation in the root entity (so for 2 suffixes, you'd have 4 entries, for 3 suffixes, you'd have 8…).

Since 1.5, psiberx has made it possible to use conditionals via dynamic appearances, which require a lot less of an overhead. (Personally, I've gone from 96 entries in the root entity down to 9!)

But while the solution has changed (and improved), the problems remain and require handling.

Body genders

There are two body genders with different proportions, and you can't make them wear the same shirt (at least not without clipping). To solve that, you can do what CDPR did and have one variant per rig.

The suffix for the body is Male / Female, the ArchiveXL string substitution is {gender} and resolves to m or w.

Body types

ArchiveXL allows body modders to register a custom body tag, which can then be used for suffixes and for substitutions in dynamic variants. To learn more about this, check ArchiveXL: body mods and refits.

print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetBodyTypeSuffix(ItemID.new(), GetPlayer(), nil))

Camera modes

Sometimes, you need to hide parts of the item in first person. – for example helmets, since you don't want to have half a helmet floating in front of your face (unless you consider that immersive; most people don't).

Arm states

The arm states represent the different cyberware. For example, since you can't hire the forearms for mantis blades, you can roll up the sleeves just for this. The definitions are:

If the arm states aren't working as expected, check if the table above is outdated by comparing the names with the source code.

print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetArmsStateSuffix(ItemID.new(), GetPlayer(), nil))

Foot states

To achieve gender equality in regard to foot states, you need to use Toggleable Feet. The substitution key for dynamic appearances is feet.

If the foot states aren't working as expected, check if the table above is outdated by comparing the names with the source code.

print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetFeetStateSuffix(ItemID.new(), GetPlayer(), nil))

Conditions

Conditions are a feature of dynamic appearances . They can be used in two places:

In your .app file

Inside your .app file for appearanceAppearanceDefinition.name:

This lets you to select a different appearance based on body gender, camera state... (see the tables above).

By using conditional appearances, you can still make use of partsOverrides to use chunkmask hiding.

In your mesh_entity.ent file

Inside your mesh_entity.ent for component.name:

Substitutions

Substitutions are a feature of dynamic appearances . They can only be used inside your mesh_entity.ent.

Substitutions allow ArchiveXL to load a different mesh based on different circumstances.

Which suffixes exist?

For a list of active suffixes, check the tables above.

Disabling Suffixes

You can disable suffixes by adding the following line to your .yaml entry:

appearanceSuffixes: []

Suffix load order

1. the base appearance (with no suffix)

2. the most specific suffix collection it can find

Example:

V has a female body gender and you're in photo mode (third person camera). Your base appearance is called appearance_.

Which substitutions exist?

Since 1.8.0, ArchiveXL supports substitutions for Dynamic appearances. You can use them in two places:

• inside mesh entity components in the fields name, depotPath and appearance

• in the .app appearances for the field name

Any placeholders will be interpolated at run-time (replaced with the correct value for your current state)!

If any of the placeholders aren't working the way you expect them, check if the table below is outdated by referring directly to the source. (Please update the wiki if that happens!)

Substitution load order

For Dynamic appearances, you can conditionally switch out components or entire appearances by name. You can switch use any of the entries from Which substitutions exist?

The order works as follows:

Summary

This page explains resource patching, a very powerful ArchiveXL feature that lets you modify resources without conflicting with other mods or even game updates. Also allows you to reuse e.g. material definitions in multiple meshes, possibilities are endless!

Why do I need this?

While ArchiveXL: body mods and refits has solved one problem, it introduced a new one. You now have a bunch of meshes inside your .archive, and you have to copy the materials across each of them.

Not only does resource patching fix that issue, it also allows multiple mods to modify the same resource without conflicts! Now you can have multiple mods add appearances to the same weapon and more.

How do I use this?

In general, have a file that contains your changes (and only your changes), this is your "patch file". And you should know what file you want to patch, the "target file". Add the following code to your .xl file:

resource:
  patch:
    <source_file_path_1>:
      - <target_file_path_1>
      - <target_file_path_2>
    <source_file_path_2>:
      - <target_file_path_3>

You can patch multiple files with the same or different files, as many as you'd like. (Don't duplicate the first two lines)

Example: If you have many meshes and want to share materials between them, don't define materials in your mesh files, instead have another mesh file with just the materials! Then add the following lines to your .xl file:

resource:
    patch:        
        tutorial\archive_xl\your_new_item\materials.mesh: # relative path to your material mesh
            - tutorial\archive_xl\your_new_item\pwa.mesh  # paths to the target meshes
            - tutorial\archive_xl\your_new_item\pma.mesh

And just like that, it will work. All your meshes will have the materials you defined in your material mesh and any change to it will propagate to the patched meshes.

What else can I patch?

You can patch pretty much any .ent, .app or .mesh file! Give it a try via .xl file.

What is the minimal patching level?

.mesh file

appearances (added/replaced appearances use materials from patch mesh)

original_mesh:                          patch_mesh:
  appearances:                            appearances:
    appearance_black:                        appearance_black:
      - black_material                          - black_material
      - black_material                          - black_material
    appearance_black_2:                      
      - black_material                       
      - black_material                       
  materials:                              materials:
    black_material: multilayered.mt         black_material: metal_base.remt

After patching, appearance_black would use metal_base.remt, while appearance_black_2 would still use multilayered.mt.

.ent file

You can patch appearances, components, entity, visual tags

.app file

You can patch definitions (components, parts values, parts overrides, visual tags)

Distributed patching: Scopes

Some things are scattered across multiple files — for example, there are different player entities for first and third person. Fortunately, ArchiveXL solves this problem in the cradle by defining patchable scopes. You can find examples on the github repository:

• the player ent

• player customization (e.g. appearances)

• photomode .ent files

Including scopes:

resource:
    patch:
        tutorial\archive_xl\player_patch.ent:
          - !include player.ent # or player_ma.ent / player_wa.ent

This will include all the needed files for patching without the need to specify each of them manually.

Adding entries to scopes:

photo_mode.character.altPoses: *AddPosesF

This will add the list &AddPosesF to the list of photo_mode.character.altPoses. Photo mode scopes were added in version 1.19

Expanding scopes

If it becomes necessary, you can expand scopes and add your own files to them. For example:

resource:
  scope:
    player_customization.app:
      - your_modder_name\patches\your_custom.app

Summary

Wait, this is not what I want!

Switcher names

Base game switchers

Modded switchers

To prevent the character creator from becoming a cluttered unusable mess, we strongly encourage sticking to already-established switcher groups.

Tattoo switchers

Summary

This page explains how ArchiveXL expansions work in the context of the character creator. It is currently a work in progress.

Hair materials

The full list of hair style materials as supported by CCXL extension:

Summary

Starting with version 1.14, ArchiveXL allows you to create resource symlinks. This guide will teach you how to avoid duplicate meshes for dynamic substitution that way.

Why do I need this?

Rhetorical question, it's not. But body types don't care.

This is where linking comes in.

Linking resources

Like most other things, you do this by adding a block to your .xl file. The example below will re-use the item for rb (Hyst's realistic butt) for both ebbrb and ebbprb (boobs in various states of push-uppery):

And just like that, we have one mesh instead of three.

Now we can do away with the extra components and simply use body mod substitution — and anything duplicate can be linked.

Summary

This page will teach you how to convert your existing ArchiveXL mod to the "new" system.

Prerequisites

• An ArchiveXL mod that you want to convert

We will go through the process step-by-step. I'll explain what I'm doing as I go along.

Step 0: The .yaml

Instead of one entry per item variant, we only need one entry per item.

Our variants are defined via $instances and generated via substitutions. Let's take a look at this:

What did we do here?

• We defined a list of $instances, which will generate all of our different appearances

• We replaced all parts that are different with the corresponding key from $instances. The rest will be magic.

And that !+ stuff?

Step 1: The root entity

Instead of one entry per variant and gender, we only need one entry in total.

Our appearance's name must still match the .yaml, but only up to the variant separator: we're going with appearance_root_entity_.

What did we do here?

• We added the DynamicAppearance tag to enable the feature

• We deleted all appearances but one

• We deleted everything variant-related from the appearance

• We deleted the appearanceName, so that ArchiveXL will re-use name for the .app

Step 2: The .app

What did we do here?

• We deleted all but one appearance per gender

• We added the condition &gender=w and &gender=m

• We deleted the partsOverrides

Gender matching now happens via condition. The different meshes for male and female body gender are loaded in the different mesh entity files.

But that will always load the default appearance!

Right! You've been paying attention! Let's take a look at that next.

Step 3: The mesh entity

We will only change a single field (meshAppearance).

Before, it was mesh_white_red (the default appearance), and each appearance overwrote it via partsOverride. We're now changing it to dynamic:

Old: mesh_white_red New: *mesh_{variant.2}_{variant.1}

What did we just do?

• By adding a leading *, we told ArchiveXL that this field is involved in magic (substitution in this case)

• By replacing white with {variant.2}, we're using the second parameter from the yaml's appearanceName (shirt).

• By replacing red with {variant.1}, we're using the first parameter from the yaml's appearanceName (ribbons).

Parameters? Variants? What?

Let's unpack this.

In this example, we have the following mesh appearances:

• mesh_white_red

• mesh_black_red

• mesh_black_blue

By using ! in the appearanceName, we're telling ArchiveXL that everything after is part of the mesh appearance definition:

The + in the variant splits it up. If we didn't have it, we couldn't use variant_1 and variant_2.

How would that look?

Let's compare our setup ( *mesh_{variant.2}_{variant.1}) to the alternative.

yaml:

Our meshAppearance would be *mesh_{variant}.

Recap

Unless you got hopelessly lost, this should have taken no more than ten minutes, and your mod just works(tm).

You now have one root_entity entry, two appearanceAppearanceDefinitions in your .app, and one mesh_entity per body gender.

Let's simplify this even further.

Currently, we have two mesh_entities:

Each of them points at a different mesh:

Delete one of the mesh entities and rename the other:

The .app file

Delete one of your appearances, and strip the suffix name from the other, leaving only appearance_root_entity_.

Change the path of your partsValue to the only remaining mesh entity, and save the file.

The mesh_entity: Round 2

Method 1: Conditional Components

Pro: Especially with many body mods, you can just put all the logic into the components

Cons: All of these components will be added to the player entity, even if half of them will be hidden. This is bad for performance, especially if everyone does it.

Method 2: Component substitution

The best way of dealing with multiple meshes is to have a single component and let ArchiveXL handle all the heavy lifting by using substitutions in the path:

This is our mesh's depot path:

A combination of

Summary

Wait, this is not what I want!

What do tags do?

Base game tags

ArchiveXL tags

Base Game Tags and ArchiveXL Tags - Visual Guides

Root entity tags

There are a few tags that can be added to the root entity or in the .app file. Here's a list:

EmptyAppearance

This will hide an item under certain conditions. Add the following tag to the root entity:

EmptyAppearance:FPP

You have the following other options to achieve the same end:

force_Hair

A tag that forces hair to show up while wearing a head item. By default, head items turn hair invisible. By adding this tag to the root entity, you can override this process.

force_FlatFeet

A tag that forces female V's feet to be flat. Only works with a foot item as $base in the .yaml: use this if you're making flat shoes and don't want female V's feet to look as if she was wearing heels.

Footsteps: Setting footwear sounds

Adding Custom tags

1. PartsOverrides can't un-hide components for you. It can only hide them. If you want to load a different mesh (for example, a de-formed hakama when wearing a kimono or haori), then you're flat out of luck.

2. By being clever about your submeshes, you can offer different versions of your mesh (cropped! No arms! No legs), and users only need to install an .xl file! No need to have different meshes or even different .archive files.

Example

Registering the tag

Add custom tags in your .xl file (not in your .yaml!)

Connecting the tag with the item

Simply add the tag to your appearance's tags array near the bottom of the individual entries.

Making use of Custom Tags in your projects

This section will show an example how Custom Tags are utilized with Body Mods and AXL Clothes. This reference can also be applied for other projects.

To make use of custom tags, one of the Visual Tags below must be included within your .app file information list:

• hyst_boobs_natural [this tag will load the existing natural chest shape that is available when FemV doesn't wear clothes]

OR

• hyst_boobs_squish [this tag will load a squished chest shape that is ideal for tight garments such as bras or corsets]

Summary

This page explains how to enable body mod support in ArchiveXL:

Checking the current body

Run the following code snippet in CET to see which body is currently installed:

Body modders: Adding support

1. Registering the body mod

1. Create an .xl file in your Wolvenkit Project's resources folder (File -> New file -> ArchiveXL)

2. Optional: Name it the same as your current project (e.g. boobs_for_back_problems.archive.xl)

3. Put the following file content:

2. Patch the player entity files

Set up the patch .ent

If you downloaded the template project, a patch .ent will already be included.

1. Inside the patch .ent, find the entMeshComponent under the components array.

2. Change its name to match your body mod, e.g. Body:BoobsForBackProblems -> Body:NewBody

Register the patch .ent

Make sure that your patch .ent is added to the game by telling ArchiveXL about it. Add the following block to your .xl file:

Include only the relevant body gender!

3. Test

That's it, everything should work now! Let's test.

2. Launch the game and load into a save

If yes: Congratulations, you've made it much easier for people to add refits for your body!

Troubleshooting

General errors

The process is so simple that there aren't many things to go wrong:

If that doesn't work, check if the component gets added correctly. There are two ways to do this:

CET:

Invisible mesh for body xyz

Clothing mods: Making use of the tags

The problem

The Solution

If a mod supports body tags, ArchiveXL can detect the current body mod, and conditionally load the correct mesh. Now, everything can be put into a single .archive!

Dynamic Appearances

Suffixes

If you're sticking to the classical approach, you need to add the following lines to your .yaml:

Supporting mods

The following body mods support dynamic body switching.

Summary

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 Game Components explained -> Character Creator: .inkcc

• To convert an existing hair mod to CCXL, check Convert a hair mod to hair CCXL mod

Requirements

You have downloaded the example project from Nexus

TL;DR

If you would rather understand what you're doing, please skip to Step 1: Deleting .ent files!

1. Download example project

2. Add your .mesh file to the project

3. Copy the appearances, materialEntries, and localMaterialDefinitions 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

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

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

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.

We'll now go through everything step by step.

3.1 Appearances

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

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

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)

Now, let's look at the materials themselves.

3.3 Materials

@context

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:

@long

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

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

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

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

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.

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.

Step 6: The .incharactercustomization file

Here is where everything connects to each other.

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

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

• link: Targets one of the headGroups entries

• names: Contains the headGroup's options

The second entry: hairstyle_cyberware

This entry defines the hairstyle for cyberware_01.

6.3 gameUiAppearanceInfos

The 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:

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

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

Step 8: Renaming and moving

Now it's time to custompath your project.

Troubleshooting

Hair colour extensions 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 3.2 Material definitions and double-check everything.

I have duplicate entry in hairstyles options!

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.

Summary

This page will tell you how to use ArchiveXL to add body tattoos to the character creator

Wait, this is not what I want!

• 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

Requirements

• You have downloaded the example project from Nexus, and merged it with your project's source folder

Step 1: Extracting the essentials

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:

base\characters\common\player_base_bodies\player_man_average\arms_hq\a0_000_pma_base_hq_r.mesh

Rename the .mesh file

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

your_modder_name\ccxl\your_tattoo\models\your_tattoo_pma.mesh

Edit the .mesh in Blender

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)

Step 2: Setting up the .mesh

In this section, we will configure your .mesh file to load the texture(s) via the included .mi.

Explanation

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

Let's do it!

1. Open your .mesh file in Wolvenkit

2. Create or edit a materialEntry:

   1. Set the name to your_tattoo

   2. Set isLocalInstance to true (check the box)

3. Create or edit a local material instance: If your mesh does not have preloadLocalMaterialInstances, use localInstances.materials instead.

   1. Set baseMaterial to your_modder_name\ccxl\your_tattoo\textures\your_tattoo.mi (the relative path to the .mi file)

4. Create or edit an appearance: the chunkMaterials need to point at your_tattoo.

Step 3: Setting up the .app

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:

Step 4: Renaming the files

Now, use dynamic renaming feature and rename your files.

Moving your .mesh file

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:

Moving the other files

You can use the dynamic renaming feature (check the box) to safely move all the files in your project.

The inkcharcustomization file?

Change the localizedName entry to something globally unique – call it something like UI-customization_yourmoddername_my-first-tattoo.

Step 5: The Translation Entry [The .json]

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.

Step 6: The .xl file

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.

customizations:
  male: your_modder_name\ccxl\your_tattoo\your_tattoo_pma.inkcharcustomization
  female: your_modder_name\ccxl\your_tattoo\your_tattoo_pwa.inkcharcustomization
localization:
  onscreens:
    en-us: your_modder_name\ccxl\your_tattoo\localization\your_tattoo.json

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?