1 of 100

Cyberpunk 2077 Modding

Home

Welcome to the Cyberpunk 2077 modding wiki!

This is the dedicated repository for modding guides, resources and know-how.

This wiki is a community project! Do you want to improve or add anything? right now, or reach out on and find us in the #wiki channel!

For Mod Users:

Using Mods

Modding your game, for users

This page contains instructions on installing mods. If you want to create mods instead, check here.

If this doesn't cover your needs, maybe check out our more detailed guides:

Installing Cyberpunk
Installing mods via Vortex

How to install mods

TL;DR:

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 enable REDmod. 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:

STEAM C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077\

GOG C:\Program Files (x86)\GOG Galaxy\Games\Cyberpunk 2077\

You can install mods by hand or by using Vortex.

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

/r6

folder

/red4ext

, ArchiveXL, TweakXL

- 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

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.

For instructions on how to install, see here.
For documentation on the Vortex installation toggle, see here.
For instructions on how to activate it, see here for GOG and here for Steam and Epic.

REDmods are installed in Cyberpunk 2077\mods, where every mod has a subfolder with an info.json.

Installing Mods

You can install mods via Vortex or manually. There are upsides and downsides to each — however, for beginners, we recommend using Vortex.

If you had terrible experiences with Vortex for other games, be assured: Cyberpunk integration is working extremely well. Maybe give it another chance?

anual 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/

Troubleshooting

If you have problems with Vortex, check the corresponding section of the guide.

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

Getting Started

Install the core requirements for Cyberpunk2077 modding, decide how to manage your mods, and set up the mod manager

If you already have the game installed and configured, you can proceed to the guide how to install mods with Vortex.

Before you get started

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.

Visual C Redistributable 2022
.NET 6.0+
The latest graphics driver for your GPU
If you are on Windows, Windows 10 or above and the latest Windows Update

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"

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.

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

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.

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 framework compatibility.

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 downgrading Cyberpunk, or wait until the frameworks update.

Preventing the game from auto-updating

GOG

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 (:
1. Right-click on Cyberpunk 2077 in your Steam Library and select Properties
2. On the side bar, click on Local Files
3. 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)
4. Navigate two levels up
Find the file appmanifest_1091500.acf
Set the file to read-only:
1. Right-click on the file and select Properties
2. 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.

Don't forget to deactivate it again later!

Downgrading

GOG

Disable auto-updates
Head to the Cyberpunk game detail page
Find the settings button next to the Play button
Select Manage Installation -> Configure…
Select the game version

Epic

Sorry, choomba, you're fucked. No downgrading possible.

Steam

Steam doesn't directly support downgrading, but you can use 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 Steam now so that you don't forget to do it later. We'll wait. The depot for the current version 1.63 is download_depot 1091500 1091501 3385393324409330817 (this is version specific. Please reach out to update the version if it's outdated.)

Open Steam
Press Win+R
Type steam://open/console to get into the steamdb console
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 3385393324409330817
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.

This should leave you with the correct previous game version. You can right-click cyberpunk2077.exe to verify the versions in Properties > Details.

You might still need to do a script cache reset or other cleanup before the game starts up nice, so head on over to those instructions if need be.

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.

Installation

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

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.

Usage

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

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

EXAMPLE: A simple archive mod C:\GoG\Cyberpunk 2077\mods\modA\archives\mod_a.archive.

You need to deploy your installed mods before playing a modded game.

You can handle deployment and load order with

the REDlauncher that comes with the game
Vortex Mod Manager from NexusMods
or use the REDmod WolvenKit integration and manage your mods easily from within the WolvenKit Mod Manager.

You need to start a modded game in order to load the deployed mods in game.

Legacy archive mods in <Cyberpunk 2077>/archive/pc/mod are still supported, but their load order cannot be managed with REDmod.

These mods will load before any redmods.

Deploying Mods and Starting the Game

REDmod can stage installed mods to work when the game starts with the modded flag:

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

Installing

In order to utilize deployed mods with REDmod, you need to run the game in a specific modded mode. You can do this by launching the game through WolvenKit or manually by specifying a command parameter.

Depending on your other mods, you might need to install as well.

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.

Example: modA contains a script file C:\Gog\Cyberpunk 2077\mods\modA\scripts\cyberpunk\player\player.script. modB contains a script file with the same name C:\Gog\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.

Advanced Topics

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

Commands

Deploy

deploy - Deploys mods to the game by compiling them together

Synopsis

Usage:
  redmod deploy -root=<path> [options]

Arguments:
  -root=<path>

Options:
  -mod=<name>
  -h, --help

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
redmod deploy -root="C:\Gog\Cyberpunk 2077" -mod=modB modA modC
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.)

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

--- Example:

❌/environment/decoration/industrial/pipes/entropy_pipe_01/entropy_pipe_01_module_small_l020_a.mesh

✅base/environment/decoration/industrial/pipes/entropy_pipe_01/entropy_pipe_01_module_small_l020_a.mesh

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:

