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 are an absolute beginner who has never done this before, check out Adding new items. The guide will tell you when to switch over.

• You can find the technical documentation for dynamic variants on ArchiveXL's github.

• If you want to create an Atelier store, see Your own Atelier Store

• To quickly generate instances with up to two keys, check out W's generator (Codepen.IO)

Prerequisites

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

• WolvenKit >= 8.11.0 (you should have it )

• TweakXL >= 1.4.4

• ArchiveXL >= 1.5.0

• Red4ext >= 1.17.0

• Cyber Engine Tweaks (for spawning items)

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?

With vanilla item additions, you need one entry in the root entity per suffix. This gets out of hand quickly. When making stockings, there are four feet states (flat, flat_shoes, lifted and high_heels), and two body genders (Male and Female) . That leads to 4x2 entries for a single item.

For 15 appearances (colour variants) per mesh, I (manavortex) ended up with

• 120 entries in the root entity (4*15 per body gender)

• 120 entries in the .app file, (4*15 per body gender)

• six mesh_entity files (flat, lifted, and heels for each body gender. I used the same for flat and flat_shoes, or I'd have ended up with eight.)

The most frustrating part was that everything was just duplication. Each set of entries in the .app file would only differ by name (_pwa and _pma to select it from the root entity), and the mesh entity path in partValues. Everything else was virtually identical, but I had to copy-paste and maintain 120 entries.

I cried to psiberx, who went and made the problem go away.

Dynamic variants put the logic into the mesh entity file. Instead of defining appearances with suffixes, I can conditionally define which component gets loaded, and ArchiveXL does the rest.

If you still aren't convinced, go to Adding new items and start duplicating entries. Everyone else, to the batmobile!

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

Step 0: Download the example project

This guide assumes that you have access to the prepared example project, so go and grab it.

2. Find the template project on Nexus.

3. Download it and extract the files to your project's root folder, so that the source directory merges with the existing one.

Step 1: Understanding the process

The yaml

For a general explanation of what the yaml file does, check #the-control-file-yourmodname.yaml. This section will only cover the differences between a dynamic and a regular yaml.

This is your dynamic project's yaml file, minus any properties that aren't influenced by the dynamic appearances:

Items.my_custom_shirt_dynamic_$(base_color)_$(ribbons):
  $base: Items.GenericInnerChestClothing
  $instances:
    - { base_color: white, ribbons: red,  icon: 01 }
    - { base_color: black, ribbons: red,  icon: 02 }
    - { base_color: black, ribbons: blue, icon: 03 }
  appearanceName: root_entity_dynamic_appearance_!$(base_color)+$(ribbons)
  displayName: my_custom_shirt_dynamic_i18n_$(base_color)_$(ribbons)
  icon:
    atlasResourcePath: tutorial\torso\my_custom_shirt_dynamic_variants\ops\preview_icons.inkatlas
    atlasPartName: slot_$(icon)

This section will explain how that works - except for the appearanceName, you will find that in #the-root_entity.

Record names

TweakXL will generate one record per entry in $instances, according to the rules that you're using in the item name. This happens via property interpolation.

The example above will generate three item entries by substituting $(property_name) with the value of the property from the entry. If that isn't clear enough, check the example and the resulting item codes at the end of the line.

tems.my_custom_shirt_dynamic_$(base_color)_$(ribbons):
  $instances:
    - { base_color: white, ribbons: red,  icon: 01 } # Items.my_custom_shirt_dynamic_white_red
    - { base_color: black, ribbons: red,  icon: 02 } # Items.my_custom_shirt_dynamic_black_red
    - { base_color: black, ribbons: blue, icon: 03 } # Items.my_custom_shirt_dynamic_black_blue

Game.AddToInventory("Items.my_custom_shirt_dynamic_white_red") 
Game.AddToInventory("Items.my_custom_shirt_dynamic_black_red") 
Game.AddToInventory("Items.my_custom_shirt_dynamic_black_blue") 

Display names

Like the record names, the displayName property is also generated for each entry:

  $instances:
    - { base_color: white, ribbons: red,  icon: 01 } # my_custom_shirt_dynamic_i18n_white_red
    - { base_color: black, ribbons: red,  icon: 02 } # my_custom_shirt_dynamic_i18n_black_red
    - { base_color: black, ribbons: blue, icon: 03 } # my_custom_shirt_dynamic_i18n_black_blue

All you need to do is to make sure that such an entry exists in your localization file.

Icons

The icon name in the record is also generated for each entry. They are all using the same inkatlas, but you can generate that as well if you want - I've done it for the Netrunner suits, since I needed more than 100 icons.

  $instances:
    - { base_color: white, ribbons: red,  icon: 01 } # slot_01
    - { base_color: black, ribbons: red,  icon: 02 } # slot_02
    - { base_color: black, ribbons: blue, icon: 03 } # slot_03

The only important thing here is that the naming follows your inkatlas file's slot definitions.

If you want to make gendered icons, please check Gendered preview icons -> #does-this-work-with-dynamic-variants

Exercise 1: Create more records

With clever hook-ups in the mesh entity, you can set up your items so that they can be changed with a simple .yaml edit — that means, the user can switch out the ribbon colour without ever starting Wolvenkit!

We'll use that here to enable "hidden" appearances.

I have hooked up the example project to support two base colours:

• black

• white

and three ribbon colors:

• red

• blue

• green

By editing the $instances block in the .yaml, you should be able to spawn 6 different shirt in the game without touching any of the additional files!

The root_entity

For a general explanation of the root entity, check #root_entity.ent. This section will only cover the differences between a dynamic and a regular root entity.

The appearance name in the root entity corresponds to the appearanceName property in the .yaml without the variant:

You can leave the appearanceName blank. In that case, ArchiveXL will look for an appearance with the same name as the name attribute.

Since the appearance in the .app is called app_file_dynamic_appearance for clarity, and there is no root_entity_dynamic_appearance_ in the .app, this will not work for the example project.

The .app

For a general explanation of the .app file, check #appearance.app. This section will only cover the differences between a dynamic and a regular .app file.

.app file: Conditional switching

You can define appearances for different circumstances by changing the appearance names. This will let you influence the mesh entity even further by e.g. hiding parts of the mesh via #chunkmask. And the best part is: you don't even need to touch your root entity.

In the context of our example project, this means that you can define your appearances like this:

The mesh_entity

For a general explanation of the mesh entity, check #mesh_entity.ent. This section will only cover the differences between a dynamic and a regular mesh entity.

Like appearance definition names, components in the mesh entity support #ent-file-conditional-switching. On top of that, they also support #substitutions.

Check #the-diagram's bottom left corner for a demonstration of both, or read up the ArchiveXL documentation on how they work.

Substitutions

In your mesh entity, you can use substitutions in path names to load different meshes. This is better than #ent-file-conditional-switching because it won't create extra components.

To enable substitution, your depot path must begin with an asterisk *. Each substitution needs to be enclosed in braces, e.g. {gender}.

For a list, check #which-substitutions-exist

.ent file: conditional switching

Just like in the .app file, you can apply conditional switching to component names. It works exactly like #app-file-conditional-switching:

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 vanilla variants, but that the rest of the files has gotten a lot more manageable:

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

Tools and utilities

Generating display names

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

Troubleshooting

Please see the original guide's #troubleshootingsection.

Summary

Published: Sep 09 2024 by Sumi Last documented edit: Sep 09 2024 by manavortex

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

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.

  $instances:
    - { type: sleeves, base_color: white, ribbons: red,  icon: 01 }
    - { type: nosleeves, base_color: black, ribbons: red,  icon: 02 }

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

before:

appearanceName: root_entity_dynamic_appearance_!$(base_color)+$(ribbons)

after:

appearanceName: root_entity_dynamic_appearance_$(type)_!$(base_color)+$(ribbons)

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 Chunkmasks: partially hiding meshes), 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, probably. During your exploration of the wiki you will likely come across many different ways to create item variants. The benefit is that you don't have to manage as many root entity files, but it's just a matter of preference and what works best for your project.

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 ItemAdditions: File structure explained.

