Adding new items

No more replacers! Add your own gear with TweakXL and ArchiveXL

Summary

Created by @manavortex Published November 04 2022

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

It uses the following versions:

• Cyberpunk 2077 game version 1.6.2 Hotfix

• WolvenKit >= 8.9.0

• TweakXL 1.1.4

• ArchiveXL 1.4.3

• Red4ext 1.12.0

Assumed skill level: You should be able to find your way around WolvenKit, but I aim to keep this as noob-friendly as possible.

For experienced modders

I have repeatedly observed that newbies are fine with this guide, while people who know how to mod are not. Watch out for boxes like this one to avoid those pitfalls.

The guide was created after reading this one and being left with a bunch of question marks. To get a deeper understanding, refer to the initial guide and follow the linked resources or consult ArchiveXL's documentation.

You can find a tool to troubleshoot your ArchiveXL mod here.

Grab the example files

• Create a new Wolvenkit project

• Download the prepared files from manavortex's mega or Nexus and extract them to the root of your new project (overwriting the "source" folder

If you would rather start from scratch: Check the detailed instructions here.

For an explanation of the file structure, see the item structure explained subpage.

Understanding is not required as long as you follow the guide to the letter.

⚠ Do not edit those files outside of WolvenKit, and whatever you do, do not let Microsoft Excel touch the clothing.csv! ⚠

You should now have the following files:

The example files are set up to load a shirt with two different appearances, which you can spawn directly:

Game.AddToInventory("Items.my_custom_shirt_redwhite")

Game.AddToInventory("Items.my_custom_shirt_redblack")

Start the game

Press "Install and Launch" in WolvenKit. This will do the following things:

1. Copy all supported file entries from source to their destination under packed, overwriting older files (but not removing files that you renamed!)

2. Copy all files under packed into your game directory, again overwriting older files

3. Launch the game.

You should now see your item. If not, consult the section Troubleshooting below, or retrace your steps and make sure that everything works before proceeding to the step below.

Great! You added items! Now what?

You can now

• customize your preview images

• Add an atelier store

Diagram

This is how everything connects. Looks pretty scary, but you can find a step by step breakdown on the corresponding wiki page.

Don't panic, we've got this.

Adding an appearance (example: blackblue)

Before you add an appearance, make sure that your item is loading up correctly and looking as expected. If you have to debug, you will have to look through every appearance you made!

For experienced modders: This includes you! :)

If you would rather have a step-by-step guide for a gendered variant, see the next section.

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

1. *.yaml: Adding an entry

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

3. rootentity.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

For a diagram of how everything connects, go here.

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

     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:

   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 rootentity.ent

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

You do not need to change the appearanceResource.

Step 3: Add it to my_custom_shirt.app

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  

You can leave partsValues alone - this just points at the file that loads the mesh, and you've already set it up above when setting up the file.

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

Now we're adding the new appearances:

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:

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

Test it

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

Game.AddToInventory('Items.my_custom_shirt_blueblack')

Adding a Male Instance

This part of the tutorial isn't fully up-to-date with the overhauled file structure yet, so keep that in mind when studying the screenshots.

Also, this part is super easy to follow and even if you make a mistake, fixing it won't be a problem. But hey, you've put in a lot of work and made great progress, so why not take a sec and back up your project files? Better safe than sorry, right?

Before we proceed with the tutorial, it's important to address a common issue you might have encountered while creating your mod.

If you've tested the mod on a Male V, you might have noticed some weird glitches like mesh clipping or wonky shapes.

You see, we've been using a mesh designed specifically for Female V, and that's why we've been running into some roadblocks. But don't worry, we're here to help you overcome this challenge!

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

If you plan on using other meshes for your mod, ensure that it has ma or pma in its name.

Keep in mind that some ma meshes may still have clipping issues when paired with certain types of clothing, while pma meshes are specifically designed for V and don't have this problem.

If you decide to create your own mesh, be sure to fix any potential issues before using it in your mod. Check out our 3D modeling guide for helpful tips and resources.

Remember, a little extra effort in the beginning can save you a lot of headaches down the line!

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.