WINEDLLOVERRIDES="winmm,version=n,b" %command% -modded

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 modding discord 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 here. 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: Switch to the libraries tab and open the drop down menu

Select "version" and "Add"

Repeat the process for d3dcompiler_47
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 CET wiki page.

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

Do you want to know more?

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 here, starting with VirtualAtelier as a dependency.

Search for a matching log file in the Cyberpunk folder (either the mod's name or in the mod's folder). Here are instructions on how you do that.

=> If you have found a log file, go here.

=> If you have not found one or it contains no errors or warnings, go here.

A log file exists

If you can't find one, go here.

The file is empty

This means that your mod is loaded, but never initialized. Go here.

The file has errors

The mod itself is broken. You can now go and troubleshoot it.

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

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. Let's do that now.

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.
Return to Level 1 and repeat it for the requirement.

Users: Troubleshooting after a game update

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 .

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
Reset your installation:
- Fall back to a clean state ( | | | )
- Enable all and make sure that the game starts
- Re-enable your other mods (check for how to do it fastest)
Find help on in #mod-troubleshooting

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.

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: The unofficial community modding toolkit.
WolvenKit CLI: The command line interface version of WolvenKit. (Formerly CP77 Tools)

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: https://docs.unrealengine.com/4.27/en-US/SharingAndReleasing/Deployment/Cooking/
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.
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.

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.

For Mod Creators:

Modding Tools

Frequently used tools for modding workflows

Editors

WolvenKit

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

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.

010 Editor

What is 010 Editor?

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

PixelRick's Cyberpunk Save Editor

Introduction

CyberpunkSaveEditor is a tool used to edit Cyberpunk 2077 sav.dat files

REDmod

Using Redmod to create mods.

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)

if you're looking for how to use REDmod to install and manage mods as a user, click here

Exporting Resources to Raw Formats

REDmod can export .mesh, .w2mesh, .xbm, rsvg and .svg files using the resource-export command.

redmod resource-export -depot=<depot> -input=<resource-path> -output=<file> -<optional parameters>

PARAMETERS

    -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

Exporting .xbm

REDmod can export REDengine .xbm files to several raw formats for editing.

dds: DirectDraw Surface bmp: Windows Bitmap jpg: Joint Photographics Experts Group tga: Truevision Targa png: Portable Network Graphics

XBM PARAMETERS

    -bitmap-mipmap=<uint>           - mipmap selection

    -bitmap-source=<bool>           - export uncooked file (default = false)

    -bitmap-flip=<bool>             - flip texture (default = false)

    -bitmap-gamma=<bool>            - forced gamma setting (default = false)

redmod resource-export -depot="M:\" -input="base\test\example.xbm" -output="M:\base\test\example.png" -bitmap-flip=true

you can also export textures using the wolvenkit gui (recommended)

Importing Raw Files to REDengine

using the import and resource-import commands


redmod resource-import -depot=<depot> -input=<relative path to file to be imported> -output=<absolute path to the new redengine file>

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)

.json: Texture region set definition.

.mesh (Mesh)

.xml: Speed Tree XML Resource File .smd: Source Mesh Data

.fbx: Autodesk FBX

.curveset (Curve Set)

.csv Comma Separated Value Table

.mlsetup (MultiLayer Setup file)

.json: MultiLayer Setup JSON File .mlsetup: MultiLayer Setup File

.genericanimdb (Generic anim database)

.csv: csv file

.cubemap (Cubemap)

.dds: DirectDraw Surface

.bmp: Windows Bitmap

.jpg: Joint Photographics Experts Group .tga: Truevision Targa

.png: Portable Network Graphics

.exr: OpenEXR

.rig (Rig)

.re CDPR proprietary format

.ies (IES Light Profile Data Resource)

.ies: IES light profile

.mlmask (Multilayer Mask)

.tiff: Tagged Image File Format

.tif: Tagged Image File Format

.json: JSON

.rsvg (SvgResource)

.svg: SVG Resource definition file

.xbm (Bitmap Texture)

.dds: DirectDraw Surface

.bmp: Windows Bitmap

.jpg: Joint Photographics Experts Group .tga: Truevision Targa

.png: Portable Network Graphics

.tiff: Tagged Image File Format

.tif: Tagged Image File Format

.exr: EXR

.cube: Cube LUT

Importing Animations

redmod import -gameRoot=<depot> -inputPath=<file> -animset=<resource-path> [options]

Synopsis

Arguments:
  -gameRoot=<depot>
  -inputPath=<file>
  -animset=<resource-path>

Options:
  -outputPath=<resource-path>
  -animationRename=<name>
  -h, --help

Description

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.

Examples