• If you want to add an atelier store, see Your own Atelier Store.

• If you want to add preview items, check Your own inventory preview icons.

• If you want to port a mesh from a different game to Cyberpunk, check Porting 3d objects to Cyberpunk

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, delete everything - these will get autogenerated.

3. Open the file root_entity.ent.

   Expand the list appearances. Delete all entries but the first (most likely default).

4. Open the file my_custom_shirt.app. Expand the list appearances. Delete all entries but default.

5. Open the file mesh_entity.ent Select resolvedDependencies and delete all the entries. (We don't need Judy's top anymore.)

6. Make a back-up copy of your t1_custom_shirt.mesh, then open it.

   1. Expand the first appearances at the top of the file. Open the appearance default and check which material is linked in the chunkMaterials array.

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

Items.My_Custom_Shirt:                      << name of your item (the spawn code)
  $base: Items.Shirt
Items.My_Custom_Helmet:
  $base: Items.Helmet
# For items that should hide hair, use records with the "Hair" suffix.
Items.My_Custom_HelmetWithHair:
  $base: Items.HelmetHair
# For items that should have an intrinsic modifier, e.g. Armor
Items.My_Custom_HelmetWithArmor:
  $base: Items.Helmet_Intrinsic
# For feet items that use heels (clicky sound)
Items.MyCustom_Heels:
  $base: Items.FormalShoes

You can use the following base types:

Step 1.5: EquipmentEx

psiberx's mod EquipmentEx (github | nexus) 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:

Items.MyNecklace:
  $base: Items.GenericHeadClothing
  placementSlots: 
    - !append OutfitSlots.NecklaceShort

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 string cheese. 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 ArchiveXL tag. Check the linked page for how to do that.

Footstep sounds

To find the correct tags for footstep sounds, check ArchiveXL: Tags -> #footsteps-setting-footwear-sounds.

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

4. the .json file with the translations

The .xl file

This file will be in the same directory as your mod's .archive file. It lets ArchiveXL register the factory (my_shirt_factory.csv) and the localization file (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 the xl file'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, next section), the game will find entries like this:

Items.my_custom_shirt_redwhite:
  entityName: my_custom_shirt_factory_name             << this is for the factory.csv
  appearanceName: appearance_root_entity_white_red     << this is for the root_entity.ent

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 root entity 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 dynamic appearances, an entry looks like this:

Four mappings take place here:

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

2. appearanceName: In the root entity 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: This hooks up your custom preview.

What is it, precious? The $base parameter

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

.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 TweakXL's creating records.

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.

• root_entity.ent

• appearance.app

• mesh_entity.ent

• the mesh file

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 dynamic appearances, 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 factory.csv.

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

	appearanceName: black_red_appearance_name
	name: appearance_root_entity_black_red

new:

	appearanceName: black_blue_appearance_name
	name: appearance_root_entity_black_blue

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 right mesh entity file 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 below)

Mesh Entity: Making Changes

When you move this file, you need to change the path inside every appearance inside the .app 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 rootentity.ent. Each of the appearances will load mesh_entity.ent via partsValues.

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

An entry will look as follows:

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

For ArchivXL >= 1.4.0, 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)

4. In the new appearance, find the array partsOverrides and expand it.

5. Select the item inside.

6. Find and expand the Array appearanceAppearancePartOverrides and expand it.

7. Select the first item.

8. Open the array componentsOverride and select the first item.

9. Change the value of meshAppearance to the name of your new appearance in the mesh:

componentName: t1_tutorial_custom_shirt_4711   << no need to change this  
mesh_appearance: mesh_black_blue                << corresponds to meshMeshAppearance.name in my_mesh.mesh  

Mesh

The mesh file maps materials to appearances. To find out how exactly it does that, find the material section 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.

   2. Change the name to the one you've defined in the appearance.app above (in this case: mesh_black_blue):

   3. Select the array chunkMaterials and change the entries in the right-hand panel to the name of your new material (e.g. black_blue)