To avoid any issues, it's crucial to pay close attention to this step and double-check that the correct materials are present in the localMaterialBuffer and materialEntries, and that the indices are adjusted correctly.

This will ensure that your mod works as intended without any glitches or errors. If you need a refresher, click here to return to that section.

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.

duplicating mesh_entity.ent and creating the new mesh_entity_m.ent for out new mesh

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  

All of the changes made to mesh_entity_m.ent file

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

If you are unclear about why this step was taken, we recommend reading up on suffixes!

Edit the rootentity.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.

All of the changes made to rootentity.ent file

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

All of the changes made to appearance.app file. Paths are not up-to-date!

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

Consider reviewing the guide to ensure that all steps have been followed correctly and that the values have been set appropriately. Ensure that the mesh is compatible with the male variant of V. If errors persist, review the troubleshooting section for further assistance.

Troubleshooting

There is a tool designed to help you with the process of finding missing dependencies. You can find it here.

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

• red4ext/plugins/ArchiveXL/ArchiveXL.log

• red4ext/plugins/TweakXL/TweakXL.log

Second of all, make sure that you do not have capital letters in any of your path or file names - as of 1-1-6, they are not currently supported.

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

If you are here because of a link from a different guide:

You can find out which entity file your item uses by right-clicking on your mesh and selecting "find files using this". Add the .ent file to the list and open it in WolvenKit. Then, replace the contents of the "components" array with those of an .ent file from the correct folder — don't forget to change the path to your mesh again!

I spawn my item, but nothing happens!

Before you start digging into your file structure, check if there are any leftover yml files from earlier versions/deploys in your tweaks directory. Do a full text search in e.g. Notepad++ in any files in the folder with the name of the item you want to spawn.

If no additional yml 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?

  • Does the value for entityName have a corresponding entry in the factory (my_tshirt_factory.csv)?

  • Does it point at the correct rootentity(tutorial\myshirt\rootentity.ent), or did you rename or move it?

  • Did you make any typos?

• rootentity.ent:

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

  • Are you using any suffixes? Are you using the correct ones? Try creating a fall-back entry without any suffixes.

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?

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

The item spawns, but…

Congratulations, you've made it into the right half of the diagram! The error will be somewhere here:

If you set your mesh_entity.ent to point at a vanilla mesh, you can rule out your custom mesh and .mlsetup as a source of errors. Original game meshes will always have a working default appearance and will thus always be displayed!

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 that works, then the problem is your mesh.

Troubleshooting a mesh

For more detailed error handling, check the sections below.

ℹ In the "Mesh Preview" tab of your mesh, you can "Generate Materials for Appearance". If the correct colours show up, you can at least rule out that the error is in the .*mesh or the *.mlsetup!

• Make sure that you have the same number of entries in materialEntries and localMaterialBuffer.materials .

• Go through the CMaterialInstances in localMaterialBuffer.materials.

  • Make sure that the files you're loading exist.

  • Make sure that you don't load a mlmask under a key for an mlsetup or vice versa.

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 the original one

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

Check your mesh file:

• Check the connection between appearance, materialEntry and localMaterial.CMaterialInstance. Are the names correct?

• Go through the CMaterialInstances in localMaterialBuffer.materials.

  • Make sure that the files you're loading exist.

  • Make sure that you don't load a mlmask under a key for an mlsetup or vice versa.

My mesh has the wrong appearance!

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

yourModName.yaml - is the appearanceName correct, or did you forget to change it? rootentity.ent - does the name corresponding to the field above point to the appearanceName with the right name? 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 - does it use the correctly named material? materialEntries - is the index correct, or is it pointing at the index of the actually displayed material? localMaterialBuffer - does the CMaterialInstance use the correct .mlsetup file?

Finally, check the .mlsetup: 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 question:

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 appearance is resolved, but not displayed (short glitch), the first thing you should do is to change the path in the mesh_entity.ent to one of the game's default meshes. This will rule out errors on your part. (Yes, even if your mesh worked in another mod. No, I'm not speaking from experience, why do you ask?)

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.

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.

By right-clicking on a tab title, you can move it to a new document group for easier copying.

Good luck, soldier.