redmod import -gameRoot="E:\modding\depot" -input="E:\raw files\animtest1\macarena_long (1).re" -animset=base\animations\npc\generic_characters\male_average\open_world\generic_male_average__stand__rh_cane_lh_cigar__01.anims -output=base\out\new_test.anims -animationRename=stand__rh_cane_lh_cigar__01__smoke__02"
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.

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:

 * root_folder
 * | -📁 mods
 * | |-📁 <Mod Name>
 * | | |-📁 archives
 * | | |-📁 scripts
 * | | |-📁 tweaks
 * | | |-📁 customSounds
 * | | |-📄 info.json

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:

{
    "name": "MODNAME",
    "description": "Description for the mod.",
    "version": "1.0.0",
    "customSounds":    [ ]
}

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

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.

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.

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.

Script Modding

To make a script mod in REDmod:

make a new mod and create a new folder here: <Cyberpunk 2077>/mods/MODNAME/scripts
copy the .script file(s) you want to change from <Cyberpunk 2077>/tools/redmod/scripts❗ 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.

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

{
    "name": "MODNAME",
    "description": "Description for the tweak mod.",
    "version": "1.0.0",
    "customSounds":    [ ]
}

✅ Done. To test, launch the game with REDmod.

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.

Example

{
  "name": "newmodtest",
  "version": "1.0.0",
  "customSounds": [
    {
      "name": "amb_bl_eq_medical_electronics_small",
      "type": "mod_skip"
    },
    {
      "name": "w_gun_revol_power_overture_fire_suppressor",
      "type": "mod_skip"
    },
    {
      "name": "w_gun_npc_dian_reload",
      "type": "mod_sfx_2d",
      "file": "are_you_sure_about_that.wav",
      "gain": 1.0,
      "pitch": 0.1
    }
  ]
}

Parameters

name - the game audio event to override
type - the sound type. Options are:
- mod_skip: do not play this sound event
- mod_sfx_2d : will be played without any positions / attenuation
- mod_sfx_city : has a longer attenuation that is suitable for city sounds
- mod_sfx_low_occlusion : has a long attenuation that isn't occluded much e.g. a VO or quest sound that you don't want to be muffled
- mod_sfx_occlusion : medium attenuation with normal occlusion
- mod_sfx_radio : needs to be tuned to a broadcast channel (e.g. radio)
- mod_sfx_room : has a shorter attenuation suitable for something that can be heard across a room
- mod_sfx_street : has a medium attenuation, good for something to be heard down a street
- mod_sfx_ui: for menu and ui sound replacement
file - the .wav file to use (inside /customSounds)
gain and pitch

Blender scripts and plugins

Plugins

Scripts

Noesis

What is Noesis?

Introduction

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.

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
custom lipsync maps

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

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.

AMM

Appearance Menu Mod

Appearance Menu Mod has its own documentation at…

You can find help on their Discord.

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.

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. Learn more

MESH

3d models

XBM

2d textures

ENT (entity)

Parent file for most visual assets which is directly linked by the Tweak DB

APP (appearance)

Sets up appearances for assets such as NPCs and vehicles referenced by entity files

MT (material template)

Base shader files for REDengine

MI (material instance)

Instanced shaders for mesh materials

MLMASK (multilayered mask)

Mask component of the Multilayer supershader

MLSETUP (multilayered setup)

Material setup component of the Multilayer supershader

MLTEMPLATE (multilayered template)

Pre-defined tiling surface component of the Multilayer supershader

HP (hair profile)

Color ramp data to set colors for meshes using the hair shader

Visual Asset Graphs

Vehicles

Body

Cheat sheet: Face and skin

Skin tones, complexions, make-up

Skin tones by index

List compiled by wolv

Freckles / cheek make-up

For a list of freckles and make-up sorted by colour and skin type, see NoraLee's .

Lipstick

For a mod fixing various mix-ups in the character creator, see .

Lipstick colours and styles are sorted in (more or less) ascending order in the appearance list in the mesh.

Style order is Default - Glossy - Matte (no suffix, _02, _03)

Link:

Eyeliner and kohl

to be done

Complexions

Every complexion has its own associated texture file. These are sorted by body gender under

The files are ending in 01..05. Each complexion has its own appearance in the head mesh, e.g.:

Eye make-up

Equipment

Everything about gear

Armour

List

Description

Other

List

Description

Spawn Codes (BaseIDs/Hashes)

Item spawn codes and how they link to appearances

Lists

A selection of lists for looking up item codes. Alternatively, you can browse through the game's files, or search e.g. the fandom wiki.

A list with BaseIDs

Google Sheets (August 2022), supports filtering

Player equipment only: Not all items that you find in the player folder are actually hooked up to spawn. If you can't find an app file, 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:

Vest_17_basic_01

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 recoloring items!

TweakDB

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 to create a .bin that can be loaded into the game with . 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.

Appearances Mappings

In base\appearance_mappings.json, entity types have their resources defined. The vehicle definition is below:

key

value

Vehicle Filename Parsing

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 (play around with this regex here):

(?:v_)?([a-zA-Z]+|av)\d?_([a-zA-Z]+)_(?:[a-zA-Z]+(?:_[a-zA-Z]+)*)__(?:int|ext)\d{2}_([a-zA-Z]+(?:_[a-zA-Z]+)*)_\d{2}.*\.ent

