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 Last documented update: October 26 2024 by AllKnowingLion Minimum required ArchiveXL version: 1.5

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

#body-modders-adding-support

#clothing-mods-making-use-of-the-tags

To learn more about body mods, check the Overlay textures by framework page.

Checking the current body

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

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

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:

player:
  bodyTypes: [ NewBody ]  # for substitutions, this will be converted 
                          # to snake case: new_body

2. Patch the player entity files

We'll make use of ArchiveXL: Resource patching for this.

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:

resource:
    patch:
        path\to\your\patch_file.ent:
          - !include player_wa.ent 
          - !include player_ma.ent 

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

3. check if the body tag registers by running the CET command.

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:

1. Update ArchiveXL

2. Double-check your .yaml via yamllint and make sure you don't have syntax errors (indent matters)

3. Check ArchiveXL's log file

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

CET:

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

RedHotTools:

If that still doesn't work, consider using the template from Nexus, which has been tried and tested on May 18 2024 with ArchiveXL

Invisible mesh for body xyz

Make sure that your mesh has appearances and materials. If you are using ArchiveXL: Resource patching, it's easy to forget a new body's mesh in the list like a gonk. This has never happened to the author, by the way.

Clothing mods: Making use of the tags

The problem

Even with the AKL AutoRefitter, the process of supporting body mods is tedious. And even worse: you then have to pack everything separately for Nexus:

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

If you're using dynamic appearances, you don't need to register a suffix and can simply match or substitute for the body tag:

appearance name:
t0_recoloured_netrunner_suit&body=new_body

substitution:
*my\mod\meshes\p{gender}a_netrunning_suit_{body}.mesh

Suffixes

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

  appearanceSuffixes:
    - !append itemsFactoryAppearanceSuffix.BodyType

Now, you can use the suffixes in your root entity just like camera states or body genders:

appearanceName: my_custom_shirt&FPP&NewBody

Supporting mods

The following body mods support dynamic body switching.

Summary

Published: ??? by manavortex Last documented update: August 2 2024 by LadyLea

This page will tell you about tags and how they can be used to influence item behaviour. It also teaches you how #adding-custom-tags can help you conditionally un-hide items.

Wait, this is not what I want!

• Tags are used for calculating Garment Support score, see Garment Support: How does it work?

• There is an own page for Influencing other items

What do tags do?

Tags are a way to tell Cyberpunk that an item has certain properties and should behave in a certain way. This makes the game apply properties to your items, which can then be utilized by the game and ArchiveXL.

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

If you don't want your new boots to sound as if V was barefoot, add one of the following tags to the #root-entity:

Boots
Heels
Sneakers
Stilettos

Adding Custom tags

Custom tags let you set component chunk masks from the .xl file without the need of touching either .app or .ent file.

Why would I need this? partsOverrides exists!

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.

Not convinced? Pity, but if you find a new use case for those things, do edit it in!

Example

Registering the tag

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

overrides:
  tags:
    my_custom_unhiding_tag:
      my_hidden_component_name: {show: [0, 1, 2, 3]}
    my_HideSeamfix:
      t0_000_pma_base__full_seamfix: {hide: [0, 1, 2, 3]}

Connecting the tag with the item

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

Summary

Published: August 2023 by manavortex

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

• Translations (check #how-does-the-game-assign-display-namesfor a guide)

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

You can find more detail about this on the sub-page ArchiveXL: Suffixes and Substitutions -> #which-substitutions-exist

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

• If you are a mod user and want to dynamically recolour an item, check the Recolours and Refits guide -> sub-page Emissive -> #switching-existing-colours

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.

Summary

Published: May 18 2024 by manavortex Last documented update: May 18 2024 by manavortex

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.

If you want to avoid duplicate material definitions, check ArchiveXL: Resource patching.

Why do I need this?

While ArchiveXL: body mods and refits has solved one problem, it introduced a new one. If you want to use the preferred approach of mesh path substitution, then you'll end up with a million duplicate files.

While ArchiveXL: Resource patching will let you keep your materials in one spot, why would the chest size be relevant for a pair of socks?

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

resource:
  link:
    tutorial\archive_xl\my_item\l1_pwa_rb.mesh:
     - tutorial\archive_xl\my_item\l1_pwa_ebbprb.mesh
     - tutorial\archive_xl\my_item\l1_pwa_ebbrb.mesh

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

Published: May 18 2024 by manavortex Last documented update: July 23 2024 by

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)

Use them like this:

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.

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

Published: June 30 2024 by manavortex Last documented update: June 30 2024 by manavortex

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 deleted the appearanceSuffixes (we'd only need them for Gendered preview icons, and we can't be arsed with that)

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

Defines the variants — you'll get a gold star for paying attention, but we're getting to that later (#step-3-the-mesh-entity)

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

Instead of one appearance per variant and gender, we will squash everything down so that we have only one appearance per gender. In #lets-simplify-this-even-further, I will teach you how to reduce that even further, but for now, we'll be going step by step.

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:

appearanceName: appearance_root_entity!$(shirt)_$(ribbons)

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:

tutorial\torso\my_custom_shirt\mesh_entity_pwa.ent
tutorial\torso\my_custom_shirt\mesh_entity_pma.ent

Each of them points at a different mesh:

tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_pwa.mesh
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_pma.mesh

Delete one of the mesh entities and rename the other:

tutorial\torso\my_custom_shirt\mesh_entity.ent

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

Just like with appearances, you can also use #conditions with component names.

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:

*tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_p{gender}a.mesh

A combination of

Summary

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

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 , check the corresponding pages in the Modding Guides section

• Dynamic appearances have their own guide (see )

• There is an own page for

• To conditionally hide items or parts of items, check or (especially the section about )

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

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:

Foot states

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

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:

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?

• 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)!

Substitution load order

The order works as follows: