Summary

Created: by @manavortex Last documented edit: June 10 2023

This page is a part of the Adding new items guide and explains how the different files interact with each other.

Structural files: telling the game about your mod

We need four files to tell the game about our new items:

1. the .yaml, which tells TweakXL about your item's properties

2. the .xl file, which tells ArchiveXL which files to register

3. the .csv, telling the game about your custom files

The .xl file

This file will be in the same directory as your mod's .archive file. It lets ArchiveXL register the (my_shirt_factory.csv) and the (translation_strings.json).

You usually touch this only once, unless you want to add more factories or translation files.

.xl: Making changes

You only need to change this file if you have changed the factory's file path (moved the file) or want to add a second factory file (there is no need to, though).

The .json file (custom texts, i18n)

This is the localization file for language-specific entries (green boxes on 's screenshot). If no entry for a language is defined, then the English one will be used.

An entry will look like this:

.json: Making changes

You need to change this file every time you want to add a new text entry to your mod. The easiest way to do this is by duplicating an existing entry.

The .csv file (the factory)

The factory connects your .yaml to the corresponding rootEntity.ent via entity_name.

When reading your .yaml file (e.g.tutorial_my_custom_tshirt.yaml, ), the game will find entries like this:

The csv file is where ArchiveXL will find an entry with the yaml's entityName in the first field. It will then check the corresponding for an appearance with the name in appearanceName.

Making changes

You only need to change this file when

• you move a root entity (update the path!)

• you add a new entityName — for example, a second t-shirt that you want to have its own root entity.

The control file: yourModName.yaml

This file controls the adding of items to the game. Unless you are using , an entry looks like this:

Four mappings take place here:

1. entityName: Points to the (see documentation there as for what it works)

2. appearanceName: In the specified in the factory, it will look for an appearance by this name.

1. displayName/localizedDescription : In the translation_strings.json, find an array where the value for [3] (the last entry) is identical to this key. Then, check which gender V has, and display either femaleVariant or maleVariant.

2. icon:

What is it, precious? The $base parameter

$base defines which slot the item will use. For the full documentation, see "".

.yaml: Making changes

You need to touch this file every time you want to add a new item (or when you want to change an existing one). It is easiest to duplicate an existing entry.

If you want more than just the base properties, check the documentation for .

The game files

Now that we're done with the base structure, we can take a look at the game files. Like for any of the vanilla game items, we have four of them. This guide will only hold information that's directly relevant to adding item, but in the individual sections below, you will find links to more documentation about the files.

• appearance.app

• mesh_entity.ent

Overview

This is how the files connect to each other. If your head explodes now, don't worry: it's not as complicated as it looks, and the item addition guide will walk you through step by step.

root_entity.ent

The entry point from your yaml, this file is a glorified lookup dictionary: for any appearanceName, it will specify an .app file and the name of an appearance in the .app file.

An entry looks like this:

Suffixes

Unless you are using , the root entity's name field is where you would put suffixes for different appearance variants.

Root Entity: Making Changes

When you change the path of this file, you need to adjust the path inside the .

Adding a new appearance:

Expand the list appearances and duplicate your already working entry.

Change the following fields: appearanceName => everything before the & must match appearanceName in your *.yaml name => must match the name you're going to put in your app.app

Example:

old (copy):

new:

mesh_entity.ent

This file holds a collection of components that determine how our equipment item behaves and moves. Each kind of equipment has different types of components, which is why you need to pick the for each equipment slot.

By bundling them in this file, we save ourselves a lot of copy-pasting inside the .app file. The only component we actually need to change is the one with "Mesh" in its name, typically entGarmentSkinnedMeshComponent:

The component's name will be used in appearance.app's materialOverride array (see )

Mesh Entity: Making Changes

When you move this file, you need to change the path inside every appearance inside the . file.

Otherwise, you only need to touch this file if you move the .mesh file.

appearance.app

Contains a list of appearances as mapped by . Each of the appearances will load mesh_entity.ent via partsValues.

If you're not using , you specify the components' appearances and chunkMasks in the partsOverrides.

An entry will look as follows:

partsValues will define what file(s) to load (as a list of components), while partsOverrides tells the which appearance to use.skipp

For ArchivXL >= , appearance overrides can understand the following variables for meshAppearance:

Appearance: Making changes

When you move this file, remember to change the path inside the root_entity.ent

You need to touch this file every time you add a new appearance:

1. Open the .app file and expand the list appearances.

2. Duplicate an item and select the new one.

3. Change its name to the one you just defined in the .yaml (black_blue_appearance_name)

Mesh

The mesh file maps materials to appearances. To find out how exactly it does that, find the on the mesh wiki page.

For our purposes it's enough to say that you can define your individual appearances here.

Mesh: Making changes

1. Find the array appearances and open it.

   1. Duplicate any meshMeshAppearance.

For further information and guides, check or see .

The final result

This is how everything plays together:

Summary

Created: July 11 by @manavortex Last documented update: July 11 by @manavortex

This page will tell you how to mod weapon attachments and scopes.

If you can contribute, please sign up and update this page!

Component visibility

Component visibility is defined by the visibilityAnimationParam:

To always display a component, set the value to None (clear the field).

Summary

Published: Sep 09 2024 by Last documented edit: Dec 14 2025 by

This page is an extension of ItemAdditions: Dynamic Appearances and explains how to fine-tune item visibility conditions beyond the basic scope.

Please also check ItemAdditions: Dynamic Appearances -> for more examples.

Via root entity

You can use yaml instances to create different appearance names. These let you use different root entity entries which can point at different appearances in the .app file – letting you use partsOverride to show or hide different parts of your item!

Let's look at an example.

Editing the .yaml

We're adding the type parameter to the custom t-shirt's definition array.

Since the variants only start after the exclamation mark, we can generate different appearance names:

before:

after:

This will look up the following names in your root entity:

root_entity_dynamic_appearance_sleeves_

root_entity_dynamic_appearance_nosleeves_

Then you would add the following entries to your .app file with the names :

root_entity_dynamic_appearance_sleeves_

root_entity_dynamic_appearance_nosleeves_

Now you have options. The next step will depend on your goals. In the .app file, you could use partsOverrides to hide different parts of the mesh for each appearance (like the sleeve submesh for the no-sleeve version. See ), or you could set partsValues to different mesh.ent files (like a standard and looser-fitting version).

But wait, couldn't I accomplish this by doing [x] instead?

Yes, there are several ways to organize your item variants. The benefit is that you can use a single entry in your .yaml file for multiple variations, but it's just a matter of preference and what works best for your project.

Wait, this is not what I want!

• If you want to add a custom hat from the start, start with ItemAdditions: Dynamic Appearances and come back here once you've done that and have a hat minus the hair. The process for hats is no different than for other garment items.

Prerequisites

• You know how to add custom garment items with Dynamic Appearances

• You either have your own WolvenKit project with a custom hat or you've downloaded the starting point project from

Assumed Skill Level

If you can successfully add custom garment items with Dynamic Appearances to the game, you shouldn't have any problems with this guide.

Step 1: Finding appropriate basegame hat hair meshes

In WolvenKit use the Asset Browser to navigate to base->characters->common->hair

Notice that for each basegame hat, there are four folders with hat hairs ending with a number between 1 and 4. These numbers are related to the different hair types:

Find a set of hairs that seem to be a good starting point for your custom hairs.

Step 2: Adding the meshes to your project

Use Wkit's mesh preview and decide on a starting point for your hat hairs. For this guide, we'll use h1_012_xx_hat__googles_hh_xx.

Add the meshes of the set to your project with the ma/wa body type token and for all suffixes between 01 and 04. In the end you should have added 8 meshes to your project.

Step 3: Renaming the hat hair meshes

Add a new folder for the hair meshes to your project namespace. In this guide we'll use yourmoddername\yourmodname\hair_meshes.

Move all the mesh files you added in Step 2 to the new folder.

Rename the files. You can rename them to your liking, but it's important that they

• still contain an m or w indicating the gender

• you replace the number suffix with the matching hair type name (01- short, 02 - long, 03 - dreads, 04 - buzz)

• all follow the same schema for the file name with just the body type token and the hair type name being different

In this guide, we'll rename h1_012_xx_hat__googles_hh_xx to h1_xx_yourmodname_hair_xxxx with the body type token after h1 and the hair type at the end.

E.g. h1_012_wa_hat__googles_hh_03 becomes h1_pwa_yourmodname_hair_dreads.

The result should look something like this.

Step 4: Adding the hair component to your entity

Open the mesh entity of your hair item. In this guide the mesh entity is yourmodname.ent. Right-Click on the hat component h1_yourmodname and select "Duplicate in Array/Buffer".

Expand the duplicated component.

• Right-click on the id and select "Generate new CRUID".

• Click on the name property and change it to h1_yourmodname_hair. This name will be important when we update the .app!

• Click on the meshAppearance property and change it to *{hair_color}

The final component should now look like this:

Step 5: Updating the .app file

Open your .app file, yourmodname.app. A working hat should have (at least) two appearances, one for first person view and one for third person view. In first person view, both the hat and the hairs should be hidden.

• Expand the appearance for first person view. In the example project it's yourshortname_yourmodname_&camera=fpp.

• Navigate to the partsOverrides property, expand the first element and in it the componentsOverrides property.

The result should look like this:

Step 6: Checking your result

Install the mod, give your V the hat item via console, equip it and check the result. If you followed all the steps your hat should now come with hair.

Check both genders and all four hair types to be make sure it works correctly.

Step 7: Make your hat hair compatible with CCXL hair colors

7.1 Converting the .mesh files

In a file explorer open your Cyberpunk 2077 main directory and from there navigate to /red4ext/plugins/ArchiveXL/Bundle and open the file PlayerCustomizationHairFix.xl in a text editor.

In Wkit find the original file of your first copied hair mesh in the Asset Browser and copy its relative path. In this guide that will be base\characters\common\hair\h1_012_wa_hat__googles_hh_01\h1_012_ma_hat__googles_hh_01.mesh.

Search for the path in the PlayerCustomizationHairFix.xl and once found, scroll down to its context section.

Make a mental note that this mesh uses a short base material and has a cap.

Open the related mesh file. h1_pma_yourmodname_hair_short.mesh in our example and click on the ArchiveXL button and select "Convert hair to CCXL material".

In the dialog that opens, select the matching main style for your mesh and if the mesh uses a cap select the "Include a Cap .mi file" check box. Since we won't use custom .mi files for now, we leave the dropdowns for the .mi files empty and click "Finish".

Now scroll down to the localMaterialBuffer property and expand it and expand the materials.

Expand the values of the @context property and fill the values of the ShortBaseMaterial and CapBaseMaterial with the values you found in the PlayerCustomizationHairFix.xl.

In the @short and @cap entries, add the same material paths to the baseMaterial property and set its Flags to Soft.

Save the file. The result should look like this for a mesh that uses a short base material and has a cap.

7.2 Rinse and repeat

Repeat the steps from section 7.1 for all hair .mesh files and use the matching values for short, long or dreads. When you convert a buzz hair mesh, select "Cap" in the conversion dialog and don't check the "Include a Cap .mi file" checkbox.

7.3 Adding the necessary entries to the .xl file

Open up your mod's .xl file and add the following entry to the patch region:

If you used different names or paths, make sure that the targets match your hair mesh file paths.

Add the following scope region:

This should again match the paths you used.

If you started with the example project, the final .xl file should now look like this:

Install the mod and make sure that each hair type and gender works with base game colors as well as CCXL colors.

Step 8: Make it yours

If you plan to use one of the template/example projects as a base for your own mod, you will need to rename each and every file, component and reference in the project.

In short

• Rename everything that contains "yourmoddername" to use your actual modder name instead

• Rename everything that contains "yourmodname" to use your mod's name instead

Step 9: Edit your hair meshes

You now have eight different meshes that will probably require at least some editing in Blender to fit to your hat. This is especially true if you picked other hairs than hat hairs to start with. This is where the fun starts!

Summary

Created by @manavortex Updated October 05 2023

This page is a sub-page of Adding Weapons and tells you how to create a custom projectile for a throwing weapon.

To create a custom throwing weapon, check the parent guide and use knife as a base type.

Step 0: the yaml

We now need to register our projectile. We already have a weapon, so let's define our projectile:

Now, we need to tell our weapon about it. Add the following lines to its definition:

If your weapon wasn't throwable before, it is now — but the projectile is still invisible. Time to change that.

Step 1: the entity file

You can find all projectile entities in base\gameplay\projectiles.

There are two kinds of .ent files: the ones that support multiple appearances, and the ones that don't. You can tell them apart by opening them and checking the appearances array (the first entry in the list).

Pick the right kind of entity for your weapon:

Use e.g. this entity file if you want to use multiple appearances:

Use e.g. this entity file if a single appearance is enough for you:

Add the file to your project, then rename it and (if you have one) move it to your weapon's folder.

Step 2: The factory

Now it's time to connect everything by registering the projectileTemplateName from your .yaml file in your factory.csv. As a reminder, this is the line we're talking about:

Make sure that the corresponding entry points at your projectile's entity file from .

From now on, your projectile will no longer be invisible. If it is, try setting your factory path to one of the game's original projectile entities - debugging time.

Step 3: the .app

1. Expand the appearances array

2. Select any of the appearances

3. Check the appearanceResource's depot path

Step 4: The right mesh

1. Open your .app file . For each of the appearances, do the following:

   1. Expand the components array

Step 5: Test

If you did everything correctly, you should now have a custom projectile for thrown weapons.

Troubleshooting

For troubleshooting steps, please see the page.

Summary

Created: by @manavortex Last documented edit: June 10 2023

This page is a part of the Adding new items guide and deals with finding the correct files for an ArchiveXL item addition.

• For an explanation of the file structure, see .

• If you want to add an atelier store, see .

• If you want to add preview items, check .

• If you want to port a mesh from a different game to Cyberpunk, check

Overview:

Optional, but very recommended: Clean out obsolete entries

1. Open the file translation_strings.json in WolvenKit. Expand the array root and then the array entries. Delete all entries but one.

2. Open the file my_shirt_factory.csv in WolvenKit. In compiledData, delete all entries but one. In data

This guide will detail how to add an Atelier store with your items. It is part of the ArchiveXL tutorial, but you can complete these steps independently.

Wait, this is not what I want!

• Find a guide on

Summary

Published: 29 Oct. 2023 by Last documented update: Jul 05 2024 by

This guide will cover a sub-case of Adding new itemsvia ArchiveXL (added in 1.13). Dynamic variants are both easier and more flexible. Unless you don't need different appearances, you will want to default to this approach.

Wait, this is not what I want!

• If you want to understand how things work, check out the links during the rest of the guide.

• You can find the technical documentation for dynamic variants on .

• If you want to create an Atelier store, see

Prerequisites

You need at least the following tools and versions (get the most recent):

• >= 8.11.0 (you should have it )

• >= 1.4.4

• >= 1.5.0

You define an appearance as dynamic by adding the DynamicAppearance tag to the visual tags in its root entity.

If you don't know what that means yet, read on — it will hopefully become clear soon.

How is this better than the old approach?

Skipping and skimming

This guide contains the minimal amount of fluff and will link background information rather than giving it. Any links will tell you what you're supposed to read.

For that reason, you shouldn't skip or skim unless the section tells you that it's optional.

That being said, make sure to check the section if you run into issues, and to run File Validation ->to check for common mistake.

Step 0: Run the generator

1. If you haven't, go and create a . I'll name mine my_archive_xl_item,

2. In the File -> Add files... menu, select ArchiveXL item

1. Fill out the wizard with your item's information. For the example project, I'll create a t-shirt:

0.1: Import the icons

Import the auto-generated .png icon files ( -> Import All). They are just dummy icons, but they will help telling apart your shirts while you work on them.

Check for a guide on how to create the final thing. Most people do this at the end of their project, so you don't have to do it now.

Generated files

Depending on the options you picked, your project will now look similar to this:

Step 1: Connecting the decal (and understanding variants)

This section will teach you how to make use of the variant to switch out item parts via .yaml. As a reminder, this is our yaml:

DynamicAppearances makes everything after the ! available in the mesh entity under the key variant. By adding +, you can split the variant into parts. Expand the box below to see more examples, because this is where the magic lives.

By default, our _mesh.ent looks like this (because the generator re-uses CDPR's file structure)

As you can see, the paths are already dynamic - the m or w has been replaced with {gender}. This makes sure that our mod will display the right file based on your V's body gender.

Now, let's get that decal connected.

1. Select the first deactivated component, and turn it on by checking a few of the boxes (e.g. the first 3).

2. Select the second and third deactivated component, and delete them.

3. Based on the value of secondary (see the expandable above), we have the following values for variant.2:

Thanks to ArchiveXL's substitution, we only need one component to pick our choice from three .mesh files — based on the value for secondary in the yaml.

Exercise 1: Other options

Dynamic mesh picking based on yaml params saves a lot of duplication, typos can lead to crashes — if you enter semurai instead of samurai, the game will try to find (for female V) manavortex\equipment\torso_inner\my_custom_shirt\meshes\t1_079_pwa_tshirt__casual_dec_semurai.mesh and then crash because it doesn't exist.

This is generally bad, so which options do we have to prevent it?

An example of a real mod

I use both of these techniques in my mod. Every mesh file contains several states of the same item, and I use partsOverrides to switch between them based on the yaml configuration.

For details, expand the box.

The diagram

Now let's look at what we just did and check the diagram. You'll see that the control files are almost identical to the, but that the rest of the files has gotten a lot more manageable:

And that's it! With this and the , you should hopefully be able to add items to your heart's content!

Tools and utilities

Generating display names

I have written a to auto-generate display names, you can find it on my github. If you don't know how to use this, check .

Creating preview icons

This problem is so common that it has its own wiki page:

Troubleshooting

Please see the original guide's section.

Summary

Created & Published: November 04 2022 by @manavortex Last documented Update: March 12 2025 by mana vortex

This guide will walk you through adding your own items to Cyberpunk 2077, which can then be spawned via console.

It has been verified with the following versions (yours should be equal or higher)

Assumed skill level: You should be able to find your way around WolvenKit, but I aim to keep this as noob-friendly as possible. In case you prefer visual learning, there is also a video version of this guide available here -

This guide will give you a working mod with a very basic structure. In the section , you're guided through various processes that will help you to understand how things connect, and teach you how to use ArchiveXL to add your own items.

The guide was created after reading and being left with a bunch of question marks. This guide is horribly outdated and I'm only citing it here because it got me started into the rabbit hole. &#xNAN;To get a deeper understanding of the process, you can follow the linked resources, or consult ArchiveXL's .

Wait, that's not what I want!

• Visual learners rejoice: You can find a video of this guide on youtube ()

• To troubleshoot your ArchiveXL mods, you can use 's .

• If you want to convert a mod to dynamic appearances, check the

Or maybe for something completely different?

• To learn about Cyberpunk's material pipelines, check out

Step 0: Grab the example files

• Create a new Wolvenkit project

• Download the prepared files from and extract them to the root of your new project (overwriting the "source" folder)

You should now have the following files:

Start the game

Press in WolvenKit. This will do the following things:

1. Wipe the folder packed

2. Copy all supported file entries from source to their destination under packed

Now, you can

1. Launch the game.

2. Spawn one of the tutorial items via Cyber Engine Tweaks and equip it: Game.AddToInventory("Items.my_custom_shirt_redwhite")

   Game.AddToInventory("Items.my_custom_shirt_redblack")

You should now see your the tutorial item. If not, consult the section below, or retrace your steps and make sure all mods are installed correctly before continuing with

Great! You added items! Now what?

You've successfully pushed a button and everything worked, but so far, you haven't done anything.

If you're okay with this, then you're done now. Otherwise, you'll want to keep reading.

Otherwise, you will want to complete one or more of the following steps:

• change the mod to use (e.g. shoes or glasses)

• Learn about for e.g. or check the

• Learn about making more variants:

Diagram

This is how everything connects. Looks pretty scary, but is actually simple: whenever you want to rename or repath something, make sure that you catch both ends of the connecting lines.

You can find a breakdown-by-entry on the .

Adding an appearance

To add an appearance, you will have to touch the following files:

1. *.yaml: Adding an entry

2. appearance.app: Adding a mapping between root_entity and mesh's appearance

3. root_entity.ent: Adding a mapping between yaml's appearance and app's appearance

Step 1: Register it in your *.yaml

1. Duplicate the entire appearance block for an already working item. ⚠Mind the indent!

2. Change the first line to a unique name like Items.my_custom_shirt_blueblack

3. Set the new appearance name for the root_entity.ent

The total entry should look like this:

Step 2: Add it to the root_entity.ent

Find the step-by-step guide in the on the "" page.

If you want to add a , make sure to add the DynamicAppearance tag here.

Step 3: Add it to my_custom_shirt.app

Find the step-by-step guide in the on the "" page

Step 4: Add it to the .mesh

This tutorial assumes you already know how to . Quick reminder about the mlsetup:

1. Export it to json

2. edit the mlsetup.json with the

3. Import it back

Find the step-by-step guide in the on the "" page

Test it

Now, log into the game and spawn the item variant. The name is the header you defined in the yaml file, in this case

Adding a Male Instance

If an item is rigged for the female body gender, it will look wonky if worn by a male-rigged V. (But we have a snarky tooltip, so that's OK!)

This section of the guide will teach you how to fix that, adding versions for both body genders.

Finding the mesh file for the male variant

To fix this issue, we'll need a mesh that's compatible with Male V.

In the interest of keeping things simple, we've found just the mesh for you! It's called t1_024_ma_tshirt__sweater.mesh and it can be found in the base\characters\garment\citizen_casual\torso\t1_024_tshirt__sweater directory.

Now, add the file to your project, move it to the tutorial\torso\my_custom_shirt\ folder and rename it from t1_024_ma_tshirt__sweater.mesh to my_mesh_m.mesh.

Next, follow the steps you used for the original my_mesh.mesh by removing any unnecessary entries and adjusting the indices.

Creating a .ent File for Your Custom Mesh

It's time to set up the .ent file for our mesh. Don't worry, it's easy!

Start by making a copy of the mesh_entity.ent file that you previously created for the female version by duplicating it, and rename it to mesh_entity_m.ent.

Inside the mesh_entity_m.ent file, find the first component of the type entGarmentSkinnedMeshComponent. Set the following values:

Edit the yourModName.yaml

Inside the yourModName.yaml file set the appearanceSuffixes array to itemsFactoryAppearanceSuffix.Gender

Edit the root_entity.ent

1. Find the array appearances.

2. Expand the first entry.

   1. Append &Female to the name attribute. This will change the name from appearance_root_entity_white_red

Edit the appearance.app

1. Find the array appearances

2. Duplicate the first entry to create a new one and expand it

3. Set the name attribute to my_shirt_m

Testing the mod

To test your mod, it's important to ensure that it works correctly for both male and female V. This means you'll need to have two separate save files, one for male V and one for female V, unless you're using a mod that allows you to quickly switch between them.

Test your mod independently for both cases by loading the appropriate save file and checking that the mod is working as intended. To spawn and equip your item, use the command specified in your YAML file.

The final touches

If everything is working: Congratulations! You have successfully made a mod!

But before you can share it, you need to do one last thing, which is changing the file structure. Otherwise, everyone will overwrite the same tutorial files, and only one of those mods will work.

You can find a full guide on how to do that .

Troubleshooting

Before starting to troubleshoot, make sure that you have all the requirements installed and up-to-date — , and .

First of all, check the logs for errors including the name of your mod:

• red4ext/plugins/ArchiveXL/ArchiveXL.log

• red4ext/plugins/TweakXL/TweakXL.log

Fix any errors that

ArchiveXL added clipping!

You have read right past those warning boxes telling you about . Make sure that you add them back.

My item warps weirdly

... deforms incorrectly, or is a puddle on the floor?

Most likely, you have ignored the when picking your mesh_entity.ent: Make sure that you're using an entity file that corresponds with the slot that you are trying to replace (e.g. if your item is a pair of shoes, you need an entity file from base\characters\garment\player_equipment\feet).

I can't add my item with the spawn code!

When you can't spawn your item with CET, then the error is between the yaml, the factory, and the root entity.

If no additional yaml files are messing things up, then the error is somewhere in the first part of the chain and relatively easy to fix:

Check the following places:

• yourmodname.yaml:

  • Is the indentation correct, as shown in the picture? You can use to check.

  • Did you make any typos?

My item shows empty text instead of name/description!

Something went wrong with your json file:

If there are no errors in any of the log files, check the following places:

• yourmodname.archive.xl:

  • Does the key localization - onscreens - en-us exist?

The item spawns, but…

Congratulations, you've made it into the lower left part of the diagram, and can also make use of Wolvenkit's now! The error will be somewhere here:

Nothing happens when I equip it!

There is a short glitch (or maybe not), but the previous item is still visible, and nothing happens. Or, for head items, V is bald all of a sudden because their hair is gone.

Narrow it down

Let's check if the game finds your root entity. For that, we'll do two things (don't forget to un-do them later):

1. Change the base type

2. Add a tag to the root entity

Helmets are hiding hair by default, unless you tell them not to. We'll make use of that by changing your item's $base in the .yaml:

In your root entity, open visualTagsSchema -> visualTags -> tags (create any entries that are missing) and add the following CName:

You can now start the game and equip your item again.

V has hair

Your root entity is working, and the error is somewhere here:

V is bald

Your root entity is not recognized and the error is somewhere here:

It's invisible in photo mode!

Try using other equipment slots, just to check. E.g., if your item is a face item (mask), set its $base in the yaml to e.g. Items.GenericOuterChestClothing

Parts of my mesh are invisible!

You have an incorrect material assigned. Check your chunkMaterials in the mesh.

ArchiveXL ignores my dynamic variants!

No, it does not. You have an incorrect material assigned. (And I'm totally not writing this after 3 hours of troubleshooting -.-)

The game crashes!

That means the chain is working, but something isn't loaded correctly. That's good! Check the following files:

• appearance.app: Check the partsValues and partsOverrides entries. They need to point at the mesh_entity.ent, not at the mesh.

• mesh_entity.ent: Does the component

If the default mesh is displayed correctly, then we have narrowed down the problem.

If the default mesh is not displayed correctly, then there's an issue between the root_entity and your .app file, or in the .app file's internal logic.

Troubleshooting a mesh

For more detailed error handling, check the sections below, or check .

The easiest way to troubleshoot your mesh is by using Wolvenkit's and keep an eye on the log view.

If none of that helps, I suggest

• doing a gdb export

• throwing away your mesh (don't close the WKit tab yet), falling back to an original game item

• doing a gdb import

My mesh is black and shiny!

Congratulations, this is about the easiest-to-resolve error that you could've had. Your mesh is loaded correctly, there is only a problem with the rendered material.

The easiest way to troubleshoot your materials is by using Wolvenkit's and keep an eye on the log view.

My mesh has the wrong appearance!

Either an appearance is incorrectly selected (app file), or it is incorrectly resolved (mesh file). Check the following places for copy-paste/duplication mistakes:

yourModName.yaml - is the appearanceName correct, or did you forget to change it?

If you are not using , also check the following two files: root_entity.ent - does the name corresponding to the field above point to the right appearanceName in the right .app file? appearance.app - does the appearance's partOverride set the correct appearance in the componentsOverride?

Now, check the mesh file (close and re-open it to make everything refresh):

appearance - do the chunk entries point to the material that you want? materialEntries - is the index correct, or is it pointing at a different material? localMaterialBuffer - does the CMaterialInstance use the correct .mlsetup file?

Finally, check the .mlsetup itself: does it actually use different colours, or is it just a duplicate?

My mesh is invisible!

Here we go. This is the big one, and it's Not Fun. The error can be anywhere between the yaml and the mesh. You can rule out one of the files with the following questions:

Does file validation yell at you? If not: The error is between the yaml and the root entity. Check the .yaml, the .xl, and the root entity itself. The most common cause are incorrectly spelled appearanceNames. If yes: Unless the errors are warnings, fix them first.

Does the glitching stop after <10 seconds? If not: the appearance can't be resolved - ignore the .mesh If yes: the appearance is resolved, but can't be displayed - ignore the .yaml

If the hint above doesn't solve it, proceed to troubleshoot in the same way as "My mesh has the wrong appearance!" above.

My garment tucks into/under other garments incorrectly

That's due to - check the link to learn more.

Visual tags aren't working!

If you are hiding components via visual tags, these tags have to go into the .app file rather than the root entity. File validation should complain about this.

I can't find anything, kill me now

Time to restore your files one by one to the last working backup and restart from there. Don't delete them, keep them in a different folder - you will be able to copy a lot of stuff over.

Good luck, soldier.

Summary

Published: July 08. 2023 by Last documented update: Feb 07 2024 by @manavortex

This guide will teach you how to change the ArchiveXL item addition process to make it work for a weapon.

Summary

Created & Published: June 10 2023 by @manavortex

This page is a part of the Adding new items guide and contains the steps necessary to create different equipment types.

For an overview of prefixes for the different component types, see here.

Step 1: The .yaml

You define the item slot in your .yaml file by specifying the root entry type via a $base record. Base records come in many different types, some include intrinsic modifiers that add slight stat improvements to items, or add special sound to items. A complete page with clothing items, their intrinsic modifier, and their baseids can be found on the official Cyberpunk 2077 wiki's article for clothing .

You can use the following base types:

Step 1.5: EquipmentEx

psiberx's mod EquipmentEx ( | ) adds a whole new wardrobe system, providing extra slots that CDPR forgot to include with the basegame. This feature requires the mod to be installed — without it, only the $base types from step 1 will be considered.

All you need to do is adding the last two lines to your .yaml:

When selecting an entity file, make sure to match it to the corresponding body part for your clothing item. This helps ensure that animations and placements work correctly, preventing visual glitches. Always refer to mesh_entity.ent for defining components properly.

Step 2: the entity file

Some item properties are defined in the file mesh_entity.ent via components. If you use the wrong kind of entity, you might end up with your shirt being a puddle around your feet, or . To get around that, you need to make sure to pick a file that correspond's to your item's body part.

You can find all entity files under base\characters\garment\player_equipment:

If you want to be super thorough, you can stick to the right gender

(Optional) Step 3: Hide it in First Person

You can hide items most easily via . Check the linked page for how to do that.

Footstep sounds

To find the correct tags for footstep sounds, check -> .

Summary

Created: May 27 2025 by Last documented update: May 29 2025 by

This is supposedly meant to be a comprehensive guide to how to create an entirely new weapon — independent of the game's own files. The approach guarantees full compatibility with whatever other modders do, as well as making it virtually time-proof.

Download the packed project from at Nexus Mods and take a look at the files yourself, if you feel like you need any more enlightening.

Wait, this is not what I want!

• What do you mean? Of course this is exactly what you want.

• For an in-depth guide about weapon additions, check

• If you want to add clothes, check

Requirements

• For custom color variants, you should have installed (you don't want to do this by hand)

To complete this guide, you need the following tools (and should know your way around them):

Step 1: Gathering the files