For a filename like v_sport2_mizutani_shion__ext01_body_01.ent, this would match the following groups:

Group 1: sport
Group 2: mizutani
Group 3: body

Group 1 (base)

Name

av

Aerial

sport

Car

standard

Car

utility

Car

Group 2 (category)

Name

Mahir

Mahir Motors

Group 3 has no mapping, is of the type partType.

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.

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

base
steering_wheel
pedals

Exterior

base
bumper_f
bumper_b
hood
trunk
door_fl
door_fr
door_bl
door_br
fuelcap
fuelport

Wheel

wheel

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.

Modifying the Tweak DB

The Tweak DB can be interacted with using Cyberpunk's official REDmod, or numerous community solutions such as TweakXL, CET, and redscript.

Player Garments/Equipment Graph

The following is a diagram which maps the relationship between game files for use with TweakXL and Archive XL:

Scripting

Game components explained

What do the different files do? How do I mod them?

Appearance: .app files

All the dirty detes on appearance files

If you want to modify an .app file to change an NPC's appearance, check !

Appearances

The real meat of the file: a list of appearance definitions, loaded via .

appearanceResource

baseEntityType: name that exists in the 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 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
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.
looseDependencies: lazy-loaded resources (confirmation needed)

Components

A list of components that are part of your current appearance. There are various types of components, which are documented .

Components that you add in the 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 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 .

For usage instructions, see .

commonCookData

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 mod to prevent such issues.

Components

This page contains documentation for the most common component types. WIP.

See the 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 .

Components are 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. 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 : 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.

Documented Components

Equipment/Hair

entGarmentSkinnedMeshComponent

Can be used interchangeably with entSkinnedMeshComponent.

Loads a mesh from a .
Supports .
meshAppearance will select an appearance by name from the mesh's defined .
Lets you enable and disable shadows with the properties castShadows and castLocalShadows

This is the good kind of mesh component, the one that will work without trouble, as opposed to .

entSkinnedMeshComponent

See below at

entSkinnedClothComponent

Like , but with a physicalMesh and physics. Usually comes together with an (they're usually named collar for clothes and dangle for hair and accessories).

entAnimatedComponent

Adds physics to garments and hair meshes.

NPCs

gameDismembermentComponent

Defines dismemberment rules for NPCs. (TBD: ???)

Generic

gameinteractionsComponent

Adds interaction prompt to entity. (Shouldn't work without gameTargetingComponent, but this hasn't been double-checked.)

entColliderComponent

WIP

gameTargetingComponent

Allows targeting via CET.

gameScanningComponent

WIP

Game icons: The inkatlas file

Apart has prepared a reference project with an import-ready inkatlas. You can download it .

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 .

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…

Edit, import, or export textures?
Learn about textured materials?
Use a textured material 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.

3d Modelling

Find knowledge on editing 3d models here

Check the sub-pages for more detes, or check the section's sub-pages. For hands-on advice, see the guide section, for example

Relevant files

Mesh

A mesh defines the shape and surface of any in-game object.

For more information on .mesh files and how they work, see .

For more informations on materials and mesh appearances, see .

Morphtarget

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.

with 3DS MAX (archived)

3ds Max Workflow for Cyberpunk 2077

Requirements:

- 3ds Max 2014-2022 - - -

Setup:

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

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 exported animation, 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 here (courtesy of Vesna).

Troubleshooting normal maps

In-game, your normal map isn't looking as expected

Import settings

The texture has to be imported without the isGamma flag. Import over an already-existing normal map to rule out this as a source of error. See for more detail.

UV scaling

Cyberpunk actually considers the UV map's scaling when calculating the weight of the normal maps:

Since the neck part is scaled much larger than the chest, this will make the parts of the mesh visibly distinct.

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.

What are materials?

Materials are a specific instance of a , 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.

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 .

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.mltemplate base\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 matTile, 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 normalStrength 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)

Vortex Mod Manager

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 Cyberpunk 2077 mods 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 here – don't worry, it's free.

Why do I need this?

Technically speaking, you don't. You can install mods manually or use Mod Organizer 2 (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 Nexus support or join our Discord 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 a lot of options. 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 Install or Setup section of this guide.

Click this link, 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,
1. Select "Slow Download"
2. Wait through the five seconds cooldown
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

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 Settings section of this guide. (Why are you reading this?)

Logging into Nexusmods

If you are already logged in, proceed to the next section "Adding Cyberpunk"

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

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 Settings section.
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"

Vortex can now manage your game! Proceed to the next section, Settings.

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 Mods section.

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
Deploying: The mod has been copied from Vortex's staging directory to your Cyberpunk game directory.

Deploy mods when Enabled

Automatically deploys each mod as you enable it, merging step 3 and 4. We recommend enabling this, as it saves you a click.

Install Mods when downloaded

Automatically completes step 2 when you download a mod. We recommend disabling this as it lets you address issues and popup one after the other

