Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Weapon, armour, consumable, hair, cyberware..
Welcome to the equipment section. Here, you can find guides on how to edit equipment and wepaons in Cyberpunk. The section is split into the following subsections:
This section contains hands-on guide for editing equipment.
If you want specific information (where is...), check here:
References, lists and overviews contains overviews, such as
We also have a section on 3d Modelling, where you can find specific knowledge on how to edit objects. For a detailed step-by-step guide, see R&R: Refitting (step by step).
For help about editing textures, see the Textures and LUTs section.
For general troubleshooting and help with Wolvenkit's interface, see
How do I change this item?
Created by @manavortex Published August 20 2023
If you just want to change the emissive colour, check R&R: Emissive
This will guide you to the process of making your own custom edit of my Netrunner Suits mod. It has several sections, which you can find linked below (but please check the wiki's navigation tree anyway).
The steps in this guide teach you how to recolour or refit almost every item in Cyberpunk. Keep reading!
Setup:
If Wolvenkit is already set up: ~ 5 - 30 minutes for MLSB
Full setup: 30 minutes to ~2 hours (most of which you can spend afk)
Recolouring: 5 minutes once you know how it works, < 1h to get there
Refits:
Import Export: 5 minutes once you know how it works, < 1h to get there
Actual refitting: as long as you fucking want >.<
If you are editing modded items, you should seek permission first. For your personal use, you can (legally) do what you want, but making mods takes time and effort.
Please respect mod creators' wishes in that regard.
You can check find the standard permissions on a mod's Nexus page, Description
tab, under the Permissions and Credit header right next to the requirements.
Do not skip or skim anything. Also, if you find a TL;DR block, this sums up all sections until the next header (in this case, until #overview).
I'm writing these guides with the minimal amount of fluff and no background information — that will be linked, but not included, which is the opposite approach from the rest of the internet and the Lord of the Rings.
The sections are annotated with a rough estimate of how long a total newbie would need. They're guesses, so if you're slightly off, don't worry. If you're wildly off, you might want to get in touch.
If you skip or skim in these guides, you will get in trouble. Unless a section's first paragraph offers you to read on somewhere else, do not skip. Don't skim and do ok it was something like this. You're supposed to stick to the road, where you won't run into monsters, and the guide will not tell you what to do if you encounter any.
The bright side of this approach is that you don't need to understand what you're doing as long as you do what the guide says.
You will find two kinds of links. It's usually clearly annotated which is which.1
The first will help you do something, leading to other guides on this wiki. They usually link the specific section that you need to complete. Please be thorough here as well, as the rules above apply.
The second contains background information and references (like "here's how this can look"). They are optional, you can browse or ignore them, and skim all you want.
To do this, you must have MLSetupBuilder running at least minimally. If you don't, then please complete the section "Step 0: Setup" below.
This guide will walk you through the following steps
Doing the necessary setup
If you already have MLSB working, please read #netrunner-suit-preview!
Creating a Wolvenkit project with the right files
Editing a colour variant of your choice in MLSB
Refitting the Netrunner suit to a different body
This section will link you to guides for installing Wolvenkit and MLSetupBuilder, which allows you to use the cool preview of which parts of an item you're colouring.
You will also be told how to download and extract the files for the #netrunner-suit-preview.
If you have done both, you can skip it and proceed with creating a Wolvenkit project.
Make a decision if you want to use these features independently of the Netrunner suit:
Yes: you need to configure MLSetupBuilder. Follow the steps on the linked list until you have a full depot, then proceed with #netrunner-suit-preview
If you can't set up a depot in MLSB (because computer go brr), you might want to hit up the Redmodding Discord to find help with your problem, or file an issue on github (Wolvenkit | MLSB). You can still use the #netrunner-suit-preview.
No: You have to options now. Please pick one.
Partial preview: I've prepared a bunch of files for you. #netrunner-suit-preview will show you where to put them.
No preview at all: This will make it harder because you're recolouring blind, but if you're cool with that, you can proceed with R&R: Your own Wolvenkit project.
In this step, we'll enable custom previews by downloading the files I've prepared and extracting them into MLSB's depot. It should take you no more than five minutes.
The Netrunner suit uses custom multilayer masks. To get an accurate preview in MLSetupBuilder, you need to complete this section.
You can make recolours blindly by just tweaking the colour values without knowing which parts of the mesh they affect, so you can skip this step and #install-the-mod,
This is where MLSB (and Wolvenkit) store the files they extracted.
Go to this Nexus page. You can find two files here, one with the modded multilayer masks, one with the original ones
Download the archive with the modded mlsetup
Extract the entire archive into MLSB's uncook folder, or drag and drop the base
folder from inside the archive there. You can find the path in MLSB's settings:
Open the Model Library and search for t0_005_pwa_body__t_bug
.
Click on the entry. If a 3d model shows up, you're done here and can go on.
If no model shows up, select View -> Logs from the taskbar. It will complain about files being in the wrong spot. You need to make sure that the files you downloaded in Step 1 end up in exactly these folders and none other. If the file paths are ending in .dds, open MLSB's preferences and configure it to use pngs instead.
The tutorial assumes that the mod is installed manually rather than via Vortex. If you have already done that, no sweat — it means that a few files might be in different places, and all this is annotated.
If you don't want the extra complication, simply deactivate the mod in Vortex and follow the steps below.
Extract the downloaded archive directly into your and go to the next section.
Download the mod from Nexus
Open the downloaded .zip file. You will see something like this:
These files need to go directly into your , where they will merge with the existing folders.
This is the same directory that contains REDprelauncher.exe
.
Extract or copy them to that folder. If you're asked to overwrite existing files, click Yes
.
I can't tell you exactly how to do that, because each program works slightly differently. I'll include instructions for 7zip, just in case:
Make sure that either nothing or everything is selected
Click the Extract
button in the taskbar (it looks like a blue minus)
Find the Copy To
field and do either of these things:
Paste the path to your into the field
Click the …
button next to the field, navigate to your and click OK
Click OK
If you get a Confirm File Replace
popup, click Yes to All
.
Optional, but recommended: Launch the game and make sure that the mod works:
Equip a suit in the Atelier Store's preview OR
Spawn one via Cyber Engine Tweaks and equip it (e.g. Game.AddToInventory("Items.mana_netrunner_suit_nylon_black_gold")
)
Now that you're all set up, we'll create a Wolvenkit project.
Created by @manavortex Published September 30 2023
This page is a part of the Recolours and Refit guide and will walk you through the process of creating your own Wolvenkit project. Here, we will:
create our project
solve load order via project name
get the files from the mod that we want to change
Time to complete:
~30 minutes for the tutorial
once you know how it works: < 5 minutes to create a project and add the correct files from a mod
his guide contains the minimal amount of fluff and will link background information rather than giving it. Any links will tell you which parts you're supposed to read — if they don't, you're free to ignore them.
For that reason, you shouldn't skip or skim unless the section tells you that it's optional.
The principles you learn here are universal. Once you have understood how this works, you can recolour and refit any Cyberpunk item.
If you are editing modded items, you should seek permission first. For your personal use, you can (legally) do what you want, but making mods takes time and effort.
Please respect mod creators' wishes in that regard.
You can check find the standard permissions on a mod's Nexus page, Description
tab, under the Permissions and Credit header right next to the requirements.
The checklist below will make sure that you're ready to go for the tutorial. The links in the description will tell you how to complete each step if you can't do it on your own yet.
To edit an appearance, you need to make a mod. For that, you need a Wolvenkit project.
Normally, you get an example project to download — but you already have all the necessary files, since you downloaded them from Nexus.
This guide will teach you how to change stuff without the original creator's help. It's easy!
There are two ways you can go about the process: do either a full repack of my mod, or create a compatibility archive. This section will explain the differences, the next one will walk you through the process of setting things up for either of those options.
Once you've made your decision, you can proceed to the next section and create your Wolvenkit project. If you aren't certain yet, you can keep reading to find the pros and cons listed more clearly.
Your mod completely overwrites the original mod, creating your own local copy.
I do this with mods for my own personal use — I don't care if the original mod is updated, my character will only ever wear that one custom variant.
Anything I do to the mod in the future won't affect you
Anything I do to the mod in the future won't affect you
If you update or reinstall the original mod, you will overwrite your changes
If you're anything like me, you'll lose track of which files you have or haven't modified
You'll create a compatibility mod that will exist together with the original.
I do this with mods where I only want to change little things, e.g. removing a submesh. When the original mod updates, I can update my compatibility mod in <5 minutes.
You can still update and reinstall the original without overwriting your changes
Your mod has only exactly those files that you've actually changed
You have to keep the original installed
Only works together with the original
Updates on the original mod might necessitate an update on your part
Your mod has to load before the original, so you need to fix load order. (This guide will tell you how)
This is where you decide for one of those options.
The .archive that Wolvenkit packs for you will have the same name as your project. Stick to the recommendations in Step 4, or read the expandable box to learn more.
From Wolvenkit's menu bar, select File -> New Project
Fill the fields in the dialogue:
Creation Location
: This is where your loose files are going to live. From here, Wkit can pack it as a mod and install it to your game directory.
Select any folder outside of your game directory.
Project Name
: The name of your project, and subsequently, the name of your .archive file.
If you want to overwrite: Name it the same as the original mod's .archive
(_ArchiveXL_Netrunner_Variants
)
If you want to patch: To maintain Load Order, your project needs to come before the original in ascii sort order. Pick any of the following:
_00_ArchiveXL_Netrunner_Variants
_ArchiveXL_00_Netrunner_Refit
_ArchiveXL_Netrunner_00_Variants
My personal preference is 2 and 3, as that will put the files next to the original mod.
This part will show you how to add files to your project (you can't change them if you don't).
You have installed the mod from Nexus.
Skip to #how-to-export-files if you don't care.
To alter an existing item, you need to create a mod that will overwrite the original resource. This mod must modify that file first - which is where the load order comes in.
Do not move or rename any of those files, they need to be exactly where Wolvenkit puts them.
The section
describes the process of #how-to-export-files
tells you which files to use it on for #selected-files-recolour #selected-files-refit
For the general documentation on adding files to your project, see here.
In Wolvenkit, open the Asset Browser (pinned at the right-hand side by default), and toggle the switch to "Mod Browser".
Find _ArchiveXL_Netrunner_Variants
, then click on it. It will be near the bottom of the list, together with your other mods starting with _
If you want to overwrite the complete mod, run this query in Wolvenkit's Mod Browser:
Add all files to the project — everything.
Now, switch the Project Explorer to Resources
. It will be empty; you have to create the following folder structure:
Find and copy the following files from your game directory into the subfolders of resources
(there'll be a screenshot in a minute)
From: Cyberpunk 2077\r6\tweaks\manavortex
To: resources\manavortex
From: Cyberpunk 2077\r6\scripts\manavortex
To: resources\r6\scripts\manavortex
From: either
vanilla install: Cyberpunk 2077\archive\pc\mod
REDmod: Cyberpunk 2077\mods\RANDOMNUMBER_ArchiveXL_Netrunner_variants\archives
To: resources
Add all those files to your project, then skip the rest of this page and go to R&R: Emissive
All material colour definitions are stored in .mlsetup
files, which we'll be editing in R&R: Colour Editing.
If you want to edit a file that is not part of High Fashion Netrunning Suits, you need to find it first.
If it is part of a different mod, see Analysing other mods and use that archive. You just need to adjust your search queries below.
If you want to modify base game items, you need to find their mesh (check Spawn Codes (BaseIDs/Hashes)). Once you have that, you can use "find used files" from the Asset Browser's context menu to find all .mlsetups, or you open the mesh in Wolvenkit to follow the material definition chain.
All material definitions in this mod are in the folder manavortex\torso\netrunning_suit\textures
The first level subfolders group the .mlsetup
files by material (e.g. nylon
, snake
, other
)
The texture files inside the folders are named like material_baseColor_accentColor
. Base colour and accent colour should correspond with the in-game suit name.
If there is a subfolder inside the material folder, the mlsetup
s inside are using the secondary mlmask
. That's not going to mean anything to you, but we'll get back to it on R&R: Colour Editing.
If the names aren't clear enough or if you can't guess which file you have to take, you can open netrunner_recolours_translation.json
in Wolvenkit:
Expand the root
node and then the entries
node. By selecting a node, you can see the translation text. The field for secondaryKey
contains the colour variant, which corresponds to the mlsetup file name:
For a refit, you only need two files (one if you don't care about the emissive properties):
Simply add both files to your project, then hit up the R&R: Refitting (step by step) section to get them fixed.
Depending on which files you added, you now proceed to the next guide:
R&R: Colour Editing / R&R: Emissive
How to change the Netrunner suit's glowey bits with ArchiveXL Dynamic Variants
~ 30 min tops for the tutorial
once you know how it works:
< 1 minute for .yaml edits
< 5 minutes for material edits
Most mod authors put the list of available appearances as a comment into the .yaml file — the line will be starting with a #
.
For the Netrunner suit, you can choose from the following emissive colours:
To change the emissive of an existing suit, you only need to change a text file. Find it in your game directory:
Change the current entry against one from the list above.
After your edit, make sure of the following things:
There is still a comma (,
) after the text you changed
There is still a colon (:
) in front of the text you changed
The line you changed still has the same number of leading spaces (indent). Only spaces at the beginning matter, anything else is just looking pretty.
Save the file and start the game.
If you did everything correctly, the emissive will now have a different colour.
If you made a spelling mistake (or selected the appearance off
), then the emissive will be gone.
If V is naked, then you fucked up (deleted the , or the :). In that case, remember that you can un-do the last change with Ctrl+Z
!
All the emissive materials live in .mi files. Inside the archive, they're bundled in this folder:
Each file will be named emissive_VARIANT
, (VARIANT
being the colour as listed in the table above). E.g., the file for the regular green emissive will be called emissive_green.mi
Open the file in Wolvenkit and check the values
array. You'll see something like this:
You can make changes in the panel on the right — feel free to experiment. You can make a copy first in case you break something, but even then, you can still install the original mod again and re-extract the file.
All emissive files use one of two templates:
manavortex\torso\netrunning_suit\textures\emissive\_emissive_glitch_base.mi
manavortex\torso\netrunning_suit\textures\emissive\_emissive_base.mi
If you are missing any properties, open the template and copy them from there.
Doing a custom recolor of the Netrunning suit
None of this is required for completing this guide, but if you're curious, you can poke around the wiki and learn a lot more about materials! Just follow the links and get lost... :)
<1h for the tutorial
< 5 minutes once you know how it works
If you can check all those boxes, let's go.
MLSetupBuilder can't directly edit game files. For that reason, we need to
export our .mlsetup
to an .mlsetup.json
edit that file via MLSetupBuilder
import it back
You can't skip any steps in this section that don't say otherwise.
Do not move any of the files. Wolvenkit will lose track of them if you move them around.
Getting the file into the tool, and opening the right preview
Now that you have added the right file(s) to your project, right-click on them or on their folder and select the option to export them as json:
Once you have done that, switch to your project browser's raw
tab, right-click on the first file, and select the option to open it in MLSetupBuilder:
This will open MLSB with the correct file already loaded.
Alternatively, you can also open MLSetupBuilder by hand, then press Ctrl+I
or select Import
from the menu.
Check if the .mlsetup that you want to edit is in a subfolder layer_mask_2
No: Search for t0_005_pwa_body__t_bug
Yes: Search for t0_001_wa_body__t_bug
Click on the entry that has no suffixes (_cuff
or _tight
) to load the model into the 3d viewport.
Close the library tab again.
Songbird's suit has a custom mlmask, which I've been too lazy to set up. Future MLSetupBuilder updates will support dynamic switching.
There will be a bunch of links in this section, which you can absolutely ignore. They'll lead you to look-up tables or extra theory.
If you are here to edit other mlsetups, you can skip this section
Click through the layer list on the left (1).
The Material
value (2) changes based on your layer selection, as will the available options
Change the colour by clicking on it in the Color Picker (3)
Click "Apply Edits", Hotkey: Ctrl+Shift+A
(4)
Repeat the process until you're satisfied
Now export the .mlsetup
(shortcut: Ctrl+E
).
Overwrite the file you imported (e.g. mirror_hex_black.mlsetup.json
)
This section tells you how to deal with custom materials. You can identify them by their broken preview icon.
Since I knew that I was going to share this, I've moved custom materials into a subfolder manavortex
in their original path.
To get the original color picker back, we'll need to change the path while you're editing the material, then put the original back when it's time for export. You do it like this:
Click into the material path (orange box)
Press Ctrl+A
to select the path.
Press Ctrl+C
to copy it. Paste it into a text document so that you can restore it later.
Find the subfolder manavortex\
in the path and delete it
If the name of the material is mirror_01_300
, change it to mirror_01_100
You now have a working colour palette and can edit the material.
When you're done, click into the material path again and restore the original value.
You can now export (ctrl+E)
Switch back to Wolvenkit.
Make sure that the Project Explorer shows either of the tabs source
or raw
Find the file that you just edited
Right-click on it and select the option to convert it from JSON:
Time to test! Install and launch your Wolvenkit project:
If you did everything right, your recolour will now be active.
You know how to read — if you can read and struggle with this guide, then it's not yet good enough. Please reach out to on the Redmodding Discord so that I can improve it.
: You need Wolvenkit on your computer, and you need to be able to start it. Follow the steps in the linked guide until you can open the program.
Follow the steps under until you reach Configure MLSetupBuilder
.
You have and configured
Once you have a Wolvenkit project, you can and see any changes you made become active right away.
Full Repack | Compatibility Archive | |
---|---|---|
You can now browse the archive, or use (next to the big red toggle button) to find files inside the archive by searching for archive:ArchiveXL_Netrunner
.
mesh | path in files |
---|---|
mesh | path in files |
---|---|
This page is a part of the and will tell you how to change the suits' emissive materials.
will show you how to swap between existing colours in the .yaml file.
The second section will show you how to .
Since ArchiveXL's feature is that cool, you can switch the emissive material simply by changing the property in the .yaml file.
This guide gives detailed instructions for how to change the , but the same principle applies for all items with dynamic appearances.
Static | Animated |
---|
Open it in a text editor such as , and find the list $instances
near the top of the file. It will look like this:
Unfortunately not! The mod author has to enable this feature via and split/colorize their meshes accordingly.
If a mod doesn't mention in the description that they support this feature, you can use the techniques under to make your own recolours anyway.
This section assumes that you can use Wolvenkit. If you have no idea about that yet, please check the first part of this guide: .
See on for how to extract the file.
If you're satisfied with your colour, it's time to test! Save your file, then your Wolvenkit project:
If you did everything right, your recolour will now be active. Otherwise, check .
This page is a subsection of the . It will teach you how to recolour Cyberpunk items via MLSetupBuilder.
Another guide:
Theory:
Theory:
You know how to read — if you can read and struggle with this guide, then it's not yet good enough. Please reach out to on the so that I can improve it.
You have either decided against a preview, or for the preview
You have a
You have from the original mod's .archive and added them to your project
If your material list is saying [object object], check the
If you don't care for this, you can skip to
Switch to MLSetupBuilder's .
An .mlsetup
is a list of 20 material definitions, which are projected on the 3d object like layers of paint. The is a list of 20 cut-out stencils, which block out parts of the layer. (You can see a live example by clicking through the list of layers in MLSB!)
If you want to know more, you can read up on the shader.
You have
Some suits are using custom materials, which MLSB isn't yet equipped to handle. You can identify them by the missing icon in the preview (see the screenshot below). For details on how to handle those, check below.
Change more .mlsetup files, or head to
If you don't have any of those in your .mlsetup or if you are just recolouring MlSetups independently from the Netrunner guide, then you can skip to
Otherwise, check .
Wolvenkit (short: WKit)
The Cyberpunk modding tool — this lets you browse files and pack your custom mod.
For recolours: MLSetupBuilder (short: MLSB)
>= 1.6.7 (most recent — see the wiki)
A plugin for Wolvenkit, installed from inside Wolvenkit. You need this to make recolours.
For refits: Blender
A fully-blown 3d editing software (free and open source). You only need this if you want to do refits.
For refits: Cyberpunk Blender IO suite
Optional, but recommended: the Blender plugin for integration with Wolvenkit
Needs original mod?
no, is a full replacement
yes
Can update original mod?
no — doing that will nuke your changes
yes
Needs load order?
No, replaces original mod
yes, needs to load before original mod
suit
manavortex\torso\netrunning_suit\meshes\pwa_netrunning_suit.mesh
emissive
manavortex\torso\netrunning_suit\meshes\pwa_emissive.mesh
suit
manavortex\torso\netrunning_suit\meshes\pma_netrunning_suit.mesh
emissive
manavortex\torso\netrunning_suit\meshes\pma_emissive.mesh
blue | glitch_blue |
green | glitch_green |
orange | glitch_orange |
pink | glitch_pink |
violet | glitch_violet |
turquoise | glitch_turquoise |
red | glitch_red |
white | glitch_white |
yellow | glitch_yellow |
gold (warm white) | glitch_gold (warm white) |
black | glitch_greenblue |
glitch_darkblue |
glitch_matrix |
off | glitch_redblack |
Irons, threads and everything else
This section contains guides how to alter or overwrite already existing items (please see the page tree in the navigation menu on the left).
If you want to look up Variants and appearances, find the corresponding page in References, lists and overviews.
The troubleshooting section for the Recolours & Refits guide
Created by @manavortex Published September 30 2023
This page is a part of the Recolours and Refit guide. It will
The troubleshooting steps below will be expanded as people follow this guide and run into problems. If you encounter anything not on the list,
make sure to double-check the guide — did you complete all required steps in the correct order?
find @manavortex on the REDmodding Discord, for example in #mod-dev-chat
You can check Archived: Exporting and importing meshes or seeTroubleshooting your mesh edits for general troubleshooting.
Export the target file again
Overwrite the exported file in your project's raw
folder with your changes
Import back
You can find tool-specific troubleshooting on MLSB's wiki page.
That's okay, you can still complete the guide without a full depot, or you can check MLSetupBuilder's wiki page for more instructions.
You either need to import garment support, or delete the parameters.
Step-by-step guide on refitting a mesh - for newbies!
This page is a subsection of the Netrunning Suit guide. It will teach you how to do custom refits in Blender.
< 1h for import, export and setup (< 5 min once you know how it works)
as long as you want on the actual editing
It's highly recommended that you grab the Wolvenkit Blender IO Suite, since the latest release has an auto-refitter for the most common body mods.
You're already supposed to have a project. If you don't, check R&R: Your own Wolvenkit project
First, you need the mesh of the body that you want to refit for. (Technically speaking, you could do without, so if you like suffering, go ahead and skip this step.)
There are two ways of acquiring the body mesh:
Check the Nexus page of the body mod you're using — there's a good chance that the modder is simply offering a resource that you cna import into Blender.
It might be easier and faster to simply export the base body.
Switch to the Mod Browser
In the Wolvenkit search bar, find the base body mesh:
Female body gender: base\characters\common\player_base_bodies\player_female_average\t0_000_pwa_base__full.mesh
Male body gender: base\characters\common\player_base_bodies\player_man_average\t0_000_pma_base__full.mesh
Check the preview to make sure that you're grabbing the right mesh, then add it to your project by double-clicking or via context menu.
In the Mod Browser, now search for the following files:
female body gender:
manavortex\torso\netrunning_suit\meshes\pwa_netrunning_suit.mesh
manavortex\torso\netrunning_suit\meshes\pwa_emissive.mesh
male body gender:
manavortex\torso\netrunning_suit\meshes\pma_netrunning_suit.mesh
manavortex\torso\netrunning_suit\meshes\pma_emissive.mesh
Add them to your project by double-clicking or via context menu.
If you don't want to use the emissive mesh, you can delete it now.
The whole process is explained here.
TL;DR:
Find "Export Tool"
Select the mesh(es) you want
Body
Netrunning Suit
optional: emissive submesh
Click Export button
In Wolvenkit, switch to the raw
folder (or scroll all the way down). Right-click on the glb file, and select "Open in File Explorer":
You will now see a Windows Explorer window. Copy the file path like this:
You might see the submesh and armature numbers changing through the guide. That is to keep you on your toes because I didn't take them in one setting, and also because they don't matter - any number from .001
to .999
will be removed on reimport with Wolvenkit.
Open Blender and create a new file. You will probably be greeted by a bunch of standard objects that we need to get rid of:
Now, let's import our meshes.
From the "File" menu, select "Import" and then one of the entries for "gltf":
You will now see a file picker.
In the path bar at the top, paste the path from the previous step.
Select the mesh(es) that you want to refit, and import them
Now, repeat the process with the body mesh. If you don't know where it is, you can find it here (..
means that you need to co up a directory from the one with the netrunning suits):
..\..\..\..\base\characters\common\player_base_bodies\player_female_average\t0_000_pwa_base__full.glb
If you have imported without the plugin, you will see something like this and need to hide the armatures. If you have imported with the plugin, it will already have done that for you.
You are currently in Object Mode, which will let you select whole objects.
Optional, but recommended: change the colour of the body mesh to better see clipping (see the next screenshot for details):
Click on the body mesh, or find it in the Scene Collection under its armature parent, and select it there.
Select the "Material Properties" tab in the right sidebar (a round red icon near the bottom at the list)
Click on "Use Nodes" to uncheck it
Set a base colour that is not white to see clipping
Starting in version 1.5.0, the Wolvenkit Blender IO Suite features an auto-refitter, which supports many custom bodies and will be expanded in the future.
If you want to use the plugin instead of refitting by hand, make sure to select all meshes (Step 1 on the list below) before following the instructions underWKit Blender Plugin: AKL Autofitter.
We will use the Proportional Editing mode here, which leaves garment supports intact and prevents the risk of string cheese. If you don't vibe with that, you can read up here on other approaches for refitting, or refer to the community guides section.
While still in Object Mode
, expand both armatures (not the one with the body) and select all included meshes.
Switch into Edit Mode by hitting Tab or selecting it from the dropdown at the topleft
Turn on "Proportional Editing" by checking the round button at the top of the viewport and select a low Proportional Size like 0.1m at the bottom of the drop-down menu next to it.
Hide the body mesh by shift-clicking on the body armature's eye icon twice: it's in the way, and we need to select some vertices.
Make a selection — somewhere close to the future highest point.
Show the body mesh again:
Shift-click on the eye icon next to the body armature to show everything
left-click on the eye icon (no shift, just a regular click) to hide only the armature)
We will use scaling (shortcut: S
) and movement (shortcut: G
).
You can lock the axis on which you are moving by pressing X
, Y
or Z
You can scale the strength of the proportional modifier by using the mouse wheel — but only after you have a tool selected.
I'm afraid that this is where you draw the rest of the owl - you need to refit the suit. Try playing around with the settings. For example, you can start by pressing G
- Y
to let out the chest, then try scaling.
Do this until you have covered all skin that you don't want exposed. Now it's time to export our edited meshes, and import them back.
Pro tip: Keep the .blend file open until you have seen the refit in action. It's quite likely that it still clips somewhere and that you'll have to get active again.
Switch back to Object mode by pressing Tab
select all meshes under one armature (e.g. the emissive meshes)
If you are exporting without the Wolvenkit Plugin, select the armature as well.
From the menu, select File -> Export
Overwrite the file you originally imported from (pwa_emissive.glb
)
Repeat the process with the other armature.
As of 8.9.1, Garment Support is still experimental. If your meshes look like string cheese or twitch all over the place, you can delete the parameters. That will destroy the automatic deform when you put a jacket on, but at least your mesh will work.
In the Import Tool, select the first file that you want to import, then check the Import Garment Support
box.
Do the same for the second mesh and the emissive components.
Import both glb files.
Time to test! Install and launch your Wolvenkit project:
If you did everything right, your refit will now be active. If not, it's troubleshooting time.
Check the Export/Import guide for step-by-step instructions
If anything is wrong with your mesh, head to Troubleshooting your mesh edits
Check R&R: Troubleshooting for tutorial-specific issues
Otherwise:
Happy modding, choomba!
You can find the general troubleshooting for 3d edits and -imports under Troubleshooting your mesh edits.
Make sure that you switch the Viewport in Blender to Viewport Shading (the third globe in the topright corner)
File paths are which files belong together. If you have moved files, do this:
You know how to read — if you can read and struggle with this guide, then it's not yet good enough. Please reach out to on Discord so that I can improve it.
Anything else: Check this list or go hunting - here's the !
then you need to uncheck Export With Materials
in the export tool's .
Changing how an item looks in-game
Created by @manavortex Published November 05 2022
This guide will teach you how to change an item's appearance by editing its MultilayerSetup (*.mlsetup file), how to rename materials, and how add your own mlsetups (custompathing).
For a step-by-step walkthrough for a recolour of the Netrunner suit, check R&R: Colour Editing
If you want to edit emissive (glowing) material, check R&R: Emissive -> #changing-the-presets
It uses the following versions:
MLSetupBuilder >= 1.6.7 (get the latest release)
Most items in Cyberpunk are not textured, but use a procedurally generated material consisting out of an mlmask (a list of alpha masks) and an mlsetup (a list of material paths and -colours). There is a section on the exceptions below.
If you want to learn how mesh material assignment works in general, you can check the corresponding page.
For an overview of base materials and example files, you can check here.
If your changes do not become active, you will want to install Material and Texture Override from Nexus.
Please keep in mind that video guides might be outdated, as they are much more difficult to update than a wiki page. Refer to the written guide below if you run into any troubles!
This tutorial assumes that you already know which mesh and appearance you want to change. If you don't know that, you need to find the correct game file. If you only have a cheat code, see Spawn Codes instead.
We will use the female variant of the puffy vest (as I've already mapped and documented it):
Add the item to your project and open it in WolvenKit. You want the original to look up material names, even if you overwrite it with your own mesh.
We will change the appearance bwstripes
, which is used by Vest_17_basic_01
:
chunkMaterials
corresponds to the chunkMasks
: For submesh_00, the material at array position 0 will be used, for submesh_01 the material at position 1, and so on.
This vest has only one chunkMask, so there's only one material.
Remember its name (ml_t2_002_ma_vest__puffy_bwstripes
) and find the corresponding material definition:
Most meshes have their materials under localMaterialBuffer/materials
. However, some of them (especially those with physics) use preloadLocalMaterialInstances
instead.
You will (hopefully) see a material with three entries in values
(order doesn't matter):
For the purpose of this guide, all that matters is the mlsetup, which determines all the individual material assignments in this CMaterial. For an explanation of the shader, check here.
If you have your own mlsetup file, this is where you need to set tohe path. See custompathing for further details.
Most materials in Cyberpunk use the engine\materials\multilayered.mt
material and assign colours via an .mlsetup file. If you're used to textures, you are probably going to hate this. As somebody who has been where you are: the mlsetup system is cool. Genuinely. Give it a chance!
If you would rather use a textured material, check here.
A multilayered material consists of multiple layers of materials, projected on the mesh through the mlmask: white parts get affected, black parts are blocked out. (Again, for a full explanation, check here).
You can turn any multilayered material into its cyberspace variant by changing the material from engine\materials\multilayered.mt
to base\characters\common\cyberspace\silverhand_overlay_cyberspace_mml.mi
We're going to edit the mlsetup file and then import it back, causing a global change in the appearances of every item which uses this particular material file. (If you don't want that, see Custompathing below).
We do that by editing the MultilayerSetup. Check the MLSetupBuilder wiki page for how to do that.
Add it to your Wolvenkit project.
If you don't have MLSetupBuilder installed, you need to do that now. If you don't know how to use it, please check #using-mlsb
For a documentation of multilayer properties, see here. For a list of reference images, check Multilayered: Previews
Export the file, overwriting the original .mlsetup.json
Switch back to Wolvenkit
Right-click on the .mlsetup.json
and import it from json.
This is already working. You can pack the project and see it in action!
Since you haven't changed anything in the mesh itself, you can (and should) delete it from your mod. Only keep it if you want to do the steps below.
If you want to put up your own .mlsetup, rather than overwriting the original one, you can do that. All you have to do is changing the DepotPaths to the relative path of your mlsetup.
Keep your folder and file names unique! If you have two mods adding a file at the same location, the second one will be unable to overwrite it and will use the first mod's file. That is, unless your mods are in REDmod format, which will be loaded even later and in order of their folder names.
Understood? No? That's fine. Just keep it unique. :D
You can rename a material by changing the "name" property inside the CMeshMaterialEntry
in the materials
array:
Inside the appearances block, the material assignment to the individual submeshes happens by name, so don't forget to change the chunkMaterial
names!
To add a new material to a mesh, you need to create two entries. The first of those needs to be in the materialEntries array:
Now, add an entry in the localMaterialBuffer.
If your mesh doesn#t have entries under localMaterialBuffer
, use preloadLocalMaterialInstances
instead.
You can now use your new material just like the regular, old materials.
How to add decals to existing items
This guide will teach you how to add decals to existing items.
It will walk you through the following:
#step-1-cutting-the-decal-mesh
Adding it to the mesh entity
Setting up the material
Any links will lead to extra information and are not required to complete this guide.
To add new items to the game, check Adding new items
To learn about materials, check the Shaders section or follow the links from there.
This guide assumes that you have an existing Wolvenkit project with your item and just want to add the decal mesh. If you don't have one, you can grab the template project from ItemAdditions: Dynamic Appearances.
You should have an .xbm texture inside your Wolvenkit project for your decal, and a .png export of the decal that we'll use in Blender. If you don't have a texture, you can
copy any .xbm
Replace this png with your decal
import the png again (premultiplyAlpha
must be checked)
For this guide, I will be using a sock mesh.
Start by exporting your mesh from Wolvenkit and importing it into Blender. You should see something like this:
In the viewport, click on the submesh that you want to have the decal.
If you want it to span multiple submeshes, you should merge them into one submesh to cut from. Shift-click to select them all, then duplicate them (Hotkey: Shift-D
) and join them together (Hotkey: Ctrl+J
).
Switch to Edit Mode (shortcut: Tab
)
Turn the viewport to the side (shortcut: Numpad 3
)
Turn on X-Ray mode (shortcut: Alt+Z
). This lets you select right through the mesh, in my example, on both sides of the leg.
Use the selection tool (shortcut: W
, it should be active) to select your decal mesh. It should look something like the left side of the screenshot below.
We will refine this later — select generously, too much is a lot better than too little!
Duplicate these vertices (Shortcut: Shift+D
)
Split them into a new submesh or new submeshes (Shortcut: P
-> Selection)
You should now have something like the right half of the screenshot.
This guide will add a new chunk to an already-existing mesh.
For more advanced cases (such as use with dynamic variants), you can split off the decal into its own file, or you can use an extra appearance that will hide all other submeshes.
If this is your first rodeo, do not do any of that.
If you take a look at the outliner, you will notice a new submesh in the scene collection. This is your decal mesh. We need to change its name to register it as a new chunk.
Switch back to Object Mode (Hotkey: Tab
)
In the Outliner, click on your meshes until your decal mesh lights up
Change the name: it needs to be the submesh with the highest number (see the red box in the screenshot below). Double-click the name, then change it to (in this example)submesh_04_LOD_1
.
Depending on your mesh, you will end up with a different number than 4!
With your new submesh selected, it's now time to clean up.
Switch back to Edit Mode (Hotkey: Tab
)
Cut away all vertices that you don't need. (Hotkey: X
)
As the decal shader supports transparency, you can be generous here as well. Having too much is better than having too little!
After cutting away everything that you don't want/need as part of your decal, select the rest (Hotkey: A
)
The decal should be one piece, so let's make sure to merge by distance now (hotkey: M
).
Now, let's make sure that our decal is above the surface of the original mesh by using the Shrinkwrap Modifier
.
I'll show you how to do this in a way that preserves potential garment support. If you run into issues with your decal mesh (being invisible or crooked), you can always delete it later.
Switch back to Object Mode (Hotkey: Tab
)
Duplicate your mesh (Hotkey: Shift+D
)
Select just one of the two meshes, and switch to the Data tab
Delete all shapekeys (starting at the bottom).
If your mesh doesn't have any, you can skip step 13 and delete your extra duplicate.
Now, switch to the Modifiers
tab. Leave the Armature modifier alone.
Add a Shrinkwrap
Modifier (Deform -> Shrinkwrap).
Configure it. Try the standard parameters below — if you have clipping, you can play around with the modifier after.
target
: The mesh you originally cut from (you can use the eyedropper symbol)
Wrap Method
: Select Nearest Vertex
Offset
: 0.0005 m
(sometimes it's necessary to increase it to something like 0.002 m
)
Your decal should be floating directly on the surface of your mesh, with just enough offset that it's not clipping. When you're satisfied, apply the shrinkwrap modifier:
Now let's merge it with the original submesh with the garment support. Select the duplicate that you made in Step 6.
Switch to Edit Mode (Hotkey: Tab
)
Select all vertices (Hotkey: A
)
Delete them (Hotkey: X)
Switch back to Object Mode (Hotkey: Tab
)
First, select your decal mesh (with the offsets) by clicking on it in the Outliner
Second, select your empty mesh (with the shapekeys) by shift-clicking on it in the Outliner
Now, join them together (Hotkey: Ctrl+J
)
You now have a decal mesh with an offset and garment support shapekeys. Awesome! Let's take care of the material now.
With your new submesh selected in Object Mode, switch to the Shading perspective. Delete the existing material assignment and create a new material:
Click the X above the node browser to delete the existing material assignment
Create a new material
In the node browser, add a new image texture (Hotkey: Shift+A, Texture -> Image Texture)
Click on "open" in the orange node and point the path to your decal png
Drag-and-drop the "Color" dot on the orange box to the "Base Color" dot on the green one
If your mesh's surface hasn't changed yet, you need to assign the material:
Open the Material tab
Switch to Edit mode (Hotkey: Tab
)
Select all vertices (Hotkey: A
)
Assign them to your new material
For more information on this, check UV Mapping: texturing a 3d object (but the page will only send you back here).
Our decal is now showing our new material. Make sure that it has exactly one UV map by checking the Data
tab:
Time to change to the UV Editing
perspective. You should be in Edit Mode (Hotkey: Tab
if not) and have all pixels of your decal mesh selected (Hotkey: A
if not).
You will see something like this (to learn more about UV maps, look up our theory page):
We will now unwrap our decal. I'll do both UV islands at once - if you have only one (because your decal is on a jacket or something), then your life will be easier.
You should be unwrapping a roughly rectangular 2d surface that has undergone merge by distance
. If you haven't done that yet, refer to Step 3, item 4 — or read up on UV seams.
With everything selected in the UV Editor
on the left, select UV -> Unwrap -> Unwrap (Hotkey: Ctrl+U
)
This will unwrap the mesh. Hopefully, you get nice and clean UV islands. If not, you may have to play puzzle
I'll show you a simple example of doing it by hand. If you want anything more complex, you should hit up Google, as there are plenty of best practices and even Blender add-ons.
At the end, we want a nice and straight grid over the full width and height of the decal, with the correct orientation. Let's start by fixing up the UV islands.
Select a row or column. From the right-click menu, select one of the following:
Straighten
: Will put them all in a line
Align Auto
, which does one of the following:
Align Horizontally
: Will put them all on the same Y-axis
Align Vertically:
Will put them all on the same X-axis
Keep doing that until you have a nice grid.
While straightening out your UV layout, keep an eye on your decal in the viewport on the right. Sometimes, vertices need to be crooked, or your mapping will look like shit.
If you can't get a grip on your OCD, you can shift vertices over the mesh's surface by clicking on them, then pressing G
twice and sliding them along the edges.
If you have multiple UV islands, you can move them on top of each other.
Make sure to keep a little offset between the vertices, because Blender's glb export does not play nice with shared UV coordinates — it will split your mesh into a million individual triangles.
If you need an exact identical layout, know that the UV mapping tiles infinitely, so you can simply select one of the islands and move it by a full tile in any direction (G -> X -> 1)
Check the individual decals in your viewport and fix up any that are flipped/rotated:
Click on a vertex in the viewport
Select linked (Hotkey: Ctrl+L
)
Fix the UV mapping (Right-click: Flip horizontal/vertical, or rotate)
When you are done, export your mesh from Blender to glb. Include all submeshes.
Now it's time to head back to Wolvenkit and activate our new decal chunk.
This guide will add a new chunk to an already-existing mesh.
For more advanced cases (such as use with dynamic variants), you can split off the decal into its own file, or you can use an extra appearance that will hide all other submeshes.
If this is your first rodeo, do not do any of that.
After successfully importing your new submesh into Wolvenkit and open it.
First, we need to add your new chunk to each of your appearances. For this example, we will use the material decal
.
Find the appearances
array at the top of the file and expand it.
Under each appearance, find the chunkMaterials
array and expand it.
If you already have an entry for your new submesh, change its value to decal
. If you don't, right-click on the last entry to duplciate it. You should now have something like this:
If you save your mesh now, file validation will complain that the decal
material doesn't exist. It's right; we haven't added a material definition yet. Let's do that.
Find the materialEntries
array inside your mesh and duplicate the last entry
Change its name
to decal
Make sure that isLocalInstance
is checked
Increment its index
by one (e.g. 29 -> 30)
Now that our chunk knows which material it's supposed to look up, we need to provide the actual material.
Find the array localMaterialBuffer
Find the array materials
(directly underneath)
If it's empty, go back up and find preloadMaterialBuffer
instead
Duplicate the last entry. This is your new decal material. Now we need to make sure it behaves like a decal, too.
Change its baseMaterial to base\materials\mesh_decal.mt
.
This will tell the game which shader to use, and mesh_decal is for exactly this.
As of now, your decal will be completely transparent. Let's change that.
Now we need to get the right material properties. The easiest way is to find another material that uses mesh_decal and steal them from there:
Sort the results by file type by clicking on the column, then find and open a .mi
or .mesh
Switch back to your own mesh and copy these values into your mesh_decal material's values
array (the one from step 3.3)
If you don't have one, go back to #prerequisites -> #the-rest
The other properties should be numbers only. If you don't know what they do, you can delete them for now.
See Textures: Importing, editing, exporting -> #troubleshooting
See Troubleshooting your mesh edits
PartsOverrides, visual tags, and how to use them
This guide will explain how to influence meshes by directly in the .app file, overriding whatever is defined for the components in the .ent file which loads them.
Cyberpunk 2077 uses a clever system to layer clothes on top of each other while minimizing clipping. It's called GarmentSupport, and as of 2024, it's almost completely functional.
Where partsValues lets you define the individual entity files that you'll load, partsOverrides lets you assign properties which take precedence over those defined in the .ent file:
Components need to be unambiguously identified by their name as defined in the .ent file. For that reason, it's good practice to have globally unique identifiers.
Due to cyberware, V has more arms than Shiva the Destroyer (although not at the same time). Arms are why we can't have nice things.
The player base body component name is
Normally, you can override only components from .ent files that you include via partsValues in the same appearance. ArchiveXL expands this by letting you manipulate any components that are loaded as part of the player.ent:
To delete an already existing reference, set the numeric value to the right of the depot path to 0:
This mechanism is how e.g. your sunglasses disappear when you put on a helmet.
Visual tags in the root entity will get applied to every appearance in the app.
How to make it iconic
This guide will show you an example for adding a modifier to an existing game item; in this case, making David's jacket iconic.
It will point you towards further reading material in case you want to dig deeper.
Paste the following contents into the text document and save it:
That's it. When you start the game now, the item's quality will be iconic.
You created a tweak edit.
If you want to safely delete a record property, set its value to None. For example:
You might not want to actually do it.
The example below might have all sorts of unintended side effects, as David's jacket is not a cyberdeck:
Put your item in place of a default game item. Supports variants.
Created by @manavortex Published November 05 2022 Updated Feb 28 2024
This tutorial will teach you how to switch a player mesh for an NPC garment and map its variants to the existing colours.
Other relevant know-how for this process (you don't need to read them if you already know which item you want to replace):
Perquisite: You need a Wolvenkit project.
Find the mesh that you want to use ("the old mesh") and replace it with the one that you want to switch in ("the new mesh").
Example: Replacing the short-sleeved poser jacket with the monk shirt with the tied-back sleeves.​ For the male variant, replace _pwa_
with _pma
_ and _wa_
with _ma_
.
Find both files in the Asset Browser and add them to your project.
Move the replacement mesh to the original mesh's folder.
Rename the old mesh (e.g. "t2_084_pwa__short_sleeves.mesh
" -> "original.mesh
").
Rename the new mesh to replace the old mesh (e.g. "t2_135_wa_jacket__monk_shirt.mesh
" -> "t2_084_pwa__short_sleeves.mesh
")
Open both meshes in WolvenKit by double-clicking them in the Project Explorer — we will now transfer the appearance names to enable variants.
The game looks up appearances in a mesh file by name. If none can be found, then game meshes will fall back to the default
appearance, which is how the early replacers worked — every variant (base_01, old_01, rich_01) would simply spawn the default appearance.
We can simply transfer the names from the old mesh to the new mesh by renaming the entries in the appearances array.
Now that we have done that, we can start recolouring.
Each appearance in the appearances array has a list of chunkMask entries (one per submesh), which are assigned a material by name.
You can now save your mesh, then install your mod by clicking on the green arrow in Wolvenkit's toolbar. Once you have started up the game, the old item will now look like your new mesh — including its variants.
Enjoy!
Replace your clothes with an NPC's that requires blender editing.
This tutorial will teach you how to swap player's clothing items with NPC's that requires blender editing.
Without mesh editing, some NPC meshes will clip quite badly, because they don't have as many poses and animations as V. Some are even worse, since they'll be flying around rather than following V's movements.
Prerequisite: you have the mesh that you want to fix already in your project. For this tutorial, we'll want Maman Brigitte's jacket: t2_001_wa_jacket__maman_brigitte.mesh
For female body gender, search for _pwa_
For male body gender, search for _pma_
Open Blender
delete the standard objects from the scene (Shortcut: A -> X)
Import the player mesh (File -> Import -> Cyberpunk GLTF)
Import the NPC mesh
Delete or hide the NPC item's armature
Delete the NPC item's armature modifier (or make sure that it points at the player item's armature)
Repeat the process for each submesh.
If you don't have the same number of submeshes, you can simply use the "biggest" mesh you have (e.g. the coat's base mesh rather than the seams)
Select the player item's mesh
Select the NPC item's mesh
Switch to Weight Paint mode in the dropdown on the top left of your viewport
Select "Transfer Weights". Use the settings from the second screenshot.
Make sure that the NPC mesh's armature modifier is targeting the player armature:
Make sure that you select Object Mode while adding modifiers.
Select all submeshes under the NPC's armature
Use the Wolvenkit Blender plugin to export them over the player item's mesh (overwrite it)
Switch to Wolvenkit
Import the player item's mesh via Import Tool
Optional: copy the NPC's appearances, materials and material definitions to the player mesh
Optional: rename the appearances to match those in the original player item
Sometimes you will need to do a bit more of editing but that is not a topic for this tutorial.
Now you have functional clothing attached to the player and not flying arround.
Key | Value (DepotPath) |
---|---|
Find the file that you want to edit in the .
In the project explorer under Wolvenkit's archive
folder, right-click on am mlsetup
file
This folder will only be visible in the "source" or "archive" tab of your
Select ""
Optional: If you don't see an mlsetup.json
in your project, switch the to source
or raw
.
Right-click on the file and .
Published: Jan 21 2024 by Last documented update: Jan 21 2024 by
Tool/Software | Version |
---|---|
Unless your previous material was already using mesh_decal, right-click on the values
array and
Open the and search for base\materials\mesh_decal.mt
Right-click on the file and select
Find the decal material inside the other file, and
Adjust the properties. Find the one that says DiffuseTexture
and point its DepotPath
to your decal's .xbm
(right-click it and select )
. If you have done everything right, then your mesh should now have a decal!
Published: November 12 2022 by Last documented update: January 21 2024 by
This page will teach you how your clothing can influence other clothing items, for example hiding the sleeves under a jacket. You have to do this manually for every item that you want to affect, a much better way to address the problem is the game's system.
For even further customization options for wardrobe items, see 's readme.
To use it with your clothing item, you need to change the component names to use the right prefixes. Check the section on for details.
To learn how to hide things via PartsOverrides, check
You can't use PartsOverrides on components defined in the same .app file. Either use components from other files, or load them
In the .app file, each appearance lets you define , which — as the name implies — let you override previously defined components. An entry looks as follows:
You can make use of for your components.
You can find arm component names on -> . Alternatively, you can browse the corresponding entity files in the by base\characters\common\player_base_bodies > .ent
, the file names will start with a0_.
These can be used in addition to PartsOverrides and will let you influence your item even further. To learn more about , read .
However: Due to technical limitations, any visual tags that hide parts of the mesh must go into the .app file to take effect. will warn you about this.
The following tags are used by the base game; however, to make use of them, you require .
With visual tags, you can force-show hair, hide an item in first person, or turn body parts on and off. Find the full list under
If you want to un-hide chunks rather than hiding them, you need to define a custom tag via ArchiveXL. See for details.
Published: Jan 29 2024 by Last documented update: May 04 2024 by
Find . Then, create the following text document (you can name it what you want):
To add attachment slots to an item, simply and append it to your item's slotPartList
.
For a guide how to import meshes into Cyberpunk, check .
Make sure that you replace an item that you can actually spawn — not all items in V's folder are actually spawn-able =>
If there are more entries than variants available, or if you're just curious which spawn code corresponds to which appearance, go for a guide how to find out.
For a full guide on , follow the link (you don't have to).
For a more detailed explanation, you can check , but all we care about right now is this lookup chain:
For a guide on how to edit an .mlsetup file (or to change an item's appearance in general), see .
This tutorial will not cover changing materials and appearances from an NPC's mesh to player's. For that, visit the tutorial . To add an item rather than replacing one, see .
In this guide, we'll fix up a coat by transferring weights from a different item. Prerequisites: - - - Wolvenkit
Use the to find a player mesh of roughly the same size/length/cut. For this tutorial, we'll use River's coat:
t2_087_pwa_jacket__river_short
Add it to
both meshes
and test it!
If you don't know how to import meshes, visit this
For adding appearances and materials, visit this
If you have any questions about modding join server and we will help you out.
MultilayerSetup
base\characters\garment\citizen_casual\torso\t2_002_vest__puffy\textures\ml_t2_002_ma_vest__puffy_bwstripes.mlsetup
MultilayerMask
base\characters\garment\citizen_casual\torso\t2_002_vest__puffy\textures\ml_t2_002_ma_vest__puffy_default.mlmask
GlobalNormal
base\characters\garment\citizen_casual\torso\t2_002_vest__puffy\textures\t2_002_ma_vest__puffy_n01.xbm
>= 8.12 for Cyberpunk 2.1
>= 4.0
the most recent one, but at least 1.5.2.2
the old mesh |
|
the new mesh |
|
How to determine the item type
Created by @manavortex Published June 10 2023
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.
TL;DR:
Change equipmentSlot
in the yaml (for options, see Step 1)
Replace the mesh_entity
(see Step 2)
Replace the .mesh
(e.g., instead of a shirt, find in-game shoes)
Optional: Port an external item
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.
You can use the following base types:
You can absolutely set up a shirt and then put $base: Items.GenericHeadClothing
- V is the only person I know of who can wear their undies on their head without impairing their functionality.
However, before you start abusing the system that way, you might want to look into 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:
Find a full list of outfit slots in the github readme.
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
If you want to know more about components, check the wiki page. This is completely unnecessary for the purpose of this guide!
You can hide items most easily via ArchiveXL tag. Check the linked page for how to do that.
If you don't want your new boots to sound as if V was barefoot, add one of the following tags to the #root-entity:
How to set up the folder structure from scratch
Created by @manavortex Updated 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
TL;DR: If you can't be arsed doing this by yourself, find a template project with one working item (female rigged) here.
For mesh_entity.ent,
your entity file needs to correspond to your item's body part. If you put a shirt in an entity file for shoes, it will deform badly once you put it on.
If you rename your components, we recommend using CDPR's naming prefixes for reasons of garmentSupport. You don't need to understand how this works, just name your component like l1_myCustomPants
instead of myCustomPants
and call it a day.
For further details, check here.
It is good practice to keep local copies of everything that you change (=> custompathing
) instead of overwriting files under base
. This makes sure that no other mods will overwrite your changes.
ℹ Only keep files under base
if you are okay with them being overwritten!
Open the file translation_strings.json
in WolvenKit.
Expand the array root
and then the array entries
. Delete all entries but one.
Open the file my_shirt_factory.csv
in WolvenKit.
In compiledData
, delete all entries but one. In data
, delete everything - these will get autogenerated.
Open the file root_entity.ent
.
Expand the list appearances
. Delete all entries but the first (most likely default
).
Open the file my_custom_shirt.app
.
Expand the list appearances
. Delete all entries but default
.
Open the file mesh_entity.ent
Select resolvedDependencies
and delete all the entries. (We don't need Judy's top anymore.)
Make a back-up copy of your t1_custom_shirt.mesh
, then open it.
Expand the first appearances
at the top of the file. Open the appearance default
and check which material is linked in the chunkMaterials
array.
Now is a good time for a backup.
An item addition with dynamic appearances, and what you can do for this
Created by @manavortex Published: 29 Oct. 2023
This guide will cover a sub-case of Adding new itemsvia ArchiveXL. Dynamic variants are both easier and more flexible. Unless you don't need different appearances, you will want to default to this approach.
Since 1.13, there is now support for ArchiveXL: dynamic materials. Unless you're a beginner, check it out, this is awesome!
It uses the following versions (yours should be equal or higher, the most recent stable release works fine)
TweakXL >= 1.4.4 (the most recent version)
ArchiveXL >= 1.5.0 (the most recent version)
Red4ext >= 1.17.0 (the most recent version)
Cyber Engine Tweaks (for spawning items)
You can find the technical documentation for dynamic variants on ArchiveXL's github.
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.
TL;DR: It just is, source: trust me bro. Proceed to the next section.
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!
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
This guide assumes that you have access to the prepared example project, so go and grab it.
Find the template project on Nexus.
Download it and extract the files to your project's root folder, so that the source
directory merges with the existing one.
You will be able to change the template project just by following the steps, but if you want to make your own mods, then you're going to want to understand this.
Depending on how you learn best, you can also fuck around and try to understand the connections yourself. In that case, check #exercise-1-create-more-records at the end of the section.
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 file contains the biggest part of the dynamic magic.
This is your dynamic project's yaml file, minus any properties that aren't influenced by the dynamic appearances:
This section will explain how that works - except for the appearanceName, you will find that in #the-root_entity.
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.
Like the record names, the displayName
property is also generated for each entry:
All you need to do is to make sure that such an entry exists in your localization file.
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.
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
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!
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.
This is where you enable the feature by adding the tag DynamicAppearance
to the visualTagsSchema
(the last entry in the file):
For dynamic appearances, your root_entity
file will contain one entry. Each item should have its own 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.
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.
For dynamic variants, components in the .app file will be ignored. You have to use a mesh entity.
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:
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.
Unless you are using #app-file-conditional-switching, this is where the magic happens.
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.
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
ArchiveXL will create all components, hiding those that aren't matched by your current conditions. If possible, use #substitutions instead.
Just like in the .app file, you can apply conditional switching to component names. It works exactly like #app-file-conditional-switching:
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!
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.
Please see the original guide's #troubleshootingsection.
No more replacers! Add your own gear with TweakXL and ArchiveXL
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 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.
This guide will teach you the basic structure - after you have done that, take a look at the guide for ItemAdditions: Dynamic Appearances for how to easily make many colour variants.
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.
There is a new way of connecting your files: ItemAdditions: Dynamic Appearances. If you want to create lots of options, this is what you want to do.
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)
If you would rather start from scratch: Check the detailed instructions here.
Understanding of the file structure is not required as long as you follow the guide to the letter, but if you want it anyway, see the item structure explained sub-page.
âš Do not edit those files outside of WolvenKit, and whatever you do, do not let Microsoft Excel touch the clothing.csv! âš
Wait, am I not supposed to do anything first??
Actually, no! This is how you later debug your custom items — by packing your project and checking that everything works in-game. So we're starting with a dry run here.
Wipe the folder packed
Copy all supported file entries from source
to their destination under packed
Copy all files under packed
into your game directory (it will overwrite without prompting)
Now, you can
Launch the game.
Spawn one of the tutorial items via Cyber Engine Tweaks:
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 that everything works before proceeding to the step below.
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.
To start changing the existing files, check the ItemAdditions: File structure explained page for "Making Changes
" headers.
Otherwise, you will want to complete one or more of the following steps:
If you want to create more appearances or use variants (e.g. for different body genders or camera prefixes), you want to check out ItemAdditions: Dynamic Appearances. Do yourself a favour!
There is no exact migration guide yet. Maybe you'd like to write one?
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 Atelier Store
Learn about Porting 3d objects to Cyberpunk
This is how everything connects. Looks pretty scary, but is actually simple: whenever you want to rename or something, make sure that you catch both ends of the connecting lines.
You can find a breakdown-by-entry on the corresponding wiki page.
With ArchiveXL >= 1.5, there is a new way of making these connections, saving most of the work of making many variants. You can still complete this guide and then see the documentation for dynamic loading on its own page.
If you want to do more than 5 variants (for both body genders and camera modes), that approach is strongly recommended. Since there isn't a detailed guide yet, you can find us on Discord in the #archive-xl channel.
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:
*.yaml: Adding an entry
appearance.app: Adding a mapping between root_entity and mesh's appearance
root_entity.ent: Adding a mapping between yaml's appearance and app's appearance
*.mesh:
Adding a MeshMaterialEntry
Adding a MaterialInstance
Adding a material
Connecting those things
For a diagram of how everything connects, go here.
Duplicate the entire appearance block for an already working item. âš Mind the indent!
Change the first line to a unique name like Items.my_custom_shirt_blueblack
Set the new appearance name for the root_entity.ent
appearanceName: appearance_root_entity_black_blue
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.
ℹIf you make any mistakes here, the worst that happens is an empty string.
Now, add a new entrie to your .json file:
The total entry should look like this:
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.
Find the step-by-step guide in the appearance section on the "Item structure explained" page
This tutorial assumes you already know how to recolour an item. Quick reminder about the mlsetup:
Export it to json
edit the mlsetup.json
with the MLSetupBuilder
Import it back
Find the step-by-step guide in the mesh file section on the "Item structure explained" page
Now, log into the game and spawn the item variant. The name is the header you defined in the yaml file, in this case
If it works, this is an excellent moment to take a backup! If not, check #troubleshooting at the end of the page, fix your problem, and make a backup after.
This is a great opportunity to switch over to the ItemAdditions: Dynamic Appearances tutorial. The tutorial below will still result in a working item, but the new technique is much more flexible and will also result in less work.
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!
Screenshots in this part of the mod may be outdated.
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.
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:
Inside the yourModName.yaml
file set the appearanceSuffixes
array to itemsFactoryAppearanceSuffix.Gender
If you are unclear about why this step was taken, we recommend reading up on suffixes!
Find the array appearances
.
Expand the first entry.
Append &Female to the name attribute. This will change the name from appearance_root_entity_white_red
to appearance_root_entity_white_red&Female
.
Duplicate the first (and only) entry to create a new one.
Expand the newly create entry
Set name : appearance_root_entity_white_red&Male
.
Set appearanceName : my_shirt_m
.
Find the array appearances
Duplicate the first entry to create a new one and expand it
Set the name
attribute to my_shirt_m
(as defined in the root_entity)
Find the array partsValues
Set the resource path to your new male mesh entity file:
resource : tutorial\myshirt\mesh_entity_m.ent
Find the array partsOverrides
Find the array componentOverrides
Set componentName : my_shirt_m
Set partResources : tutorial\torso\my_custom_shirt\mesh_entity_m.ent
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.
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.
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.
That's it! If everything works, you're done!
Before starting to troubleshoot, make sure that you have all the requirements installed — Red4ext, ArchiveXL and TweakXL.
The easiest way to spot what's wrong is to use Wolvenkit's new FileValidation feature, which will print warnings and errors to the log file for you, starting at version >= 8.9.1.
First of all, check the logs for errors including the name of your mod:
red4ext/plugins/ArchiveXL/ArchiveXL.log
red4ext/plugins/TweakXL/TweakXL.log
You have read right past those warning boxes telling you about component name prefixes. Make sure that you add them back.
... 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!
Before you start digging into your file structure, check if there are any leftover yaml 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 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
.
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.
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!
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.
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):
Change the base type
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.
Your root entity is working, and the error is somewhere here:
Your root entity is not recognized and the error is somewhere here:
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
You have an incorrect material assigned. Check your chunkMaterials in the mesh.
No, it does not. You have an incorrect material assigned. (And I'm totally not writing this after 3 hours of troubleshooting -.-)
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.
For more detailed error handling, check the sections below, or check this page.
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 its material.
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.
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.
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?
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 appearanceName
s.
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
The fastest way to find your error is Wolvenkit's FileValidation (in version >= 8.9.1). Save the root_entity.ent
, and the recursive valudation will check the whole chain for errors and print them to the log files for you.
As of July 2023, you can download the right version from the Nightly page (for example this one, as it's pretty stable).
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.
That's due to garment support - check the link to learn more.
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.
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.
Adding weapons
This guide will teach you how to change the ArchiveXL item addition process to make it work for a weapon.
For a much more detailed step-by-step guide, check New Iconic Weapon: Step by Step
For an overview of weapon properties, check Cheat Sheet: Weapon BaseStats
For an overview of weapon audio profiles, check Cheat Sheet: Weapon Audio
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 here) 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:
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.
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).
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
.
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
visualTags (violet): Must match the visualTags in your .yaml
file. If multiple entries match, one will be chosen at random.
Unlike with an entity file, the appearance name doesn't matter. You can name all of them foo
, and as long as you had the visual tags right, it still works (I would advise against it, though)
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):
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.
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:
Optimally, the number of components in the .ent
file should be the same as in any appearance's component
array (red arrow on the screenshot above).
If it's not, that could indicate that you have the wrong .app file. It could also mean nothing, but if you run into trouble in step 6, this might be why.
Configure the yaml as described here
Set up one (1) appearance for testing by assigning the correct visual tags. Do not delete the other appearances yet, future you might need them for troubleshooting.
Start the game and make sure that you can spawn a custom weapon with the appearance you picked and that it
shows up in inventory/photo mode
shows up in first person
If that's not the case, check the (see the blue box in step 2).
If that doesn't help, you may have taken the wrong .app file - go looking again.
You haven't changed anything at this point: the goal here is to make sure that your visual tags are correct and that you can spawn a weapon addition.
It's crucial that you make this work — anything you do after this point will add complexity and make troubleshooting more difficult, so this is where you shore up your bases.
Optional: You just added a weapon to the game that didn't exist before. Take a moment to bask in the success!
Custompath your :
Create a copy of the file and move it to a custom folder
rename it
Change the baseEntity
path in your .app file
Optional, but recommended: Repeat step 5 and make sure that everything spawns
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).
After you've changed the paths, launch the game and make sure that your weapon
shows up in your inventory with your meshes
shows up in first person with your meshes
shows up in photo mode at all (it shouldn't be invisible, but will still have the default appearance)
all parts and extra meshes are visible
is in the right position in regards to V's hands (at least as much as for the Tactician shotgun)
all parts and extra meshes show the correct appearances
Fix any issues that might arise before you proceed.
This is why we kept the original appearances around: if you run into any issues here, you can compare your stuff with the original, un-changed game variants.
Don't forget that you can
split off meshes or submeshes for individual pieces (for chunkmask hiding or extra materials)
add more components (duplicate existing ones, or copy them from the mesh entity)
Once everything works, delete all the default appearances, then duplicate and adjust the one you customized to show your color variants.
Now, finally, copy a working appearance from the .app file to your . This will make your weapon show up in photo mode.
Luanch
If you wish to add a custom icon, follow the steps in the corresponding guide.
To make your own HUD icons for the lower right corner, check here.
You can change which weapon audio preset your custom iron uses by changing the following property in the .yaml
(see a list under Cheat Sheet: Weapon Audio):
You can set up throwing weapons just like a regular weapon, but the projectile (when you throw it) will default to . Check here for how to have custom projectiles.
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.
This is especially important if you add a melee weapon of a different size than the original: if you only replace LOD 1, there will be a separate, invisible hit box that does not align with your new weapon.
In Blender, put your custom mesh in both LODs.
If your weapon is significantly bigger than the original one, you'll notice that the hitbox won't auto-scale with your mesh. If you know how to solve this problem or want to brainstorm, hit up @Mx_OrcBoi
on Discord!
First of all, unequip and re-equip the item. If that doesn't fix it, try respawning it.
That is due to a base game change (bug?): iconic weapons don't show fluff texts anymore (huge thanks to @RMKSoundSystem on Discord for learning that).
To make it work again, you need to either
Add the following line to your .yaml:
Set $base like this:
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.
How to make a custom projectiles for throwing weapons
Created by @manavortex Updated October 05 2023
To create a custom throwing weapon, check the parent guide and use knife as a base type.
This process is about as finicky as the one for weapon additions. Make sure to test your changes after each step.
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.
A projectile needs an .ent
file as the factory's entry point, not an .app
.
You can find all projectile entities in base\gameplay\projectiles
.
Ignore anything that has default
in its name.
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.
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:
Your factory should have two entries: one for the projectile, one for the weapon itself.
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.
If you're using a mesh entity (with an empty appearances
array), you can skip this step.
Expand the appearances
array
Select any of the appearances
Check the appearanceResource's depot path
Add this file to your project
Rename it and move it to your custom folder.
Open your root entity. For all of the appearances, change the appearanceResource
path to that of your .app
.
If you are using a mesh entity (without an .app
file), that's where you will find the component
s. Skip step 1 on the list below.
Open your .app
file . For each of the appearance
s, do the following:
Expand the components
array
For any components that have Mesh
in their type name:
Change the mesh depotPath
to your weapon's custom mesh
Change the meshAppearance
to one of your weapon's appearances
Open resolvedDependencies
and replace the path to the original mesh with your own.
If you did everything correctly, you should now have a custom projectile for thrown weapons.
Tutorial for gonks
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)
Before beginning, ensure you have the following software installed and properly set up:
Cyberpunk 2077 - 😑
Start by opening WolvenKit and create a new project. This will be the base for your new iconic weapon mod.
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.
For first time modders, understanding all this in one go will be difficult. You can just keep these explanations handy and revisit them when required.
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
.
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.
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 do we know that it's called "Crosshairs.Tech_Round" ?
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.
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!
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:
What good is a new gun without a new name? We need to tell our game about these.
Open your WolvenKit project and navigate to the archive folder
Create a new folder named after your mod, for example midas_collection
Within this folder, make a subfolder named localization
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.
Open the file in Wolvenkit and create a new entry in localizationPersistenceOnScreenEntry
. It has the following properties:
secondaryKey
s must be globally unique, or they will overwrite each other.
Create another entry with the secondaryKey of MC_gun_description
and write a little fluff text for the description.
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
.
Wolvenkit will move the .xl file to the same directory as your mod's .archive file, where ArchiveXL will see and process it.
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:
Instead of displayName: MC_gun_name
, you can also write displayName: LocKey#MC_gun_name
. However, TweakXL will do this for you!
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.
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.
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.
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.
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.
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:
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.
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.
Increased Headshot Damage & Crit Chance: This change rewards accuracy and skill, making the weapon ideal for players who excel in precision shooting.
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.
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.
You can add the code below to a new tweak (.yaml
) file, or add it to your weapon's file.
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.
Stats can be added individually to statModifiers
or in groups to statModifierGroups
.
After a bit of tinkering, this is what my weapon tweak now looks like (expand the box below):
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.
Blueprint
Item Quality
Buy & Sell Price
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").
A big part of tweak modding is exploration — poking through tweaks until you find just the right thing to copy or change, or looking for something specific in hundreds of files.
We'll end up with WilsonWeaponModAbility
, which defines the abilities and stats that we care about.
Condition: Prereqs.ProcessHitTriggered - Does the bullet hit anything? Effect: MultiplyDamageWithVelocity - Increases the guns damage with 25% if the Player velocity is greater than 10.
Condition: Perks.IsHitQuickMelee - Is the attack a Quick Melee attack? Effect: MultiplyDamage - Increase damage by 50%
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.
You can add the tweaks below to your weapon's file or create a new tweak file.
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.
Add another entry (you can duplicate an existing entry)
Set the secondaryKey
to the value in your tweak file, MC_gun_iconic_description
Set femaleVariant
to your text — this will be showin on the tooltip in yellow.
. Make sure that it has the correct secondary key , and enter your fluff text as femaleVariant
.
Now that we have an ability, we need to register it as a mod:
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.
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.
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.
Now we have a custom preqrequisite, but we still have to fine-tune and link it:
Conditions are at the heart of a prerequisite, and here we have four.
Perks.IsHitTargetAlive_inline2
-> We don't want headshots on deadbodies to heal the player
Perks.HitIsBodyPartHead_inline0
-> Actual condition to check for headshots
Prereqs.Is_Attack_Ranged
-> (Custom) We don't want quick melee attacks to heal
Prereqs.Is_Weapon_Ranged
-> (Custom) We don't want grenades to be counted for this check.
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:
Uncomment the effector in your weapon tweak and test your mod. You should now be healing every time you hit headshots.
Here's a demo for how iconic weapon should behave.
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.
Slot | Records |
---|---|
File in modded dir | was originally copied from |
---|---|
WolvenKit >= 8.11.0 (you should have it )
vanilla | dynamic | |
---|---|---|
Create a
If you your project, you can immediately spawn them in Cyberpunk via Cyber Engine Tweaks:
Appearance name | Explanation |
---|---|
can help you spot errors in your paths.
Tool | latest version tested | oldest version tested |
---|---|---|
To troubleshoot your ArchiveXL mods, you can use 's . It's not fully supporting
Press in WolvenKit. This will do the following things:
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:
can help you catch the error.
The easiest way to troubleshoot your mesh is by using Wolvenkit's and keep an eye on the log view.
The easiest way to troubleshoot your materials is by using Wolvenkit's and keep an eye on the log view.
Published: July 08. 2023 by Last documented update: Feb 07 2024 by @manavortex
This page is a sub-page of and tells you how to create a custom projectile for a throwing weapon.
Everything but the yaml works exactly like adding regular items (with a or , an and your weapon's mesh). This example will use a root entity.
Make sure that the corresponding entry points at your projectile's entity file from .
For troubleshooting steps, please see the page.
Published: December 2023 by destinybu Last documented edit: Feb 07 2024 by
You can find another guide about this topic under
For an overview of weapon properties, check
For an overview of weapon audio profiles, check
WolvenKit (8.12+) -
MLSB (MultiLayerSetupBuilder 1.6.7+) -
A text editor: or, if you want to get fancy,
Core mods: , ,
Optional: ,
If you are stuck, refer to the at the end of the page.
For this tutorial, we will use the gun 'Unity' as our base (Items.Preset_Unity_Default).
If you want to use a different weapon, you can refer to or find a list of all in-game items .
To understand how the base gun works, open the in WolvenKit and search for Items.Preset_Unity_Default
.
To read more about Tweak modding, check . This isn't necessary for understanding this guide!
Open the overridden tweak file in a code editor of your choice (such as or VS Code). You will be presented with a .yaml
file containing roughly a million fields.
Now open up the CET :
In later steps of this guide, you'll need to look up properties. Either keep a copy of your full tweak file (e.g. on your desktop), or refer to above.
If you want to take a look at these lists, use WolvenKit's or for onscreens.json
.
Good thinking, but no. In Cyberpunk, only one mod can edit any given file. That is why exists, and we'll use it to create a new translation entry for us.
Place a dedicated file in your midas_collection
\localization
folder. This is where we'll add our own translation entries – after that, we only need to tell ArchiveXL about the file and lean back.
Property name | your value | explanation |
---|
For more detailed guidance on these properties, check out the .
You can read more about how array operations work in .
You can find an overview of existing weapon stats under
These arrays don't directly contain the stats, but have inline objects, which in turn will contain the actual stats. I recommend browsing to each of these stats in the Tweak Browser to find out what each one does. You can also read about and what they do here.
The example (together with instructions on finding your way around the TweakDB) has moved to ->
For an explanation of what these do, please see ->
We have found an iconic mod in the for Wilson's gun, so now let's see that we apply this to the Hand of Midas.
two , which we are yet to implement
Open the .json
file that you've created when
Now that we have , we'll fill in the two , one to punish the player for missing, and the other to reward them for headshots.
Let's do what Edison did — we find something to be inspired by. A search for effector
in the finds an awful lot of entries, so I've picked an example for us — a Netrunner item that restores memory:
The player's health is also a statPool item, it's called BaseStatPools.Health
. We can copy this example and change it to meet our needs (for the final result, see ):
For more information on this, check ->
You are now a certified weapon modder. Pat your self on the back twice, you've done it. A special request from me (@DestinyBu). If you found this guide helpful, go ahead and document your own findings on the Wiki and maybe ping me if you ever get around to finishing your Mod. A big thanks to for (inspiring) forcing me to do this.
Open the CET Console in game search for your Tweak in the . If your tweak doesn't show, there's a validation error in the tweak.
Validate your .yaml tweaks to check for errors.
Head
Helmet,
HelmetHair,
Helmet_Intrinsic, HelmetHair_Intrinsic,
Helmet_EP1_Intrinsic_Armor,
Helmet_EP1_Intrinsic_Runner,
Helmet_EP1_Intrinsic_ExplosionDmg,
Helmet_EP1_Intrinsic_Zoom,
Hat,
Cap,
Scarf,
ScarfHair,
Balaclava,
Balaclava_Intrinsic
Face
Glasses, Mask, Mask_Intrinsic, Visor,
Visor_Intrinsic_QH,
Visor_Intrinsic_Zoom, Tech, Tech_Intrinsic_Zoom
Outer Torso
Coat, Coat_Intrinsic, Dress, FormalJacket, FormalJacket_Intrinsic, Jacket, Jacket_Intrinsic_Armor, Jumpsuit, Jumpsuit_Intrinsic,
LooseShirt, Vest, Vest_Intrinsic_Armor, Vest_Intrinsic_Reload, Vest_EP1_Intrinsic_Armor, Vest_EP1_Intrinsic_Grenade, Vest_EP1_Intrinsic_Inhaler
Inner Torso
FormalShirt,
Shirt, TankTop,
TightJumpsuit, TightJumpsuit_Intrinsic,
TShirt, Undershirt, Undershirt_Intrinsic
Legs
FormalPants, Pants Pants_Intrinsic_Armor, Pants_Intrinsic_Carry,
Shorts, Skirt
Feet
Boots, Boots_Intrinsic, CasualShoes, FormalShoes
Special
Outfit, Outfit_EP1
rootentity.ent
base\gameplay\items\equipment\underwear\player_underwear_item.ent
appearance.app
base\gameplay\items\equipment\underwear\appearances\player_underwear_item_appearances.app
mesh_entity.ent
âš
Check the red hint box âš
base\characters\garment\player_equipment\torso\t1_080_pwa_tank__judy.ent
my_mesh.mesh
base\characters\garment\gang_monk\torso\t2_135_jacket__monk_shirt\t2_135_wa_jacket__monk_shirt.mesh
my_tshirt_factory.csv
base\gameplay\factories\items\clothing.csv
translation_strings.json
base\localization\en-us\onscreens\onscreens.json
preview_icons.inkatlas
base\gameplay\gui\common\icons\items\item_icons6.inkatlas
preview_icons.xbm
base\gameplay\gui\common\icons\items\item_icons6.xbm
tutorial_my_custom_tshirt.archive.xl
Wolvenkit -> New File -> ArchiveXL
tutorial_my_custom_tshirt.yaml
Wolvenkit -> New File -> TweakXL
number of root_entity entries
120
1
number of .app entries
120
1
number of mesh entity files
6
1
number of components per mesh entity
2
5
app_file_dynamic_appearance
Your regular appearance. Is displayed when none of the conditional ones apply.
app_file_dynamic_appearance&camera=tpp
This is only active in third person perspective. The item will be completely invisible in first person.
app_file_dynamic_appearance&camera=fpp
This becomes active whenever you are in first person perspective. You'll usually want this to remove the mesh from your face via partsOverrides.
app_file_dynamic_appearance&gender=male
You shouldn't do this — instead, use #substitutions in the mesh file path.
8.12.1
8.9.0
1.5.2
1.1.4
1.8.1
1.4.3
1.18.0
1.12.0
Cyber Engine Tweaks (for spawning items)
1.28.1
1.28.1
| Hand Of Midas | the default translationse |
| only set this if you want to show a different translation when your item is equipped by a person of the male body gender |
| 0 | The actual entry in the translation list, make sure to set this to 0 so that it's autogenerated |
|
| The key used in tweak files to identify this translation string |
More detailed explanations for the guide "Adding new items"
Created by @manavortex Updated June 10 2023
This page is a part of the Adding new items guide and explains how the different files interact with each other.
If you have come here from the main page because you want to change the existing files, search for Making changes
in each section. To add new appearances, the following files are relevant:
.json (translations)
You do not need to touch the mesh entity.
Unless stated otherwise, any linked resources are optional and might not even be related to this exact guide.
We need four files to tell the game about our new items:
the .yaml, which tells TweakXL about your item's properties
the .xl file, which tells ArchiveXL which files to register
the .csv, telling the game about your custom files
the .json file with the translations
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.
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).
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:
If you don't need a male-specific translation, you can leave it blank — by default, femaleVariant
will be used.
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 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:
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.
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.
When editing this file, please keep in mind that indent is important!
The first line of each block must not have spaces, the blocks below must have the same amount of spaces. More spaces means more nesting.
Making mistakes here might break your entire mod, so if in doubt, run your edited file through an online yaml validator.
This file controls the adding of items to the game. Unless you are using dynamic appearances, an entry looks like this:
The entry above will let you add the item via Game.AddToInventory('Items.my_custom_shirt_redwhite')
Four mappings take place here:
entityName
: Points to the factory.csv (see documentation there as for what it works)
appearanceName
: In the root entity specified in the factory, it will look for an appearance by this name.
The appearance name will only be considered up to the first suffix. If you want to know what those pesky & things are doing, read up the corresponding documentation.
You don't need to know this unless you aren't using dynamic appearances and want to add variants for different genders or camera perspectives. We're making them go away by puttingappearanceSuffixes: []
.
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
.
icon:
This hooks up your custom preview.
$base
defines which slot the item will use. For the full documentation, see "Different equipment slots".
The inherited properties can cause problems (see "Suffixes, and whether you need them" for more detail).
You don't need to know this unless you want to add variants for different genders or camera perspectives: we're avoiding them by puttingappearanceSuffixes: []
.
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.
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.
With ArchiveXL >= 1.5, there is a new way of making these connections, saving most of the work of making many variants. You can still complete this guide and then see the documentation for dynamic loading on its own page.
If you want to do more than 5 variants (for both body genders and camera modes), that approach is strongly recommended. Since there isn't a detailed guide yet, you can find us on Discord in the #archive-xl channel.
appearance.app
mesh_entity.ent
the mesh file
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.
Would you like to know more? Full documentation of the root_entity is on its own page.
Understanding this is not necessary for the purpose of this guide.
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:
If you don't know what this means, skip it and wait for the full step-by-step guide!
For using dynamic appearances, you only need one appearance here, which must match the field appearanceName
in the .yaml
up to the variant separator !
Make sure to add the DynamicAppearance
tag here.
Unless you are using dynamic appearances, the root entity's name
field is where you would put suffixes for different appearance variants.
You don't need to know what suffixes are unless you want to make variants for different genders or camera types. In fact, you will want to skip this until you have a confirmed and working mod!
To disable them, each entry in your .yaml contains the following line:
appearanceSuffixes: []
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):
new:
You do not need to change the appearanceResource
.
For experienced modders
This file replaces the component
array inside the .app!
Check here for how to find the right mesh entity for each equipment slot.
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.
Would you like to know more?
Full documentation of mesh_entity The mesh entity for dynamic appearances More intel on components
Understanding this is not necessary for the purpose of this guide!
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)
When changing component names, you want to leave the #component-prefixes (t1_) in place — the game needs them to calculate collisions!
If the text in this box tells you nothing, just ignore it for now
If you're using dynamic appearances, you can use property interpolation in paths. For example, *p{gender}a
will resolve to pwa
or pma
, based on V's body gender.
Read more about this on ArchiveXL's github.
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.
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
.
For experienced modders
The .app file's component array should be empty: this is not an NPC appearance! :)
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
:
If you don't know what this means, skip it and wait for the full step-by-step guide!
For using dynamic appearances, you only need one appearance here. In this case, components will be ignored — make sure to put them all into your mesh_entity!
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:
Open the .app file and expand the list appearances
.
Duplicate an item and select the new one.
Change its name to the one you just defined in the .yaml (black_blue_appearance_name
)
In the new appearance, find the array partsOverrides
and expand it.
Select the item inside.
Find and expand the Array appearanceAppearancePartOverrides
and expand it.
Select the first item.
Open the array componentsOverride
and select the first item.
Change the value of meshAppearance
to the name of your new appearance in the 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.
The mesh file maps materials to appearances. To find out how exactly it does that, find the material section on the mesh wiki page.
Would you like to know more?
#appearan
The documentation for .mesh files lives on their own page!
Understanding this is not necessary for the purpose of this guide, but you might want to reference it once you run into trouble.
For our purposes it's enough to say that you can define your individual appearances here.
Find the array appearances
and open it.
Duplicate any meshMeshAppearance
.
Change the name to the one you've defined in the appearance.app
above (in this case: mesh_black_blue
):
Select the array chunkMaterials
and change the entries in the right-hand panel to the name of your new material (e.g. black_blue
)
Find the array materials
and open it.
Duplicate the last entry. (Yes, use the last one, please, it's important for step 3).
Select the new last entry
Set the following values:
If you duplicated the last material, you can just increase it by one.
Find the array localMaterialBuffer
and open it
Duplicate any entry with an mlsetup (You will see an entry MultilayerSetup
under values
)
Drag it to the last position of the array (that's important, because the materials entries match by numeric index)
Select the new item, open values
, and select MultilayerSetup
.
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.
This is how everything plays together:
Common Problems and How to Fix Them
In this guide, I will do my best to address the most common first person issues I've seen, and how to fix them.
This guide assumes that you have an already working in-game item, and at least a basic understanding of WolvenKit.
If you're creating a fix for someone else's asset, why not drop them the final files - or a link to this guide?
This is probably the most common problem I've seen, and is also thankfully the easiest to fix.
Open up the mesh entity (.ent
) file for the item you need to fix:
Expand the components
array, then find any component
s with Mesh
in their types, and check if they require fixing. In my example project, it's both the jacket and the sleeves.
Scroll down and find the array renderingPlaneAnimationParam
, which will most likely be grayed out.
Click on it. In the right pane, change None
to renderPlane.
Repeat this process for any other component, as needed
When finished, save the file (either Ctrl + S or the Save button top left).
Install and test the mod in-game. If you did it correctly, your sleeves should now render properly.
To fix this problem, you need to hide your item in first person perspective.
This part of the guide will show you how to turn the entire item invisible. If you don't want that, check #problem-3-partial-hiding-justdraculathings
This fix starts in the .yaml
file (which should live under your Wolvenkit project's resources
folder in the subfolder r6/tweaks
, perhaps in a subfolder).
If you are editing someone else's mod, you need to copy their .yaml
to your project. If you don't know which file that is, check their Nexus mod files, as it will be part of the original .zip file.
If you don't have a yaml because you're changing an in-game item for some reason, you need to start at #fixing-the-root-entity. If you convert it to a dynamic appearance, you can stick to these parts in the rest of the guide.
Open the file in any text editor (recommended: Notepad++)
Helpful documentation on .yaml files resides here. Hopefully it looks something like this:
Check if there is something called $instances
. If yes, the mod is using ItemAdditions: Dynamic Appearances and you are done here — go to #dynamic-variants-hiding-fpp
Find the line appearanceSuffixes
. Again, If the mod is using ItemAdditions: Dynamic Appearances (there is something called $instances), you can skip this step.
If the line isn't there, add it. Use the same number of leading spaces as in the surrounding lines!
Add the line itemsFactoryAppearanceSuffix.Camera
to the array. If you have something else in there, add a comma.
Repeat this process for any other items in the .yaml
that you need to fix.
Save and close the file.
For dynamic appearances (if the yaml has a key called $instances
), go to #dynamic-variants-hiding-fpp
Switch back to Wolvenkit.
Open the root entity (.ent) file (it should have an array called appearances
)
You now have two ways of hiding the item in first person:
This will not work with ItemAdditions: Dynamic Appearances!
Find the array tags
at the end of the list.
In the panel on the right, click "add new item" (the yellow +) until you have an empt text field.
In the text field, enter EmptyAppearance:FPP
Find and expand the appearances
array.
For each entry in there, you need to complete the following steps (the example project has only one entry).
Select each entry
Duplicate it via right-click menu
For the old entry: Change its name
to end in &TPP
(third person perspective)
For the new entry:
Change the name
to end in &FPP
(first person camera)
Change the depotPath to base\characters\appearances\player\items\empty_appearance.app
change the appearanceName
to default
For legacy appearances (if the yaml does not have a key called $instances
), go to #legacy-variants-hiding-fpp
Switch back to Wolvenkit.
Pick one of the two options below (we recommend#hiding-fpp-in-the-.app)
Open the .app file in Wolvenkit
Open the appearances
array
Select each appearance and add &camera=tpp
to the name.
Open the #mesh-component-entity-simple-entity in Wolvenkit
Open the components
array
Select each component with Mesh
in its type and add &camera=tpp
to the name
Alternatively, you can duplicate the component and have two for different meshes. This will be covered in #problem-3-partial-hiding-justdraculathings
Save and close the file. Repeat the whole process for any other items that need to be obliterated in first person. Install and test. If all went well, no more obstructed vision!
Fixing this is very similar to Problem #2, just with a few extra steps.
Create an additional FPP appearance by following the steps in #hiding-fpp-via-appearance-definition. Skip 2.4.3 and 2.4.4.
The depotPath
should point at the same .app file as the &TPP appearance.
Change the value for appearanceName. For example, add _fpp
Open your .app file and expand the appearances
array.
You need to repeat the following steps for every appearance in the .app.
Select an appearance and duplicate it
Change its name
to correspond to the appearanceName
that you used in your root entity (Step 3)
At this point, it can be done in a few ways, depending on some factors:
Open up the appearance's partsValue
array
Open the .ent file that is linked inside
In the .ent file, open the components
array and check any component with Mesh in its name:
Open the linked .mesh file in Wolvenkit
Select Mesh Preview
In the right-hand panel, you will see a list of checkboxes.
If there is only one submesh, you need to edit it in Blender to split off or delete the offending parts - complete the section #creating-a-second-.mesh before proceeding. I'll wait.
Toggle them off until the part that is in your face turns invisible. In my example, submesh 01 hides the upper collar.
Remember the number (01 in the example below)
Proceed to the section for Chunk Masks.
You can learn more about chunk masks under 3d objects: .mesh files -> Submeshes, Materials and Chunks. This is not necessary for the purpose of this guide.
Switch back to the appearance (.app) file
Expand your first person appearance.
Expand the partsOverrides
array. If it's empty, click on the array itself, then in the right pane, click create item in array.
Select componentsOverrides
by clicking on it.
In the right panel, click on the yellow + to create a new item in array.
Open up the mesh entity (.ent) file and expand the components
array.
Find the component that needs its parts hidden and copy the name. In my example, the component is examplejacket1_fur
.
Back to the appearance (.app) file. Paste the component's name from the mesh entity into the componentName
field.
Click on chunkMask
and uncheck the submeshes that you want to hide. (You found out which ones that were in #finding-the-right-submesh - In my example it was submesh 01)
Optional: If you need to hide more parts or affect more components/meshes, rinse and repeat.
Save the appearance (.app) file and install the mod to test. If all went well, there should no longer be parts clipping into view.
The clean way to do this is to split the original mesh into submeshes, which you can then hide via chunkmasks. If you want to do that, skip straight to #editing-the-.mesh
To show a different item (one with the clipping bits removed) in first person perspective, we need to create a second .mesh file and a corresponding meshentity .ent that we can display. This guide will show you how.
Duplicate the .mesh
file that's clipping in first person. For my example, I'm using the jacket mesh
Duplicate the meshentity .ent
file that belongs to the .mesh
file.
Change their names to end in _fpp to indicate that this is a mesh for the first person perspective (or do whatever you want, but this guide assumes...)
In the .app
file, open your first person appearance.
Add a partsOverride
by following the steps under #chunk-masks (skip step 9)
Change the depotPath to your new _fpp meshentity file.
Save and close the .app – it is now pointing at your new _fpp meshentity.
In the _fpp meshentity file, open the components array
Select the component with Mesh in its name, open it and change the depotPath for the mesh to your new _fpp mesh file.
Save and close the .ent - it is now pointing at your _fpp mesh.
For the next step, we need to export our .mesh file and edit it. You can use any 3d editing program, but this guide will use Blender 3.6 and the Wolvenkit Blender IO Suite.
Optional, but recommended: If you don't have the Wolvenkit Blender IO Suite installed, do that now.
Export your _fpp .mesh file.
If the export throws an error, uncheck the Export Materials option in the settings panel (you don't need it)
You now have a .glb
file in your project's raw
folder. You can find it like this:
Switch the Project Explorer to the source
or raw
tab
Right-click on your exported file
Select the option to show it in Windows Explorer
Now, hit up the 3d editing: Submeshes page and edit your mesh.
If you stuck to the guide, you shouldn't run into any errors. If you do, check the Troubleshooting your mesh edits page, or reach out to us on Discord in #mod-dev-chat.
???
Profit
Published: October 08 2023 by Last documented update: February 18 2024 by
To implement anything in this guide, you will need with the mod's files. You already have that if you're fixing your own mod (hopefully). If not, check out this guide on how to analyze other mods!
If you are changing someone else's mod, the easiest thing is to the same as the mod's .archive
file and add all the files from the original mod. You can do that by switching to the and for archive:name_of_file
In Wolvenkit, find the
When you are done, use the to import back the .glb file.
the project
{gender}
m or w depending on V's body gender
{skin_color}
{hair_color}