2. Find the array materials and open it.

   1. Duplicate the last entry. (Yes, use the last one, please, it's important for step 3).

   2. Select the new last entry

   3. Set the following values:

      Copy

      name:  mesh_black_blue           <<< as defined in step 1 and used by meshMeshAppearance in appearances[]  
      index: <index of item in array>  

      If you duplicated the last material, you can just increase it by one.

3. Find the array localMaterialBuffer and open it

   1. Duplicate any entry with an mlsetup (You will see an entry MultilayerSetup under values)

   2. Drag it to the last position of the array (that's important, because the materials entries match by numeric index)

   3. Select the new item, open values, and select MultilayerSetup.

   4. Set baseMaterial/DepotPath to the .mlsetup file that you want.

For further information and guides, check here or see https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators/files-and-what-they-do/3d-objects-.mesh-files.

The final result

This is how everything plays together:

Summary

Created & Published: November 04 2022 by @manavortex Last documented Update: July 05 2024 by manavortex

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 - https://www.youtube.com/watch?v=r3nyFm-9h9o&t=3s

This guide will give you a working mod with a very basic structure. In the section #great-you-added-items-now-what, 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 this one 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. To get a deeper understanding of the process, you can follow the linked resources, or consult ArchiveXL's documentation.

Wait, that's not what I want!

• Visual learners rejoice: You can find a video of this guide on youtube (https://www.youtube.com/watch?v=r3nyFm-9h9o)

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

• If you want to convert a mod to dynamic appearances, check the ArchiveXL: Dynamic conversion guide

• If you want to use dynamic appearances out of the box, check ItemAdditions: Dynamic Appearances (this is the preferred approach as soon as you're creating different options).

Step 0: Grab the example files

• Create a new Wolvenkit project

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

You should now have the following files:

Start the game

1. Wipe the folder packed

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

3. Copy all files under packed into your game directory (it will overwrite without prompting)

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 #troubleshooting below, or retrace your steps and make sure all mods are installed correctly before continuing with #great-you-added-items-now-what

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 Different equipment slots (e.g. shoes or glasses)

• Learn about #variants-and-suffixesfor e.g. #adding-a-male-instance or check the #hiding-body-parts-diagram

• Learn about making more variants:#adding-an-appearance

• Create Your own inventory preview icons

• Create Your own Atelier Store

• Learn about Porting 3d objects to Cyberpunk

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 corresponding wiki page.

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

4. *.mesh:

   1. Adding a MeshMaterialEntry

   2. Adding a MaterialInstance

   3. Adding a material

   4. Connecting those things

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 appearanceName: appearance_root_entity_black_blue

4. For lookups in your translation file (translation_strings.json): Change the values of displayName and localizedDescription to the corresponding secondary keys in the json file. This is optional.

   Copy

     displayName: my_shirt_localization_name_black_blue
     localizedDescription: my_shirt_localization_desc

   ℹIf you make any mistakes here, the worst that happens is an empty string.

5. Now, add a new entrie to your .json file:

   Copy

   localizationPersistenceOnScreenEntry - []   
   	femaleVariant: my item - now in black and blue
   	maleVariant:  
   	secondaryKey:  my_shirt_localization_name_black_blue

The total entry should look like this:

Items.my_custom_shirt_blueblack:
  $base: Items.GenericInnerChestClothing
  entityName: my_custom_shirt_factory_name
  appearanceName: appearance_root_entity_black_blue
  displayName: my_shirt_localization_name_black_blue
  localizedDescription: my_shirt_localization_desc
  quality: Quality.Legendary
  appearanceSuffixes: []

Step 2: Add it to the root_entity.ent

Find the step-by-step guide in the root entity section on the "Item structure explained" page.

If you want to add a dynamic appearance, 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 appearance section on the "Item structure explained" page

Step 4: Add it to the .mesh

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

1. Export it to json

2. edit the mlsetup.json with the MLSetupBuilder

3. Import it back

Find the step-by-step guide in the mesh file section on the "Item structure explained" 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

Game.AddToInventory('Items.my_custom_shirt_blueblack')

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:

mesh:   DepotPath:   tutorial\torso\my_custom_shirt\my_mesh_m.mesh      << path to your mesh  
        Flags:       Default                               << leave this alone  
name:   my_shirt_m    << this corresponds to the appearanceOverride in appearance.app  

Edit the yourModName.yaml

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

Items.my_custom_shirt_redwhite:
  $base: Items.GenericInnerChestClothing
  entityName: my_custom_shirt_factory_name
  appearanceName: appearance_root_entity_white_red
  displayName: my_shirt_localization_name_white_red
  localizedDescription: my_shirt_localization_desc
  quality: Quality.Legendary
  appearanceSuffixes: [ itemsFactoryAppearanceSuffix.Gender ]
  icon:
    atlasResourcePath: tutorial\torso\my_custom_shirt\ops\preview_icons.inkatlas
    atlasPartName: slot_01

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 to appearance_root_entity_white_red&Female.

3. Duplicate the first (and only) entry to create a new one.

4. Expand the newly create entry

   1. Set name : appearance_root_entity_white_red&Male.

   2. Set appearanceName : my_shirt_m.

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 (as defined in the root_entity)

4. Find the array partsValues

   1. Set the resource path to your new male mesh entity file: resource : tutorial\myshirt\mesh_entity_m.ent

5. Find the array partsOverrides

   1. Find the array componentOverrides

      1. Set componentName : my_shirt_m

   2. Set partResources : tutorial\torso\my_custom_shirt\mesh_entity_m.ent

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.

Game.AddToInventory("Items.my_custom_shirt_redwhite")

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

Troubleshooting

Before starting to troubleshoot, make sure that you have all the requirements installed — Red4ext, ArchiveXL and TweakXL.

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

• red4ext/plugins/ArchiveXL/ArchiveXL.log

• red4ext/plugins/TweakXL/TweakXL.log

ArchiveXL added clipping!

You have read right past those warning boxes telling you about component name prefixes. 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 hint box 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 spawn my item, but it's not added to my inventory!

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.archive.xl:

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

  • Did you make any typos?

• my_tshirt_factory.csv:

  • Is there an entry where the first value matches the entityName from the yaml (my_tshirt in the picture above)?

    • Without leading or trailing spaces?

  • Does the second value of that entry have the correct root entity path? (tutorial\myshirt\root_entity.ent in the picture above) If you moved the root_entity.ent, you have to adjust this entry.

• root_entity.ent:

  • Do you have an appearance with the name matching your item's appearanceName in the yaml?

    • Without leading or trailing spaces?

  • Are you using any suffixes? Are you using the correct ones?

    • Try setting an empty suffix array in the .yaml, just to see if that works: appearanceSuffixes: [ ]

    • Try creating a fall-back entry without any suffixes in the root_entity.

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?

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

  • Does it point at the correct file (tutorial\ops\translation_strings.json), or did you rename or move it?

  • Did you make any typos?

• yourModName.yaml:

  • Is the spelling for the key you defined after displayName and localizedDescription identical to the one in the json file?

• translation_strings.json:

  • Is the spelling of the key defined in yaml's displayName and localizedDescription identical?

  • Did you set the femaleVariant (default)?

  • Are you using quotation marks? If so, switch to single quotes!

  • If the field for primary_key is not empty, then its value must be unique (probably on a per-file basis). Set it to 0.

The item spawns, but…

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:

$base: Items.GenericHeadClothing

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

force_Hair

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 entry point to a valid mesh? Try it with a default mesh as detailed above.

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 this page.

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

• replacing the arrays appearances, localMaterialBuffer.materials and materialEntries with those from your previous mesh.

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.

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 dynamic variants, 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 garment support - 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: December 2023 by destinybu Last documented edit: Feb 07 2024 by

We'll be making a fully featured new Iconic weapon in this guide, which is designed for first-timers and goes into details into every aspect about weapon modding. (not appearances)

Wait, this is not what I want!

• You can find another guide about this topic under

• For an overview of weapon properties, check

• For an overview of weapon audio profiles, check

Prerequisites

Before beginning, ensure you have the following software installed and properly set up:

1. WolvenKit (8.12+) -

2. MLSB (MultiLayerSetupBuilder 1.6.7+) -

3. A text editor: or, if you want to get fancy,

4. Cyberpunk 2077 - 😑

5. Core mods: , ,

6. Optional: ,

Iconic Weapons in a nutshell

Each Iconic weapon is a variant of a base weapon, with an hidden (from the player) mod. This "hidden" mod contains a statModifiers array (to list all the stat changes this Iconic will have from the base weapon) and an OnAttach array. The OnAttach array is where you'll want a GameplayLogicPackage to go. You may or may not need to define conditional effectors in there, but if you want your weapon to have the customary Iconic yellow description then be aware that there is where it's written (in the UIData of the GameplayLogicPackage).

Step 0: Understanding the structure

The rest of this guide will hold your hand through a deep dive, step-by-step, of your first custom Iconic made from zero. If you get lost through it, or if you'd rather find your own flow, you'll be well served by returning to check the code of an Iconic weapon already in the game (as you'll be building up from a base weapon in the same way, and it's solid footing).

Step 1: Create a New Project in WolvenKit

Start by opening WolvenKit and create a new project. This will be the base for your new iconic weapon mod.

Step 2: Choose the weapon and create an override

Decide on the weapon you want to modify to make a new new iconic.

After locating the Unity gun in the tweak browser, right-click on the item and select "Add TweakXL Override". This allows you to modify and customize the weapon’s attributes to create your new iconic weapon.

Step 3: Editing and understanding your new tweak

How does it work?

The .yaml file may seem complex at first glance, but the actual structure is extremely simple. Your weapon has properties – those stand on the left side of the :, such as ammo. The properties have different values, and those stand on the right side of the :, such as Ammo.RifleAmmo.

Step 4: Making a new weapon

4.1: New weapon, same as the old weapon

Making a new weapon is fairly simple. In your tweak file, change the Item ID in the very first line to "Items.Hand_Of_Midas" and save (Hotkey: Ctrl+S).

That's it, you've created a new weapon now. This weapon will look & behave exactly like the Unity handgun, but trust me, it's new.

To test it out, boot up your game and load any save.

Type in the command below and hit Enter.

You can now see your newly created weapon in your inventory.

Unfortunately, there is no way to tell it apart from the Unity handgun.

We'll get to fixing that, but first, a little cleanup: open up your WolvenKit & rename your overridden tweak file to "hand_of_midas.yaml". We will store all the edits that need to be done to our new weapon in this file.

4.2: Changing the carbon copy

Let's change something that will differentiate our weapon from the default Unity.

To do this, open your renamed tweak file & find the crosshair tag (hotkey: Ctrl+F). Replace it as shown below, and save your file.

Now hot reload your game (Insert how to link here) or close it, reinstall your mod in WolvenKit & relaunch your game (From here on, this will be referred to as hot reload).

Spawn in both the Unity & Hand of Midas using the CET console:

You should now be able to see that both the Unity & Hand Of Midas, although otherwise identical, now have different crosshairs.

How did we figure out the crosshair ID?

How do we know that it's called "Crosshairs.Tech_Round" ?

Method 1: The REDmod DLC

If you have the REDmod DLC installed, you can use a text editor like Notepad++ to do a full-text search under Cyberpunk 2077/tools/REDmod. By searching for crosshair:, you can find all value assignments in the game files.

By searching for "Crosshairs." in the Tweak Browser. Most things we find inside the weapon tweak will be searchable within the Tweak Browser, and some within the Asset Browser.

Editing the Tweak will allow us to modify all of our gun's behaviors, and I encourage you to play around with these.

Step 5: Removing redundant code

We're only changing a single property in the Hand of Midas. For that, we have a tweak file with more than 200 lines of code. Can't we do this in a better way?

We can, and we should!

Using $base instead of $type

As shown above, when using $type to define a tweak, we need to add all the required properties for the type, but when using $base to define one, we only need to add the properties we are changing, the rest are taken from the parent.

Now go ahead and change it so we use a $base & only define the crosshair. Your entire tweak should now look like this:

Step 6: The personal touch

What good is a new gun without a new name? We need to tell our game about these.

1. Open your WolvenKit project and navigate to the archive folder

2. Create a new folder named after your mod, for example midas_collection

3. Within this folder, make a subfolder named localization

How does the game assign display names?

In your full tweak file, search for the field called displayName. You'll likely encounter something like displayName: LocKey#49794.

This connects the displayName property of your item with a locaization key, which is the mechanism that the game uses to support multiple languages. Think of the LocKey of a list entry, with different lists being used for different languages.

So we edit onscreens.json?

Setting up a localizationKey

Open the file in Wolvenkit and create a new entry in localizationPersistenceOnScreenEntry. It has the following properties:

Create another entry with the secondaryKey of MC_gun_description and write a little fluff text for the description.

Tell ArchiveXL about our new translation file.

In your WolvenKit project, go to the resources folder and create a plain text file with the following contents:

Rename this file to midas_collection.archive.xl.

Next, revisit your "hand_of_midas" tweak file to establish the weapon's name and description in the game.

Add the following lines under the existing properties:

These lines set the display name and the description of your weapon using the keys defined in your localization file. The values on the right side of the : must match the secondaryKey values from your en-us.json file and be globally unique.

After completing these steps, install your mod and launch the game. Your new weapon, "Hand Of Midas", should now appear with its unique name and description, fully integrated into Cyberpunk 2077's multi-language environment.

Step 7: Make it Iconic

To elevate the 'Hand of Midas' to its iconic status, we need to modify the .yaml again, where we set all of the gun's unique features:

The new things you're seeing are arrays, which is a technical term — you can think of them as lists, since they can hold multiple items.

statModifiers will hold all the stats for your gun. from recoil to damage. Since the $base: Items.Preset_Unity_Default already defines statModifiers, and we'd like to keep those. So we're adding an entry to the list, using!append-once followed by the new entry Quality.IconicItem.

This makes the weapon iconic, which means:

• it has a fancy golden background

• there's a dialogue box when you disassemble it

To prevent it from being disassembled, we also add IconicWeapon to its tags array.

Upgrade compatibility

We make sure that the weapon updates correctly by setting the

What exactly it does is somewhat of a mystery, so let me know if you find out.

Go test

Once these modifications are in place, install your mod and enjoy the newfound Iconic status of the 'Hand of Midas' in the game.

Technically, you've already made a new Iconic weapon & I should call quits on this tutorial, but it's never as easy as that, is it? Give yourself a pat on the back & onto the next step.

Step 8: Audio - Gun Go Boom

Let's talk theme.

The gun is called Hand Of Midas, so it would be fitting to have the gun sounds be more… gold-ish, right? How do we achieve this?

We could add custom sounds using RedMod, but due to how that works, we could end up with conflicts that we don't want to bother with. So let's look for guns that already have a sound like that. Dex's gun Items.Preset_Liberty_Dex already has a nice metallic ring to it, so let's just steal its sound effect. To do this, find the gun in Tweak Browser and look for the property audioName.

Now add this value to your weapon tweak as shown below.

Install your mod and test it out, Hand Of Midas now sounds metallic like we intended it to.

Step 9: Weapon Design 101 - Conceptualization of your Iconic (Optional)

So now let's make it completely overpowered and take all fun out of using it!

Joking. Let's talk about how we can avoid that trap.

The 'Hand of Midas' is envisioned to be a unique piece with its own character - ideal for players who relish precision and skill. So we need strengths and limitations to give it a clear identity. Here's how we achieve this:

1. Increased Recoil: This adds a layer of complexity and skill. High recoil means each shot requires careful consideration, appealing to players who enjoy a challenge and the satisfaction of mastering a weapon.

2. Smaller Magazine Size & Increased Reload Time: Every bullet counts. A smaller magazine encourages accuracy over spray-and-pray, and a longer reload time not only adds a strategic layer to combat but also gives players time to appreciate the weapon's aesthetics.

In summary, these design choices don't just balance the weapon; they enhance its identity. The "flaws" don't destroy the gun — instead, they contribute to making the 'Hand of Midas' feel powerful and rewarding for those who can wield it effectively.

Building on Strengths

Once the limitations are set, focus on the weapon's strengths to complement its defined character.

1. Increased Headshot Damage & Crit Chance: This change rewards accuracy and skill, making the weapon ideal for players who excel in precision shooting.

2. Increased Zoom on ADS & Extended Effective Range: Enhances the weapon's utility in long-range combat, aligning with its identity as a sharpshooter's choice.

Step 10: Be a stat wizard

To change the stats discussed in the step above, we again need to tinker with the statModifiers & statModifierGroups in your weapon tweak. Open up the tweak for Items.Preset_Unity_Default and navigate till you find the two arrays.

To change the gun's recoil, we'll add a new statModifierGroup tweak as shown below

Now add this stat group to your weapon's tweak (see the last line).

Install your mod, launch the game and test your changes. You should see that the gun's recoil is increased, but doesn't feel overwhelming.

You now know how to change your weapon's behavior. Play around & discover other stats and modify your gun to make it feel unique.

After a bit of tinkering, this is what my weapon tweak now looks like (expand the box below):

Step 11: Finishing up the Tweak

There are a lot of values to play around with in a tweak file. You are often better off leaving most of them alone. These are some properties you probably should look at when designing a gun.

1. Blueprint
2. Item Quality
3. Buy & Sell Price

Step 12: Making an Iconic Mod (Special Ability)

The main thing that makes an iconic weapon so special is its iconic mod. These are like any other weapon mod, but hidden from the UI. Before you start hacking up your own, it is very important you have a look at the existing Iconic Mods in game.

For now, let's look at Items.Preset_Lexington_Wilson (also known as "Dying Night").

Wilson's iconic iron

We'll end up with WilsonWeaponModAbility, which defines the abilities and stats that we care about.

MultiplyDamageWithVelocity Effector

Condition: Prereqs.ProcessHitTriggered - Does the bullet hit anything? Effect: MultiplyDamageWithVelocity - Increases the guns damage with 25% if the Player velocity is greater than 10.

MultiplyDamage Effector

Condition: Perks.IsHitQuickMelee - Is the attack a Quick Melee attack? Effect: MultiplyDamage - Increase damage by 50%

Adding an iconic mod

Since our weapon demands perfection, we'll punish the player for not hitting headshots & reward them for hitting headshots. And because we want to make it hurt, we'll use HP reduction & Healing rewards.

Defining the ability

In this section, we first define our special ability Cranial_Cashback:

The ability contains

• the description for our iconic ability as a localizedDescription

Let's start by registering the description.

2. Add another entry (you can duplicate an existing entry)

3. Set the secondaryKey to the value in your tweak file, MC_gun_iconic_description

4. Set femaleVariant to your text — this will be showin on the tooltip in yellow.

5. . Make sure that it has the correct secondary key , and enter your fluff text as femaleVariant.

Defining the mod

Now that we have an ability, we need to register it as a mod:

Adding the mod to the weapon

Now we can finally add the mod to the weapon by adding it to the slotPartListPreset:

Everything hangs together now, let's see if it works.

Go test

Install your mod — if your gun shows the yellow iconic description on hover, you're good to go. If not, you may have to respawn it via CET.

Designing effectors

Heal on headshot

We'll heal for 80 HP every time the player pops somebody else's skull with the Hand of Midas. How do we do that?

However, the prerequisite for this effector is Items.MemoryReplenishmentEffector_inline0, which doesn't sound helpful.

We could now try to find an existing preReq that checks for headshots, but we can also write our own.

Creating a custom prereq

Now we have a custom preqrequisite, but we still have to fine-tune and link it:

Creating a custom condition

Conditions are at the heart of a prerequisite, and here we have four.

1. Perks.IsHitTargetAlive_inline2 -> We don't want headshots on deadbodies to heal the player

2. Perks.HitIsBodyPartHead_inline0 -> Actual condition to check for headshots

3. Prereqs.Is_Attack_Ranged -> (Custom) We don't want quick melee attacks to heal

4. Prereqs.Is_Weapon_Ranged -> (Custom) We don't want grenades to be counted for this check.

The final effector

Now let's change our effector to use this prerequisite.

Instead of punishing the player for just missing headshots, we can make our job easier by removing the HP every time they shoot, and compensating for the reduction in HP when hitting headshots by increasing our heal. Here's how we can do that:

We've done a lot so far, so I'll leave all our changes here:

Test it!

Uncomment the effector in your weapon tweak and test your mod. You should now be healing every time you hit headshots.

Summary: The iconic weapon in action

Here's a demo for how iconic weapon should behave.

Troubleshooting (Check this when you're stuck)

You've created/modified a tweak but it doesn't show effect in game, what next?

• Open Cyberpunk 2077\red4ext\plugins\TweakXL\TweakXL.log and look for any error messages towards the end, this can help when TweakXL has issues loading a tweak.

• Check for other mods with same Tweak/Archive names.

  Tweak Folder - Cyberpunk 2077\r6\tweaks

  Archive Folder - Cyberpunk 2077\archive\pc\mod

• Look at WolvenKit logs located towards the bottom. Yellow or Red text means there's warnings/errors in your file that need addressing.

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

• Learn more about

• If you are using , you can use to quickly create spawn codes and Atelier entries

Requirements

Generating an icon

First of all, the template archive (kindly provided by Apart) and find the folder virtual_atelier_inkatlas_icon_template with the following files:

Put the .inkatlas and .xbm into your project (if you're using the , you can put them into the ops folder). Then, rename them to atelier_icon:

Creating the atelier file

1. Now, add your item.

​ Ignore "Icon path" and "description", we have these in the item itself.

1. Click "Add Item". Repeat the process with as many items as you want.

2. Click "Generate".

Placing the atelier file

In your project's resources folder, create a subdirectory r6/scripts (if it doesn't exist already), and move the atelier file that you downloaded into there:

Now, it's time to test! Install the mod and start Cyberpunk.

Troubleshooting

My atelier store causes scripting errors!

I'm not sure how you managed to read past all the red and yellow boxes on this page, but make sure that the path under atlasResource has forward slashes / instead of backwards slashes \.

If that wasn't it, you might have to re-generate your Atelier store.

My atelier store makes the game crash!

That happens when there are two atelier stores with the same store ID. Do a full-text search for the store ID (MyTutorialAtelierStore) in r6\scripts and make sure that you don't have any duplicates.

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.

Component visibility

Component visibility is defined by the visibilityAnimationParam:

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

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.

Wait, this is not what I want!

• For a much more detailed step-by-step guide, check

• For an overview of weapon properties, check

• For an overview of weapon audio profiles, check

Prerequisites

• You are familiar with ArchiveXL item additions as per the "" guide

Selecting the base

Weapons work a little different from regular ArchiveXL items, starting right at the root entity. With the help of @Apart and psiberx, I was able to figure out the process and document it for you.

Start by finding the .app file of an original weapon of the type you want to make (Theres a list ) and adding it to your project. We will change that file, rather than assembling anything by hand.

In the app file, you can also find the value for the yaml file's $base property:

Getting the mesh_entity.ent

You need the correct mesh entity to go with your appearance file. You can find them under base\weapons\ - search for the name of your weapon, or just navigate through the folders.

This file makes the weapon show up in photo mode. Instead of going into the PartsValues, it will be linked in the app file's root as baseEntity (there's a screenshot below). Leave it alone for now, it's easier to make the appearances working correctly in the .app file and then copying over an entire component array.

Factory: .app instead of root_entity

Instead of a root entity file, you need to point your factory.csv directly to your iron's app file (the one from the section above).

Appearance selection

An equipment item's lookup chain goes from the appearanceName in the yaml to the root_entity, where the appearanceName will lead to the correct appearance in the .app file.

With a weapon, all that happens through visualTags.

YAML: Define the field:

Native weapons often use one shared VisualTags to reference multiple appearanceName and randomize the result. If you want to use a specific native appearance present in a VisualTags native group, you can use appearanceName to specify which. E.g: visualTags: [ Neon ] appearanceName: neon2

.app file: Define the visual tag

visualTags (violet): Must match the visualTags in your .yaml file. If multiple entries match, one will be chosen at random.

Step by step

As the process is finicky and there can be all sorts of sudden unexpected behaviour, here's the best way to go about this.

The list links you to sections of the guide which tell you to change things. Optimally, you do a dry run with one appearance to make sure that something shows up in the game at all, then start fine-tuning, but you do you.

Here's what's worked for me (@manavortex):

1. Find the .app file of a suitable base weapon, add it to your project, and rename it. Don't change anything for now, future you might need the original data for troubleshooting later.

2. Find the correct .ent file. It might be linked in the .app's baseEntity field. If not, you can find it with the following Wolvenkit search query:

3. Start the game and make sure that you can spawn a custom weapon with the appearance you picked and that it

   1. shows up in inventory/photo mode

   2. shows up in first person

If that doesn't help, you may have taken the wrong .app file - go looking again.

1. Optional: You just added a weapon to the game that didn't exist before. Take a moment to bask in the success!

2. 1. Create a copy of the file and move it to a custom folder

   2. rename it

   3. Change the baseEntity path in your .app file

3. Optional, but recommended: Repeat step 5 and make sure that everything spawns

4. Now it's time to actually change things. Open your appearance's component array and make sure that the MeshComponents load your custom stuff (anything that has a depotPath pointing to a .mesh file).

5. After you've changed the paths, launch the game and make sure that your weapon

   1. shows up in your inventory with your meshes

   2. shows up in first person with your meshes

   3. shows up in photo mode at all (it shouldn't be invisible, but will still have the default appearance)

   4. all parts and extra meshes are visible

   5. is in the right position in regards to V's hands (at least as much as for the Tactician shotgun)

   6. all parts and extra meshes show the correct appearances

Fix any issues that might arise before you proceed.

1. Once everything works, delete all the default appearances, then duplicate and adjust the one you customized to show your color variants.

3. Luanch

Your own HUD icons

Weapon Audio

Custom throwing weapons

Editing weapon meshes

When exporting an existing weapon mesh for your custom weapon, make sure to uncheck LOD Filter — the lower LOD mesh is used for calculating the hitbox.

In Blender, put your custom mesh in both LODs.

Troubleshooting

My weapon is fully invisible, no matter what I do!

First of all, unequip and re-equip the item. If that doesn't fix it, try respawning it.

My iconic melee weapon ignores its localizedDescription!

To make it work again, you need to either

add a blueprint:

Add the following line to your .yaml:

change the base type

Set $base like this:

My weapon is spawning as the original weapon/my mesh edit isn't reflecting!

Make sure all the items under "resolvedDependencies" are deleted in your appearances, especially if they are using "Soft" or "Embedded" flags. The game might load vanilla meshes instead of your own meshes.

Summary

Created by @manavortex Updated October 05 2023

This page is a sub-page of 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:

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

4. Add this file to your project

5. Rename it and move it to your custom folder.

6. Open your root entity. For all of the appearances, change the appearanceResource path to that of your .app.

Step 4: The right mesh

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

   1. Expand the components array

   2. For any components that have Mesh in their type name:

      1. Change the mesh depotPath to your weapon's custom mesh

      2. Change the meshAppearance to one of your weapon's appearances

   3. Open resolvedDependencies and replace the path to the original mesh with your own.

Step 5: Test

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

Troubleshooting