If your looking for places to edit, locations that have already had their sectors located can be found on the Wolvenkit wiki here.
The CET wiki has a list of interesting locations for teleport here.
The AMM Discord has an entire channel dedicated to finding interesting places. Join up and have a look.
Once you have locations you can edit them following the guides by Kratoes in the World Editing section of this wiki, or export them to Blender by following the guide over on the Wolvenkit wiki.
Scripting
Game components explained
What do the different files do? How do I mod them?
Please see the individual subpages in the menu to get to the content, or use the "Next" button at the bottom of the page.
A couple different TweakDB records (also called groups) can be used to create a vehicle. The YAML .tweak files shown the examples here can be processed by WolvenKit to create a .bin that can be loaded into the game with TweakDBext. The groups section creates the record, and the flats are automatically generated from that.
In addition to adding the record, the Vehicle.vehicle_list.list flat (array:TweakDBID) must be updated with the TweakDBID of the new record (Vehicle.vehicle_template is the TweakDBID of the template, as an example), and Vehicle.vehicle_list.initially_unlocked_list (array:TweakDBID) can be added to for that vehicle to be available upon the start of the game.
``
Vehicles
The pages following this aim to give a detailed view of the resources that make up each vehicle in the game, with the hope that you'll be able to create (not just modify) vehicles for the game.
you can also export textures using the wolvenkit gui (recommended)
if you're looking for how to use REDmod to install and manage mods as a user, click here
REDmod is a command line tool developed by CDPR and Yigsoft which allows us to interact with game files in a variety of ways
Modules for mod creators:
resource-export - Export REDengine files to raw format for editing
resource-import - Import raw files to REDengine formats for use in your mod
animation-import - import .re animation files to an animset
util-hash - Hashes paths/string with given hash algorithm
help - Displays helpful info about the other avaliable modules (use -h or -help on any command)
For further information, see the sub-pages in the wiki's menu tree.
Exporting Resources to Raw Formats
REDmod can export .mesh, .w2mesh, .xbm, rsvg and .svg files using the resource-export command.
-depot=<depot> - directory-path to the depot (e.g. "C:\depot")
-input=<resource-path> - resource path of the file to export (relative to depot)
-output=<file> - absolute path to the output file
❗
preserving the folder structure!
add an info.json file to <Cyberpunk 2077>/mods/MODNAME/scripts with some mod info
✅ Done. To test, launch the game with REDmod.
{
"name": "MODNAME",
"description": "Description for the script mod.",
"version": "1.0.0",
"customSounds": [ ]
}
The open source tool we all know and love, which is getting better with every bug you file.
Notepad++
010 Editor
Assets
Blender
3ds Max
Maya
Substance
Gimp
Krita
Paint.NET
Photoshop
Archived (legacy)
These tools are no longer maintained/supported
Silver
material variants
Metals: rolled
How roughness affects a material (the colour was not changed)
Noesis
What is Noesis?
Introduction
Noesis' UI with CP77 python plugin
From the website: Noesis is a tool for previewing and converting between hundreds of model, image, and animation formats. It utilizes a robust plugin system, with support for native extension modules and Python scripts.
Noesis is considered one of Cyberpunk 2077 Modding's cornerstones for its ability to open .mesh files and convert it into a wide variety of other 3d file extensions (like GLB and FBX) thanks to alphaZomega's CP77 Python script that makes that possible.
Download
Noesis
Download Noesis from Rich Whitehouse's website
alphaZomega's CP77 Python plugin
Download the plugin from here
\
Setup
After installing Noesis, put the fmt_CP77mesh.py file in the python folder located inside the plugins folder, and make sure that oo2ext_7_win64.dll is placed next to the plugin in folder.
Basic export/import process
Exporting
Open your .mesh file in Noesis64.exe, then right click on it inside the app and press Export, from there you will be given file extensions to export into, .FBX is the go-to for any usual process and for easier importing into 3D Apps like Blender and 3DS Max.
Same goes for .xbm files.
Importing
Open your 3d file (like .fbx or .glb) in Noesis64.exe, export and select .mesh - CyberPunk 2077 mesh [PC], when a dialogue box shows up browse and select the .mesh file that is appropriate for your import(for example if it was a shirt you'd probably export over .mesh files that has shirts in them), then click OK.
Glossary
List of words that need more context
A comprehensive list of jargon you might see on this Wiki or around our community. This glossary is not alphabetical, so be sure to use your browser search function to find what you're looking for. (CTRL+F for most applications)
General
GitHub: A website which hosts code and helps programmers collaborate on projects. The source code for e.g. WolvenKit or Cyber Engine Tweaks is hosted there. You can compile the WolvenKit source code yourself, or for non-developers you can find WolvenKit releases here first.
REDengine: The proprietary video game engine developed by CD Projekt Red for The Witcher 3 and Cyberpunk 2077. Witcher 3 uses REDengine 3 (RED3), Cyberpunk 2077 uses REDengine 4 (RED4).
Modding Tools
CP77 Tools: The original Cyberpunk 2077 modding Command Line Tools. (Renamed and moved to WolvenKit CLI)
Official Modkit for The Witcher 3 (WCC): An official CDPR command-line tool for modding The Witcher 3. Legacy WolvenKit makes extensive use of the Modkit.
REDmod: An official CDPR command-line tool for modding Cyberpunk 2077.
WolvenKit
masklist: The masklist file is a custom .txt document used as a helper file to generate new mlmasks using the Import/Export tool.
Material json: Material json files are used by the Import/Export tool during for the mesh I/O process. The json will be named after the mesh file then suffixed with .Material.json (i.e. judy_01.Material.json)
Game Files
Cooked: A redengine resource file file that is compressed by the REDengine build process. Files extracted with the Asset Browser using WolvenKit (including Legacy) are cooked files. See also:
Packed: CDPR games do not load loose files, but rather compress resources into archives. This compression process is called packing. The Witcher 3 uses ".bundle" files while Cyberpunk 2077 uses the ".archive" file format.
Modding
Reference: A string value in a resource that exists in another resource, and it is used to chain resource together as they are loaded into the game. Some examples are a DepotPath that points at another resource, a list index that points at a material entry, and an appearance that points at a component.
Vanilla: Original or unmodified i.e. Johnny Silverhand's vanilla appearance can be changed with a DLC.
Animation Modding
Animation Modding - WolvenKit Integration
The REDmod animation import tool can be used as a Plugin in WolvenKit.
Add the .re animation file you wish to import to your /Raw folder in your mod project
Add the .anims animation set file from the game with the Asset Browser
Click View > Import/Export tool
In the Import/Export tool, navigate to Import: a list of all .re animation file in your /Raw folder will appear
Double click the entry to change the import options:
Select the .anims animation set file to import from the dropdown
Select the animation name you wish to override from the dropdown
Click process
INFO - It is best to name .re animation correctly even if you replace an existing animation, because the imported animation will always have the filename of the .re file.
INFO - You need to have the .rig file used by the .anims animationset present in your WolvenKit project.
Animation Modding - Manually
See also: Import Command
The import command imports an .re animation file into an existing .anims animation set file.
Optional parameters include specifying an existing animation name to rename inside the animset file (otherwise the filename of the .re animation file is used) or specifying a different output path (default is overwrite).
INFO - It is best to name .re animation correctly even if you replace an existing animation, because the imported animation will always have the filename of the .re file.
INFO - You need to have the .rig file used by the .anims animationset present in your depot path.
010 Editor
What is 010 Editor?
010 Editor with CP77_CR2W template file
010 Editor is a generic hex editing software which is capable of reading and writing REDengine W2RC files. A custom template for the 010 Editor created by @alphaZomega must be used to parse game files as human-readable.
Download
The 010 Editor can be downloaded from Sweetscape's website
010 Editor Template for Cyberpunk 2077
alphaZomega's CP77_CR2W.bt 010 template can be downloaded from the following link:
Setup
Install 010 Editor and run it.
install alphaZomega's template by navigating to Templates > View Installed Templates, then click Add and add CP77_CR2W.bt.
Navigate to your Cybeprunk 2077 installation, locate the oo2ext_7_win64.dll file, then copy and paste the DLL to the same location as the BT template file.
Scripts
Unkarkify and Rebuild
Unpack and pack the compressed "KARK'd" data within a CP77_CR2W file
Erase
Deletes an entire name and value's worth of a section inside the aforementioned formatted file
changeMatHdrs
Changes all the Material headers' numbers inside a file to be a universal one with zero offsets
insertMatHdrs
Creates a new material header inside a file
Cyberpunk Hair Material
There is next to nothing here yet. Maybe you'd like to change it?
Hair properties are collected in .hp (hair profile) files. Each hair profile has two greyscale maps and a gradient.
It does not use a normal map.
Gradient
A gradient with hair colour information. This is used to color individual strands via the ID map.
ID(entity)
Maps the individual hair strands by colour: Value <=> position on the gradient
Flow
Controls "bending" direction of hair by assigning a colour to the strand.
FlowStrength
A multiplier how strongly this should affect hair
For more information, you can read up on a conversation by the expert .
Blender scripts and plugins
Plugins
for WKit export "With Materials"
Scripts
Archive
This section contains an overview of things that you might encounter while modding vehicles. For a full list of sub-pages, please check the link tree in the left-hand menu.
Appearances
For the documentation on .app files (appearance definitions), see here or check the appearance mappings subpage.
Entity Files
For the documentation on .ent files, see .
An example entry for a vehicle entEntityTemplate from a vehicle's .ent file looks like this:
key
example
TweakDB Modding
To make a tweak mod in REDmod:
make a new mod and create a new folder here: <Cyberpunk 2077>/mods/MODNAME/tweaks
copy the .tweak file(s) you want to change from <Cyberpunk 2077>/tools/redmod/tweaks❗preserving the folder structure!
add a info.json file to <Cyberpunk 2077>/mods/MODNAME/tweaks with some mod info
✅ Done. To test, launch the game with REDmod.
Textures: .xbm files
Details about in-game textures
This wiki page contains documentation about xbm files and their properties.
Wait, this isn't what I want!
Would you rather…
textures?
Learn about ?
Use on your mesh?
TL;DR
.xbm files are simply CR2W representations of DDS files, which are read by REDengine. This means they are nearly completely compatible and all features of DDS files are included in XBM files.
Header
While most of the XBM file is taken up by the texture data itself, it is useless without a section telling the engine how to read and use this data. Because of this, a part of the XBM file is set apart for the header, where info about the size, mipmapping, and general details of the texture are stored.
The use of this header is for the engine to read the data and adjust it correctly, for example, if your texture data is that of a 1024x1024 texture, but the header says it is 512x512, the engine will read it as 512x512, compromising or otherwise changing how the texture data is displayed.
As well, texture format is stored here. If the texture data is, say, for a 3D texture, while the header says it is a 2D texture, the engine will read it as 2D. As well, mipmap information is kept here, mip maps being lower-resolution versions of the same texture for LOD and texture filtering uses.
Setup
The setup section of the XBM file is in essence an extension of the header. It contains settings that, more than just describing basic information about the texture, also describe bit depth, texture type, and format, as well as extended features, like gamma correction, streamability, and mipchains.
Meshes and Armatures: Rigging
How everything is connected, or: why your edited mesh moves weirdly
For a documentation of the import/export options in Wolvenkit, check here.
For Simarillius's Blender script to merge several armatures, check here.
For a youtube video how to transfer weights between rigs, see here.
The connection between a mesh and a rig is made via vertex groups. Any number of vertices can be assigned to a group, which is then matched to a rig's bone via name.
How much every bone influences the vertices is determined by vertex weight, which can be altered in Blender's Weight Paint perspective:
Vertex weights are assigned for every vertex group, and each vertex will move on the basis of the sum of all its weights.
To preview the deform in Blender, you can select the mesh's parent armature and enter the "Pose Mode". There, you can either apply an , or select individual bones and rotate/move them. The Armature modifier will morph your mesh according to the pose, letting you spot errors much faster than trying to debug them in-game.
You can see a video of the process (courtesy of Vesna).
WolvenKit
WolvenKit - The ultimate mod editor for REDengine games
To dowload the tool and know more about it, go to the WolvenKit Wiki:
WolvenKit is an open-source modding tool for Cyberpunk 2077 and The Witcher 3: Wild Hunt. Our vision is to develop a standalone software which can read and write all REDengine file formats, simplify and accelerate modding workflows, and help you create great mods for great games.
Game icons: The inkatlas file
Apart has prepared a reference project with an import-ready inkatlas. You can download it here.
Summary
The .inkatlas is a map file that slices into slots, which are then used by the game for pretty much everything that is a picture - from your HUD to peoples' phone avatars to item preview icons in shops or custom atelier images.
Guides
For a guide how to create custom icon previews, see .
For a guide how to create a custom Atelier icon, see .
Referenced from base\appearances_mappings.json, base\vehicles\vehicle_filename_parsing.json contains a regex string is defined that outlines the allowable file names for .ent files ():
For a filename like v_sport2_mizutani_shion__ext01_body_01.ent, this would match the following groups:
Group 1: sport
3d Modelling
Find knowledge on editing 3d models here
Check the sub-pages for more detes, or check the section's sub-pages.
Relevant guides
Due to its complexity, we don't have a dedicated guide on Blender. However, if you have no idea how to start, various other guides cover part of the process:
Deploy
deploy - Deploys mods to the game by compiling them together
Synopsis
REDmod
https://www.cyberpunk.net/en/modding-support
REDmod is a modding framework and a set of command line tools for modding Cyberpunk 2077 that allow you to compile script and tweak source files and allow for sound and animation modding.
If you already have REDMod installed and just want to enable mods, check .
Parts & Parts Categories
These are the part names used in filenames for .mesh and .ent files. Each header is their category - base is used in both Interior & Exterior.
Interior
Shaders
RED4 shaders (mt)
What are shaders?
Every visual asset in REDengine uses a specific shader, designated by REDengine as MT (.mt) files. Even meshes "without a shader" are in-fact using a debug shader such as debug_coloring.mt. Shaders are the most basic expression of a surface, ranging from glass, skin, concrete, and steel. Each shader contains a combination of constant hidden-variables, and exposed variables for artists to tweak. For example, all skin exhibits some similar properties such as subsurface scattering so there is no reason to expose this; artists cannot use the skin shader without subsurface scattering. However skin color can vary dramatically, so these parameters are exposed to the artists using textures or color parameters. Artists are able to create "instances" of shaders called which contain localized variations of the textures and properties exposed by the base shader.
Appearances Mappings
In base\appearance_mappings.json, entity types have their resources defined. The vehicle definition is below:
key
value
TweakDB
What is the Tweak DB?
Cyberpunk 2077 uses a single static database file which contains data about gameplay elements. This database file can be located at the following path within the Cyberpunk 2077 game installation:
Cyberpunk 2077\r6\cache\tweakdb.bin
This file and the accompanying system Cyberpunk 2077 uses to register and control gameplay elements is called the Tweak DB. The Tweak DB is responsible for registering all player-facing items such as vehicles, weapons, and apparel. In other words, to create a new standalone gameplay item mod developers must take advantage of the Tweak DB.
base
steering_wheel
pedals
Exterior
base
bumper_f
bumper_b
hood
trunk
door_fl
door_fr
door_bl
door_br
fuelcap
fuelport
Wheel
wheel
WolvenKit: The unofficial community modding toolkit.
WolvenKit CLI: The command line interface version of WolvenKit. (Formerly CP77 Tools)
Raw: Generic term used to refer to non-REDengine files that have a resource counterpart. The raw format of the REDengine XBM texture format can be TGA, PNG, DDS, etc. e.g. "Do you have the raw texture?" - This is an inquiry about the TGA/PNG/DDS counterpart to a game texture file.
Resource: A technical term for a REDengine asset file (e.g. .xbm, .mesh, .env).
Uncooked: A term used to describe a redengine resource file (not a raw file) in its most basic uncompressed state. e.g. After using the Official Witcher 3 Modkit to import an FBX to W2MESH, this file is uncooked. Rather than calling these files imported, the uncooked terminology is derived from the cooked (compressed) file state.
W2RC/CR2W: The file magic number for REDengine files. REDengine resource files are commonly referenced as W2RC/CR2W files for shorthand.
Materials are a specific instance of a shader, to be used on a mesh or subset of meshes. Materials are contained inside mi (material instance) files or within mesh files themselves as a CMaterialInstance chunk. While internal material instance chunks can be handy to have inside the mesh, external mi files can be used for multiple meshes.
It's important to remember that materials are simply instances of shaders. The variables contained within the material only take effect when those same variables are present inside the base shader. For example, if RoughnessTexture is not present within the base shader adding this property to a material instance will have absolutely no effect.
The Daisy Chain
The mechanism behind the link between shaders and meshes can be thought of as a daisy chain. Meshes do not directly link shaders, but instead rely on a variable number of daisy chained materials. Some meshes may use a single internal material instance, which specifies a base shader.
The other approach which is just as, or perhaps more common is chaining several mi files together. The benefit of doing so, is the ability to globally adjust materials for hundreds or thousands of meshes. When chaining multiple materials together, the properties of each material overwrite those that are below.
{
"name": "MODNAME",
"description": "Description for the tweak mod.",
"version": "1.0.0",
"customSounds": [ ]
}
The import command imports an .re animation file into an existing .anims animation set file.
Optional parameters include specifying an existing animation name to rename inside the animset file (otherwise the filename of the .re animation file is used) or specifying a different output path (default is overwrite).
INFO - It is best to name .re animation correctly even if you replace an existing animation, because the imported animation will always have the filename of the .re file.
Arguments
-gameRoot=<path>
directory-path to the depot for animset and output (e.g. C:\modding\depot)
INFO - this is the base depot from which relative <resource-paths> are loaded
INFO - You need to have the .rig file used by the .anims animationset present in your depot path.
-inputPath=<file>
absolute path to the animation .re file
-animset=<resource-path>
resource .animset file to use
INFO - resource path must start with base\ (e.g. base\animations\npc\generic_characters\male_average\open_world\generic_male_average__stand__rh_cane_lh_cigar__01.anims)
Options
-outputPath=<resource-path>
resource .anims file name to write, default is to overwrite the input animset (resource path must start with base\)
-animationRename=<name>
parameter representing the old name of animation to be replaced by the new animation (default is the filename of the .re animation file)
INFO - the imported animation will always have the filename of the .re file even if you specify the animationRename parameter.
-?|-h|--help
Prints out a description of how to use the command.
Imports the animation file E:\raw files\animtest1\macarena_long (1).re into the animset file E:\modding\depot\base\animations\npc\generic_characters\male_average\open_world\generic_male_average__stand__rh_cane_lh_cigar__01.anims and replaces the animation with the name stand__rh_cane_lh_cigar__01__smoke__02 with the name macarena_long (1). The result is saved to to E:\modding\depot\base\out\new_test.anims.
Description
The deploy command stages installed mods to work when the game starts with the modded flag.
archives from <Cyberpunk 2077>/mods/<name> are staged to load
scripts in <Cyberpunk 2077>/mods/<name>/scripts are compiled into a modded script blob
tweak files in <Cyberpunk 2077>/mods/<name>/tweaks are compiled into a modded tweakDB blob
sound files in <Cyberpunk 2077>/mods/<name>/customSounds are staged to load
You can specify a specific load order with the -mod parameter
Arguments
-root=<path>
the game root folder for which the deploy command is run.
INFO - this needs to be <Cyberpunk 2077>
Options
-mod=<modA dirname> [<modB dirname> ...]
stage only the mods in the given directory names (without the leading mods\), in left to right load order precedence. You must escape any spaces by enclosing the argument in double quotes (for example Mod With Space should be given as -mod="Mod With Space".)
-?|-h|--help
Prints out a description of how to use the command.
Examples
redmod deploy -root="C:\Gog\Cyberpunk 2077"
Stages all installed mods under C:\Gog\Cyberpunk 2077\mods for loading
Stages only the three mods C:\Gog\Cyberpunk 2077\mods\modA\, C:\Gog\Cyberpunk 2077\mods\modB\ and C:\Gog\Cyberpunk 2077\mods\modC\ for loading. In this case, modB will override both modA and modC, and modA will override modC (in case any of them modify the same asset paths.)
Curiously, this regex doesn't work for vehicles such as the Type 66, or the 911, since numbers aren't permitted in Group 2. It's unknown if this is even used, or if there is replacing done at some point.
Morphtargets are a special kind of mesh used for alternate and additional shapes beyond the static shape a .mesh can define. If your source is a .morphtarget, you need to primarily work with that rather than the .mesh.
To start creating mods or using mods for Cyberpunk 2077 you must first install REDmod.
REDmod is shipped as free DLC with the game. You need to add it inside the platform store (GOG, Steam, Epic). You can click the link below, or find more detailed instructions further down on the page.
If you're accessing Cyberpunk through Steam Family Sharing, you'll be unable to install REDMod (thanks, Steam!). In this case, you can ask the person who's family sharing with you for their Tools folder.
GOG
Steam
When REDmod is installed correctly you will find a new folder tools/redmod inside your game root directory, with subfolders: bin, scripts, tweaks.
Using the save editor puts you at risk of creating a bricked savegame. This means that the save will still load in Cyberpunk, but certain things in the game are broken (e.g. quests are stuck or won't trigger).
If your savegame crashes on load, please check the section.
Version Compatibility
Game Version
CyberCAT version
Usage Instructions
On Windows, save games are stored in
Import your savegame
Make the necessary changes
Export your savegame again. Save it in the same folder.
Known Issues
Appearance editor is disabled until its fully fixed.
Only gender and voice tone can be changed.
Loading / Saving of presets still works
Troubleshooting
Folder structure
Make sure that you export to a savegame folder. They contain the following files:
metadata.9.json
sav.dat
screenshot.png
CyberCAT needs those files to correctly export the savegame.
Asking for support
Please keep in mind that nobody is paid to work on this tool — CyberCAT is maintained by volunteers in their free time.
Once you have exhausted all other means of support, you can find help in #save-editing on the . Please have the following things handy:
Components
This page contains documentation for the most common component types. WIP.
See the Comprehensive Component Hierarchy List for all possible components used in the game, organized by hierachy. Use for researching and documenting components.
For a hands-on guide on how to safely change components in .app files, look here.
Components are not a file type but an internal data structure and part of .ent or .app files.
Components are how the game adds anything to the in-game world, from pag3d data over player interaction prompts to explosion sounds.
Entities and Appearances use components in order to slim down what data each game object has to carry, adding or removing them as needed.
Component names
In general, these should be globally unique so you can target them via . Feel free to ignore this (almost everyone else does), but do read the next section.
Body and clothing component prefixes
Body component prefixes affect how the game calculates and you're strongly encouraged to stick to those naming conventions to make use of it.
Please see the for a list.
Component Properties
Common component properties explained. For a more detailed list, please see .
chunkMask
Only used for meshes: Determines which parts of a mesh will be displayed or hidden. Numeric indices correspond with the submeshes by index.
depotPath
Relative path to a resource within the game files. Used to load dependencies — meshes, rigs, animations, effects.
- Unbundle the game files with WolvenKit.CLI (aka CP77Tools)
- Install Noesis and rename Noesis64.exe to Noesis.exe (The original noesis.exe is 32-bit and the Noesis Plugin "fmt_CP77mesh.py" needs 64-bit)
- Place "fmt_CP77mesh.py" in "noesis\plugins\python" copy "oo2ext_7_win64.dll" from "Cyberpunk 2077\bin\x64" and place it in the same folder as "fmt_CP77mesh.py"
The plugin has some customization option if you open it in a text editor.
Recommended Settings are:
- Next place "CP77_NOESIS_CMD.ms" in "C:\Program Files\Autodesk\3ds Max 20XX\scripts"
- Open "CP77_NOESIS_CMD.ms" in a text editor and set your Noesis.exe path.
In 3ds Max:
Run the MaxScript from Scripting > Run Script...
Click on "Import to Scene" and select the .mesh file you want to edit. Your custom settings in "fmt_CP77mesh.py" will effect the imported mesh.
FBX Settings for Import:
MaxScript Settings for Export:
\
FBX Settings for Export:
**When exporting your mesh the plugin will ask you to select a mesh to export it over, in most cases you should select the original mesh.
Multilayered Material: Properties
Documentation of properties, with screenshots if applicable
Material properties
colorScale
Colour of the material.
material
Depot path to the base material template from which the surface inherits its properties (lightbreaking, subsurface scattering…).
Example values:
base\surfaces\materials\paint\car_paint\car_paint_metallic_01.mltemplatebase\surfaces\materials\metal\enameled_hq\enameled_hq_01_30.mltemplate
matTile
Scaling of the material across the mesh. The higher the value, the smaller it is.
metalLevelsIn
TODO
metalLevelsOut
This value corresponds to a greyscale texture across the entire mesh.
normalStrength
Applies or ignores the base mesh's normal map to this layer. This value can be greater than 1!
offsetU
For logos: X-offset on the texture
offsetV
For logos: Y-offset on the texture
opacity
Transparency of the layer, 0 means that it isn't displayed, 1 means that it's fully visible.
roughLevelsIn
TODO
roughLevelsOut
Determines the roughness of a material
Microblend properties
mbTile
Like , this determines the scaling of the microblend. The higher the value, the smaller it is.
microblend
Depot path to the base microblend. Contains a seamless pattern which will be projected on the surface. Think of an extra normal map that tiles across a layer.
microblendContrast
A crossfade between the layer mask and the microblend mask (the black parts of the microblend texture). If you set this to >=1, then the layer will be blocked out where the microblend texture is black.
microblendNormalStrength
Like for the microblend.
microblendOffsetU
X-offset for the microblend (not sure why you'd need this)
microblendOffsetV
Y-offset for the microblend (not sure why you'd need this)
Mod Structure
When creating a REDmod, there is a certain file structure that you need to follow to ensure that it can be used by others. You will want to have a folder that is the name of the mod and in this folder you will have a file named info.json. Whether you are doing Animation Modding, Script Modding, TweakDB Modding, Audio Modding, or other mods (archive mods), you will also need to have at least one subfolder for the mod files to go into. This subfolder should be located on the same level as the info.json file, and be nested directly inside the folder with the mod name.
An example REDmod might look something like this:
When sharing you mod, you would package the folder that is the name of the mod. You could also package the mods folder with the "mod folder", but it is not necessary and it is assumed one might have other mods in their mods folder anyways.
info.json
For a REDmod to be recognized and loaded by the game engine, you must include an info.json file. This file sits in the root folder of the mod's folder at the same level as the subfolders containing your modded files. There are two required entries and a few optional entries that can be in this json file. At minimum a name field and a version field are needed:
In the above:
The name field is the mod's name and should generally be the same as the folder the info.json file sits in.
The version field is the mod's version. The version should generally use "Semantic Versioning"
INFO - Semantic Versioning is a method of versioning where each number gives meaning for a release based on their position. It uses the format MAJOR.MINOR.PATCH where a MAJOR release change is one which will break workflows, MINOR could break a workflow but is generally safe and might introduce deprecations, and a PATCH is a small non breaking change that all users on the same MAJOR and MINOR can update to without any issues.
Assets explained
What is an asset?
An asset is a specific, objectified concept in the game that can be highly detailed like a blade of grass, or larger like a building, or intangible like sound effects. Unity defines an asset as, "Shorthand for anything that goes into a video game – characters, objects, sound effects, maps, environments, etc." Every asset is defined in a set of normalized asset files that describe its relationship to the game, other assets, and itself.
Visual Asset-Related File Formats
The following list contains file formats that are used to compose visual assets such as vehicles and weapons.
The community-devloped tool WolvenKit can be used to browse game archives and extract game files.
MESH
3d models
XBM
2d textures
ENT (entity)
Parent file for most visual assets which is directly linked by the
APP (appearance)
Sets up appearances for assets such as NPCs and vehicles referenced by
MT (material template)
Base shader files for REDengine
MI (material instance)
Instanced shaders for mesh materials
MLMASK (multilayered mask)
Mask component of the
MLSETUP (multilayered setup)
Material setup component of the
MLTEMPLATE (multilayered template)
Pre-defined tiling surface component of the
HP (hair profile)
Color ramp data to set colors for meshes using the hair
Visual Asset Graphs
Vehicles
Change logs
This page explains the features added in the different game versions.
Added:
Load mod load order from a text file. by Auska
RedMod deploys a list of mods in order - passed through the command line.
This change now makes it you don’t have to pass the names in the command line but read it from file.
We can specify load order of archives in another load order file.
Fix mesh Export paths and allow exporting to non-base resource paths. by Mana Vortex
The fbx importer would throw an error if in the resource path there wouldn't be base
The description field is optional for all mods, but it is generally suggested one should include it so other tools have something to display for a given mod.
The customSounds field is semi-optional. It is required for Audio Modding.
%USERRPROFILE%\Saved Games\CD Projekt Red\Cyberpunk 2077
{
"name": "MODNAME",
"description": "Description for the mod.",
"version": "1.0.0",
"customSounds": [ ]
}
The real meat of the file: a list of appearance definitions, loaded via root entity.
appearanceResource
baseEntityType: name that exists in the Base Types Map and mapped to the correct .ent file
commonCookData: the .cookedapp file that stores a copy of the data for faster loading
appearanceDefinition
A list of appearance definitions to be called from a root entity file. The definitions are independent from each other (unless parentAppearance is used? Confirmation needed) and load meshes and effects via components.
name: the appearance's name that is listed in its .ent file
parentAppearance: the appearance this one inherits information from
proxyMesh: the .mesh file loaded for rendering the vehicle at a distance (confirmation needed)
resolvedDependencies: pre-loaded resources. You will usually want to delete these if you're adding items from scratch.
A list of components that are part of your current appearance. There are various types of components, which are documented here.
Components that you add in the root entity will be shared among all appearances in the .app.
partsValues
This only works for player equipment and weapons (April 2023)
Allows you to add one or more component entities into your appearance. They will be treated as if the components were part of the appearance's components array.
partsOverrides
Overrides component definitions via name. They can be defined in the appearance's own components array or loaded via component entity.
To save a few processing cycles, CDPR doesn't evaluate .apps on load, but instead keeps a pre-cooked cache under base\cookedappearances. CommonCookData is the lookup path for such a file. As long as the file in question exists and isn't empty, your changes might not register, or components that you removed will still be displayed.
Once you start modding, you'll want to install the cookedapps nulled mod to prevent such issues.
The game just updated, and you're crashing. Now what?
Overview
Who doesn't know it? Your modded game is working, then there's an update, and from one moment to the next everything is a smoking crater. Unfortunately, that's normal: as long as you're living on earth, things fall down when you let go of them, and game updates break mods.
This page will give you a brief overview on what you can do in the situation described above by linking to the corresponding sections of the troubleshooting guide.
If you are on Linux and have exhausted these options, make sure to double-check the , as Steam sometimes resets these between updates.
What can I do?
The first step is to update your core frameworks. Check every mod on — make sure that you have a version from after the update.
There are no framework updates!
You're too fast, choomba: modders haven't gotten around to updating the frameworks yet. That leaves you with two options:
and play vanilla until the updates arrive
I updated my frameworks, but the game is still crashing!
You can try to temporarily disable any mod from the script section of. Sometimes, that fixes your issues.
Your game and the core frameworks need to be version-compatible. You can make sure of that by
One by one,
Make sure to follow the instructions carefully – they will prevent you from running into a bunch of other issues.
What other options do I have?
If these instructions didn't help you, there probably are no updates yet and you'll just have to wait. You can find warnings about version mismatches in .
Of course, you can always
look around in the or use your browser's search function there (Ctrl+F and type)
check a and disable them for now
your installation
You might want to deactivate ReShade before you start debugging. Especially after DLSS, it has been known to cause crashes.
Likewise, you'll want to turn off your antivirus to rule it out as a problem source.
Best practices / pitfalls
A collection of code-related knowledge
LUA
Gain performance: Early Return
You're probably used to coding like this:
In LUA, you can skim a few processing cycles by using the early return style:
You can gain a significant amount of performance this way, especially when doing this in a loop.
Fixing/preventing nil access
LUA throws an exception if it encounters nil in unexpected places. The corresponding error will look like this:
Open the corresponding file, find the correct line, and check what is being accessed there. It will look like variable.property, or perhaps something will be concatenated to a string ("something something text" .. variable).
You can assign a default value to the property in question:
While that won't solve any other problems, it will at least make the error go away.
Switch in LUA: Lookup Tables
Who doesn't know the problem? You want to know if your string is A, B, or C, but not D — and LUA doesn't have a switch statement.
Fortunately, there is a built-in and performant way to
Performance killers: strings
String concatenation and comparison can be the difference between a brief stutter and a complete freeze or even crash to desktop. This is not a joke — see for more detail.
Comparing/Searching
Lua internalizes strings. That means these two strings will share a single representation in memory:
The comparison between those two strings will be almost-instant.
This becomes a problem when comparing strings in a loop (see ):
Every single pass of the loop will create a memory representation of "This is the same object!" and then discard it again.
Takeaway:
If at all possible, define things outside the scope of loops!
Finding in strings
Lua's regex implementation is very limited. There is a limitation for pipes. For example, the following example will actually iterate twice after creating internal string representations:
It is faster to just do this:
On top of that, string.match will return the entire string if no match is found:
The alternative:
Takeaway:
Avoid regex
Concatenation
For a performance analysis of different kinds of string concatenation, check .
Scopes
Modding on Linux
How to get mods working on a SteamDeck
Summary
This page tells you how to set the launch options for Steam under Linux. If you have trouble after an update and have exhausted all the usual steps, make sure to double-check them — sometimes, Steam helpfully deletes them for you to make sure that your game crashes on startup.
TL;DR
You need to
install d3dcompiler_47
install vcrun2022
set your launch options to WINEDLLOVERRIDES="winmm,version=n,b" %command% -modded
Setting the launch options by hand
Under Linux, you have to start the game by setting the following launch options for Cyberpunk:
If you can't get it to work, follow the steps below to apply the launch options via Protontricks, or search the #red4ext-support channel on the for winmm to find out what else you can do.
Setting the launch options via Protontricks
Make sure
If you don't want to read text, find a video documenting the process . Thanks to #Connor for providing the screenshots and transcription!
To configure the necessary parameters, you can use the app Protontricks, which you can download through the built-in app browser "Discover":
Open Protontricks (you can search for this by selecting start menu)
When Protontrick opens, select Cyberpunk:
Choose "Select the default wineprefix":
Choose "run winecfg":
Add an override: Check either of the blocks below
If you would rather do it via library, check the expandable block .
via Library
Switch to the libraries tab and open the drop down menu
Select "version" and "Add"
Apply via "OK". You're now done with Protontricks.
Switch to steam and make sure that the launch options are set. They should look like this:
WINEDLLOVERRIDES="winmm.dll,version=n,b" %command%
If that didn't help you, you might be able to find the solution on the .
ArchiveXL
Adding stuff to the game, for the major-leagues
Summary
Published in August 23 by
OK, so what is this?
ArchiveXL ( | ) is one of the of Cyberpunk 2077 modding. Together with TweakXL, It allows you to add things to the game, such as
and
world sectors
This page will document how to set item properties via tags & suffixes (the vanilla way), or via dynamic switching (new, cool, version >= 1.5).
Let's dive right in.
Variants and suffixes
What are variants, what do I need them for?
When adding items, you will normally offer multiple (variants), for example, the same shirt in black, white, and red. This is what you're modding for, after all: making cool things.
And what are suffixes?
Sometimes, you want to load different meshes/appearances under different circumstances. Until ArchiveXL 1.5, the process was extremely tedious, but thanks to psiberx, have been replaced with conditions (read up on to learn how to make use of that).
While the solution has changed (and improved), the problem remains:
Body genders
There are two body genders with different proportions, and you can't make them wear the same shirt (at least not without clipping). To solve that, you can do what CDPR did and have one variant per rig.
Body types
On top of that, you can add body mods (mostly chest size, but occasionally full refits). Starting with 1.5, these will be ! That means, no more compatibility archives, since AXL can simply load different meshes for you…
Camera modes
Sometimes, you need to hide parts of the item in first person. – for example helmets, since you don't want to have half a helmet floating in front of your face (unless you consider that immersive; most people don't).
Tags
Tags are a way to tell Cyberpunk that an item has certain properties and should behave in a certain way. Thanks to ArchiveXL's extended tag system, you can for example force flat feet for female V, or un-hide hair from a head item.
You can find a list of tags in .
Dynamic variants
If you have ever tried to make ten colour variants of an item for two body genders with four different states of feet, then you're familiar with the struggle. Version 1.5.0 of ArchiveXL solves this problem by introducing dynamic variants, allowing you to define rules to hook up your yaml straight to the mesh entity. picking components and even appearances dynamically.
You can find the technical (usage) documentation for dynamic variants on .
You have to use a mesh entity for dynamic variants, as components in the .app file will be ignored.
You no longer need suffixes in the .yaml. However, if you want to use suffixes for your switching, psiberx recommends doing that per appearance name in the .app file, so that you can still use chunk masks via component overrides.
Here's an overview of how the dynamic variants work. By comparison, is the old diagram.
Especially for multiple items, the new way is much faster.
Importing Raw Files to REDengine
using the import and resource-import commands
Redmod can be used to import a large variety of files into REDengine formats for use in your mods.
Red Engine Format
Raw Format
.fnt (font)
.ttf: TrueType font
.otf: OpenType font
.cff: Compact Font Format
.regionset (Texture Region Set)
Textures
What kinds of textures exist, and what do they do?
This page aims to give an overview on different kinds of textures and what the game is using them for.
By default, all textures in Cyberpunk2077 are Y-flipped (upside down). WolvenKit will take care of that for you during import/export via the VFlip property.
If you just want to know how to import/export textures, see .
Types of files
Diffuse/Albedo
This texture is directly projected onto a mesh to give it colour and appearance. Used by shaders like metal_base.remt.
Naming convention:
In the game files, these files will be named <name>_d.xbm (e.g. base\environment\decoration\food\packaged_food\textures\synthetic_snack_01_d.xbm)
When importing a diffuse texture with a non-default file name, make sure to check the isGamma box in the import properties.
Normal
Also known as "bump map", this texture is used to give a mesh depth and surface details. Used by shaders like metal_base.remt.
Naming convention:
In the game files, these files will be named <name>_n.xbm (e.g. base\environment\decoration\food\packaged_food\textures\synthetic_snack_01_n.xbm)
For a guide how to make your own normal maps, see .
Roughness
Also known as "gloss map", this texture defines how light scatters across the surface of your 3d model. Used by shaders like metal_base.remt.
For an overview image, see .
Naming convention:
In the game files, these files will be named <name>_n.xbm (e.g. base\environment\decoration\food\packaged_food\textures\synthetic_snack_01_r.xbm)
Metalness
Also known as "metallic map", this texture defines which parts of the material behave like metal and which parts don't. Used by shaders like metal_base.remt.
For an overview image, see .
Naming convention:
In the game files, these files will be named <name>_m.xbm (e.g. base\envment\decoration\food\packaged_food\textures\synthetic_snack_01_m.xbm)
Atlas
Used for in-game items and UI elements, these textures contain a collection of images. They are made available to the game via files.
Naming convention:
In the game files, these files will be named atlas_<name>.xbm (e.g. base\gameplay\gui\fullscreen\hacking_minigame\atlas_minigame_programs.xbm)
Additional intel
Roughness/Metalness overview
Requirements explained
How do I get my fucking mod working and what do dependencies have to do with it?
Summary
This guide will show you how to debug a dependency chain to troubleshoot a mod. It'll use VirtualAtelier for an example, but the same principle applies to each and any mod.
In the process of this guide, you will be told to check a certain mod's log file. If you don't know how to do that, check page for a step-by-step guide.Technique: Reading log files
Theory: What is a requirement?
It is something that your mod needs to work; for that reason, requirements are also called dependencies. The game will load them first.
Most of them are other mods.
Level 1: The mod itself
Situation
You're trying to install a mod — and it's not working.
Step 1: Try to find its log file
For Atelier stores, there won't be individual log files. Skip , starting with as a dependency.
Search for a matching log file in the Cyberpunk folder (either the mod's name or in the mod's folder). are instructions on how you do that.
=> If you have found a log file, go .
=> If you have not found one or it contains no errors or warnings, go .
A log file exists
If you can't find one, go .
The file is empty
This means that your mod is loaded, but never initialized. Go .
The file has errors
The mod itself is broken. You can now go and .
The file only has warnings
Your mod is being loaded, so the dependencies are OK (if they aren't, the log file would tell you so).
Warnings in the log file don't necessarily mean that something is outright broken. But since you're here and your mod isn't working, that is probably the case. Proceed with .
You can't find a log file
The good news: the mod itself is not the problem.
The bad news: you'll have to check its requirements.
Level 2: The requirements
Step 1: Finding the requirements
Open the mod's Nexus page and check the Description tab (the first one). You will see something like this:
Step 2: Re-do Step 1 for each requirement
For each of the dependencies:
If it's marked as optional and you don't have it installed, ignore it and proceed with the next.
If you don't have it installed and it's not marked as optional, install it.
If it's marked as optional with a condition and you match (e.g. "install if you're using codeware"), install it.
Audio Modding
Audio Modding - WolvenKit Integration
The REDmod animation import tool can be used as a Plugin in WolvenKit.
Add the .wav sound files you wish to import to your /customSounds folder in your mod project
Click View > Sound Modding tool
In the Sound Modding tool, choose which to mod from the list of game sound events
Adjust the parameters
Click Save
Audio Modding - Manually
Place raw .wav audio files inside <Cyberpunk 2077>/mods/<name>/customSounds. Include a info.json file with your mod (<Cyberpunk 2077>/mods/<name>/customSounds/info.json) where you sepcify how to use your custom sounds.
REDmod is a command line tool developed by CDPR and Yigsoft which can be used to stage installed mods to work with a modded game.
This section is for managing mods with Redmod. For creating mods, see
Downgrading / Preventing auto-updates
Only update once all frameworks are stable!
Things fall down when you let go of them, and mods break whenever a game updates. That is due to .
Always make sure that your framework mods are up-to-date.
You should generally wait with updating to the latest game version until all mods are up-to-date. If it's too late for that, you can try Cyberpunk, or wait until the frameworks update.
Cheat Sheet: Head
Head file paths
If you want to , you need and . If you want to make a custom NPC, you can check .
Garment Support: How does it work?
What is Garment Support and how does it work?
If garment supports are causing trouble for you, your easiest option is to delete the parameters from your mesh. For detail, see .
To make use of garment support, keep the component name prefixes. If you change the mesh, make sure to .
Credit goes to psiberx ( with initial explanation of the algorithm) and IslandDancer for providing screenshots and know-how
Textures, Materials and Shaders
Overview and introduction
This is the landing page for materials in Cyberpunk 2077. It contains a definition and a rough overview.
Check the section's sub pages in the wiki's navigation tree for more detailed information about the different kinds of materials. Additional material-related information can be found here:
Morphtargets
Overview of working with morphtargets
COMPATIBILITY WARNING
Full .morphtarget editing is enabled in Wolvenkit >= 8.9.1.
Cheat sheet: Rigs and animations
.anims
There is nothing here yet. For general documentation on how animations work, see
Re-using materials: .mi
External materials, .mi files, and how everythign plays together
Put yourself in the shoes of a hypothetical modder.
You are creating a mod that offers multiple versions of the same item (e.g. toy props or hair)
You have created a base material
redmod resource-import -depot=<depot> -input=<relative path to file to be imported> -output=<absolute path to the new redengine file>
Type Extension
.morphtarget
What is it?
Morphtargets are a special kind of a mesh, or more accurately a .mesh is a more limited version of a mesh without the ability to define targets by itself (with a few exceptions.) A full model can consist of multiple .meshes and .morphtargets.
Morphtargets (or more generally just 'targets') are used for additional deformation beyond what rigging can do, as well as for creating alternative and/or additional shapes for a mesh. Blender calls targets shapekeys.
To be exact, cp2077 has three kinds of targets:
.morphtarget is a separate type, and has an associated .mesh (baseMesh) because redengine splits the full data needed for the model into these two separate types. The .morphtarget always defines the shape, overriding the .mesh. The .mesh stores the other information as usual. .morphtargets are used for, for example, body and head customization.
GarmentSupport is a property of a .mesh. It is also a target and this is a more common way to define targets than the separate type. GarmentSupports are used, for example, to slightly shrink a t-shirt so that it doesn't clip when you put a jacket over it.
Vehicle damage submeshes. This is a static end state of a target, inserted directly as an extra submesh rather than a target.
How do Targets Work?
A simple and perhaps familiar.morphtarget example is chest size for FemV. There are three states: default, small, big. The default corresponds to the base mesh shape, and is the Basis shapekey in Blender.
The two other states are defined as targets. Each target defines a 'delta', a set of offsets for base mesh vertices from their positions in the default shape - including any other active deform, like a pose in photomode. If you fully enable one of these targets, you effectively have a mesh with the chest area reduced or enlarged.
Targets can be also enabled partially, with the states between off and fully on (the 'end state') interpolated by the engine or 3D software. This can be used for animations, but in the cp2077 context generally is not.
Targets can be blended together. If two targets are enabled fully or partially, their combined state is blended into one shape. In cp2077 some targets are mutually exclusive (like the chest size), and others are inclusive (your V's face is a combination of the selected eyes, nose, mouth, jaw, and ear target states all blended together.)
Exclusive/inclusive is not a limitation of the targets themselves, but of how cp2077 activates them..
Target Activation
The game engine activates targets by name (and region) in specific conditions.
Character customization targets are activated when the character is loaded (and dynamically in the CC view.)
GarmentSupports are activated when equipping a garment that goes "on top of" the garment with GarmentSupport.
Morphtargets, What Are They Even Good For?
So, some uses are probably already obvious. But targets enable quite a bit of exciting modding:
Modding anything with a .morphtarget without breaking the targets like before
You can for example mod the CC tattoos, or piercings...
...Or any aspect of character face customization. Vampire catboy Legolas here we come!
TBA
The main limitation currently is that we do not have a way to add activations, at least generally. You need to hook into a target name that the engine already uses.
Editing Morphtargets
For best results, export an original game file and start from there, as exports from older Wolvenkit versions may not work.
This Section is Incomplete
One thing deserves highlighting right up front: whenever you are doing 3D work on a model that has a .morphtarget, you work with the .morphtarget, not the.mesh. The .mesh is only used for things the target doesn't include, like appearance definitions.
Fundamentally the 3D workflow goes like this in Blender (use the blender cp2077 plugin import/export):
WkitExport the .morphtarget
BlenderImport it
Make your edits to base shape and/or shapekeys (if you need to - the base shape edits are automatically propagated to shapekeys.) You can edit just like you would a .mesh, because it is a mesh.
BlenderExport to a file named after the .mesh
BlenderExport to a file named after the .morphtarget
WkitImport the .mesh.gltf first. Wkit will treat it just like it would a 'real' .mesh
WkitImport the .morphtarget.gltf
...And that's it. You can pack the mod.
Tips for Morphtargets
Make sure to test your targets work blended with other targets, not just by themselves
You can create targets from scratch, all that matters is that the name matches the original. This is handy for zeroing out targets you don't need or want, for example.
I prefer to use either of the .gltf formats over .glb. They're all GLTF but .gltf is slightly more widely supported, plus you can open it up in a json editor. -- Auska
If you don't know if a mod is optional, it's most likely not.
Why would I want this?
REDmod preloads any mods on its list, loading them as if they were a part of the game's regular structure. This leads to a brief delay during startup (while it does that), but the loading times during gameplay will be much faster.
Using Mods
The game loads redmods from this path: <Cyberpunk 2077>/mods/<name>.
Legacy archive mods in <Cyberpunk 2077>/archive/pc/mod are still supported, but their load order cannot be managed with REDmod.
Legacy mods will load before any redmods.
Before being able to play a modded game, you need to deploy your installed mods.
Then, you need to activate mods before starting the game.
How do I deploy?
You can handle deployment and load order with
the REDlauncher that comes with the game
Vortex Mod Manager from NexusMods
REDmod WolvenKit integration and manage your mods easily from within the WolvenKit Mod Manager
starting Cyberpunk with the parameter -modded
What is deployed?
Scripts: Compiled into a script blob
<Cyberpunk 2077>/mods//scripts
Tweaks: Compiled into a modded tweakDB
<Cyberpunk 2077>/mods//tweaks
Sound files
<Cyberpunk 2077>/mods//customSounds
Activating mods
GOG Galaxy
Open GOG - Cyberpunk 2077
Click Manage Installation -> Configure ...
Open the Features Tab
Select Enable mods
Click OK
Play the game
A window will open showing progress on mod deployment.
Steam and Epic
Navigate to Cyberpunk 2077
Click Play
Click the Settings button and Enable mods
Click Play (Do not skip this)
A window will open showing progress on mod deployment.
Conflicts and Load Order
Conflicts are handled on a per-file basis, but can be handled by specifying a specific load order. The rules here are the opposite of e.g. Skyrim: the first mod to change a file wins.
Example:
modA contains a script file
Cyberpunk 2077\mods\modA\scripts\cyberpunk\player\player.script.
modB contains a script file with the same name:
Cyberpunk 2077\mods\modB\scripts\cyberpunk\player\player.script
This will discard all changes modB made, since by default, REDmod and the game loads mods alphabetically (modA overrides changes in modB).
However, you can specify a load order with REDmod, which the game will respect.
Troubleshooting
If a REDmod is giving you trouble, you can force a redeploy by either of the following means:
Either of
Delete the content of r6/cache/modded in your Cyberpunk directory
or
Uninstall the mod
Start the game
As soon as it launches, close the game again
Reinstall the mod
Now, restart the game. REDMod will rebuild the cache and hopefully fix your problem.
REDMod's redeploy is triggered on either of these changes:
mods change: You added or removed a mod
A mod's version changes: The version number in the info.json was changed.
A mod's files change: You added or removed archives
Deploying Mods - Manually
The REDmod deploy command stages installed mods to work when the game starts with the modded flag.
Deploying Mods - WolvenKit Integration
Open the WolvenKit Mod Manager.
Click the Deploy Mods button in the toolbar.
You will see all installed mods in your game. Enable the mods you would like to play with.
Handling Conflicts - Manually
You can specify a specific load order with the -mod parameter:
This will override changes to \cyberpunk\player\player.script that modA makes in favor of modB. It will also tell the game to load modB before modA and modC.
Handling Conflicts - WolvenKit integration
Open the WolvenKit Mod Manager.
Adjust the load order by dragging and dropping rows.
Click the Deploy Mods button.
You can adjust the load order by dragging and dropping the installed mods inside the mod manager.
When you click the Deploy Mods button, the current load order will be forwarded to redmod.exe and mods will be deployed and loaded in this order.
Starting a Modded Game - Manually
To start a modded game that loads mods deployed by REDmod use the -modded flag on Cyberpunk2077.exe
Example:
This however will skip the initialization process that should be done after any new REDmod mod install.
INFO The executable is located at <Cyberpunk 2077>\bin\x64\Cyberpunk2077.exe
In GOG, this is a global setting — you can only disable auto-update for all of your games.
Open the settings and select the entry Game features in the sidebar, then uncheck the box for Auto-update games.
Epic
In the EPIC launcher, this is a global setting — you can only disable auto-update for all of your games.
Open the settings menu and scroll down to MANAGE GAMES, then disable auto-updates.
Steam
Unlike the competition, Steam will not give you any control about auto-updating. For that reason, you need to forbid it from writing to a specific file on disk, without which it will be literally unable to update. Here's how:
Find the steamapps folder (:
Right-click on Cyberpunk 2077 in your Steam Library and select Properties
On the side bar, click on Local Files
Select Browse. This will take you to Cyberpunk's install directory, which is inside the folder we want (e.g. C:\Steam\steamapps\common\Cyberpunk 2077)
Navigate two levels up
Find the file appmanifest_1091500.acf
Set the file to read-only:
Right-click on the file and select Properties
At the bottom of the dialogue, check the Read-only box
As long as Steam can't write to this file, it can't update Cyberpunk. Once you are ready to update, simply uncheck the Read-only checkbox again.
Sorry, choomba, you're fucked. No downgrading possible.
Steam
Since 2.0, Steam supports downgrading to version 1.63_hotfix.1.
Right-click on the game in Steam and select Properties, then go here:
For downgrading to other versions, see the expandable box below.
Using steamdb to attempt to download a previous depot
Longer instructions can be found in this MakeUseOf guide, but the condensed version (courtesy of our lovely Discord community) goes as follows:
First turn autoupdate off for Steamnow so that you don't forget to do it later. We'll wait.
Here are the version-specific commands that you need to run. If you can't find your version on the list, check here.
2.0 Base Game: download_depot 1091500 1091501 7695458851217910405
The engine morphs garments to avoid clipping — for example, if you equip a pair of boots and V's jeans no longer cover the shoes, but get tucked under.
Garment Support in action
This process is accomplished via 'parameters' on the mesh:
These will show up as shape keys in your Blender export
Component prefixes
Garment support will be applied based on garmentScore. For this, the prefix of the component name will be considered (components are named in your .app or .ent file's component array).
A high garment score means that the item is "on top", squishing anything worn "below". (See The algorithm for details.)
The prefixes are as follows:
h0_
t0_
s0_
l0_
...
Any component with a 0 in its prefix will be treated like a body mesh (no deform/squishing)
h1_
Head inner (mask, sunglasses)
h2_
Head outer (helmet, bandana)
t1_
Torso inner (shirts)
How it looks if it's broken
Often, you can salvage things by deleting the parameters in WolvenKit
The algorithm
TL;DR: High garment score means "on top", items below will get squished.
The game calculates the garment score by checking the prefix of component names, where the one with the lowest prefix is the innermost:
After considering the component name, the game will consider the tags in the .ent's visualTagSchema:
An example for t0_000_pma_base__full (the default body component, torso+legs):
In its original state, a 3d object (mesh) is a collection of vertices (pixels). The space between those vertices is filled by faces, which form the 3d object's surface.
The shader is the thing that goes on top of the surface, rendering a material such as glass, skin, concrete, steel…
Without a shader, objects would be invisible in the game, the surface simply being transparent. In Cyberpunk, a default shader will be assigned in such cases (such as debug_coloring.mt).
In Cyberpunk 2077, REDEngine shaders are implemented as .mt/.remt files.
How can I use shaders?
If you have ever messed with an item's materials, then you already have.
To use a shader, you create a Material Instance, where you can configure the parameters.
Not every parameter of a shader can be configured: since skin always has subsurface scattering, it makes no sense to tweak this. But since skin color already varies dramatically if you don't throw exotic chrome into the mix, you can change them easily via tint.
In the context of Cyberpunk, a material is the thing that lets the shader define the surface properties of a 3d objects: .mesh files. Typically, you create a local instance, which will then pull in a shader via baseMaterial.
The property baseMaterial can point at a .mt / .remt file directly, or to an intermediary .mi file:
The .mi file
Each part of a mesh (submesh) can have a different material assigned.
Did you know? You can make Cyberpunk's default textured material glow.
Multilayered
This is specific to Cyberpunk, and it is incredibly cool. If you're used to textured materials, you're probably going to hate it at first, but it has incredible versatility and re-usability.
The facial animations are linked in the .ent files under base\characters\base_entities\xxx\xxx.ent. They are otherwise referenced from an entAnimationSetupExtensionComponent inside the .app file.
Deforms
Deforms can be found under base\characters\base_entities\*\deformations_rigs.
You duplicate and re-duplicate the material for each of your variants, changing the properties that defines the colour
You wish that there was less copy-pasting involved
You only change 2 of 6 properties, but you always have to copy all of them!!
.mi files to the rescue
A .mi file encapsulates a material in a reusable template file. Take any of them from the game, move them to your custom directory, and group all the properties that you keep copy-pasting into the .mi.
Then, in your material, you can now use your .mi file as baseMaterial, and only change the properties that are actually different!
Instead of copy-pasting six properties, you now copy-paste only two.
Only add the properties that you want to change in relation to the .mi file
Making material templates
Let's take it another step further – we can make a bunch of different colours to re-use across your files. An example for this are hair files, or the plastic materials I've used in my toy prop pack.
For this, I first created a plastic_base.mi with all the common properties, and then created one additional .mi file for each shade of plastic, setting plastic_base.mi as baseMaterial, leaving me with the following folder structure:
If I decide that my plastic is too shiny, I can edit _plastic_base.mi instead of touching every template individually. Pretty neat, isn't it?
The technical term for doing this is "daisy chaining". (Image: Wikimedia commons)
And if one of my items happens to have a custom normal map and/or texture, then I just add them in the values array of my material and call it a day.
Maximally lazy: external materials
But we can take this approach even further! If you don't have any properties, your mesh doesn't even need materials! You can simply use the externalMaterials list instead. You do this by unticking the isLocal property in the materialEntries definition:
material entries and indices
Warning
You can of course mix and match local and external materials! Just make sure that the materialEntries indices are pointing at the correct material.
However:
If you are using preloadLocalMaterials, you need to use preloadExternalMaterials instead of externalMaterials.
A selection of lists for looking up item codes. Alternatively, you can browse through the game's files, or search e.g. the wiki.
Player equipment only:
Not all items that you find in the player folder are actually hooked up to spawn. If you can't , you ran into one of those.
From a BaseID to an item's materials
As an example, this will use Reinforced Puffer Vest (Items.Vest_17_basic_01)
The base ID
An item's spawn code is called BaseID. It looks like this:
and will be used to spawn items via CET (Game.AddToInventory("Items.Vest_17_basic_01")).
A base ID consists out of two parts. The first one (Vest_17) determines the item, the second one (basic_01) determines the variant.
Finding the files
Head to WolvenKit and search for the first part of the BaseID:
You will find at least one entity file and an appearance file.
If you find multiple files, you need to open the correct one. You can identify those by the folder path: for player meshes, the name of the last folder will contain either _pwa_ or _pma_, and the path will include either that or player.
The .app
Open the apperance file. You will see a bunch of appearances:
We only care for _m and _w right now, since they are using different meshes.
Open the array components and find the one holding the mesh:
We can see that the basic_01 appearance is using the default material, and the basic_02 appearance is using the bbstripes material:
To find your way through the mesh, check the guide for !
In the console, enter this command exactly to start the download (it'll be the entire 60 GB so be prepared): download_depot 1091500 1091501 7695458851217910405
After the game finishes downloading, go to the installation location listed in the console, and copy either just the changed files (you can view the manifest for the new version) or the whole thing over your game directory to overwrite the new changes.
If you have the Phantom Liberty DLC, you will need to do the steps 4 and 5 again for the DLC itself with the command: download_depot 2138330 2138330 4702299018468121610
Make sure you have all the required programs to operate mods and their managers; these are separate from modding framework requirements, but just as important.
This guide assumes that you have already bought Cyberpunk 2077 on the platform of your choice (Steam, GOG or EPIC).
Installing the Game
If you already have the game installed, you can skip this section and proceed with Configuring Cyberpunk
In order to set up your game to be best suited for mods, you'll want to keep a few things in mind:
TL;DR: If possible, install Cyberpunk 2077
on an SSD to speed up load time
outside of Program Files to keep Windows from "protecting" your files
For the purpose of this guide, we will assume the following install paths:
Game install
C:\Games\Cyberpunk 2077
Mod download and staging
C:\Games\Mods
Performance
Like everything else, Cyberpunk will run significantly faster from an SSD rather than a HDD.
Permissions
Folder permissions can cause problems down the line, especially for Windows users. Most users never run into these, but you can prevent them altogether by installing your game to a folder like C:\Games rather than C:\Program Files.
By default, all three platforms (GOG, Steam, and Epic) want to install the game to their own install location, which defaults to C:\Program Files. That wouldn't be a problem if not for Windows and what it will permit there, which is not much.
This can (but doesn't have to) cause problems in two different spots by "protecting" the Cyberpunk install dir from modding tools such as mod managers (like our recommendation Vortex) or even CDPR's own REDmod launcher. But hey, at least things are very secure.
You likely won't run into any of these problems, but you can rule them out altogether by installing Cyberpunk to a directory other than C:\Program Files or C:\Program Files(x86), like C:\Games\Cyberpunk 2077
Now we will go through the install options to use on each platform to accomplish this, and the recommended settings for modded Cyberpunk 2077.
Installing Cyberpunk: GOG
Open GOG Galaxy, click on "Owned Games" in the left sidebar, and scroll until you find Cyberpunk. Single click on its picture to display the main Cyberpunk page.
Click the button at the top of the page labeled "Install".
In the pop-up window, choose your install location:
Click the drop-down box
select "browse"
browse to the target folder (we're assuming C:\Games)
You don't need to create a subfolder for Cyberpunk, as GOG will do that for you.
Optional: Select a game language other than English
Optional: Create a desktop shortcut by ticking the first box "Create desktop shortcut"
Optional, but recommended: Disable auto-updates by unchecking the second box "Keep this game up to date automatically"
How the window should look for recommended install.
Press "Install"
Wait until GOG has done it's thing, then proceed to the next section.
Configuring Cyberpunk: GOG
Once the game has installed, we want to make it run with mods. Click the button to the right of the play button (formerly the install button) pictured below.
The Cyberpunk 2077 main page on GOG, with the sidebar open on the left
From there, select "Manage Installation" and then "Configure". A window will pop up where you can change your desired settings:
Installation (first tab): Disable auto-updates
Features (second tab): Enable mods
DLC (third tab): Select at least Cyberpunk 2077 REDMod
You may select any additional settings you like, but these are the minimum recommended options.
That's it, you are done with your install of the game! You can now move on to installing Vortex.
Installing Cyberpunk: Steam
If you already have the game installed, you can skip this section and proceed with Configuring Cyberpunk
To be done
Configuring Cyberpunk: Steam
To be done
Navigate to Cyberpunk 2077
Click Play
Click the Settings button and Enable mods
Click Play (Do not skip this)
That's it, you are done with your install of the game! You can now move on to installing Vortex.
Installing Cyberpunk: Epic
If you already have the game installed, you can skip this section and proceed with Configuring Cyberpunk
To be done
Configuring Cyberpunk: Epic
To be done
Navigate to Cyberpunk 2077
Click Play
Click the Settings button and Enable mods
Click Play (Do not skip this)
That's it, you are done with your install of the game! You can now move on to installing Vortex.
You may now move on to mod manager and mod installation.
If you are experiencing crashes caused by CET, try running Cyberpunk in
If you can't open your overlay, check
If your CET just stopped working (without a game update) or if you've been sent here to do a clean install, see below how to
Otherwise, read on for the full troubleshooting instructions.
General troubleshooting
Before trying anything else, please make sure that your Windows and your graphics driver are up-to-date – this actually helps in around 50% of all cases. If you need instructions, you can find them in the red box under the general troubleshooting guide's section.
Step 0: Go to your install directory
Go to your Cyberpunk 2077 game directory, since all paths given in this guide will be relative to that folder.
TL;DR:
CET is installed to bin\x64\plugins\cyber_engine_tweaks
The log file is bin\x64\plugins\cyber_engine_tweaks\cyber_engine_tweaks.log
Example:
Step 0.5: Update your game and the mod
Each version of CET is compatible with exactly one game version. Nobody keeps track of those other than "the most recent ones work together".
For that reason, the Redmodding Discord can only support you the most recent version.
If there's a mismatch, then you can find a warning in the following file:
If you don't have that file, proceed to Step 2.
Step 1: Check the install folder
Go to your Cyberpunk 2077 game directory and check the following subfolder:
It should have at least the following files:
If you do not have these folders, then CET isn't installed correctly. Head to and start with step 3.
Step 2: Check for a log file
If everything looks okay in step 1, check if you have a file cyber_engine_tweaks.log inside the cyber_engine_tweaks folder from the previous screenshot.
You don't have a log file
No log file means that CET isn't starting up.
The easiest fix is to .
If you did that and it didn't help, check your antivirus. Most likely, it is protecting you from scary things like Cyber Engine Tweaks. Disable it.
If that didn't help either, update everything - Windows, your drivers, etc. You can find links and instructions in the red box on the .
You have a log file
If you do have it, you can open it and try to make sense of the error message. You can find more information on that , or find help in the #cet-suppport channel on our .
Reinstall CET
Uninstalling (the full game or just the mod via Vortex) can leave files behind, which will fuck things up for you after a reinstall. This section tells you how to avoid that.
If you are using Vortex, turn it off (it will get angry otherwise)
Complete either of the following steps:
rename bin/x6/plugins to plugins_
Reset your keybind
Find the file \bin\x64\plugins\cyber_engine_tweaks\bindings.json and delete it.
Start the game.
You should now see a popup asking you to bind a key. Otherwise, read on.
I can't bind a key
If you do not see the popup at all, or do a .
Cick into the "Binding..." field.
If that doesn't help, make sure to turn off all your overlays (Discord, Steam, Microsoft Game Bar, Random Useless Bloatware) or start Cyberpunk in the Windowed Borderless mode.
Microstutters and Performance
If you're experiencing performance issues with CET, first make sure to as per the instructions to rule out side effects from old files.
If that doesn't make the problems go away, make sure to update Windows and your graphics driver as per the red box under Troubleshooting's section.
If that doesn't help, you can find us in #cet-support on the . Please note that people there will first suggest everything else from this guide, so you might as well get it out of the way first.
Crash to Desktop on Alt+Tab
Make sure to update Windows and your graphics driver as per the red box under Troubleshooting's section, as this is the only chance you have of getting rid of your crashes.
This is a known issue with AMD cards, and it's not something the CET developers can fix. Everyone who could fix it is informed, but such things take time. If you're on an AMD card, you can try running your game in Windowed Borderless mode. Otherwise, you just have to live with the crashes.
Broken mods: How to help
A mod is crashing and you know which — what now?
This page assumes that you have made use of the troubleshooting guide, have identified a broken mod and want to help fixing it.
It will help you rule out side effects and collect the necessary information for a bug report. Of course you can always reach out, but there's a good chance that you'll be asked to do the stuff on this list, so you might as well do it first.
If you can't or won't do that, please !
Thank you!
Without people like you, many bugs would never be discovered and fixed, and modding would be even more frustrating than it already is. So thank you for taking the time!
Step 0: Check the Nexus page
Are you on the most recent version?
"Crashes when you equip your strap-on? I fixed that a month ago. Just update! :)"
Make sure that you're on the most recent version of both the mod. You probably are, but — better double-check.
This recommendation comes from a professional software developer, who has "fixed" more than one software problem by just updating the software.
Is there a "known issues" section or a pinned comment?
Maybe the mod author knows about this problem and hasn't been able to fix it. If they do, then either the description will mention it, or there will be a pinned post in the comments section.
If there isn't either, then you have found something new. Exciting!
Step 1: Isolate
The first step is to isolate the problem. Make sure that it is exactly this mod and no other. It works like this:
Temporarily from your game.
Install only the problem child together with all . Make sure that they're all on the most recent version. Does the problem still happen?
(If not, then it's something else)
Now, disable only the problem child. Does the problem go away?
(If not, then it's one of the dependencies)
If the problematic mod is a core framework, please read as well.
If you can reliably reproduce the problem (that's Netrunner speech for "it happens every time without fault"), then you have everything you need for a bug report.
For a core framework
If your problem child isn't one of , you don't need to read this.
The core frameworks are generally extremely stable. That's not to say that they don't have bugs, but such bugs are generally found and fixed quickly.
If you suspect that one of them is the cause of your crash, make very sure that you have no dependent mods installed, since those will be inactive as long as the dependency isn't there (think of it like a fuse box: without electricity, the fridge can't keep making that noise).
Step 2: Gather the necessary data
Since your problem could be anything, we'll go about it the other way. I'll list everything that you could include, and tell you when it's needed.
Reproduction steps
When: Always
Any information you collect is helpful, but fixing a bug is easiest if you can watch it with your own eyes. For that reason, we need a list of the exact steps needed to make the problem happen.
Write the steps they need to do, not the ones they don't.
A lengthy example in case you're unclear about why you'd need a list
Imagine the following (hypothetical) bug report:
OK, so the game crashes with only your mod and its dependencies (ArchiveXL, TweakXL, Red4ext) installed! I'm on the most recent version. Here's what I did:
I created a new character. Has to be a nomad, female body gender and male brain gender, doesn't work if it's anything else (I made a hot blonde, here's a screenshot, aren't they cute?) Then I added the pink unicorn hat and the Sword of Truth via cheat. Has to be the sword, the Mace of Maybe works! Then hit the car mechanic and the game crashes. Oh yeah, it only does that if you do the hat before the sword! And also only on the pink version, the green variant works fine! Cheers!
Do you know what to do? I lost track halfway through, and I wrote that. Also, did they equip the items, or is it enough to have them in your inventory?
Save game
When: If the problem happens
at a certain location or a certain quest phase
when loading into exactly this save (if it happens for all of your saves, then it's probably not needed)
Your save games can be found in the following folder:
which is the same as
Find your individual save game folder (e.g. AutoSave-0) and .
Log files
When: If the problem child
adds an error in any log files that doesn't happen without it (use the )
Is a plugin (lives in Cyberpunk 2077/bin/x64/plugins)
Is dependent on a plugin (like above, but with more subfolders)
What:
The log file with the error
If it's a plugin mod, then add the plugin's log. Most common here is Cyber Engine Tweaks; the log file is Cyberpunk 2077/bin/x64/plugins/cyber_engine_tweaks/cyber_engine_tweaks.log
Crash report
When: If the problem child is one of the .
These mods are the foundation that everything else builds on, and the people who develop and maintain them are incredibly competent. Please don't waste their time — make very sure that you have the problem. You don't call your internet provider before checking your network cable and restarting your router!
You can find the crash reports in this folder:
which is the same as
Find the most recent one (e.g. Cyberpunk2077-20230816-225038-11372-16140) and .
Step 3: Reaching out
You're 100% sure that the mod is the cause of the problem, and you have collected the necessary information, so now you can reach out and provide a helpful bug report.
The first place to go is the mod's Nexus page.
If there is a Bugs tab, you can create a new bug report
If there is a Posts tab, you can leave a post
If there is a Comments
Step 4 (optional): Discord
If you can't reach the mod author, you're welcome to hit up the , for example in #mod-troubleshooting. Someone there might be able to get the word out.
Corrupt(ish) saves
If you have found a mod that until it is installed again, please let us know so that we can update the troubleshooting guide!
Vehicles
Vroom Vroom
The list below has the main entity files for the vehicles in the game, should be a good starting off point for whatever your wanting to do to them.
Vechicle
Ent File
Archer Bandit
v_standard2_archer_bandit_01.ent
Archer Hella
(police version)
Exporting and importing meshes
How to export and import meshes (WolvenKit <=> Blender)
Summary
Created by @manavortex
Published November 05 2022
This guide will show you how to
- export meshes from the game for use in other projects
- import those meshes back into WolvenKit
It will not show you anything else. For other use cases like exporting characters, please check
Assumed skill level: You are able to read ;)
Tool
Tool version
Wait, this isn't what I want!
Would you rather…
Import/Export to fbx ?
Read more about ?
without editing them?
You can find a collection of useful Python scripts for Blender on .
You can import and export meshes via WolvenKit or - both methods work.
Before you start editing, a warning:
It is easy to beyond the point of repair. Make frequent back-ups, and continuously test if your altered mesh still imports and displays in WolvenKit, especially when editing vertices!
Exporting the mesh
glTF Binary (*.glb)
WolvenKit <= : Use the . It is pinned to the sidebar on the right.
WolvenKit > 8.8: Use the Export tool. You can toggle it from the "Tools" menu on the top bar.
Select your mesh in the Export Tool and click Export/Process Selected, or simply use Export/Process All.
If the export fails, try unchecking the following properties in the export settings (you have to do this for each individual mesh)
Export Materials
Export Garment Support
You should now havemeshName.glb in your WKit project's
Wolvenkit > 8.8 will by default export with materials for the .
Path example
Assuming you are exporting t2_002_pwa_vest__puffy.mesh, WolvenKit will do the following:
Path of mesh: <yourModDir>\source\archive\base\characters\garment\player_equipment\torso\t2_002_vest__puffy\t2_002_pwa_vest__puffy.mesh
Path of glb: <yourModDir>\source\raw\base\characters\garment\player_equipment\torso\t2_002_vest__puffy\t2_002_pwa_vest__puffy.glb
Blender: Saving the mesh
Some meshes (such as eyelashes and hair) are two-sided. See for details on how Wolvenkit handles that.
glTF Binary (*.glb)
If you have touched the topology, make sure to triangulate your mesh before exporting (Select all in Edit Mode, Ctrl+T)
You can (and should) use the — it will take care of the necessary settings.
Make sure to check the box under Data > Mesh > Tangents, as Wolvenkit will not export without it.
Importing to *.mesh
If you are following a guide with pre-made resources and it tells you to you'll want to follow the advice, as the elements in the exported structure will have different names.
Alternatively, you can run on your blend file, which will automatically fix that for you.
glTF Binary (*.glb)
In Blender, you should have overwritten your previously exported glb. With WKit's , you can now simply Import it back in.
WolvenKit will map any *.glb file under raw to the mesh with the same name under source.
WolvenKit refuses to import if the target mesh doesn't support all bones in the glb or if your mesh's topology became corrupted. If that's the case, check the .
Import/Export: _doubled
Normally, a mesh's backfaces are invisible/transparent - you aren't supposed to see a mesh from below, so it doesn't matter. But some, like hair and eyelashes, are different, and need to be doubled.
When importing via Noesis, you need to do this by hand: duplicate all the vertices in the mesh, and flip the normals.
When importing via WolvenKit, it will automagically do that for you if a mesh name ends with _doubled.
The suffix also indicates that Wolvenkit de-duplicated a mesh on export!
Troubleshooting
If your mesh won't export from Wolvenkit, try exporting it by unchecking the box.
For a list of troubleshooting steps, check the .
Autodesk/FBX (Noesis)
How to import/export meshes with Noesis
Noesis is an alternative to exporting with WolvenKit. There are legitimate use cases for why you would want this. If you don't know them, you probably don't.
TL;DR:
Noesis is outdated. Go import/export .
Explanation
5000 years ago on the slopes of Mount Doom, mods were created with nothing but pickaxes, home-spun hemp, and hex editing. Older guides will refer to Noesis as the way to go — but Wolvenkit has come a long way since then. The import/export is reliable and works, and unless you , you will probably want to .
Given that you're still reading this, you probably have a reason to use Noesis, so here we go.
To use Noesis, you need the .
Tool
Tool version
Exporting from the Wolvenkit project
Navigate the Noesis browser to your file on the disk (you can right-click on the mesh in Wolvenkit and select "Open in File Explorer")
Right-click it in the Noesis Browser and select "Export"
Export with default settings:
Done. You can now import the fbx to Blender.
Blender: Saving for import
Simply export as fbx, Blender's standard settings are fine for Noesis.
Importing
Noesis is an alternative to importing with WolvenKit.
Find your fbx in the Noesis browser
Right-click it and select "Export"
Set the Main output type to .mesh - CyberPunk 2077 mesh [PC]
Troubleshooting
Noesis Split Meshes
Noesis-split meshes are essentially how Noesis copes with higher vertex counts. It will automatically divide up your submeshes into smaller parts, which is why Noesis will often display there being more meshes than intended.
This is caused by the vertex count being too high, and will often result in the applicable submeshes not converting with the rest of the mesh, resulting in those submeshes being non-existent in the .mesh file. The solution is to simply reduce the number of vertices in the given submesh with the goal being to get the count lower than 65,000 vertices on the given submesh.
The best way to tell how many vertices a given mesh has is to open the "Viewport Overlays" drop-down menu and select "Statistics". This will allow for data on the meshes within the .blend. To narrow this down to a specific submesh, open edit mode with that submesh as active and "select all" (CTRL + A) and you will see the vertex count for that submesh.
Once you know how many vertices you have, use either "Decimate Geometry" or "Merge By Distance" to simplify the topography of the mesh, or to merge two or more vertices that are a given distance apart from one another into one.
Once this has been done, export from blender and try the conversion again.
If this doesn't quite do the trick, convert the fbx to fbx (just leave the output type set to fbx) and enter "-fbxmeshmerge" in the advanced options text box before clicking export. (It is recommended that you set an output location when doing this so as to avoid accidentally overwriting the original mesh)
Duplicate meshes detected
This often accompanies the "Noesis-split meshes" warning. A common cause for this is the use of Blender's "duplication" feature. To solve it, follow the steps above for "Noesis-split meshes" then import the resulting mesh back in to blender, and you should see that you have several blank "Objects" that came in along with your mesh. Delete those, export back out of blender, convert the fbx to fbx, then import the result into blender and repeat if needed.
Following the deletion of these Objects, you may notice deformations in the submesh/submeshes, if this is the case, replace the armature (and update the armature modifier) with a new one and export again.
Differences between fbx and glb
There are a few differences between Noesis and WolvenKit when it comes to exporting your meshes:
Autodesk (fbx)
glTF Binary (glb)
You can easily convert between the two formats by hand — or use : Switch to Blender's Scripting perspective, create a new file, paste the contents in, and run it.
Entity: .ent files
All the dirty detes on entity files
Definition
Serves as the top-level container for entities and their properties within the game. Most things that you can see, touch, or interact with have an .ent file somewhere in their hierarchy. Examples are player equipment, weapons, NPCs, interactables (doors, vending machines…)
For the purpose of modding, we distinguish between two different kinds of entity files.
To see a minimal example in action, see the guide for .
Mesh/Component entity (simple entity)
The minimal way of adding something (e.g. meshes) to the game. This entity can be directly spawned (e.g. ) or referenced from within.
For player equipment (weapons and armour), you can use mesh entities to encapsulate parts of your item. You load such .ent files via partsValues, which will be added to the corresponding appearance as if the components had been in the .app file itself.
As of April 2023, partsValues will be ignored for anything but player equipment.
This is good practice to avoid repetition, and also to make it easy on yourself if you want to change paths later in your project (imagine having defined 20 appearances with 5 components each, and then wanting to rename your mesh folder…)
Root entity
The entry point for the game to display an or . This kind of entity only defines those that are shared among all appearances. Meshes are defined in the , where they can be assigned different properties (e.g. materials) per appearance.
From ArchiveXL item additions, this kind of file is usually called a root entity.
An entity file can define multiple appearances, which can point to different .app files.
For , root entities are used as the defining key (one entity => one item, which can have multiple appearances)
Names support , allowing you to load different appearances based on body gender or camera mode. These are only used for player equipment and look like &FPP
What are suffixes?
In a , you can give the game a list of appearances and have them mapped to an by entry name. While that's pretty good already, have you ever wanted to be more specific — for example, "for a male character, use this appearance, but for a female use this other one?"
This is where suffixes come in. You append them to an appearance's name in the , and the game will pick the correct appearance (and the correct, and the correct mesh!) based on the best match.
Find step-by-step walkthrough on using suffixes in the .
If you are registering an item via ArchiveXL, you can define suffixes via appearanceSuffixes: [ … ] in the .yaml file.
Your item will inherit the suffix setup from the $base component. In the example of Items.GenericHeadClothing, that will be
What can possibly go wrong?
These bad beans can be the reason why your item is invisible!! You can and should disable the suffixes if you don't need them.
To do so, add an empty array to the yaml entry:
Which suffixes exist?
For a full list, see For a more in-depth list, check (TODO: Psi's github?)
For clothing items, the following suffixes are relevant:
Suffix
Explanation
Suffix load order
the base appearance (with no suffix)
the most specific suffix collection it can find
Example:
V has a female body gender and you're in photo mode (third person camera). Your base appearance is called appearance_.
full appearance name
3d objects: .mesh files
Documentation on .mesh files and their properties.
This page contains information on .mesh files and their properties.
If you want to export or import mesh files, see here.
If you want to learn how to edit a mesh's appearance, check this guide.
If you want to mess with a .mesh's materials, see .
A mesh file's shadow is defined in via .
In the context of Cyberpunk, a mesh is the file that defines the topology and the materials of an object in the game world.
A mesh can have several submeshes, each of which has own material assignments.
Material assignment
Step 1: Appearances
This page only contains mesh-specific information. Find more details on materials, the .
This is how to determine which parts of the mesh have which material:
ChunkMaterials
You assign materials based on the "chunks" (the individual submeshes) inside a mesh. Open the mesh file in Wolvenkit and open the "appearances" array, then make sure that each of your submeshes has an entry inside the array.
Material definition
Materials are defined in the array materialEntries inside your mesh:
While you can mix external and local materials, you can not mix preloaded and non-preloaded ones. For details, see .
Property
Description
Preload… what?
Many of CDPR's early meshes use preloadLocalMaterialInstances instead of localMaterialBuffer.materials. As far as we are concerned, you can use the two interchangeably, but:
If you are using a mix of local and external materials, you must use the corresponding lists:
local
external
If you mix the two, the materials outside of preload… will appear as transparent the first 1-2 times you trigger your item's appearance.
Step 3: Material definition
A material definition can be in a CMaterialInstance inside the mesh or in a in the project. For local materials, Wolvenkit will display material names as defined in the materialEntries.
For more details on material definitions, .
MaterialInstance: The local material
The materials themselves are inside the array localMaterialBuffer.materials (or preloadLocalMaterials in case of older meshes).
You can't go wrong by using those. However, if you don't have any properties that are unique to your mesh or appearance (for example a custom normal map), you might consider .
A material instance looks like this:
For an overview of materials that you might want to use for something, check .
For how to find out which properties a material has, check .
Material reference:
A relative path to an external material, usually encapsulated in a . Use this if you don't need to add extra properties.
On this page, you can find information how the Cyberpunk player body is set up, along with its file paths.
You can find the list of skin tones, hair and facial expressions under
There is no dedicated guide as for how to create body mods yet, but the process is roughly the same as for creating .
Using Mods
Modding your game, for users
This page contains instructions on installing mods. If you want to create mods instead, check .
If this doesn't cover your needs, maybe check out our more detailed guides:
Variants and appearances
For the purpose of recoloring or exchanging items
Summary
Created by @manavortex
Published November 05 2022
This page is a look-up for or items. For an overview of existing items, see .
As for how to find this information when it's not on the page, check
Finding and reading log files
This page will tell you how to find the right log file for your problem.
A list of framework logfiles
This section has a list of log files by framework. If you've arrived here from one of the troubleshooting channels on , the file you're supposed to find is most likely in this list.
If you aren't looking for a particular log file, please proceed to .
Cheat sheet: Materials
Various kinds of materials, and where to find them
This page contains a brief overview of existing materials. For a more in-depth explanation as well as downloadable example files, check .
For an overview of Multilayered properties, check .
For preview images of multilayered materials, check . (This page needs further data!)
numerical index of corresponding material in target list (as defined by isLocalInstance)
isLocalInstance
Selects the material target list.
True: local material in localMaterialBuffer.materials or preloadLocalMaterialInstances
False: material reference inexternalMaterials or preloadExternalMaterials
For more information on this, see the page for local/external materials.
name
unique name of material, used to select the material via chunkMaterial
Example: A mesh with two materials, one of them a local instance, one of them an external .mi file
You may have to create additional entries in "chunkMaterials": Either duplicate an existing entry from the right-click menu, or select the array and use the yellow (+) in the side panel.
How you split your .app files is largely a matter of taste. At CDPR, they usually shove everything into one file.
Defines how your item will look if a certain hair type is loaded (e.g., hide the back half of a bandana for long hair).
When resolving the appearance name via rootentity.ent, the game will look for &Short, &Long, &Dreads, &Buzz, &Bald
ignored: you are not in first person camera
appearance_&Female&TPP
best match! The game will use this one!
itemsFactoryAppearanceSuffix.Gender
This item is gendered
When resolving the appearance name via rootentity.ent, the game will look for appearanceName&Female and appearanceName&Male.
itemsFactoryAppearanceSuffix.Camera
This item has special rules for first and third person camera
When resolving the appearance name via rootentity.ent, the game will look for appearanceName&FPP and appearanceName&TPP.
itemsFactoryAppearanceSuffix.Partial
If the current item has hide_T1part part and slot OuterChest is not hidden, will search rootentity.ent for&Full or &Part
appearance_
Found first, then ignored because a more specific appearance exists.
This entity adds four physical mesh components, which will appear when it is spawned. It does not reference an .app file and does not have appearances.
itemsFactoryAppearanceSuffix.HairType
appearance_&Female&FPP
Vehicle Drive Model Data Record
%USERPROFILE%\Saved Games\CD Projekt Red\Cyberpunk 2077
C:\Users\<yourusername>\Saved Games\CD Projekt Red\Cyberpunk 2077
The first thing you will be told on Discord is to read this guide.
When installing a mod, make sure to install all of its dependencies. You will find a list on the Nexus description tab under "Requirements".
If you do not do this, your mod will not work.
You need to . Without it, most of your mods will not work.
You mod Cyberpunk 2077 by adding files to your game directory. There is no need to overwrite base game files, since the game natively supports modding.
The game directory is the toplevel folder of your game install.
Unless you changed the default settings, it will be installed to:
You can install mods by hand, by using Vortex, or by using Mod Organizer 2 with additional steps detailed here.
Regardless of your past experiences, the Nexus mod manager works reliably and well for modding Cyberpunk, as long as you do not install more than ~250 REDmods.
Dependencies / Requiremends
Although Cyberpunk natively supports modding, this out-of-the-box support is extremely limited. To allow modders greater freedom, a number of frameworks have been created to allow e.g. adding items, influencing the weather, or add flying cars.
Since this kind of mod interacts with the game's code on such a fundamental level, they are prone to breaking whenever CDPR changes their API. This is the reason why game updates break mods — we recommend to turn off auto-update and manually upgrading once the frameworks you need have been brought up-to-date.
Unless they are marked as optional, you have to install the dependencies, and their dependencies as well.
If you don't, then your mod will not work.
Overview of mod folders
TL;DR: you can ignore this.
This list is supposed to give you an overview of which files go where. It is not a bucket list of things you have to install.
Folder path in your game dir
Description of folder
/archive/pc/mod
holds .archive files from non-REDmods
/bin/x64/plugins
Cyber Engine Tweaks () ()
/mods
Directory for REDmods
Installing and activating REDmod
If REDmod is not installed and activated, your mods in /mods will not load.
Loading a mod as REDmod means that Cyberpunk will precompile it and integrate it into the game's file, optimizing load times. By contrast, vanilla mods (from /archive/pc/mod) will be loaded individually and might add to your load times.
If you had terrible experiences with Vortex for other games, be assured: Cyberpunk integration is working extremely well. Maybe give it another chance?
Manual install
"Manual install" is a rather glorified term for "extracting the downloaded archive into your game directory". However, you have to make sure that the right files end up in the right folders.
You can inspect the file structure by simply opening the downloaded file, or by using this feature on Nexus (unless a mod author has disabled it):
The file structure is different for REDmods and non-REDmods. Mod authors usually tell you which file is which, though.
REDmod:
If the downloaded archive contains an info.json and a folder named archives, you're dealing with a REDmod.
Extract the entire folder into /mods/. You should have /mods/ModName afterwards.
Non-REDmod
In your archive, find the folders corresponding to this overview and extract them directly to your game directory. Their content will be added to the already existing files, overwriting anything that needs to be replaced.
Anything else
Some mods are just a loose collection of files and it's up to you and the mod's install instructions to put them in the right place.
As a rule of thumb: usually, but not always…
.archive files go into /archive/pc/mod/
.xl files go into /archive/pc/mod/
.reds files go into /r6/scripts/
.lua files go into a subfolder of /bin/x64/plugins/cyber_engine_tweaks/
For everything else, this wiki has a dedicated troubleshooting page that has solutions to many common problems. If that doesn't cut it, you're welcome to find us on Discord in the #mod-troubleshooting channel (but your first answer will be a link to that guide).
The paths below are given relative to your Cyberpunk 2077 install directory.
Name of framework
Path to log file
redscript
r6\logs\redscript_rCURRENT.log
red4ext
red4ext\logs\red4ext.log
ArchiveXL
red4ext\plugins\ArchiveXL\ArchiveXL.log
Finding the log files
If you don't want to download and run script files from the internet, you can go here and complete the steps by hand. Otherwise:
Download this script (right-click -> save as)
You can (but probably don't want to) look at the code on Presto's github repository.
Now, do either of the following things:
Move it to your Cyberpunk game folder and double-click it
Drag-and drop your Cyberpunk game folder on the file that you downloaded
The script will have created a folder _LOGS in your Cyberpunk directory, where you will find a file with everything it has found..
Alternatively: By hand
Browse to your Cyberpunk game folderand use the windows search to search for *.log.
Make sure to include the asterisk and the dot: *.log, as you will otherwise see files that you don't care about.
Make sure to run this in the game's root folder, unless you have already narrowed down the problem (e.g. if it's a CET mod, you can run this search in bin\x64\plugins\cyber_engine_tweaks).
The list of results should look like this:
This will give you a long list of log files
You can sort this list by file size, name, or date modified by clicking on the corresponding header.
With a few exceptions, log files have the name of their mod. If they don't, check what folder they're in.
There's too many of them!
If you're drowning in log files and have no idea how to filter them, you can deleteor remove them. Don't worry, they will be re-created on next launch.
Don't delete anything that isn't Type: Text Document ending in .log! Doing that will break other mods or even your entire install.
Now, restart your game and do whatever you did to make the error appear. Then, search the Cyberpunk directory for *.log again.
Finding the relevant log file
You can ignore files that
have a date modified older than your last game launch: they won't have any information about your problem
have a size of 0: they're empty, the mod in question never initialized.
Sort the files by size (if you just deleted them) or by date modified (if you didn't)
Open each of the files in a text editor (such as Notepad, it's installed with Windows). The relevant information will be at the very bottom.
You are looking for lines with error or warning. If you want to see what they look like, scroll down to the .
If the log file doesn't have any, ignore it. Close it and proceed to the next file.
You found errors: Congratulations, you've found at least silver. Check for how to proceed.
You found warnings: These might indicate that you're on to something, but don't let them panic you. If the mod is doing what it should, just ignore them. You can already, or keep looking for errors.
Making sense of them
Error
There's definitely something going on here, you're on the right track!
Errors look like this:
An error in the log files almost always means that something exploded in a way that nobody has planned for.
If the file is directly in bin\x64\plugins\cyber_engine_tweaks, that means CET is broken and you need to troubleshoot it.
If the file is in a subfolder of bin\x64\plugins\cyber_engine_tweaks, you have found a broken mod, but CET mods won't break the game. In this case, treat it like a warning.
If the log is anywhere else, you have found .
Warning
If the mod with the warnings is working, you can ignore them.
If the game is crashing or if you can't find any errors, you can try the bisect method or troubleshoot it and hope that you're lucky.
If your warning isn't listed below, use your own best judgement.
Field with this name is already defined
This might indicate that a Redscript mod is loaded twice. Search the Cyberpunk root folder the mod name and make sure that you have no duplicates. If you're uncertain about this, try the bisect method on your r6 folder.
Use engine\materials\metal_base.remt, the example below has been copied from base\environment\architecture\watson\japan_town\building\hotel\motel_notell\room\_plastic_black.mi
BaseColor
base\materials\placeholder\white.xbm
Normal
optional: path to your normal map
Roughness
optional: path to your roughness map
RoughnessBias
0.200000003
Liquid
Use base\materials\fillable_fluid_vertex.mt or see here for details.
Referenced from base\appearances_mappings.json, base\vehicles\base_types_map.csv maps vehicle names to their respective .ent files. The names are defined in each vehicle's .app file as baseEntityType.
Name
.ent File
Arch_Nemesis
NPCs and their files
Heroes, villians, as long as their interesting (and we've located them) their here
Most of them are pretty easy to guess/find but theres the odd curveball.
Character
Entity File
Appearance File (appearanceName)
MLSETUP Builder
The tool of your choice for editing multilayered materials
Introduction: What is MLSB?
MLSetupBuilder (commonly referred to as "MLSB") is a Cyberpunk 2077 modding tool to comfortably edit MLSetup files, developed and maintained by Neurolinked.
There is a dedicated channel on the and a thread on the , where you can find a chat history full of undocumented features as well as previews from the most recent development versions.
- archive
- pc
- mod << .archive files from non-REDmods go here
- bin
- x64
- plugins << Cyber Engine Tweaks goes here
- mods << REDmods go here
- r6 << redscript folder
- tools
[2023-04-15 12:04:18.956] [error] |Something| Some Explanation
[2023-04-14 20:28:18 UTC+01:00] [1234] [ErrorSource] DoSomething(): Error ! Some Explanation: Some Details
[WARN - Thu, 13 Apr 2023 21:54:13 +0200] At Path\to\Cyberpunk 2077\r6\scripts\something.reds:1234:1:
@addField(inkScrollArea)
^^^
field with this name is already defined in the class, this will have no effect
The standard neon for advertising fonts in Night City. Comes in many colours, can be customized via textures and gradients. Check "city_deco_font" for examples.
base\fx\shaders\hologram_two_sided.mt
half-transparent holo material, allows three colours to tint it
BaseColorScale
Colour as x/y/z values (color picker blend file here)
For integration with Wolvenkit, install MLSB as a plugin:
Click on "Home" in Wolvenkit's title bar
Select "Plugins" in the left sidebar
If MLSB is installed, you'll see an "Update" button, otherwise, it will say "Install".
Do that.
We will now launch MLSB and do the initial setup.
In Wolvenkit's Plugin view, click "Open", this will open a Windows Explorer with the install folder (Cyberpunk 2077\tools\neurolinked\mlsetupbuilder)
Navigate to the folder with the higest version (at the time of this guide, that is MlsetupBuilder-1.6.7)
Start MlsetupBuilder.exe
Optional: You can pin that file to your start menu or create a shortcut if you want to launch MLSB directly.
Usage
To make the most of MLSB's features, you will want to configure it first. However, you can start using the tool right away.
Here's how (or scroll down for the screenshot):
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 project explorer
Select "Convert to JSON"
This will generate an mlsetup.json file in your project's raw folder.
This folder will only be visible in the "source" or "raw" tab of your project explorer
Right-click on the newly created mlsetup.json file
Select "Open in MLSetupBuilder"
Using MLSB
As of Version 1.6.7, this is what you will see now:
Start by importing the file from the preview. That will populate the Layer Config box with the MLSetup that you just loaded.
The preview was hiding an empty 3d viewport. To use that, you will need to configure MLSB first, but you can already click through the individual layers and assign material properties (such as roughness, normal strength, base material and colour) from the "Material Properties" panel.
Don't forget to hit "Apply" after you have changed a material.
Once you're done:
select File -> Export
overwrite the original mlsetup.json
switch back to Wolvenkit
in the "raw" folder, right-click on your file
select "Import/Convert from JSON"
Congratulations — you now have an .mlsetup! If you pack your mod and launch the game, you should now see your changes.
About That 3d Viewport
This is where you can load models from the game for a direct preview which layer will affect which parts: simply click on the "Library" button.
MLSB Library
Here, you can either browse to your model directly, or use text search:
After selecting a model, you can close the library browser again. Now selecting a layer will show you directly which parts of the mesh it corresponds to.
That's it! Happy recoloring!
Configuration
Connecting to Wolvenkit
We're assuming that you have already configured Wolvenkit. If you haven't, please do so now.
In Wolvenkit, extract a partial depot (Generate Materials).
Note that this window shows you the Depot Path for Step 5.
While it is doing that (it may take a few minutes), download WolvenKit Console and extract it to a folder of your choice.
Now, switch to MLSetupBuilder.
Select "File -> Preferences"
Apply the following settings:
Game archives folder
C:\Your\Path\To\Cyberpunk 2077\archive\pc\content
uncook folder
You can find this folder in your WolvenKit's settings as "Depot Path" (you've seen it in the window from Step 1)
Wolvenkit Depot Path
You can find this folder in your WolvenKit's settings as "Depot Path" (you've seen it in the window from Step 1)
Wolvenkit-CLI.exe
The executable of Wolvenkit Console from Step 2
Press Ctrl+R to reload MLSB and make sure that the settings are applied.
Building the depot
Again, this step is optional, you can use MLSB straight away.
Open the menu "Build" and select "Repository" to uncook the archives:
Select the following settings (if you want to uncook everything, this step can take several hours, so we'll only do the essentials for now)
Click "Uncook".
Wait. Do not interact with the program in any way until the process has finished - especially interacting with the console might just freeze up the entire windows cmd process. This is not MLSB's fault, but due to a Windows standard implementation.
This process can take some time — if you have selected everything, it can be several hours on slow machines. (You should've listened during step 1, choomba ;))
When the process is complete, close the Depot Generator window.
Optional: if you can't see any changes, press Ctrl+R to relaod MLSB.
Building the Microblend Depot
Repeat Step 1 from MLSETUP Builder, but select Microblends this time
In the bottom left corner, hit "Start"
Wait.
When the process is complete, close the Depot Generator window.
Optional: if you can't see any changes, press Ctrl+R to relaod MLSB.
That's it, you're done now and can use the 3d viewport!
Troubleshooting
Help, my Layer Config List says object Object
You need to install the most recent version. If that doesn't make the error go away and your most recent version is something with 1.6.7, update the interface.js — download it here from Neurolinked's github repository, then replace the file with the same name in MLSB's install directory, subfolder resources\app\js.
If you have installed it as a Wolvenkit plugin, that directory will be Cyberpunk 2077\tools\neurolinked\mlsetupbuilder.
There's an exception when generating my depot!
Does the progress bar still move? If yes, then you're good - ignore this.
If not, you haven't left your fingers off MLSB and need to start over. Click "Uncook", then go afk until it's done.
If that doesn't help either, it's worth trying Wolvenkit Console's latest Nightly.
This is the main vehicle record in TweakDB, referenced from VehicleObject in the game, that references all the other vehicle-related records. Below is the .tweak vehicle template (that's also in the TweakDB) that you can customize for creating your own vehicle. The name Vehicle.vehicle_template near the top will need to be customized to your vehicle name.
is an important field here, because this is the file that ties our record to the resource files needed for rendering.
Multilayered
The substance style super shader
About
A significant portion of assets for Cyberpunk 2077 leverage the complex multilayered.mt supershader. The supershader has several different component files which are used to create masks to blend procedural textures without baking them. You can read more about this technique in by CDPR Technical Art Director Krzysztof Krzyścin.
MLMASK files are the core element of the substance-style integration. These files contain an array of up to 20 textures which are used to control the blending between pre-defined surfaces called mltemplates. These mask textures are more-or-less 1:1 with substance-style layer masks.
Demonstration of how mlmask files are used to mask meshes. Each mask represents a separate surface.
As shown above, each mesh using the multilayer shader uses a unique mlmask file that is hand authored by CDPR artists. To take effect in game, each mask file is linked by the mlsetup file.
What is the mlsetup?
MLSETUP files are fairly self-explanatory when considering the name, multilayer setup. These files correspond with an mlmask file and are responsible for setting up parameters for each layer from the mlmask. Each layer within an mlsetup contains information very similar to materials or shaders.
File structure of mlsetup viewed with WolvenKit
MLSETUP Definition
Property
Description
colorScale
Sets a color from within the file
material
Path to file
matTile
Tiling multiplier for the main surface texture
What is the mltemplate?
MLTEMPLATE files are the actual visible surfaces that appear on meshes using the multilayered.mt supershader. The multilayer templates include a wide variety of surfaces such as steel, iron, aluminum, plastic, nylon, linoleum, carpet, soil, grass, rubber, concreate, and everything else imaginable. Each template can use a unique color, normal, roughness, and metallic PBR texture. The mltemplate files are selected from within each layer definition of an mlsetup file. Meshes can blend up to 20 mltemplate surfaces into a single material by masking them with the mlmask.
File structure of mltemplate viewed with WolvenKit
A sample preview of some materials created by mltemplate files
An example how colour and roughness affect the material in-game
A list of modding frameworks and links to their documentation
You're probably used to the term Core Mod from other games. However, the technical term for these kinds of mod is aframework, which is what they're usually referred to by Cyberpunk modders.
The whole world: .streamingsector
Documentation on .streamingsector files
If you want to know how to find a streaming sector, see .
For a list of interesting locations, see .
For a guide how to modify streaming sector files, see .
Material properties explained
How materials work, and how you can configure them
If you want to learn how material assignment works for the object, check
For information on material templates, see
Refitting: Mesh sculpting techniques
Best Practices for actually changing meshes
Summary
Created by @manavortex | Edited by Na
Published January 29 2023
This guide will give you a number of techniques when it comes to editing meshes in Blender (displayed version: 3.4.1)
Assumed skill level:
- You have
- You are able to read and comprehend instructions.
While the game natively supports mods, this would have had us limited to replacing already existing items, but we wanted flying cars. So a bunch of brilliant people drilled deep into the code of Cyberpunk 2077 and created a bunch of tools that let us do more.
The most prominent example of a framework mod is the Skyrim Script Extender — fortunately, Cyberpunk 2077 is rather more stable.
Since this kind of mod interacts with the game's code on such a fundamental level, they are prone to breaking whenever CDPR changes their API. This is the reason why game updates break mods — we recommend to turn off auto-update and manually upgrading once the frameworks you need have been brought up-to-date.
Existing Frameworks
The first-level frameworks (CET, Redscript and Red4ext) allow access to the game's functions and types, which are known through reverse engineering. The second-level frameworks (e.g. ArchiveXL, TweakXL, Codeware, SystemEx) make use of these to offer further methods of interaction. For details, see below.
Redscript
Redscript (Nexus | GitHub) is an open-source programming language and toolkit, natively working with Cyberpunk 2077's scripting runtime. Essentially, it is extending the already-existing Redmod scripting system by including data from the decompiled game script blob final.redscripts.
It allows additions and edits of the game's high-level logic and functions, including additions through Red4ext. The scripts are compiled into r6/cache/modded and are preloaded together with the rest of the game's cache.
Some examples for existing mod include, but are not limited to
changing combat balance
editing NPC behaviour
altering the interface
adding or removing UI widgets
Cyber Engine Tweaks (CET)
Cyber Engine Tweaks (Nexus | GitHub) is a first-level framework with a LUA wrapper, which will let you access anything exposed via RTTI by RedScript and Red4ext. On top of that, it lets you bind hotkeys for custom functions and interact with the game's Tweak database at runtime.
Additions made to the tweak database via CET are not persistent; you will need TweakXL for that.
Lots of mods and scripts run on top of CET, tweaking the game in various ways from changing the weather to adding a wardrobe system before CDPR added a wardrobe system.
The perhaps most prominent example is Appearance Menu Mod (wiki | Nexus), which turns Cyberpunk 2077 into The Sims: Capitalist Dystopia.
RED4ext
RED4ext (Nexus | GitHub) is Cyberpunk 2077's equivalent to Skyrim Script Extender. Aside from being required for many mods, it is a perquisite for other core dependencies such as ArchiveXL, TweakXL, and Equipment-EX.
With Red4ext >= 1.13, you no longer need cybercmd. Make sure to uninstall it!
Rather than being added to the game's cache for preloading, Red4ext reads and modifies the game's memory at runtime. This happens via RTTI, which is the game engine's original system for scripting and serialization.
Technical detes
Red4ext and its plugins are written in C++. The framework itself has two components:
The shared library exposes types, functions and classes via RTTI to make them available in-game. This contains reverse-engineered information from redscript.finals as well as code defined by its plugins.
The plugin loader will activate .dll files from red4ext/plugins (such as ArchiveXL, TweakXL...). They can be considered standalone programs that are activated through Red4ext and unlock other areas of Cyberpunk's code. This contains essentials like
game version checking
logging
hooking
As a modder, you can only use types and functions that are already registered via RTTI.
ArchiveXL
ArchiveXL (Nexus | GitHub) allows us to load custom resources into Cyberpunk 2077. Working under the hood, it is the essential tool to add rather than replace.
TweakXL (Nexus | GitHub) is an extension of RED4ext to modify the TweakDB by writing script extensions in both YAML and RED format. By loading files from r6/tweaks, it can alter predefined records in Cyberpunk's database, changing properties such as weapon damage or the number of hitpoints.
By interacting with REDEngine 4's database, it lets you view and alter information about game entities and behaviour in real time (accessible via Cyber Engine Tweak's Tweak Browser tab).
Equipment-EX
Equipment-EX (Nexus | GitHub) makes use of every single one of the frameworks mentioned above to overhaul CDPR's wardrobe system. Extending it from 6 slots to more than 30, it lets you save an unlimited number of outfits and supports modded items.
Codeware
Codeware (Nexus | GitHub) is not strictly speaking a framework but a library, exposing Red4ext's extra functionality to redscript (keyword @native). By defining utility functions and -classes, the mod enforces best practices, reducing the likelihood of crashes.
For example, while you could always see an NPC's appearances in Wolvenkit, it was not possible to access that information at runtime.
Log files for the frameworks
Logs: Cyber Engine Tweaks
This will tell you what mods and scripts CET is loading, and if there have been any errors in the process.
If all goes well, it will look like this:
Logs: Redscript
It will tell you which .reds files it has been loading, and if any of them failed.
Please note the warning in the log:
If the mod is working, ignore it
If the mod isn't working, this tells you what to check. You can't have mods installed twice!
If all goes well, it will look like this:
Logs: RED4ext
It will tell you which of the framework DLLs it has been loading.
If all goes well, it will look like this (version numbers are fake):
Logs: ArchiveXL
Tells you which .xl files have been found and processed and what it has been adding into the game files upon startup.
If it loads correctly, you will see something like this:
Note that the example contains a bunch of warnings. That indicates problems with the modded files (which I ignore, since they are working),
Logs: TweakXL
Tells you which tweaks have been read and processed, pointing out errors and warnings in the process. If your custom item additions don't work, you might find a hint here.
If it loads correctly, you will see something like this:
StreamingSectors are the files that define the world in Cyberpunk, they tell the engine what goes where, and define everything from the meshes you see and how you can interact with them, to the locations of lights, sounds and fx. They call up the NPCs, they define the minimap.
The fundamental bits of the structure are 2 main lists, the nodes, and the nodeData. The nodes define the assets that make up the sector, and the nodeData tells the engine where to put them. Theres a nodeRef list as well, which seem to be the link that quests use to tie in to triggers etc via the .scene files. Theres also some bits that define variants, that seem to be how sectors change after missions, not worked those out yet.
Theory
Streaming Sectors contain the world's data, holding a node tree that includes all its models and entities.
Other than the world environment, streaming sector files can also define
navigation
sound
collision
illumination
as there are several types.
LOD data and grid sizes
The world is broken up into a grid, with several sizes of squares available (bit like graph paper with major and minor grid lines). The size of the grid in use is dependent on the Level of Detail (LOD) of the sector file your looking at, which is the last digit of the filename.
Chunk sizes are as below.
LOD
Interior
Exterior
0
32
64
1
64
128
For every location, there can be multiple overlapping levels of LOD sectors with progressively more detail as you go down the levels.
For instance, Lizzies bar is located at approximately -1200, 1562, 22:
Via AMM: this targets the bouncer rather than the bar, but they're right next to each other, so it's fine.
Filenames are structured as sectortype_X_Y_Z.streamingsector . If you preview a sector in wkit, the axes are shown as Z=-Y and Y=Z.
Calculating the files
I've left the detail of the process below for record, but if you just want a list of sectors I've created a python script to find the ones that a set of co-ordinates are in. You can find it HERE. Simply enter the co-ordinates in the player_loc dict in block 3 then run all blocks. You'll be given 2 lists containing of all the interior and exterior sectors which contain the co-ords within their bounding boxes. The list also shows the distance from the centre of the sectors to the co-ords given.
From those co-ordinates we can calculate the sector files for interior/exterior sectors by dividing by the grid size for the LOD and rounding. (ie 1200/32=38 etc)
LOD
Interior
Exterior
0
-38_49_0
-19_24_0
1
-19_24_0
-9_12_0
At the level 0 files the whole building isn't covered by 1 sector, so you end up needing 4, conversely the exterior level 2 is several city blocks.
Note that the numbers are simply duplicated and rounded down.
No, I don't know how you round down 2*16 to 31 either.
Some locations are partially defined in quest sectors, where parts of the location are locked away behind story triggers (for example half of V's apartment, as a lot of decoration will only be shown after completing quests). The exact process isn't fully understood as of May 2023.
Node Types
List below is the node types I've found so far while building the blender sector import script.
You can see a material's default properties by opening the .(re)mt file in WolvenKit and inspecting the parameters array. Any properties that you don't overwrite by adding them to your CMaterialInstance or .mi file will take the default properties specified in the file.
Roughness/Metalness
A roughness/metalness preview. Yes, it's not a sphere.
Multilayered Material
For a full documentation, check the corresponding page.
To set it up, use these keys for the "values" array of your material:
GlobalNormal
path\to\normal.xbm
MultilayerMask
path\to\mask.mlmask ()
MultilayerSetup
path\to\material.mlsetup
an example multilayered material
Textured Material
The most commonly used material for anything textured is engine\materials\metal_base.remt. Despite its name, this material isn't necessarily metallic.
You can also use this material as emissive, for a documentation, see below.
The material can be transparent, you need to set the enableMask flag to True and make sure its not set to False anywhere higher in the material chain. Note this is not in the values, its just below the baseMaterial definition. When set the material will use the alpha channel of the BaseColor.
To make your mesh load a texture, use the following CKeyValuePairs in your material's "values" array:
BaseColor
path to your texture.xbm (Diffuse/Albedo)
Roughness
path to your roughnessMap.xbm (if you have one)
Metalness
path to your metalnessMap.xbm (if you have one)
Normal
path to your normalMap.xbm ()
example use of metal_base.remt as a textured material
The .xbm is a container around the texture. Export the xbm to png via WolvenKit.
If your texture has any brightness issues in-game, toggle around the isGamma flag during import.
The expected isGamma settings are:
normals: false
diffuse/albedo: true
anything that is used in .inkatlas files: true
Further properties
LayerTile
Material scaling (zoom on surface)
> 1 zooms in, >1 zooms out
Plastic
The most commonly used material for anything textured is engine\materials\metal_base.remt. Despite its name, this material isn't necessarily metallic.
To turn the material into plastic, use the following CKeyValuePairs in your material's "values" array:
You can make engine\materials\metal_base.remt glow by adding the correct parameters, or you can poke through the game files and search for emissive > .mi to find Cyberpunk material templates to learn from.
path to emissive texture, e.g. engine\textures\editor\white.xbm
The texture works like an alpha mask.
EmissiveEV
float, e.g. 2.0: emissive brightness. Brightness varies depending on your colour. Unless you want to actively blind people, you might want to stay below 4.
EmissiveColor
Glow colour as RGB (copy from e.g. mi_neokitsch_fridge_z_emissive.mi)
Texture that your screen should display, e.g. base\materials\placeholder\black.xbm
LayersSeparation
1
ScanlinesIntensity
0
ScanlinesDensity
0
Find a ready-to-use example of a turned-off screen here.
Liquid
Cyberpunk has its own liquid shader(s) such as base\materials\fillable_fluid_vertex.mt. Projecting this material onto a submesh will turn the submesh into a transparent container filled with the liquid you specified. If you flip the container on its head, the fluid will drain to the bottom and fill it up again.
To control the offsets, you need to adjust the vectors FluidBoundingBoxMax and FluidBoundingBoxMin.
It shares various properties (such as IOR, FresnelBias, BlurRadius) with the glass shader.
TintColor
liquid's color as RGB (copy from e.g. mi_neokitsch_fridge_z_emissive.mi).
FillAmount
float, e.g.0.0: Probably works in combination with the bounding box. You'll have to experiment.
FluidBoundingBoxMin
FluidBoundingBoxMax
Vectors (X, Y, Z, W) controlling the maximum distance from the container's walls. Each value is a float (decimal) speficying the axis in question - you'll simply have to play around with them (you can ignore W).
For a bottle material I've used
Max: 0.03, 0.03, 0.155
Min: -0.03, -0.03, 0.09
You can find video guides for refitting linked on the community guides page
Prerequisite: Deleting shapekeys
Before you start editing your mesh, you should delete its shapekeys. This is necessary for the Sculpt Mode to show your changes in real time, and you don't need them anymore after editing your mesh.
Order matters, because deleting a shapekey will apply it. Start at the bottom!
Some people have been told to delete the Armature modifier before sculpting. That's not necessary!
Sculpting
The obvious approach is to change your mesh by moving vertices. However, this will take a very long time and probably be frustrating. A faster way is to use Blender's Sculpt Mode.
The downside of the sculpt mode is that it can edit only the selected mesh.
For a workaround, see here.
The Sculpt Mode is pretty much What You See Is What You Get.
The easiest tools for beginners are Grab,Elastic Deform, and Smooth
In the "Tool" panel (Toggle shortcut: N), you can optionally enable symmetry (blue on the picture below).
Elastic Deform and x-symmetry are your friends!
A useful shortcut to keep in mind is F, which will let you change the cursor size.
You can import a body mesh as a reference.
You will find the player's body under
base\characters\common\player_base_bodies\player_female_average\
base\characters\common\player_base_bodies\player_male_average\
Affecting only parts of the mesh
Method 1
You can hide those parts that you don't want to sculpt.
Use the Edit Mode (Shortcut: Tab) to make a selection. Then, leave only those parts visible that you want to affect before switching back to Sculpt Mode.
Useful hotkeys:
H: Hide selection
Shift+H: Hide everything but selected
Alt+H: Unhide everything
Method 2
You can also use the Lattice Deform Method below to selectively edit only part of the mesh.
Method 3
You can use Blender's mask brush and function in Sculpt Mode to mask the parts that you do not want to sculpt.
Affecting Several Meshes
Material Separation Method
This method is a workaround that you can use when you have only 2-3 meshes. You can fuse all meshes together, then split them apart after you're done.
Pros:
Relatively simple, and good to make small, simple changes to 2-3 meshes.
Allows symmetrical sculpting.
Cons:
Destructive editing
Can be a little time-consuming because you have to join, separate, and rename meshes every time you want to import it back to WolvenKit.
Let's assume that we're sculpting Rogue's pants. For surface material assignment, the seams are an own submesh — the pants (submesh_00) are coloured via multilayered material, while the seams have a variation of metal_base with coloured stitches.
We don't want to edit those separately, so we'll fuse them into one mesh, sculpt everything in one go, and then split them apart again.
To allow splitting, we need to make sure that every submesh has its own unique material. Select the mesh, switch to the "Material Properties tab on the right", and duplicate the assigned material:
You can rename the material to e.g. "seams", but it's not necessary.
Before the next step, make sure to remember the submesh numbers, because you need to restore them later. Changes in the submesh order will mess up material assignment in WolvenKit.
You can create a copy by duplicating the meshes (shortcut: Shift+D)
Now, join the meshes together — hold CTRL, select the main mesh, and join the meshes together (shortcut: Ctrl+J)
You now have a single mesh which you can sculpt to your heart's content.
Once you're done, you can separate the meshes again. Switch to Edit Mode, then select something that belongs to the former submesh. From the menu, pick the following entry:
Select -> Select Similar (Hotkey: Shift+G) -> Material
Split your submesh by material
Then, split off the selection into its own submesh again:
Right-Click -> Separate (Hotkey: P) -> Selection
The Lattice modifier deforms the base object according to the shape of a Lattice object.
Pros:
Can edit as many meshes at once as you want, no matter what armature they are parented to.
100% Non-destructive sculpting.
No need to separate, rejoin, and rename meshes after sculpting is done.
Good for making small, local changes to multiple meshes.
Edits can be stacked on top of each other by stacking modifiers.
Does not have to go through all the steps like Material Separation Method each time you want to import to WolvenKit.
Cons:
Trying to select desired vertices of the lattice can be difficult.
Can be hard to restrict edits to areas not covered by the lattice, thus possibly making unwanted edits.
Does not allow symmetrical sculpting.
Begins by adding a Lattice to the scene. In Object mode, go to the menu Add > Lattice. Reshape the lattice so that it covers the part of the base meshes that you want to edit or all the meshes that you want to edit.
Go to the Object Data Properties panel, and increase the resolution as you wish. for most edits, 6-10 levels are fine.
A lattice I made to do some edits to the hand only.
Now select your base mesh(es). Add the Lattice modifier to the mesh then choose your Lattice in the Object option.
To apply this modifier to all base meshes, while still selecting this mesh, hold Ctrl then select all the meshes that you want to edit, or hold Shift then drag to select all the meshes that you want to edit. Click the drop-down menu arrow in the modifier, then click Copy to Selected.
Go to edit mode, select vertices and start moving them around to edit your base mesh(es).
When you are done, you do not have to apply this modifier. As long as your export settings are correct, and you remember to delete all Shape keys, the changes will be applied automatically upon export. That's why this method will make all the changes non-destructive and you can revert to vanilla by toggling the modifier.
You can stack modifiers to make desired changes to your mesh(es).
Mesh Deform Modifier Method
The Mesh Deform modifier allows an arbitrary mesh (of any closed shape) to act as a deformation cage around another mesh. This method resolves many problems of the previous methods.
Pros:
Can edit as many meshes at once as you want, no matter what armature they are parented to.
100% Non-destructive sculpting.
No need to separate, rejoin, and rename meshes after sculpting is done.
Easier control than editing vertices of a lattice.
Allow symmetrical sculpting.
Edits can be stacked on top of each other by stacking modifiers.
Cons:
If you have a lot of meshes and the vertex count is relatively high, the waiting time to bind can be just a little long.
In this example, I will work with the head mesh (1 submesh) and the body mesh (10 submeshes).
In Object Mode, duplicate everything by right-clicking on the collections and hit Duplicate Collection .
Still in Object Mode, select all the newly duplicated meshes and join them together by using hotkey Ctrl + J or navigate to the menu > Object > Join .
Now you should have an unified, joined mesh along side the vanilla meshes.
This mesh will be our cage mesh, we will use it as a proxy to make edits to the main meshes. Now we have to prepare it so that it works well as a cage.
Add a Remesh modifier to this mesh, use Voxel setting. Decrease the Voxel Size until the human shape is fairly recognizable but the mesh is not too high poly. Also, enable the Smooth Shading option. Below is my setting for this model.
Now, apply the modifier by hovering the mouse above it and using the hotkey Ctrl + A, or click on the drop-down menu arrow and hit Apply.
Now we need to "bloat" the cage mesh so that it covers the whole base meshes. We will make use of the Shrink/Fatten function. You should toggle visible the base meshes along with this cage so it's easier to see. Switch to Edit Mode, and select all vertices by using the hotkey Ctrl + A. Hold Alt + S, then drag Left Mouse button to fatten the whole mesh. For finer control, also hold Shift while dragging it. Make sure that it completely engulfs the base meshes.
Your bloated meshes should look something like this, it should completely cover the base meshes.
Switch back to Object Mode, select all the base meshes instead. Add a Mesh Deform modifier, then select the cage mesh in the Object option. Then select the drop-down menu arrow, click Copy to Selected to apply the same modifier to all base meshes. Then go to each meshes and click the button Bind to bind them to the cage. Depending on the complexity and vertices count, it can take anywhere from 1 to 30 seconds to finish binding.
You have finished binding all meshes to the base meshes. Now, all the editing you made to the cage mesh in Sculpting and Editing Mode will be reflected on the base meshes.
To see the edits easier, select the cage mesh, then go to Object properties. Scroll down to the Viewport Display setting menu, in the Display As option, chose Wire. This will render the cage as wire and you can see the vanilla meshes below as you edit.
Hint: to make symmetrical changes, enable the symmetrical editing in Sculpt Mode. If your cage doesn't cover the whole base meshes, you can add a Mirror Modifier to the cage mesh. It will be reflected on your base meshes as well.
After finishing sculpting, you don't have to apply the modifier to the base meshes. As long as your export settings are correct, and you remember to delete all Shape keys, the changes will be applied automatically upon export. That's why this method will make all the changes non-destructive and you can revert to vanilla by toggling the modifier.
You can cleverly combine these methods to make changes to your mesh as you desire.
[INFO - Sat, 22 Apr 2023 10:08:08 +0100] Using defaults for the script manifest (manifest not present)
[INFO - Sat, 22 Apr 2023 10:08:08 +0100] Compiling files: C:\Games\Cyberpunk 2077\r6\scripts\a-bunch-of-stores-atelier-store.reds, C:\Games\Cyberpunk 2077\r6\scripts\virtual-atelier\vendor-preview\GarmentItemPreview.reds
[WARN - Sat, 22 Apr 2023 10:08:08 +0100] At C:\Games\Cyberpunk 2077\r6\scripts\appearanceChangeUnlocker\mirrorUnlocker.reds:38:1:
@addField(inkScrollArea)
^^^
field with this name is already defined in the class, this will have no effect
(a bunch of these warnings)
[INFO - Sat, 22 Apr 2023 10:08:08 +0100] Compilation complete
[INFO - Sat, 22 Apr 2023 10:08:08 +0100] Output successfully saved in C:\Games\Cyberpunk 2077\r6\cache
Cyberpunk 2077\red4ext\logs\red4ext.log
[2023-04-22 10:08:05.698] [RED4ext] [info] RED4ext (v4.7.11) is initializing...
[2023-04-22 10:08:05.698] [RED4ext] [info] Game patch: 4.511 Hotfix 999
[2023-04-22 10:08:05.698] [RED4ext] [info] Product version: 4.511
[2023-04-22 10:08:05.698] [RED4ext] [info] File version: 4.7.11.13361
[2023-04-22 10:08:05.717] [RED4ext] [info] RED4ext has been successfully initialized
[2023-04-22 10:08:05.816] [RED4ext] [info] RED4ext is starting up...
[2023-04-22 10:08:05.816] [RED4ext] [info] Loading plugins...
[2023-04-22 10:08:05.816] [RED4ext] [info] Loading plugin from 'C:\Games\Cyberpunk 2077\red4ext\plugins\ArchiveXL\ArchiveXL.dll'...
[2023-04-22 10:08:05.874] [RED4ext] [info] ArchiveXL (version: 4.7.11, author(s): psiberx) has been loaded
[2023-04-22 10:08:05.874] [RED4ext] [info] Loading plugin from 'C:\Games\Cyberpunk 2077\red4ext\plugins\Codeware\Codeware.dll'...
[2023-04-22 10:08:06.180] [RED4ext] [info] Codeware (version: 5.7.11, author(s): psiberx) has been loaded
[2023-04-22 10:08:06.180] [RED4ext] [info] Loading plugin from 'C:\Games\Cyberpunk 2077\red4ext\plugins\RedHotTools\RedHotTools.dll'...
[2023-04-22 10:08:06.262] [RED4ext] [info] RedHotTools (version: 1.6.11, author(s): psiberx) has been loaded
[2023-04-22 10:08:06.263] [RED4ext] [info] Loading plugin from 'C:\Games\Cyberpunk 2077\red4ext\plugins\TweakXL\TweakXL.dll'...
[2023-04-22 10:08:06.291] [RED4ext] [info] TweakXL (version: 4.8.12, author(s): psiberx) has been loaded
[2023-04-22 10:08:06.291] [RED4ext] [info] 4 plugin(s) loaded
[2023-04-22 10:08:06.291] [RED4ext] [info] RED4ext has been started
[2023-04-22 10:09:13.572] [RED4ext] [info] RED4ext is shutting down...
[2023-04-22 10:09:14.297] [RED4ext] [info] ArchiveXL has been unloaded
[2023-04-22 10:09:14.322] [RED4ext] [info] TweakXL has been unloaded
[2023-04-22 10:09:14.353] [RED4ext] [info] RedHotTools has been unloaded
[2023-04-22 10:09:14.468] [RED4ext] [info] Codeware has been unloaded
[2023-04-22 10:09:14.469] [RED4ext] [info] 4 plugin(s) unloaded
[2023-04-22 10:09:14.488] [RED4ext] [info] RED4ext has been shut down
In Blender, check your shapekey section. It should look like the green box (or be empty).
If it does not, you need to apply any extra shapekeys, because Wolvenkit will ignore them on reimport. Expand the box below to find out how.
Get the edit out of the shapekeys
Do the following things:
Duplicate your mesh: Select it in Object Mode, then press Shift+D
Click the arrow under the - button next to the shapekey box
Click New Shape from Mix
Now, delete all the other shapekeys (select them and click -)
Delete your new shapekey as well. That will apply it.
In Object Mode, select the duplicate of your mesh (that still has all the shapekeys)
Delete your extras. That will reset it to an un-refitted shape.
Go to Edit Mode (hotkey: tab)
Select all vertices (hotkey: A)
Delete all vertices (hotkey: X)
Go back to Object Mode (hotkey: tab)
Select your shapekey-less refitted mesh
Select your empty mesh
Join them together (hotkey: ctrl+J)
If everything went well, you should now have a mesh with Wolvenkit-compatible shapekeys!
Tangents
You get an error message like this:
Message: One or more Geometry in provided GLTF doesn't contain Tangents data. Tangents must be included within glTF files.
Use the Cyberpunk Blender IO Plugin to export
Quick, easy, recommended: the plugin will tell you exactly what's broken and how to fix it. Download it here.
Alternatively, you can check by hand:
Expand if you like to suffer
Check if your mesh is triangulated. If you aren't sure whether or not it is, go into edit mode, select everything, and go to Face -> Triangulate (Shortcut: Ctrl+T)
Check your export settings and make sure that you have the correct box checked upon export:
If the error persists, check that each of your submeshes has an UV map:
If not, you have to create one (and probably UV unwrap your mesh).
Bone: neutral_bone not present in export Rig(s)/Import Mesh
The neutral bone is created by the glb export plugin when there are vertex groups without a parent bone. WolvenKit will not let you import if there is a mismatch.
Your armature in Blender needs to have a bone for every vertex group in the submesh, and there must not be vertices with no vertex group assigned.
The following two scripts help you finding and/or fixing the problem. Switch to the Blender Scripting perspective and create a new, blank text file. Then, toggle the Blender system console to see their output (Blender: Window -> Toggle System Console)
Missing bones
To find which bones you're missing, you can use this script, which will print their names to console.
Vertices without weights
You can use this Python script to either select or auto-delete vertices with no weight.
Option 1: Fuck those bones
You can import the mesh with Noesis, which will not do any of these checks. For that, you need to import/export via .fbx.
Since noesis expects differently-named submeshes under the root armature, you'll want to export the mesh via noesis, join your changed meshes on those under Noesis_Root, and import it again.
Caution: You'll have to rotate your armature in this case.
While this will get your mesh into the game, the missing bones mean that parts of it won't move the way you expect it!
Option 2: The Netrunner suit
The armature from the following mesh has a lot of bones and will often resolve most of your issues:
Try using the Netrunner body as a base for import. You can use Wolvenkit's feature for this.
To create more submeshes, you can either
Try the import setting
create more submeshes with the correct naming in Blender, e.g. submesh_01_LOD_1, submesh_02_LOD_1
Option 3: Transferring bones
It's time to play 3d puzzle and assemble bones from multiple sources. Unfortunately, there is no simple solution for this yet. You need to
find the bones that your armature is missing in other meshes
, which you should do with the linked Python script
and finally reimport everything back into Cyberpunk.
Everything else
WolvenKit will not import a mesh that has any kind of issues. Those include, but are not limited to:
non-flat faces
zero faces/edges
loose vertices/edges
There is no guarantee that any of the steps below will actually solve your problem.
Edit Mode
In Edit Mode, you can find a few commands in the Mesh -> Clean Up menu:
Delete Loose
Split Non-Planar Faces
Split Concave Faces
Merge By Distance
If you select your whole mesh, Merge By Distance will merge the individual parts, obliterating the seams. To avoid that, make sure to do them one after another:
- Select a vertex/edge/face in Edit Mode
- hold down Ctrl Num+ to select everything connected
- use Merge By Distance before proceeding to the next part of your mesh
It's still broken
Your last option is the 3d print tool to (hopefully) find out what is wrong with your mesh.
Fortunately, the tool is free, easy-to-use and already included in your Blender.
If you don't have a 3d print entry in the tools of your 3d viewport, you might need to enable the plugin in Blender's settings first.
Use the 3d print tool in edit mode to directly fix your issues
Zero Edges: Those are bad, fix them (click on them, then press X and just delete them)
Non-Flat Faces: Those are even worse, as they can make the game crash. You need to split them up until they are flat, or investigate the surrounding edges/vertices to see what's going wrong here.
Zero Faces: Only fix if you have <100 of them — the tool doesn't always identify them correctly (the mesh analyzed above was h0_000_pwa_c__basehead, which is absolutely fine).
In-Game
My mesh won't show up
In Blender
make sure that you have exactly one UV map
check Face Orientation — most materials won't show backfaces (red). You can import submeshes with the suffix _doubled to make WolvenKit generate them for you, like it does with hair.
In Wolvenkit
When saving your mesh, check the console for errors. In version >= 8.9.0, a basic material validation is taking place.
If you don't see any warnings, make sure that the resource paths in your mesh are correct and that you aren't loading invisible textures.
My mesh won't move at all
Some meshes require an entAnimatedComponent along with the garment's component. Check here for details.
Changes from Blender are missing in-game
For example, you have moved something, but the change doesn't show in the game: this most often happens when you change things around in edit mode, since they are stored as object properties rather than applied immediately.
Select the object in edit mode
Press Ctrl+A
Select "All Transforms" to apply all transformations.
My mesh is moving weirdly
E.g. you've changed a shape, but now everything moves at an offset.
As stated in the importing/exporting guide, it is easy to fuck up the mesh's properties, and this is most likely what happened. The easiest way to "fix" this is to apply your shape deformation to the original object.
Replacing the vertices
Import the original object into Blender, without any of your changes. If you have to, reexport the working file from Wolvenkit.
In Object Mode, select all meshes under the reimported armature (the original ones).
Switch to Edit Mode and select all vertices (Ctrl+A)
Delete them (x, vertices, Return)
Go back to Object mode
For each of your edited objects:
select the submesh that you edited (submesh_00_LOD_1)
select the empty submesh from the reimported armature (submesh_00_LOD_1.001)
You can now delete the empty armature and export the other one for re-import.
After joining the submeshes
My mesh is completely warped
If you have added the item via ArchiveXL or swapped out an in-game item with something that belongs in a different slot (e.g. a jacket on the head slot), you might have to fix the corresponding entity file.
My mesh is string cheese/exploding vertices/a puddle on the floor
Looks like we have guests from beyond the Blackwall
GarmentSupports
To check if it's this, equip only the edited item. If it breaks as soon as you put on another clothing item with garment supports, then the solution below applies.
Option 1 (likely to work): Import your mesh with garment supports
On the .glb import setting, check the "" box.
Option 2 (guaranteed to work): delete GarmentSupport from the mesh
This will break automatic shrinking when you put clothes over your item. But hey, if the alternative is a broken mess…
2
128
256?
2
-9_12_0
-5_6_0
worldBendedMeshNode
worldBuildingProxyMeshNode
Proxy mesh for building at further distance. Textures are normally embedded so cant export automatically currently.
worldCableMeshNode
worldCollisionNode
partial support, defines 3 types of collision, box, capsule and mesh. Can import the first 2.
worldCompiledCommunityAreaNode_Streamable
worldCompiledSmartObjectsNode
worldDestructibleEntityProxyMeshNode
worldDeviceNode
worldEffectNode
worldEntityNode
Defines an object defined by an ent file (door, vending machine, fan etc)
worldEntityProxyMeshNode
worldFoliageNode
worldGINode
worldGIShapeNode
worldGISpaceNode
worldGenericProxyMeshNode
Proxy mesh for objects at distance.
worldGuardAreaNode
worldInstancedDestructibleMeshNode
as worldInstancedMeshNode but breakable
worldInstancedMeshNode
Instanced copies of a static mesh uses a worldTransformBuffer in the nodeData to define the number of copies and positions of all the copies
worldInstancedOccluderNode
worldInterestingConversationsAreaNode
worldInteriorAreaNode
worldLightChannelShapeNode
worldLightChannelVolumeNode
worldPerformanceAreaNode
worldPhysicalDestructionNode
worldPopulationSpawnerNode
worldReflectionProbeNode
worldRoadProxyMeshNode
Road Mesh.
worldRotatingMeshNode
worldStaticDecalNode
Static Decal, nodeData has x,y,z not sure how engine decides what to project to
worldStaticFogVolumeNode
worldStaticMeshNode
Static mesh, nodeData has position data
worldStaticOccluderMeshNode
worldStaticParticleNode
worldStaticSoundEmitterNode
worldTerrainCollisionNode
worldTerrainMeshNode
The ground, textures are embedded so cant export automatically currently.
Installing and setting up Vortex Mod Manager, the recommended way to install, manage, and upgrade mods.
Windows 10 or higher is required to use Vortex mod manager. If you are not using Windows, see our Manual Install page.
Vortex is a multi-game mod manager developed for and by NexusMods, the website where most are hosted. Here you can download mods manually or with Vortex and keep track your download history.
To use Vortex, you need an account there. If you don't have one, you can sign up – don't worry, it's free.
Why do I need this?
Technically speaking, you don't. You can or use (but without our support, sorry, choom). However, Vortex for Cyberpunk is the most beginner-friendly way of managing your mods and will save you a lot of hassle.
If you have PTSD from modding Skyrim or Fallout with Vortex, be assured that Vortex for Cyberpunk is integrated extremely well. Go ahead, give it a try!
If you run into issues with Vortex that aren't addressed in this guide, you can contact or join our and find (volunteer) help in the #vortex-support channel.
TL;DR
Your staging folder must be on the same drive as your game installation
Your staging folder must not be your game install directory
Vortex has . If you put wrong options, mods can go brr.
Download
Once you are signed in on Nexus, it's time to download Vortex Mod Manager.
If you can download it on your own, you can skip to the or section of this guide.
Click , it will take you directly to the download page
Select the "Manual Download" option on the first entry:
You'll now see a download page. If you don't have Nexus Premium,
Select "Slow Download"
Wait through the five seconds cooldown
Installation
Once you run the installer, you may get a prompt from Windows, asking you if you want to allow this app to make changes to your device. Select yes, and then Vortex will begin its install.
If you chose the custom install location option, you will a prompt asking you where you would like to install Vortex to. Further instructions will assume an install location of C:\Program Files\Black Tree Gaming Ltd\Vortex
Congrats! You've finished installation! Vortex should launch automatically and you can now move onto setup.
Setup
Here is where we get into the weeds, the particulars of Vortex setup before we can use it.
If you can setup Vortex on your own, skip to the section of this guide. (Why are you reading this?)
Logging into Nexusmods
If you are already logged in, proceed to the next section ""
If Vortex didn't open by itself, open it from the start menu.
Log into Nexusmods by clicking on the red circle in the top right of your client
You will see either a browser window or an error message that Vortex couldn't open one – in this case, copy the URL in the box at the bottom and open the browser window yourself
Optional: log into nexusmods (if you aren’t)
Allow Vortex to access your Nexus account by clicking "Authorize":
Click "Log in to Vortex":
Instead of the red icon, you should now see your profile picture and username from nexusmods.
Vortex: Adding Cyberpunk
This section will tell you how to add Cyberpunk to Vortex's managed games.
On the sidebar on the left side of your dashboard, click "Games"
In the page that now shows, type "Cyberpunk" into the search bar
Hover over its thumbnail and click "manage"
The extension should download automatically
You need to restart Vortex – agree to the prompt.
Optional: If Vortex was able to auto-detect your game install, you are done now and can proceed with the section.
Vortex can now manage your game! Proceed to the next section, .
Settings
This section tells you how to set the recommended settings in Vortex, grouped by tab. If a tab isn't covered, there are no recommendations and you can do what you like.
Start by clicking "Settings" in the left sidebar of your Vortex Dashboard, then select the first tab.
Interface
The settings here tell Vortex what to do with your mods as it gets them.
Here's a screenshot of the recommended settings with an explanation below:
To put a mod in the game, Vortex requires you to complete four steps. The folders for these are configured in the .
Downloading: Putting the mod into Vortex's download cache, either by clicking the button on Nexus or by dragging-and-dropping an archive onto the client. The archive will now live in Vortex's download directory.
Installing: Unpacks the mod and copies it to Vortex's staging directory.
Enabling: This mod should be included in the next deploy
In theory, you can configure Vortex so that you hit the download button on the website and it will download, install, enable and deploy for you. The downside with that is that you might not notice errors as they pop up in the background, which is why we recommend doing that one single click by yourself.
V2077 Settings
This setting controls the automatic REDmod conversion. For an explanation of what that means, see .
This only has one setting, but it's recommended to keep it toggled "on" unless otherwise directed specifically by install instructions on a mod.
Mods
This section controls Vortex file storage. It's mostly a matter of personal preference and disk space availability on your end.
Mods: Staging
This folder MUST be on the same drive as your Cyberpunk.exe, or the deploy might fail.
Where Vortex keeps its mods, ready to deploy them into the Cyberpunk game directory.
The default folder location is {USERDATA}{game}\mods, which resolves to C:\Users\YourUsername\AppData\Roaming\Vortex\cyberpunk2077\mods
You can keep it as this, or you can make a folder for it in a place you can easily access it, like C:\Games\Mods. Wherever you decide, you want to make sure it is accessible and you can remember it in case of issue.
Mods: Download
Where Vortex stores downloaded archives. Can be wherever you like, even on a different drive.
We recommend keeping an extra folder in there for manually downloaded mods, as Vortex can manage these as well – you just have to drag-and-drop them into the client.
Dashboard
Finally, we will return to our dashboard.
No matter what settings you chose in interface, you should still have a section labeled "Tools", where at this point you should at least see four things, the last of which will be disabled:
It can be helpful here to toggle "Enable Toolbar" above it so that you can always see them wherever you are in Vortex.
These are different options to launch the game via Vortex.
Click on the three dots next to "Launch Game with REDmods Enabled" and set it as primary. This will make Vortex pick this option when you click on the Cyberpunk 2077 picture on the far left.
"REDmod Deploy Latest Load Order" is also incredibly useful if your mods are acting up: Just using the "deploy" button on the main management page can fail – by using this button, you can debug your REDmod deployment.
Use
You're almost to the mod page, but first, you need to get some mods. Let's start by installing the , which contains everything that other mods require.
Click on "Collections" in the sidebar
Select "Discover more collections."
Wait until the selection page pops up.
This will open a window in Vortex, with the thumbnail and name of the collection, which profile you want to install it to if enabled, and any additional install instructions.
Click "Install Now": This collection has no extra instructions.
You will get a new window for the first mod: click the "Download" button
The Nexus "Slow/Fast" download button for the corresponding version will open. The correct version has been picked by the mod author.
Click "Slow Download" (unless you're a premium user)
Rinse and repeat this process until you have all mods in the collection.
As this is a collection, each mod will – regardless of our settings – be installed as its downloaded. As they deploy, you will see a screen pop up with a lot of code flowing by. Don't worry, this is just Vortex deploying your REDmods.
Before you play your game, check the bell in the top right corner next to your profile picture. Click it to expand the notifications. What you want to see is all green or blue--any red or orange issues will need to be resolved before starting your game.
At this point, assuming your notifications are all green or blue, you can safely play your game. However, you won't notice many changes, as the framework mods aren't doing much on their own...
Starting up the game
The game should always launch with just the core frameworks enabled. If it doesn't, head over to the and make sure that you can launch and start a new game.
Since this is your first time launching the game with mods, you should see a prompt to bind an overlay key for Cyber Engine Tweaks (CET). (If it does not, check .) You can assign whatever you like, this button will hide or unhide the CET overlay.
While you have it open, you can navigate to the "Settings" option, and select "Skip Start Menu" and "Suppress Intro Movies" (if you don't want them). The setting will become active after the next restart.
Make sure to click save to keep your choices.
Downloading a mod with Mod Manager Download enabled
Let's get a mod that'll change something. For this example, we've picked KS UV framework, which will change V's feet.
Usually, you want to start at the description page to see the exact file that you need to download. For a detailed guide on the parts of a mod page and how to navigate Nexus, see our Downloading Mods section.
For now, you can simply go straight to the page of the KSUV mod.
So that you can see the changes in-game immediately, to know if you've installed correctly, you will download the first option, "Recommended. UV Framework New High Heel Feet with Custom Textures - Classic Install". This will change the feet visually now, and allow for custom textures later. Click "mod manager download". A window will pop up telling you that you need another mod "" installed before downloading this. You can do this after downloading this mod; your feet just won't fit in any vanilla shoes until you do. For now, click download to continue to the final download page, where you will select "slow".
Once your timer counts down, it should begin downloading in Vortex. The setting "Bring Vortex to foreground when starting downloads in browser" is enabled by default, so if you didn't change it, the Vortex window should pop up now. Otherwise, click over to it, and you should be able to see a 1 next to Downloads in the sidebar.
Assuming you're using recommended settings, the mod won't have installed itself, so you will click on "Mods" in the left sidebar. You should already have mods installed, enabled, and downloaded from the collection. Scroll down until you locate the blue "Never Installed" button next to the mod you want to install. Click it once, and if you're using recommended settings, it should enable and deploy automatically.
For this mod, a window will pop up, warning you that it may need manual adjustment, due to multiple .archive files. These are important windows to pay attention to, because many mods that have multiple files do require manual adjustment. This information is usually found on the description page, which is why you want to read it carefully before download.
For this mod, however, that is ok, and intended. You may simply click "Understood".
To test your new body framework mod, simply select "New Game" and pick a female-bodied V. If the feet are flat, it is not installed correctly. If they look a little funny, like barbie feet, you've done it right.
Downloading a mod manually to manage in Vortex
Let's install a mod without a mod manager download button and manage it in Vortex to show you how it works.
Mod authors sometimes disable mod manager integration for a variety of reasons. Usually, Vortex can handle these files just fine – if not, it will complain about it, and loudly so.
Click , which will take you straight to the files tab.
Select whichever one you like, like the "Arey", third option down.
Optional: Check what it looks like
Scroll down to the third option, Arey Hair PHYSICS ENABLED
The file doesn't have any particular instruction.
Optional: view the file contents – they sometimes contain helpful information:
Manually download the file – you know the drill by now.
Return to the Vortex "mods" page. You have two ways to install the mod now:
Drag-and-drop the downloaded file on your client, or
You should now have successfully installed the file.
If you have used the recommended settings, it should enable and deploy automatically. Otherwise, you need to do that yourself.
Start the game
If your hair is two big buns--you did it! If it's just the normal single bun with braids, go back and try again.
Congratulations! You know how to use Vortex!
Optional, depending on your browser: Select your download location for files that you don't want to keep
Wait until the installer is downloaded
Run the installer: either
select the file from your download history (Ctrl+J for most browsers)
go to your download directory and double-clicking the file
Proceed with the steps in the next section
You will now see a popup complaining about "Game support not installed". Don't panic, this is expected!
Click the "download" button at the bottom of the window to install the Vortex plugin for Cyberpunk:
Vortex will tell you that it couldn't detect your game install and prompt you to set it manually. Click "Continue".
In the explorer window that now pops up, navigate to the folder containing your Cyberpunk exe (e.g. C:\Games\Cyberpunk 2077\bin\x64)
Once you are in the right folder, click "Select Folder"
Deploying: The mod has been copied from Vortex's staging directory to your Cyberpunk game directory.
If your browser doesn't open automatically, copy the url starting with users.nexusmods in the box
Allow Vortex to authorise your account
Log into Vortex and close the page
The games page, with the extension dialogue open
Recommended automation settings
This option can also show up on the dashboard.
Mod staging folder default location
The default tools on the dashboard.
Collection installation confirmation window
The download window for a mod in the collection.
Notifications are ordered with most recent at the top--which means there was a successful REDmod deployment notification AFTER the failure, so the failure can be safely dismissed.
CET overlay on the main menu screen on the Settings option.
The example mod's "Mod Manager Download" button
The warning window that pops up in Vortex for mods with more than one .archive file
The left is what you're shooting for--if you see the right, the mod isn't working.
Arey hair by Wingdeer
The naming convention tells us that it's a hair replacer from Wingdeer for the female body gender, changing hair 48, There's also a preview picture included.
The "Install From File" button
Vanilla hair 48
Arey hair in place of hairstyle 48
Cheat Sheet: Hair
Overview of hair related things
Summary
Created by @manavortex
Published November 04 2022
Updated February 3 2023
If you want to change an NPC's hair instead, you can check or guide.
To look up hairstyles in more detail, you can use .
Name of meshes by index
These names correspond to the mesh files.
To find a hair's .app file, search the correct mesh in Wolvenkit, then right-click on it and select "find files using this".
List has been confirmed working before 1.6, but might need updating (especially since new hair was added)
Colour in files by index
Colour in CC
Name in Files
Hair .ent files
Hairs and all their components are assigned and defined via . You can find them here:
The last number in the file name matches the first number in the :
e.g., if you wanted to edit the entity file for female V's hair 28 hh_083_wa__ponytail_01, you could search for
To find a hair's root entity, repeat the same process with its .app file
This page acts as a look-up table for photo mode. For theoretical knowledge, check the Animationssection, for more hands-on advice on creating own photo mode stuff, see Animations/Poses in the Modding Guides section.
.anims
You can find all photo mode animation sets in the following folder:
You can find the following files there:
Entity
Action
Idle
Face
Poses and files
idle
The Photo Mode idle animations are named and indexed as follows:
index
animation name
translation
Weapons
We need guns, lots of guns.
Weapons dont seem to have ent files that tie them together in quite the same way as most things they do however have app files that have the component lists, so who cares?
(Just to be difficult some rifles are referenced by a random file in the quests folder called empty_entity.ent, and the katanas and knives seem to have ents)
If your wanting to import to Blender Sim created a bunch of dummy ent files to let you import things:
Generally speaking the files are in \base\weapons then organised by type and then name. But searching an app file then right clicking and find used files is faster than browsing, so here are the file names.
We do not have official documentation from CDPR about how shaders are used by artists. Thus any 2d/3d artist is looking at hundreds of black-box shaders with unknown usage. This is extremely demotivating for anyone looking to bring new assets to life with REDengine. The following list of tables is an attempt to make life easier for artists by using the community to document commonly used shaders.
About the documentation
The name and path of each shader will be documented by the header.
Next we are using a table for each texture parameter with the exact name listed by CDPR in the w2mg file, how REDengine uses each specific RGBA channel, and the usable range of the channel if not 0-1/0-255.
When applicable, vertex color properties will be listed underneath the texture table with a similar format.
Shaders
skin
Texture
Red
Green
Blue
Alpha
Vertex Colors
Description
Properties
Description
Notes
The DetailNormal texture contains generic normal details that are shared between most faces. This is not a tiling/procedural texture. The DetailNormalInfluence scalar parameter can be used to lower the intensity to simulate makeup or synthetic skin.\
The MicroDetail texture contains a microblend tiling texture used to add procedural detail to the normal map. We believe the Roughness texture blue channel is used to mask parts of the face from exhibiting this detail, such as the lips, eyelids, and ears.
mesh_decal
Texture
Red
Green
Blue
Alpha
Properties
Description
Notes
DiffuseColor multiplies against the texture color to add procedural color
glass
Texture
Red
Green
Blue
Alpha
Vertex Colors
Description
Properties
Description
Note
There are a number of ways you can colorize your glass. GlassTint is the texture used to determine glass color. TintColor is procedural color. TintFromVertexPaint value determines how much vertex color affects the glass color. GlassTint seemingly has the highest priority, as in it will override other color parameters. Below is a test result from the process of making a glass wing.
There are many different other glass shaders, this one is just the most basic that is used for small objects.
television_ad
Texture
Red
Green
Blue
Alpha
Properties
Description
Note
AdTexture: TV screen will play looping animations that are actually sprites like a .gif. We believe this is for optimization purposes since videos are heavy.
TilesWidth, TilesHeight, and PixelsHeight combine will help the game define the dimension of your tile (sprite) on the sprite sheet.
You should calculate your sprite sheet dimension so it completely fits in a square sheet. For example, a simple dimension is 5x5 tiles with 300x300 pixel sprite. Such a dimension will produce animation with 25 frames of a square sprite.
It's recommended that you use free tools like to make .gif and convert it into a sprite sheet for AdTexture
There are many screen shaders, this one is used for small TV screens.
If used cleverly with a properly done mesh, you can make use of this shader to put animation on your clothing or other items
Scalar, vector, color, and other properties will follow with their own unique description table.
An asterisk (*) is used to notate some degree of uncertainty, or need for more independent testing.
SecondaryAlbedo
?
?
?
?
Normal
Normal
Normal
None
?
DetailNormal
Additive Normal
Additive Normal
None
?
Roughness
Roughness
None
MicroDetail mask (0.5-1)*
?
MicroDetail
Additive Normal
Additive Normal
None
?
TintColorMask
?
?
?
?
Detailmap_Stretch
Additive Normal
Additive Normal
None
?
Detailmap_Squash
Additive Normal
Additive Normal
None
?
EmmisiveMask
?
?
?
?
Bloodflow
?
?
?
?
?
MicroDetailInfluence
Controls MicroDetail normal intensity
TintColor
?
TintScale
?
SkinProfile
?
EmissiveEV
?
CavityIntensity
?
BloodColor
?
DetailNormalInfluence
Controls DetailNormal normal intensity
SecondaryMask
?
?
?
?
NormalTexture
Normal
Normal
None
?
NormalAlphaTex
?
?
?
?
NormalsBlendingModeAlpha
?
?
?
?
RoughnessTexture
Roughness*
Roughness*
Roughness*
?
MetalnessTexture
Metalness*
Metalness*
Metalness*
?
?
UVRotation
?
UVScaleX/Y
?
SecondaryMaskUVScale
?
SecondaryMaskUVInfluence
?
NormalAlpha
?
UseNormalAlphaTex
?
NormalsBlendingMode
?
RoughnessScale
?
RoughnessBias
?
MetalnessScale
?
MetalnessBias
?
AlphaMaskContrast
?
RoughnessMetalnessAlpha
?
AnimationSpeed
?
AnimationFramesWidth
?
AnimationFramesHeight
?
DepthThreshold
?
MaskTexture
?
?
?
?
Roughness
Roughness
Roughness
Roughness
?
Normal
Normal
Normal
Normal
?
Control how much vertex color will tint the glass color. If set to max value, vertex color will completely replace TintColor.
FrontFacesReflectionPower
How much front face reflect light
BackFacesReflectionPower
How much back face reflect light
IOR
Index of Refraction?
RefractionDepth
?
FresnelBias
?
GlassSpecularColor
Color of light reflected from glass
NormalStrength
Control how much normal map affects mesh
NormalMapAffectsSpecular
Control how much normal map affects reflected light
SurfaceMetalness
Metalness
MaskOpacity
?
GlassRoughnessBias
?
MaskRoughnessBias
?
BlurRadius
?
BlurByRoughness
?
DirtTexture
Color
Color
Color
Color
How much screen scanline is visible
PixelsHeight*
Height of sprite in pixel
EmissiveEV
Energy Voltage of light emission
EmissiveEVRaytracingBias
Energy Voltage of light emission by Raytracing
EmissiveDirectionality
?
EnableRaytracedEmissive
Enable Raytraced Emission
BlackLinesIntensity
?
BlackLinesRatio
?
BlackLinesSize
?
LinesOrDots
?
DistanceDivision
?
Metalness
?
Roughness
?
IsBroken
If enabled, the animation will have a broken TV overlay effect
UseFloatParameter
?
UseFloatParameter1
?
AlphaThreshold
?
DirtOpacityScale
Opacity of Dirt Texture
DirtRoughness
Roughness of Dirt
DirtUvScaleU
UV Scale of Dirt Texture
DirtUvScaleV
UV Scale of Dirt Texture
HUEChangeSpeed
?
More examples of such sprite sheets can be found in the path below
Albedo
Color
Color
Color
?
Red
Ambient Occlusion*
Green
Subsurface Scattering Mask
Blue
Improved Facial Lighting Mask
SecondaryAlbedoInfluence
?
SecondaryAlbedoTintColorInfluence
?
DetailRoughnessBiasMin/Max
?
DiffuseTexture
Color
Color
Color
Opacity Mask
VertexOffsetFactor
?
DiffuseColor
Procedural Color
DiffuseAlpha
Alpha
GlassTint
Color
Color
Color
?
Red
Color
Green
Color
Blue
Color
TintColor
Procedural Color
Opacity
Overall Opacity
OpacityBackFace
Opacity of back face
AdTexture*
Color
Color
Color
Color
TilesWidth*
How many tiles are on the horizontal axis of the sprite sheet
TilesHeight*
How many tiles are on the vertical axis of the sprite sheet
Full list of components, organized by hierarchy, useful for researching and documenting new components.
If you decide to document a component, make a new expandable entry on on the Documented Components page, followed by the discovered behavior and usage and link back to that in this list.
This file contains a list of appearances with their associated components. To load them, you require a .ent.
Holds a list of components.
.ent (Entity)
Root entity
The entry point for the game to display an or . This kind of entity usually doesn't have components by itself, but only points towards the where they are defined.
From ArchiveXL item additions, this kind of file is usually called a root entity.
Mesh entity / Component entity
For player items, an .ent file can serve as a wrapper, splitting components out of the .app file by putting them in their own file.
Components
Not a file type but an internal data structure and part of or files. Components are how the game adds anything to the in-game world, from pag3d data over player interaction prompts to explosion sounds.
.inkatlas (Texture mapping)
.mesh (3d object)
A 3d object, holding , , and .
A mesh can have several submeshes, which can be displayed or hidden via .
.mi / .mt / .remt
A material definition for a shader. You can assign those to CMaterialInstance entries in your mesh and then define their qualities by changing their parameters.
For further detes on materials, see .
For an explanation on .mi files, see .
Relevant properties:
.streaingsector (world data
This file holds world environment information and -properties. Due to its complexity, information is grouped on its sub-page.
.xbm (Texture)
A regular texture file. Can be exported to .png via WolvenKit, edited, and imported back into the game.
If you stick to the game's naming schema, Wolvenkit will auto-detect the right import settings for you.
Normal maps
Can be either blue or yellow (inverted), both exists. For a guide how to make your own, see .
Cyberpunk normal maps are swizzled (a technique originally employed in DTX-5).
The red channel stores the X axis
The green channel stores the Y axis
The blue channel is empty, since the Z-data will be calculated from red and blue.
Relevant properties:
W2RC File Format Table
Extension
Description
Fully Parsed
Generic Format
<explanation>
Generic FIle Format Table
Extension
Description
Archive Format
File Structure
Name
Type/Size
Info
Header
Name
Type/Size
Info
Custom Data (WolvenKit)
The following data only applies for archives created with WolvenKit
Name
Type/Size
Info
File List
Name
Type/Size
Info
File Record
Name
Type/Size
Info
File Segment
Name
Type/Size
Info
Pathfinding/AI
Animation graph
Animation data
Mesh appearance configurations
?
Terrain related
?
?
?
?
Bink video
Bink video
Camera curve preset
?
Character editor preset
Minimap
Quest related
Cutscene related
See mlsetup
See anims
See app
Configuration for credits
6-sided cube texture
?
?
?
?
Entity
Environment definition
?
?
?
?
?
?
Font
Foliage brush
Destructible foliage element
?
Game main configuration file
?
?
?
?
?
Hair profile
?
UI animation
UI texture atlas
UI character related
UI font
UI
UI settings
UI
UI
UI
UI
UI
UI
UI
UI
Quest info
Quest info
?
?
?
?
?
?
?
?
Pins on map
Mesh/model
Instanced external shaders/materials
Masks for multilayer supershader
Setup file for multilayer supershader
Template file for multilayer supershader
Blend shapes/shape keys
Base shader
navmesh
AI navigation meshes
?
Audio
Audio
Particles
Nvidia PhysX related
Nvidia PhysX related
Nvidia PhysX related
Point of Interest Map pin
?
Quest
Quest progression
regionset
?
Similar to mt, difference is unclear
Resource list
Rig/skeleton for animation
Cutscene
Cutscene versioning
?
?
Skin profile
?
Terrain
The world in manageable pieces
Terrain
Links all the sectors
Terrain
Multiple textures
?
?
?
Leftover mesh file with RED3 extension
Leftover mi file with RED3 extension
?
Texture
Texture
Files
data
Raw file data
File List
See below.
IndexPosition
uint64
Offset of beginning of file list
IndexSize
uint32
Size of file list
DebugPosition
uint64
Always 0
DebugSize
uint32
Always 0
Filesize
uint64
Size of file (excluding Filesize)
CustomDataLength
uint32
WolvenKit only
Size
int32
Size of uncompressed data
ZSize
int32
Size of compressed data
PathCount
int32
Number of custom paths
PathStrings
zstring[PathCount]
Custom file paths
CRC
uint64
Checksum of ???
FileEntryCount
uint32
Number of files
FileSegmentCount
uint32
Number of file segments
ResourceDependencyCount
uint32
Number of resource dependencies
FileRecords
[FileEntryCount]
See below.
FileSegments
[FileSegmentCount]
See below.
ResourceDependencies
uint64[ResourceDependencyCount]
NumInlineBufferSegments
uint32
Number of inline buffers
SegmentsStart
uint32
Index of the first
SegmentsEnd
uint32
Index of the last
ResourceDependenciesStart
uint32
Index of the first resource dependency
ResourceDependenciesEnd
uint32
Index of the last resource dependency
SHA1Hash
uint8[20]
SHA1 hash of the file
Size
uint32
Size of uncompressed data
Different per material — see parameters/[2] for a list of properties
e.g. BaseColor, Metalness, NormalStrength
or VectorField, FresnelColor, Albedo
IsGamma
Override in-game gamma (lighting)?
- Set to "false" for normals
- Set to "true" for diffuse/albedo and any parts of the UI
If your mods are causing trouble, here's what you can do
dThis page contains troubleshooting information for people who are using mods rather than making mods. You will find step-by-step guides, grouped by different problems.
Did you know? You can us your browser's search function (Ctrl+F) to quickly find your problem on the page – simply type a word from your error message.
Navigation
Before you start debugging, make sure that
your graphics driver is up-to-date
Before you start debugging, update your mods and make sure that all dependencies have the latest version, in particular the (, , , and ).
If you are on RED4Ext >= 1.13, make sure to uninstall cybercmd!
This section aims to give you a quick overview. If your exact problem isn't listed here, please look through the different sections below and try anything that looks promising.
To enable REDmods, check (you need to first)
Your game is crashing
During car chases
If your game is crashing during certain car chase missions, try removing .
If you can't play because the game is crashing, this section will point you towards the right troubleshooting steps in the guide below.
If you're done with this shit and would rather reinstall, see
Crash on startup
If you're trying to start your game, but it never even launches, this is the right section for you. Otherwise:
If the game crashes before you make it to the menu, see
If the game crashes when you're trying to load a save, see
Something about files or permissions
If you think that your error is file-related, you can check the section "" or use your browser's search function (Ctrl+F) to search this page for your error.
Some other error
Your problem lies with either red4ext or redscript. Find the section "" below and follow the steps for your error message.
Crash before menu
If you're starting the game, but never make it to the in-game menu, this is the right section for you.
Otherwise:
If the game never even starts, see
If the game crashes when you're trying to load a save, see
2.0 / PL: Missing tweakdb.bin or inaccessible memory
If you run into the error above, or if the game complains about attempting to read inaccessible memory, do this:
Go to your Cyberpunk directory and find the folderr6\cache.
Find the filetweakDB.bin and copy it (Ctrl+C
If that doesn't fix it
Your problem most likely related to Cyber Engine Tweaks. To find out how to troubleshoot it, check the "" section.
Cyberpunk has flatlined
See
Crash on loading a save
If you can make it to the menu but crash out when you're loading a save or starting a new game, this is the right section for you.
Otherwise:
If the game never even starts, see
If the game crashes before you make it to the menu, see
If you can start a new game without crashing, see
If you broke it with the savegame editor
Check — in the meantime, revert to the backup.
Otherwise
Most likely, you have an issue with an .archive mod. Here's what you can do:
To rule out that it's a save game problem (those are extremely rare), start a new game.
Go to the section and start with the first two entries on the list
If that doesn't solve your problem, or if the issue is save-game related, feel free to browse around some more.
Corrupt(ish) saves
You only need to read this if you can start a new game without mods, but crash on loading a previous save game. For any other problem, please see the corresponding section(s).
Some mods store data in save files. Removing those mods may (but doesn't have to) lead to your save game crashing until you install them again.
At the current time (09/2023, before PL), that has been confirmed to affect those mods:
- see the expandable list below for uninstall instructions, or check the mod's pinned post on Nexus
Uninstalling Immersive Rippers
Error reason: Unhandled exception Expression: EXCEPTION_ACCESS_VIOLATION (0xC0000005) Message: The thread attempted to read inaccessible data at 0x10. File: <Unknown>(0)
Run (Usage instructions are on the modpage itself)
If you are experiencing this issue with a mod that is not on this list, please check
Crash during the game
This section tells you how to deal with crashes during gameplay.
When editing the inventory
Kiroshi Crowd Scanner and Tooltip Fixer do not play together (, discord). Uninstall one of them.
If you can make it crash reliably
You're lucky, because it means that you can systematically troubleshoot. Go to the section; start with .archive mods, but if that doesn't fix it, do the other folders as well.
If you can't
Occasionally, crashes can be triggered by cross-platform saves. You can disable them in the main menu under Gameplay -> Miscellaneous
If that wasn't it
… that puts you in the same boat as the rest of us: most veteran players live with occasional crashes, especially while tabbing out and back in under certain circumstances.
That being said, if the crashes exceed what you're willing to live with, you'll have to find out a way to improve it, but your options are thin on the ground. Depending on how long it takes for the crash to occur, you might try
resetting your game (if the error persists, it's not mods)
certain types of mod to home in on the cause (see the for an overviev)
Best of luck!
redscript / RED4ext
When your game doesn't even start up, either of these frameworks isn't working properly. Below, you can find a list of the most common error messages with steps to resolve them.
Corrupt or missing script files
Cyberpunk 2077 encountered an error caused by a corrupt or missing script file and will now be forced to close. Please verify...
You have a problem with Red4ext.
If you are using RED4ext >= 1.13, uninstall cybercmd if you have it — it's no longer necessary and can cause false positives.
The first step whenever you run into this error is deleting the folder r6/cache and verifying your game files.
If that doesn't help, it's time for more detailed troubleshooting:
If you are on Linux, make sure to double-check the , as Steam sometimes resets these between updates
if you don't have red4ext/logs/red4ext.log, then RED4ext doesn't work, you have to update / fix RED4ext
if you have red4ext/logs/red4ext.log, then look inside, it will tell you which mods aren't compatible with the current game patch and may be the cause of this issue
If that doesn't solve your problem, you can
and reinstall the core frameworks
Corrupted archives
Cyberpunk 2077 encountered an error caused by corrupted or missing archives and and will now be forced to close. Please verify...
One of the .archive files in your folder is broken. To find out which one, try the approach, starting with the first two folders.
The game isn't starting: other reasons
There are various non-mod-related reasons why the game couldn't be starting. If you have followed these steps and they haven't gotten you anywhere, check the errors in this section:
Other than that, there are general troubleshooting steps, because missing Windows stuff can make Cyberpunk go brr. Make sure that
your graphics driver is up-to-date
you have the most recent version of installed
you have installed (, Microsoft)
Also, try starting the game without Reshade to rule it out as a source of crashes (this happened after the DLSS patch) and temporarily disable your antivirus.
If none of that helps, find us on in #mod-troubleshooting.
Too many mods
There is such a thing as too many mods which are making the game crash. This number seems pretty random, but generally doesn't start below ~460.
To fix this, you need to disable analysis in the settings:
Failed to initialize script data
This is not a Cyberpunk error!
Check your NVidia Control Panel panel. If power saving options are enabled, turn them off:
If you don't, check for other power config options in your operating system.
Steam: verify file integrity loop
The error below is partial to Steam:
There are two potential fixes:
Run as admin
Before trying to implement any of the other solutions, configure the REDprelauncher.exe in the Cyberpunk root directory to always run as administrator.
Right-click on the file and select Properties
Switch to the Compatibility tab
Check the box Run this program as an administrator
Run without antivirus
The second reason might be that your antivirus fucks with your game files in a way that the game can't cope with.
Try the following steps:
Turn off your antivirus and your firewall - anything that counts as "System Protection".
Yes, that includes Windows Defender
Yes, all of it. That includes your computer's bodyguard if it has one.
If it works now, you need to find out how to keep your antivir away from your game directory. If it doesn't, then you can turn the stuff back on now.
You pirated the game
There's a chance of >95% that we have already found the source of your problems — pirated copies just don't mod well. That's the first reason why things won't work.
The second reason is that CDPR needs to earn money to pay people to make games for us. If you can at all afford it, please buy the game. It's a good deal: how much are you willing to spend for a movie ticket? How long does a movie keep you entertained?
You are, of course, welcome to peruse the troubleshooting guide. It might even help you. But know that pirated copies will never be explicitly supported.
Finding the broken mod: known problem children
Stuff that isn't mods
It doesn't have to be either of these. But if it is, you'll never find it with the rest of the list. Rule it out by deactivating them while you're debugging.
Antivirus
ReShade
If you can start a new game without mods, but can't load an existing save, see.
Frameworks / Core Mods
These mods are not problem children – quite the opposite. But if they are outdated, either your game or your mods won't work. Make sure that you with the most recent game version.
Script mods
Some mods go far beyond the ordinary, adding whole new features to the game (why no flying cars, CDPR?). Unfortunately, that means they're more prone to breaking than others. Here's a non-comprehensive list.
Being on this list does not mean that a mod is "bad" or that you shouldn't use it – they break much for the same reason as the frameworks do, and are fixed in the same way (the modder has to update). Until that happens, you will have to disable them.
Adds flying cars to Cyberpunk. While this is awesome, it will absolutely break whenever CDPR changes anything, and requires updating.
Displays in-world holographic arrows that direct you towards your quest objectives. Is very likely to break upon patches.
Adds car chases and a bunch of related features. While CP2077 needs more car chases and explosions, this usually breaks and will require an update.
Adds mod settings to the in-game menu – Redscript version. This needs to be updated after every game patch.
Adds mod settings to the in-game menu – CET version. The mod itself will be fine, but it's dependent on being up-to-date.
spawn0
Most famous for edits of the female body that defy gravity and wreak havoc on V's spinal disks, this modder has been around since the early days, and the same is true for their mods.
However, modding has come a long way since then, and spawn0 never followed. For that reason, their mods are known to have compatibility issues with pretty much everything in the general vicinity.
On the bright side, their mods won't crash your game and are downwards compatible until the dawn of time. With Phantom Liberty, sp0 mods have been known to cause crashes to desktop near the dam.
Finding the broken mod (log files)
Bad news: The game's logs are usually less helpful than the Swiss navy.
Good news: Mods are doing a far better job.
Bad news again: You have to find the right log file in the game directory.
Good news again: There's intel how (see below)
jackhumbert's mod will give you additional information. There is a chance that it shows you something helpful, most of the time it
If you don't want to download and run script files from the internet, you can go and by hand. Otherwise:
Download (right-click -> save as)
Link goes to Presto's
Now, do either of the following things:
Move it to your Cyberpunk install folder and double-click it
The list will give you useful information along with a list of files to check. Once you've found the broken mod, you can go for instructions on how to troubleshoot further – they also tell you when you should ask for help!
Finding the broken mod (bisecting)
You have hundreds of mods, and one of them is broken. How do you find out which one it is without wasting the entire day?
Don't worry! As long as you have less than 2048 mods, bisection lets you find the problem child with only 10 rounds. (Otherwise, it's 11)
Some mods install themselves to multiple directories, but that doesn't matter. Due to the fact how mod loading works, you can find the error like this.
If you are using Vortex, you should enable and disable mods through Vortex rather than directly on disk. The principle below still works, you're just selecting the halves inside Vortex instead of moving them between directories.
If you do opt to work directly on disk, do not save changes to files if Vortex prompts for it.
Which kind of mod is it?
If you already know which folder contains the broken mod, .
You can find a video of the process .
To find out the type of broken mod, take each Directory from the following list and complete the steps in the next paragraph after the table.
Kind of mod
Directory
explanation
Rename the game data folder (game folder for short – e.g. archive/pc/mod) to a backup folder by appending an underscore (e.g. /mod_).
You can put the innocent folders back if you want: due to the way mods are loading, there won't be side-effects.
Go bisect
Congratulations, you have found which folder causes the problem — you're more than halfway there. All that's left is to find the broken mod. Here's how.
The process is the same every time, no matter if you are moving files or folders.
If you don't vibe with text, there's a below.
Switch on half of the mods from your backup folder by moving them back to the game folder.
Bisect: Video demonstration
Audio problems
If your CPU is too busy, the game will try to save resources by dropping audio, starting with dialogue audio. Disabling spatial audio from the main menu might help:
It's not connected to CPU load
Missing footsteps had in the past been connected to a bug in Let , so it is worth debugging your script mods. However, if you're on the most recent version (check the github for previews), you might just have to your mods at random.
Mod(s) aren't loading/triggering
If the mod in question is Cyber Engine Tweaks (CET), check the corresponding subpage. If it's anything else, read on.
Normally, a mod should just work, as long as all of their requirements are working. If you aren't certain what that means, you can check for detes, or just follow the checklist below.
Make sure that you have in your launcher.
If items or hairs aren't changing, you need to install (why?)
If you've been using Mod Organizer 2 to install your mods, chances are high that it's been doing it incorrectly, at least for some of the more important mods. You'll need to do additional steps detailed in order to get MO2 working with Cyberpunk.
That wasn't it: Getting the mod to work
If your mod is or , you can check the sections below. Otherwise, follow the .
Mod isn't working: General troubleshooting
Here's what you can do:
Check that you've enabled the feature (see ).
Check the on the mod's nexus page. Make sure that you have installed them all and that they are up-to-date.
Make sure that all of your are up-to-date and starting up correctly (here's how you can )
Mod isn't working: CET
You have installed Cyber Engine Tweaks, but it's not active / not letting you bind a key:
Mod isn't working: a CET mod or script
You will find all the files mentioned below under
Find the cyber_engine_tweaks.log.
Update everything that shows an error
If any file paths are listed: Make sure that the directories exist and aren't
Deleting user settings
You almost never need to do this.
However, if you want to remove anything that Cyberpunk might have stored on your disk, you need to find and delete the following folders (as per :
%userprofile%\Saved Games\CD Projekt Red\Cyberpunk 2077
%userprofile%\AppData\Local\REDEngine
%userprofile%\AppData\Local\CD Projekt Red
You can quickly navigate to the folders by pasting the path into your Windows Explorer's path bar, or pressing Windows+R, pasting the path there, and
The nuclear option: a clean install
This is the last resort and you do not need to do this — run for the same result in less time. However, if you're still set on reinstalling, the instructions below will help you completing that in minimal time.
Back it up, baby!
Unless you back them up, your mods will be lost. If you don't want that, make backups of the following folders:
/mods
Quick (download <4GB)
Unless you , all your settings and manually installed mods will be lost.
The instructions below tell you which folders not to delete. Delete everything else.
Go to the Cyberpunk 2077 install directory
Delete everything except for the folder archive
Inside archive, delete everything but
Modular / minimal download (download <1GB
Unless you , all your settings and manually installed mods will be lost.
Will download < 1GB.
Rename or remove the following folders. If you do not have them, you don't need to do anything.
Afterwards, verify your files.
Nuke it from the orbit: The thorough version
In case neither of these options is good enough for you, you can find a full reinstall guide on .
A fresh install: Starting from scratch
You have completed either of the previous steps. Your game should start now. If it does not, you either have leftover files (check for how to get rid of them), or you have a problem that is not related to Cyberpunk. Make sure to follow the hints in the red box .
Now it's time to systematically install mods. We'll start by and making sure that the game starts up without any framework-dependent mods. Afterwards, you can add back all of your mods, and if the game stops working, find the offender via .
Don't worry about your savegames — those are fine, even if they won't load right now. We're just laying the foundation here that you can later build upon.
Let's go about it step-by-step.
Installing the frameworks
This step will tell you how to set up your Cyberpunk install with the necessary dependencies so that you can start modding.
Check the . For each of the frameworks, complete the following steps:
If you didn't have it in your previous install, skip it.
Install it (manually or via Vortex, your choice)
Install all of its
If you are using redmod (have any folders inside of /mods), you probably have installed. That is no longer necessary with RED4ext >= 1.13 and can lead to false positives. Uninstall it!
Once you are done, start up your game and load a savegame. If you don't have one or the game still crashes, start a new game.
This should now work. If it doesn't, you need to check your to see which framework is causing trouble, or find us on in #mod-troubleshooting.
You need to complete this step before proceeding: if the core frameworks aren't working without mods, they won't work with mods – adding anything now will just make debugging more difficult.
Fortunately, this is not rocket science. Be methodical and install them one by one. If you need help, you can find us on (#mod-troubleshooting)
Adding (back) your mods
If you don't (yet) have any mods, you can head over to Nexus and start installing. Make sure that you include all necessary !
This section assumes that
you installed all required
If you're using Vortex
Head directly to the section and pretend you have just removed all your mods.
If you made a manual backup:
For each folder that you have (check link for a list), repeat the following steps:
Put it back into its original place in your new/fresh install
Start up the game
Load a non-modded savegame or start a new game
If your crash(es) are back, you can now go to the section and follow the steps for your folder.
Something something files
Your error goes something like this:
These are caused by access errors – Cyberpunk is trying to read or write a file, and for some reason, it can't.
Follow the steps in this section one by one, or find us on in #mod-troubleshooting.
Make sure that the file path exists
Ignore this if you can't spot any file paths in the error message
If Cyberpunk is trying to move files to a subdirectory that it can't access, make sure that the directory actually exists (if it doesn't, create it). The most frequent candidate for this is /r6/cache/modded.
Make sure that no previous game instance is running
Sometimes, the game instance doesn't shut down properly and is still running in the background, althoguh you can't see a window. This problem goes away after rebooting.
Open your task manager (Ctrl+Shift+Esc)
Switch to the Details tab
Sort by Name and scroll to C
It is possible that your antivirus is causing this problem. Before you lose your mind, try temporarily disabling it.
Reboot your PC
Always a good idea to do that from time to time – in this case, it could make the error go away.
If it doesn't, check the next steps on the list.
Make sure that all files in the game directory are writable
Sometimes, files in your Cyberpunk game directory are set to read-only.
What kind of monster would do something like that???
We've had confirmed reports of the following culprits:
Steam
mo2 mod manager
various flavours of antivirus
You can fix this either via or via , the results will be the same.
Via system console:
Press Windows+R
type cmd and press Return to open the command line
run the following command (replace the path with your actual game dir):
Via Windows Explorer:
Navigate to the Cyberpunk game directory and right-click on it
Select Properties (the last entry in the drop-down menu)
Uncheck the "Read-only" box:
File Ownership
Sometimes, file ownership got messed up, and not all files in the folder are accessible by your current Windows account. It is a mystery how this comes to be.
You can fix it via or via ; either of those will do. If in doubt, the commandline one is more thorough.
Via commandline
In any of the commands below, you need to substitute C:/Path/to/Cyberpunk2077 with the path to your game directory.
Press Windows+R
Type cmd and press return
Run the following command (make sure to insert your real Cyberpunk path):
Via Windows Explorer
We haven't included the full instructions here, but you can check .
Reboot your PC again
If none of these things has helped, reboot your computer.
The error should be gone now.
Not to say that your game will work now – but if you still have an error, it's hopefully a different one. Go back to the start of the guide and let's fix that one too!
Redscript Compilation Failed
You're running into the following error:
This workflow is geared at the exact error above. If you have a different one, it's still worth checking this, but you can also head back and find the right section.
0. Make sure that you don't have multiple versions of installed
In the past, Codeware wasn't a standalone mod, but was instead bundled inside of other mods. Since that is different now, the leftover versions can cause errors.
Search your Cyberpunk directory for Codeware.
If you have exactly one folder, this is not your problem — proceed to .
1. Make sure that you have the latest versions
Actually check this. Do not rely on memory or common sense – if in doubt, re-download. (This is totally not something that the guide's author learned the hard way)
Check Redscript ( | )
If you are on RED4ext >= 1.13:
uninstall cybercmd
Otherwise:
Optional, but recommended:
Check that you have the latest versions of all troublesome Redmods.
2. Check redscript.log
It is in r6/log/redscript.log.
See if you can find any errors – warnings may or may not be a problem, see for context.
3. Reset Redscript
If you rename or delete any directories, make sure to create a new, empty directory.
Redscript: Disable dependent mods
Vortex: Disable them
Manual: Remove the contents of r6/scripts/.
You can zip the directory from the windows context menu, then delete its contents.
Resetting the redscript cache
delete r6/cache
verify game files
Make sure your game starts up without error.
4. Reinstall your mods
Hopefully, your problem should be gone now.
It's time to put your mods back and see if you can start the game - see .
XML Document parsed with errors
XML document parsed with errors: C:\Path\toCyberpunk 2077\r6/config/inputUserMappings.xml
Error description: Error parsing element attribute
According to InputLoader's , you can ignore this. Keep searching!
(You can also try reinstalling InputLoader and hope that the error goes away)
You forgot your CET keybind
Delete the file Cyberpunk 2077\bin\x64\plugins\cyber_engine_tweaks\bindings.json. The game should let you bind a new key at the next startup.
Photomode screenshots are blank
With 1.62, screenshots are now saved to Documents\CDPR\Cyberpunk\Screenshots , and the previous location will receive an empty file.
With 1.63, screenshots have now been moved back to \Pictures\Cyberpunk 2077
Press [none] to continue
That is due to requiring an update.
I have another problem that isn't on this list
Here's the catch-all solution. After this, your game will work (or the problem you have is not Cyberpunk related).
(optional, as this might solve it): .
If your problem doesn't go away, follow the instructions .
I really just want to get this working, what do I do?
You might want to deactivate ReShade before you start debugging. Especially after DLSS, it has been known to cause crashes.
The bad news is, at this point you have little choice but to reset your Cyberpunk install and re-mod it from scratch. The good news is that the process is really streamlined. If you don't run into any hitches, you're <30 minutes away from a working game.
Now, how do we go about this?
Is there a shortcut?
Yes! There is a batch script that will automate steps 1-4 of the list below for you.
If you don't want to download and run script files from the internet, you can go and complete the steps by hand. Otherwise:
Download the mod remover script by either
downloading it from and following the install instructions
grabbing it from (right-click -> save as) and moving it to your Cyberpunk dir
Link goes to the
Instead of following these instructions, you can also . Do yourself a favour and check the instructions, as you might be left with residual files otherwise.
Step 1: Temporarily disable all your mods
Vortex
Follow the instructions and prompts
Press the purge button — this will remove any and all installed mods.
Do not press deploy.
If all your mods were managed via Vortex:
Start Cyberpunk however you want, as long as it's not via Vortex. If it starts now, you're done here and can proceed with – otherwise, go to .
If you had a mixed install:
Complete the instructions in the section now.
Manual
Find the following folders:
and rename them to
The purpose of renaming them is that the game won't find them anymore, but you still have a back-up of the files inside. Feel free to achieve this goal however.
You can optionally create a new, empty folder with the same name.
Check if the problem is gone.
If it is, put the folders back one after the other and apply the .
Step 2: disable CET
Find the folder
and move it out of plugins (e.g. put it on your desktop).
If you'd rather delete it, make sure that you retain a copy of your mods and plugins directories, as they contain your mod settings (AMM decorations etc.)
Check if the problem is gone.
If it is, put the folder back and apply the to cyber_engine_tweaks\mods and cyber_engine_tweaks\scripts until you have found the culprit.
Step 3: Remove scripts and tweaks
First, remove (or rename) the cache:
Verify game files. Check if the problem is gone.
If that didn't do the trick, find the following folders:
and rename them, you know the drill.
Check if the problem is gone.
If it is, put them back one by one until you find the one that breaks it. If that is one of r6\scripts or r6\tweaks, apply the .
Step 4: Remove RedScript
You can try first, but at this point, you'll going to have to verify your files anyway.
Delete the following files and folders. You don't need a backup, as you can reinstall RedScript from . If any of them don't exist, that's okay — just means you don't have to delete them.
@Auska has compiled a handy script for unix people:
Step 5: Repair game files
Exact procedure as documented by @ArsenicTouch
GOG
Go to Games -> Installed, right-click on your game and select the following menu entry:
Steam
Open your library
Right-click on "Cyberpunk 2077" and select "Properties"
Select "Local Files"
Epic
Open your "Library"
On the "Cyberpunk 2077" tile, find the "…"
Select "Manage"
Step 6: Launch the game
All files you deleted have been re-acquired. If there are no left-over files from earlier modding attempts, your game should work now.
If it does not and you have exhausted the reset options as specified in this guide ( and both) and your game still does not start, then your problem exists outside of Cyberpunk. In this case, you can
check your (separately for )
Step 7: Install the core frameworks
Now that your un-modded game is starting, it's time to . Do this before you enable your other mods, as they won't work without their dependencies and can only add problems at this stage.
You can now re-enable your mods. Do it in chunks and check that the game keeps working so that you can narrow down where the problem is, in case it isn't gone for good.
Dealing with a broken mod
You have followed all the steps and your game is launching, but you now have a mod on your hands that just doesn't work, and you want it to. What do you do now?
If you join a to ask for help, people will walk you through this list, so you might as well do it first. Nobody will unbundle someone else's mod and just fix it for free unless they want to use it themselves.
1. Make sure you have the correct dependencies
Many mods require frameworks or other mods to work. Check the mod's page and description for those, and install them.
Repeat the process by installing the dependencies' dependencies, until you have everything necessary.
2. Check the mod's description
Often, the description contains detailed installation instructions, known incompatibilities and/or workarounds. Sometimes, mods worked on past versions of Cyberpunk, but the author stopped updating. In that case, proceed to of this list.
Before you get upset, please keep in mind that modders don't do this for a living (these are called "game developers" and they get paid for it). Somebody made this in their spare time, for their own use, and then decided to share it with you for free. Do you know the easiest way to avoid toxic users? It's not publishing your mods. No reward system, credit points or reputation will ever make up for online abuse.
As a mod author, I can tell you that I will ignore assholes, but gladly spend an extra hour after work to help out someone who politely asks me for help.
3. Check the mod's comment section
You're unlikely to be the first person to run into this problem. There is a good chance that the comment section on the download page has helpful information. Look for either a pinned post by the mod's author or a user discussion about your problem — these often contain a solution.
4. If you are using a mod manager: Try installing it manually
While mod managers are very reliable and get better with every new release, you should rule out that they are the cause of the problem by installing the mod from hand.
If everything else works and installing the mod by hand still breaks compilation, then it is broken. See "" below. start your game client's file verification.
5. Contact the mod's author
Describe your problem as clearly as you can, and add all useful data.
Bad bug report: "Your mod doesn't work lol pls help"
Good bug report (example): "Hi, installing your mod (manually and Vortex) causes a Redscript compilation error on startup (possible screenshot of error popup). xxx.log says <citation of error message>. All my dependencies are up-to-date, and I've ruled out that it's any other mod. Can you help me out?"
Good bug report (example 2): "Hi, when I try to equip Item <item name and colour>, it doesn't show up and I only get glitches. I'm using Hyst's boob mod and <specific version and variant> of your mod. I hope you can help me? Thank you for making this."
As per the last red box, do keep in mind that you're asking a favour. The modder doesn't have your problem, and if they do, they know exactly how to fix it. The most time-efficient response for them is to ghost you, so any kind of response is either them being nice or getting mad when you or someone involved ignores visible information.
5. Hands-on troubleshooting
At this point, you have exhausted all easily accessible solutions. If you still want the mod to work, you will have to get involved yourself. A commendable attitude! (Not sarcasm, it really is.)
This is the point where you might want to join a , because now you're entering the territory where other modders can actually help you.
Usually, there will be a that will point you towards the source of your problem. If there isn't (the game loads and the mod just fails silently), that means that the error is inside the archive and you have to become a modder.
Fixing scripts
But sometimes, you're lucky. Sometimes, the error is in a script file. You can tell this by a log entry pointing towards a file in your Cyberpunk folder (e.g. r6\scripts\my_broken_script.reds).
Open up that file in a text editor like and try to find and fix the problem. Sometimes, the log file has more information. Sometimes, an online syntax check can help you — there isn't one for redscript, but it's fairly close to lua.
Sometimes, such mistakes are trivial — a forgotten , or incorrect file encoding. Often, they are not.
A tip for
Ascending from user to modder
If the error isn't in any script files, you will have to unbundle the .archive, load it in , and get your hands dirty. We'll be seeing each other, choomba!
Save your game again and remove all mods used in version 1.63
OPTIONAL: Load the save in vanilla 1.63, it should work there too.
Download the newest version of Cyberpunk2077! The clean created save should work for vanilla and modded instances of the game.
if that doesn't help, go to Troubleshooting in the corresponding section (you will need to verify your game files).
Now, start the game.
If the error persists, verify game files through your client (you won't catch any viruses doing that)
Start the game again
Drag-and drop your Cyberpunk folder on the file that you downloaded
After running, the script will have created a folder _LOGS in your Cyberpunk directory, which contains a file listing all the log files for you.
.lua (cyber engine tweaks)
\bin\x64\plugins
Cyber Engine Tweaks
redscript
\r6\scripts
redscript mods
red4ext
\r6\tweaks
red4ext tweaks
Only do this with the last subfolder in the path, the result should be
\archive\pc\mod_
, not
archive_\pc_\mod_\.
The folder is now hidden from the game. Since it doesn't know, it will try to look inside anyway - create a new empty folder with the original name for that (e.g. /archive/pc/mod).
Start the game. You will now run into one of these two scenarios:
Your problem is gone: Jackpot. This is the correct folder for the next section: Go bisect
Before you go there, you can restore all the other folders you moved, deleting the empty directories.
Your problem is still there: This folder is innocent. Proceed with the next directory from the table above.
Remember (roughly) which batch you moved (e.g. "everything after E" or "the first half")
Start the game. You will now run into one of two scenarios:
The error is still there: Progress! Go to Step 5.
The error is gone: Progress too! Go to step 4
The error is gone: You have identified which mods aren't the problem! Good! Do the following:
In your backup folder, find the last batch of mods that you touched
Half of these go into the game folder
Go back to step 2 – you should now definitely see the problem again.
The error is still there: You have narrowed it down, let's narrow it down further.
Do the following:
In your game folder, find the last batch of mods that you touched
Half of these go back into the backup folder
Go back to step 2 for the next round – the problem might be there or not.
Repeat this process until you know which mod is causing the crash. Then, you can either try to update it, or do a full uninstall
If materials aren't updating, you need to install material override (why?)
Inside pc, delete everything but the folders content and ep1
Verify your files
Start the game and load a savegame (you can also do this after installing all of them, but if you run into issues, that will make isolating the point of failure more difficult).
you can (without crashing) do either of these things:
load a savegame
start a new game
If you didn't make it that far, the steps below won't help you and will only obscure your problem. Please head back to Step 1: Temporarily disable all your modsand complete the process.
If you need help, find us on Discord in #mod-troubleshooting!
Cyberpunk is trying to write to a file that doesn't exist
Check if you can see anything Cyberpunk in the list.
If yes, right-click on it and select End Task
If that didn't help, run the command whoami to see your current user name. You will need it for the next step.
It should be identical to your Windows username, but if you have spaces or special characters, Windows might get funny about the spelling.
Run the following command (putting your actual game dir and the username from whoami):
Delete everything you have found.
Reinstall the latest version of Codeware from Nexus.
create a new directory r6/cache/modded (this will prevent errors)
Make sure that r6/scripts is empty
Make sure that red4ext/plugins is empty (that the red4ext core frameworks aren't getting loaded)
of the person who wrote most of this guide
.
Optional: If you don't want the script to delete modded files for you (because you just want to disable mods), right-click on the file and select Edit, then find and delete line 6:
Make sure that the file is in your Cyberpunk directory. If you downloaded from Nexus, you should have a cyberpunk2077_disable_all_mods.bat.
Double-click it
Follow the instructions and prompts
Verify your game files
Optional: You can now proceed to Step 5 and start modding your game again.