Enable Mods when installed

Automatically completes step 2 when you install a mod. We recommend enabling this, as it saves you a click.

Run Vortex when my computer starts

Starts Vortex with Windows - disable or enable at your discretion

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

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 core framework collection, which contains everything that other mods require.

Click on "Collections" in the sidebar
Select "Discover more collections."
Wait until the selection page pops up.
Select Core Mods and click "Add to Vortex".

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 troubleshooting page 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 here.) 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 Files 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 "-KS- Vanilla Shoes for High Feet" 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 this link, 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
1. Click on the "images" tab (to the right of "files")
2. Find the picture named "Arey"
3. Navigate back to the "Files" tab

Scroll down to the third option, Arey Hair PHYSICS ENABLEDThe 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
- use "Install From File" in the orange bar and select the file you just downloaded in the explorer window that pops up

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
Head to the character creator and create a female-bodied V
Check hair 48 – normally, it looks like this:

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!

Comprehensive Component Hierarchy List

Hierarchy of WolvenKit.RED4.Types.entIComponent

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.

AIObjectSelectionComponent
AIOffMeshConnectionComponent
AISignalHandlerComponent
entAnimationControllerComponent
entAnimationSetupExtensionComponent
entAnimGraphResourceContainer
entEffectAttachmentComponent
entExternalComponent
- entMorphTargetManagerComponent
entFacialCustomizationComponent
entIMoverComponent
- gameRootTransformAnimatorComponent
- moveComponent
entIPlacedComponent
- entAmbientSoundEmitterComponent
- entBaseCameraComponent
  - entRenderToTextureCameraComponent
    gameuiHolocallCameraComponent
  - entVirtualCameraComponent
  - gameCameraComponent
    gameFPPCameraComponent
    gameFreeCameraComponent
    gameScreenshot360CameraComponent
    gameTPPCameraComponent
    vehicleTPPCameraComponent
    vehicleVehicleProxyBlendCamera
  - gamePhotoModeBackgroundCameraComponent
  - gameWorldSpaceBlendCamera
- entColliderComponent
- entDynamicActorRepellingComponent
- entISkinableComponent
  - entAnimatedComponent
  - entCorpseComponent
  - entInstancedAnimationComponent
- entIVisualComponent
  - cpConveyorComponent
  - entClothComponent
  - entDebug_ShapeComponent
  - entDecalComponent
  - entEffectSpawnerComponent
  - entEnvProbeComponent
  - entFogVolumeComponent
  - entISkinTargetComponent
    entMorphTargetSkinnedMeshComponent
    entSkinnedClothComponent
    entSkinnedMeshComponent
    entCharacterCustomizationSkinnedMeshComponent
    entGarmentSkinnedMeshComponent
    entPhysicalSkinnedMeshComponent
  - entLightBlockingComponent
  - entLightChannelComponent
  - entLightComponent
    cpGameplayLightComponent
    gameLightComponent
    vehicleLightComponent
  - entMeshComponent
    entDebug_MeshComponent
    entEditorMeshComponent
    entPhysicalMeshComponent
    entAppearanceProxyMeshComponent
    entBakedDestructionComponent
    HudMeshComponent
  - entParticlesComponent
  - entPhysicalDestructionComponent
  - entVectorFieldComponent
  - entVirtualCameraViewComponent
    ScriptableVirtualCameraViewComponent
  - gameBinkComponent
- entMarketingAnimationComponent
- entPhysicalTriggerComponent
  - entPhysicalImpulseAreaComponent
  - entTriggerComponent
- entPlaceholderComponent
- entSimpleColliderComponent
- entSlotComponent
  - gameHitRepresentationComponent
  - gameOccupantSlotComponent
- entSoundListenerComponent
- entStaticOccluderMeshComponent
- entTargetPointComponent
- entTransformComponent
  - entVisualOffsetTransformComponent
- entTriggerActivatorComponent
- gameaudioAcousticPortalComponent
- gameAudioEmitterComponent
- gameaudioSoundComponentBase
  - gameaudioSoundComponent
  - gameaudioVehicleAudioComponent
  - gameWeaponAudioComponent
- gameEntityStubComponentPlacedProxy
- gameEnvironmentDamageReceiverComponent
- gameinfluenceBumpComponent
- gameinfluenceComponent
- gameinfluenceHeatAgentComponent
- gameinfluenceObstacleComponent
- gameinteractionsComponent
- gamemappinsMappinComponent
- gameMovingPlatform
- gameNavmeshDetector
- gamePingComponent
- gameprojectileComponent
- gameprojectileSpawnComponent
- gameStaticAreaShapeComponent
  - gameStaticTriggerAreaComponent
- gameTargetingComponent
- gameTransformAnimatorComponent
- mpInteractionActivatorComponent
- senseComponent
- senseSensorObjectComponent
- senseVisibleObjectComponent
- vehicleChassisComponent
- WidgetBaseComponent
  - IWorldWidgetComponent
    AdvertisementWidgetComponent
    StreetSignWidgetComponent
    WorldWidgetComponent
  - WidgetHudComponentInterface
    WidgetHudComponent
  - WidgetMenuComponentInterface
    WidgetMenuComponent
- workWorkspotResourceComponent
entLocalizationStringComponent
entRagdollComponent
entTransformHistoryComponent
entVertexAnimationComponent
entVisualControllerComponent
entWetnessComponent
gameAIDirectorTensionAnalyzeComponent
gameAttachmentSlots
gameaudioMusicSyncComponent
gameBraindanceDissolveComponent
gameComponent
- AICAgent
  - AIHumanComponent
  - AIVehicleAgent
- AITargetTrackerComponent
  - TargetTrackingExtension
- cpTestComponent
- ElevatorController
- EntityStubComponent
- gameAttitudeAgent
- gameDeviceCameraControlComponent
- gameDeviceComponent
  - PSD_Detector
  - PSD_Master
  - ScriptableDeviceComponent
    ActionsSequencerController
    ActivatedDeviceController
    BarbedWireController
    ActivatedDeviceNPCController
    AlarmLightController
    AOEEffectorController
    ArcadeMachineController
    PachinkoMachineController
    BaseAnimatedDeviceController
    MainframeController
    RetractableAdController
    SlidingLadderController
    BaseDestructibleController
    BasicDistractionDeviceController
    BlindingLightController
    ReflectorController
    CleaningMachineController
    ConfessionBoothController
    ExplosiveDeviceController
    C4Controller
    ExplosiveTriggerDeviceController
    SensorDeviceController
    SecurityTurretController
    SurveillanceCameraController
    FanController
    NetrunnerControlPanelController
    SmokeMachineController
    BillboardDeviceController
    CandleController
    ChestPressController
    CoderController
    ConveyorController
    DataTermController
    DisplayGlassController
    DisposalDeviceController
    DoorController
    MovableWallScreenController
    WindowController
    DoorProximityDetectorController
    DropPointController
    ElectricLightController
    GameplayLightController
    ExitLightController
    ForkliftController
    FridgeController
    GenericDeviceController
    GlitchedTurretController
    HoloDeviceController
    HoloFeederController
    InteractiveAdController
    InteractiveSignController
    IntercomController
    InvisibleSceneStashController
    JukeboxController
    LadderController
    LaserDetectorController
    LcdScreenController
    ApartmentScreenController
    MasterController
    AccessPointController
    ActivatorController
    AOEAreaController
    BaseNetworkSystemController
    DoorSystemController
    DestructibleMasterDeviceController
    DestructibleMasterLightController
    DeviceSystemBaseController
    PersonnelSystemController
    SecuritySystemController
    SurveillanceSystemController
    DisassembleMasterController
    ElectricBoxController
    FuseBoxController
    FuseController
    LiftController
    MaintenancePanelController
    NetworkAreaController
    RoadBlockTrapController
    SecurityAlarmController
    SecurityAreaController
    SecurityGateController
    SimpleSwitchController
    SmartHouseController
    SoundSystemController
    TerminalController
    ComputerController
    SmartWindowController
    ElevatorFloorTerminalController
    TrafficIntersectionManagerController
    VentilationAreaController
    MediaDeviceController
    HoloTableController
    RadioController
    TVController
    WallScreenController
    MovableDeviceController
    NcartTimetableController
    NetrunnerChairController
    OdaCementBagController
    PortalController
    ProximityDetectorController
    RoadBlockController
    SecurityGateLockController
    SecurityLockerController
    SpeakerController
    StashController
    StillageController
    ToiletController
    TrafficLightController
    CrossingLightController
    TrafficZebraController
    VehicleComponent
    AVComponent
    CarComponent
    MotorcycleComponent
    VendingMachineController
    IceMachineController
    VendingTerminalController
    VentilationEffectorController
    WardrobeController
    WeakFenceController
    WeaponTrainingController
    WeaponVendingMachineController
    WindowBlindersController
- gameEntitySpawnerComponent
- gameEntityStubComponent
- gameInventory
- gameMasterDeviceComponent
- gameScanningComponent
- gameScriptableComponent
  - AdamSmasherComponent
  - AIRelatedComponents
    AICustomComponents
    CentaurShieldController
    AIMandatoryComponents
    HitReactionComponent
    HitReactionMechComponent
    StatusEffectManagerComponent
    AIPhaseStateEventHandlerComponent
  - AppearanceRandomizerComponent
  - AreaEffectVisualizationComponent
  - BossStealthComponent
  - CombatHUDManager
  - DEBUG_VisualizerComponent
  - DetectorModuleComponent
  - DeviceConnectionHighlightComponent
  - DeviceDebuggerComponent
  - DeviceTimetable
  - DiodeControlComponent
  - DisarmComponent
  - DisassemblableComponent
  - DrillMachineScanManager
  - DroneComponent
  - DurabilityComponent
  - EntityAttachementComponent
  - Example_FxSpawning
  - FastTravelComponent
  - FollowSlotsComponent
  - FxResourceMapperComponent
  - gameAINetStateComponent
    NPCStatesComponent
  - GameplayRoleComponent
  - InputDeviceController
  - InspectableObjectComponent
  - InspectionComponent
  - MinotaurMechComponent
  - ObjectMoverComponent
  - OdaComponent
  - PhotoModePlayerEntityComponent
  - PlayerPhone
  - QuickSlotsManager
  - ReactionManagerComponent
  - ResourceLibraryComponent
  - RewireComponent
  - RoyceComponent
  - SampleComponentWithCounter
  - SampleCounterDisplayComponent
  - SasquatchComponent
  - ScannerControlComponent
  - ScavengeComponent
  - SimpleTargetManager
  - StimBroadcasterComponent
  - TankTurretComponent
  - TestScriptableComponent
  - TrapComponent
  - UpdateComponent
  - VendorComponent
  - WeaponPositionComponent
  - WorkspotMapperComponent
- gameSquadMemberComponent
  - SquadMemberBaseComponent
- gameStatsComponent
- gameStatusEffectComponent
- gameVisionModeComponent
- scnVoicesetComponent
- vehicleCameraManagerComponent
- vehicleController
- vehicleGarageComponent
- vehiclePersistentData
gameComponentsStateSaveComponent
gameCrowdMemberComponent
- CrowdMemberBaseComponent
gameDismembermentComponent
gameDoorComponent
gameEthnicityComponent
gameFootstepComponent
gameHumanoidBody
gameImpostorComponent
gameinteractionsReactionComponent
gameITriggerDestructionComponent
- gameBodyTriggerDestructionComponent
- gamePuppetTriggerDestructionComponent
gameLadderComponent
gamemountingMountableComponent
- gameMovingPlatformMountableComponent
- gameObjectMountableComponent
- gamePuppetMountableComponent
- vehicleVehicleMountableComponent
gameMultiEcsManagerComponent
gameMuppetComponent
- gameMuppetBlackboardsComponent
- gameMuppetInputStates
- gameMuppetInventory
- gameMuppetLocomotionComponent
- gameMuppetPhysicsComponent
- gameMuppetRawInput
- gameMuppetStats
- gameMuppetUpperBodyRequestsComponent
gameMuppetInputHandlerComponent
gameNarrationPlateComponent
gameNetrunnerPrototypeComponent
gameObjectCarrierComponent
gamePhantomEntityComponent
gamePhotoModeBackgroundViewComponent
gamePhysicalDestructionListenerComponent
gamePlayerCommandConsumerComponent
gamePlayerControlledComponent
- gamestateMachineComponent
gamePlayerMappinComponent
gamePlayerTierComponent
gameScanningActivatorComponent
gameSimpleOccupantSlotSpawner
gameSourceShootComponent
gameTargetingActivatorComponent
gameTargetingLocalizedEffectComponent
gameTargetShootComponent
gameTPPRepresentationComponent
gameuiICharacterCustomizationComponent
- gameuiCharacterCustomizationBrokenNoseController
- gameuiCharacterCustomizationPersonalLinkController
- gameuiICharacterCustomizationBodyController
  - gameuiCharacterCustomizationBodyController
- gameuiICharacterCustomizationBodyPartsController
  - gameuiCharacterCustomizationBodyPartsController
    gameuiCharacterCustomizationFeetController
    gameuiCharacterCustomizationGenitalsController
    gameuiCharacterCustomizationHairstyleController
gameVisionActivatorComponent
gameWeakspotComponent
moveIMotionPlannerComponent
- moveMotionPlannerComponent
  - moveDroneMotionPlannerComponent
movePoliciesComponent
worldTrafficLightListenerComponent

Troubleshooting

If your mods are causing trouble, here's what you can do

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

Before you start debugging, make sure that

your graphics driver is up-to-date
your is up-to-date (no, really)
you have the most recent version of installed
you have installed (, Microsoft)

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!

Find a download-ready collection for Vortex .

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.

A mod is causing problems, and you have no idea which:
- Searching:
- Searching:
Deleting user settings

To enable REDmods, check .

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.

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 .

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 .

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.

Crash during the game

This section tells you how to deal with crashes during gameplay.

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

… 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 help, try (you will need to verify your game files).

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

Before trying to implement any of the other solutions, configure the REDprelauncher.exe in the 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

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

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.

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 complete the steps by hand. Otherwise:

Download (right-click -> save as) Link goes to Presto's
Now, do either of the following things:
1. Move it to your Cyberpunk install folder and double-click it
2. 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.

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.

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

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:

From your renamed folder directory_, move half of the mods over to the empty game folder directory so that they'll become active.
Start the game. You will now run into one of two scenarios:
- The error is gone: The problematic mod is in your backup folder, but you now know which mods are okay.
  - If this is the first round: Go back to 1
  - Otherwise: The broken mod was in the bunch that you moved out in the last round. When repeating step 1, you can ignore everything but the last bunch you moved.
- The error is still there: The problematic mod is your game folder. Move half of the mods out of the folder again. If this is not the first round, only do the last subset that you moved.

Repeat this process until you've identified the mod that's crashing your game.

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

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 an explanation or follow the checklist below.

Make sure that you have in your launcher.
If items or hairs aren't changing, you need to install
If materials aren't updating, you need to install
If you already have all of that, .

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. Save yourself the headache and manage your mods through or manually. Or you can look into "Root Builder" and "Wabbajack." Those keywords might help you if you choose to stick with MO2. Don't say we didn't warn you though!

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 )
Check the other log files in the game directory ()
Optional: reach out to us on in #mod-troubleshooting

Mod isn't working:

You have installed Cyber Engine Tweaks, but it's not active / not letting you bind a key:

Is CET in the right place? It has to be installed under

Is there a gamelog.log inside the directory? If not, move the folder out of plugins and reinstall from a fresh download.
Do you have installed? ( from Microsoft)

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
Search the CET folder for log files
Try to resolve any errors or reach out to us on in #mod-troubleshooting

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:

The linked above will do that for you.

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 the folder pc
Inside pc, delete everything but the folder content
Verify your files

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
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).
Optional (for CET): Start the game and make sure that it asks you to bind a key. If not, check the

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
your game is starting
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 first and complete the process.

If you need help, find us on in #mod-troubleshooting!

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:

Cyberpunk is trying to write to a file that doesn't exist

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
Check if you can see anything Cyberpunk in the list.
If yes, right-click on it and select End Task

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

Press Windows+R
Type cmd and press return
Run the following command (make sure to insert your real Cyberpunk path):
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):

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 inside of other mods. Since that is different now, the leftover versions can cause errors.

Search your for Codeware.
If you have exactly one folder, this is not your problem — proceed to .
Delete everything you have found.
Reinstall the latest version of from Nexus.
Delete the folder r6/cache
Verify your game

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:
install cybercmd (| )

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
verify game files
create a new directory r6/cache/modded (this will prevent errors)
Make sure that r6/scripts
Make sure that red4ext/plugins (that the red4ext core frameworks aren't getting loaded)

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 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 and start modding your game again.

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"
Click "Verify integrity of game files…"

Epic

Open your "Library"
On the "Cyberpunk 2077" tile, find the "…"
Select "Manage"
Click "Verify"

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 )
google your error message and try solutions at random

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!

File Formats

All inclusive list of REDengine file formats

Created by @manavortex Published April 10 2023 Game version: 1.6.1_DLSS

For an exhaustive list, see the W2RC File Format Table.

.app (Appearance definition)

This file contains a list of appearances with their associated components. To load them, you require a root entity .ent.

Holds a list of components.

.ent (Entity)

Root entity

The entry point for the game to display an NPC or prop. This kind of entity usually doesn't have components by itself, but only points towards the .app file 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 .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.

.inkatlas (Texture mapping)

.mesh (3d object)

A 3d object, holding appearances, materials, and rigging.

A mesh can have several submeshes, which can be displayed or hidden via chunkmasks.

.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 here. For an explanation on .mi files, see here.

Relevant properties:

Different per material — see parameters/[2] for a list of properties

e.g. BaseColor, Metalness, NormalStrength or VectorField, FresnelColor, Albedo

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

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:

IsGamma

Override in-game gamma (lighting)? - Set to "false" for normals - Set to "true" for diffuse/albedo and any parts of the UI

W2RC File Format Table

Extension

Description

Fully Parsed

Animation

Audio

Pathfinding/AI

Animation graph

Animation data

Mesh appearance configurations

Terrain related

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 settings

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

Particles

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

Generic Format

Generic FIle Format Table

Extension

Description

Standard CSV file

Audio file

Archive Format

File Structure

Name

Type/Size

Info

Header

See below.

Custom Data

WolvenKit only. See below.

Files

data

Raw file data

File List

See below.

Header

Name

Type/Size

Info

Magic

char[4]

Constant: "RDAR"

Version

uint32

Currently 12

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

Custom Data (WolvenKit)

The following data only applies for archives created with WolvenKit

Name

Type/Size

Info

Magic

char[4]

Constant: "LXRS"

Version

uint32

Currently 1

Size

int32

Size of uncompressed data

ZSize

int32

Size of compressed data

PathCount

int32

Number of custom paths

PathStrings

zstring[PathCount]

Custom file paths

File List

Name

Type/Size

Info

FileTableOffset

uint32

Always 8

FileTableSize

uint32

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]

File Record

Name

Type/Size

Info

NameHash64

uint64

FNV1A64 hash of the filename

Timestamp

int64

Windows filetime of file creation

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

File Segment

Name

Type/Size

Info

Offset

uint64

Offset of the data

ZSize

uint32

Size of compressed data

Size

uint32

Size of uncompressed data