Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Adding stuff to the game, for the major-leagues
As suggested by psiberx, the general usage documentation for ArchiveXL will be kept in this wiki for ease of use. You can find the readme on github or check the repository's wiki section.
ArchiveXL (nexus | github) is one of the core frameworks of Cyberpunk 2077 modding. Together with TweakXL, It allows you to add things to the game, such as
world sectors (deletions and additions)
custom lipsync maps
Translations (check #how-does-the-game-assign-display-namesfor a guide)
If you want to look up garment appearance slots: The princess is in another castle. Check Different equipment slots instead.
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.
When adding items, you will normally offer multiple mesh appearances (variants), for example, the same shirt in black, white, and red. This is what you're modding for, after all: making cool things.
On top of having different colours, you also have different circumstances – for example camera states: not even Johnny Silverhand wears his sunglasses in first person perspective.
CDPR deals with this by using suffixes, which are tedious to use. psiberx has since created a better system (dynamic appearances or conditions), which are much easier to use.
For more detail on this, please see the sub-page ArchiveXL: Suffixes and Substitutions
Tags are a way to add extra information to entities or appearances. They are defined on their own sub-page: ArchiveXL: Tags
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 more detail about this on the sub-page ArchiveXL: Suffixes and Substitutions -> #which-substitutions-exist
For a tutorial about this, check ItemAdditions: Dynamic Appearances
If you are a mod user and want to dynamically recolour an item, check the Recolours and Refits guide -> sub-page Emissive -> #switching-existing-colours
Here's an overview of how the dynamic variants work. By comparison, this is the old diagram. Especially for items with many appearances, the new way is much faster.
A list of modding frameworks and libraries, and links to their documentation
In the context of Cyberpunk modding, the core mods are often interchangeable called "(core) frameworks".
If you are trying to troubleshoot your core mods, you can run the log file utility.
For an explanation of what the individual core mods do, see below.
ArchiveXL – TweakXL – Codeware – Equipment-EX
While the game natively supports mods, this would have had us limited to replacing already existing items, but we wanted flying cars. So a bunch of brilliant people drilled deep into the code of Cyberpunk 2077 and created a bunch of tools that let us do more.
The most prominent example of a core mod is the Skyrim Script Extender — fortunately, Cyberpunk 2077 is rather more stable.
Since this kind of mod interacts with the game 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 core mods you need have been brought up-to-date.
Redscript (Nexus | GitHub) is an open-source programming language and toolkit (currently includes a compiler, a decompiler and a disassembler), natively working with Cyberpunk 2077's scripting runtime.
The scripts are compiled into a binary format recognizable by the game engine. The final blob includes original game scripts with all changes from the mods, and replaces original r6/cache/final.redscripts
or r6/cache/modded/final.redscripts
.
Redscript supports importing native types and functions registered by mods based on RED4ext.SDK, allowing modders to extend scripting runtime functionality.
Some examples for existing mod include, but are not limited to
changing combat balance
editing NPC behaviour
altering the interface
adding or removing UI widgets
Requires RED4ext.
Cyber Engine Tweaks (Nexus | GitHub) is a framework with a LUA wrapper, which will let you access anything exposed via RTTI, i.e. all scripted and native types and functions, including those added using redscript and RED4ext. On top of that, it lets you bind hotkeys for custom functions and interact with the game's TweakDB database at runtime.
Changes made via CET's Tweak Browser are not persistent, because the TweakDB gets changed at run-time. You can use TweakXL or create a CET mod to apply your changes each time the TweakDB is initialized.
Lots of mods and scripts run on top of CET, tweaking the game in various ways from changing the weather to adding a wardrobe system before CDPR added one.
The perhaps most prominent example is Appearance Menu Mod (wiki | Nexus), which turns Cyberpunk 2077 into The Sims: Capitalist Dystopia.
RED4ext (Nexus | GitHub) is Cyberpunk 2077's equivalent to Skyrim Script Extender. It consists of two parts:
RED4ext Loader – Loads and manages .dll
plugins from red4ext/plugins
. Provides essential functions such as game version checking, logging, hooking, and some REDengine 4 specific helpers for plugins.
RED4ext.SDK – Contains the reversed engineered types and helpers to extend the engine. It can also be used independently of RED4ext loader. Originally written in C++, but there's also a Rust binding.
With RED4ext >= 1.13, you no longer need cybercmd. Make sure to uninstall it!
Requires RED4ext.
ArchiveXL (Nexus | GitHub) allows modders to load custom resources into Cyberpunk 2077. Working under the hood, it is the essential tool to add and extend rather than replace. It also includes script extensions to, for example, load UI widgets from any resources than only those available to the current context.
For ArchiveXL specific documentation, check the corresponding sub-page.
Requires RED4ext.
TweakXL (Nexus | GitHub) allows modders to modify TweakDB in the form of .yaml
or .tweak
files. It also adds a scripting API allowing redscript mods to apply changes during TweakDB initialization or dynamically.
Requires RED4ext.
Codeware (Nexus | GitHub) is a library and framework for redscript and Cyber Engine Tweaks mods. It exposes many engine types and functions that are not available by default and adds new functionalities regarding many aspects of the game, such as:
game events and life cycle
spawning game objects
manipulating world states
building UI widgets
accessing type information
... and much more.
Equipment-EX (Nexus | GitHub) makes use of every single one of the frameworks mentioned above to overhaul CDPR's wardrobe system. Extending it from 6 slots to more than 30, it lets you save an unlimited number of outfits and supports modded items.
Requires RED4ext.
RedFileSystem (Nexus | GitHub) is a library for redscript and Cyber Engine Tweaks mods. It exposes functions to read / write with the file system. It supports UTF8 text and Json formats. Modders can create, read and write files within game's directory. It can be useful to store custom data, for example in a mod's directory.
This will tell you what mods and scripts CET is loading, and if there have been any errors in the process.
If all goes well, it will look like this:
It will tell you which .reds
files it has been loading, and if any of them failed.
Please note the warning in the log:
If the mod is working, ignore it
If the mod isn't working, this tells you what to check. You can't have mods installed twice!
If all goes well, it will look like this:
It will tell you which of the plugin DLLs it has been loading.
If all goes well, it will look like this (version numbers are fake):
Tells you which .xl files have been found and processed and what it has been adding into the game files upon startup.
If it loads correctly, you will see something like this:
Note that the example contains a bunch of warnings. That indicates problems with the modded files (which I ignore, since they are working),
Tells you which tweaks have been read and processed, pointing out errors and warnings in the process. If your custom item additions don't work, you might find a hint here.
If it loads correctly, you will see something like this:
Tags are a way to tell Cyberpunk that an item has certain properties and should behave in a certain way. This makes the game apply properties to your items, which can then be utilized by the game and ArchiveXL to
hiding V's junk to stop it from clipping through tight pants (hide_Genitals
)
forcing female V's feet to be flat (force_FlatFeet
)
showing hair while wearing a head item (force_Hair
)
Tags are case-sensitive!
There are a few tags that can be added to the root entity or in the .app file. Here's a list:
This will hide an item under certain conditions. Add the following tag to the root entity:
EmptyAppearance:FPP
You have the following other options to achieve the same end:
force_Hair
By default, head items turn hair invisible. By adding this tag to the root entity, you can override this process.
force_FlatFeet
Only works with a foot item as $base
in the .yaml
: use this if you're making flat shoes and don't want female V's feet to look as if she was wearing heels.
This tag will turn feet invisible for mascV unless the user has switch feet installed. You want to apply this to a conditional appearance in the .app file (&gender=m
)
For this, it is mandatory that you have unique component names. If you include your modder name, it's unlikely that anyone will overwrite them by accident.
PartsOverrides can't un-hide components for you. It can only hide them. If you want to load a different mesh (for example, a de-formed hakama when wearing a kimono or haori), then you're flat out of luck.
By being clever about your submeshes, you can offer different versions of your mesh (cropped! No arms! No legs), and users only need to install an .xl file! No need to have different meshes or even different .archive files.
Add custom tags in your .xl
file (not in your .yaml
!)
Simply add the tag to your appearance's tags array near the bottom of the individual entries.
How suffixes and substitutions work
This page will teach you about conditional appearance switching in Cyberpunk and give you an overview of existing suffixes and substitutions.
ArchiveXL did not invent suffixes. In fact, they are CDPR's solution to a problem, and they are annoying to use.
psiberx has found ways to make this less painful. This page documents these ways.
Sometimes, you want to load different meshes/appearances under different circumstances. Before ArchiveXL 1.5, the only way to do that were suffixes — registering them in the .yaml
, then adding one appearance for each variation in the root entity (so for 2 suffixes, you'd have 4 entries, for 3 suffixes, you'd have 8…).
But while the solution has changed (and improved), the problems remain and require handling.
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.
The suffix for the body is Male
/ Female
, the ArchiveXL string substitution is {gender}
and resolves to m
or w
.
You can check the current foot state by running the following command from CET:
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).
The arm states represent the different cyberware. For example, since you can't hire the forearms for mantis blades, you can roll up the sleeves just for this. The definitions are:
You can check the current foot state by running the following command from CET:
You can check the current foot state by running the following command from CET:
You can disable suffixes by adding the following line to your .yaml entry:
the base appearance (with no suffix)
the most specific suffix collection it can find
V has a female body gender and you're in photo mode (third person camera). Your base appearance is called appearance_
.
inside mesh entity
components in the fields name
, depotPath
and appearance
in the .app
appearances for the field name
Any placeholders will be interpolated at run-time (replaced with the correct value for your current state)!
Substitution will only become active if the property name starts with an asterisk (*
).
The order works as follows:
Published in August 23 by
Published: ??? by Last documented update: Feb 18 2024 by
This page will tell you about tags and how they can be used to influence item behaviour. It also teaches you how can help you conditionally un-hide items.
Tags are used for calculating Garment Support score, see
There is an own page for
Please keep in mind that you need to add those to the 's appearance definition rather than the root or mesh entity.
Tag | Effect |
---|
Tag | Effect |
---|
Check the section below for more tags
The diagrams below are somewhat outdated. Especially the arms information is not accurate. (.)
This only works for legacy ArchiveXL projects. If you're using , please use s in your .app file.
Custom tags let you set from the .xl file without the need of touching either .app or .ent file.
Not convinced? Pity, but if you find a new use case for those things, do !
Published: ??? by Last documented update: Feb 18 2024 by
For a hands-on guide to , check the corresponding pages under .
Dynamic appearances have their own guide (see )
There is an own page for
Since 1.5, psiberx has made it possible to use conditionals via , which require a lot less of an overhead. (Personally, I've gone from 96 entries in the root entity down to 9!)
To conditionally hide items or parts of items, check or (especially the section about )
ArchiveXL allows body modders to , which can then be used for suffixes and for substitutions in dynamic variants. To learn more about this, check .
Camera mode | FPP | substitution |
---|
Cyberware | Suffix |
---|
If the arm states aren't working as expected, check if the table above is outdated by comparing the names with the .
To achieve gender equality in regard to foot states, you need to use . The substitution key for dynamic appearances is feet
.
Character | Footwear | Suffix/Tag | Substitution: feet= |
---|
If the foot states aren't working as expected, check if the table above is outdated by comparing the names with the .
For ArchiveXL , you don't need to bother with suffixes at all – they will have
Suffix | Explanation |
---|
full appearance name |
---|
Since 1.8.0, ArchiveXL supports substitutions for . You can use them in two places:
For a tutorial about this, check
If you are a mod user and want to dynamically recolour an item, check the guide -> sub-page Emissive ->
If any of the placeholders aren't working the way you expect them, check if the table below is outdated by referring . (Please update the wiki if that happens!)
Placeholder | Substitution |
---|
For , you can conditionally switch out components or entire appearances by name. You can switch use any of the entries from
Appearance/Component | Priority | Description |
---|
| Hides an item in the |
| Hides an item in the |
| Hides an item in the |
| Hides an item in the |
| Hides an item in the |
| Hides an item in the |
| Toggles the partial suffix ( |
| Hides hair. |
| Hides genitals in uncensored mode and underware in censored mode. |
First Person Perspective | &FPP |
|
Third Person Perspective |
|
|
None |
|
|
Mantis Blades |
|
|
Monowire |
|
|
Projectile Launcher |
|
|
Female | Unequipped |
|
|
Female | Equipped (default) |
|
|
Female | Equipped with |
|
|
Female | Equipped with |
|
|
Male | Any | (empty) |
| This item is gendered
When resolving the appearance name via |
| This item has special rules for first and third person camera
When resolving the appearance name via |
| If the current item has |
| Defines how your item will look if a certain hair type is loaded (e.g., hide the back half of a bandana for long hair).
When resolving the appearance name via |
| Found first, then ignored because a more specific appearance exists. |
| Ignored: V's body gender isn't male |
| ignored: a better match exists |
| ignored: you are not in first person camera |
| best match! The game will use this one! |
| 1 | Has the highest priority because it requires a specific variant and one state condition. |
| 2 | Has second priority because it requires a specific variant. |
| 3 | Has third priority because it has two state conditions. |
| 4 | Has fourth priority because it has one state condition. |
| 5 | Has the lowest priority and will be used when no other elements match the criteria. |
Appearance Menu Mod
Appearance Menu Mod has its own documentation at…
You can find help on their Discord.
| Hides head. |
| Hides the whole torso. |
| Hides lower abdomen. |
| Hides upper abdomen. |
| Hides collar bone area. |
|
| Hides thighs. |
| Hides calves. |
| Hides ankles. |
| Hides feet. |
| Hides the entire legs (including feet) |
Root entity appearance (without dynamic variants) |
| .app path: |
| ArchiveXL will automatically add empty appearances for anything you have not defined |
| no partsValues, no components. Do not do this - use the line above this one instead! |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Changing the game's database entries
For a detailed guide with many explanations of properties, check the second half ofNew Iconic Weapon: Step by Step
TweakXL (nexus | github) is a mod by psiberx. It lets you alter Cyberpunk's Tweak Database, changing properties of NPCs and items or even adding new entries.
By placing .yaml
or .tweak
files in Cyberpunk 2077/r6/tweaks
, or .xl files in Cyberpunk 2077/archive/pc/mod
.
No matter the file extension, the file contents
must be .yaml
or .json
Explanation of the database: TweakDB: Game database
Additional information: TweakXL wiki on github.
Starting with version 1.5, Archive XL supports tags for body mods ! That means, no more compatibility archives, since AXL can simply load different meshes for you…
Body type detection works with simple body replacements and with the character creator extensions (customization system).
Run the following code snippet in CET to see which body type you have installed:
Create an .xl file in your Wolvenkit Project's resources folder
Optional, but recommended: Give it the same name as your Wolvenkit project
Put the following file content:
In any of the files you modded, check your components
:
morphtargetComponent
?Yes:
Add a tag with the exact name of your body in this component's tag array (for our example, NewBody
)
No:
Add a new component (of any type) and give it the following name:
Body:NewBody
If you edit the leg component for female V, you must change both the regular and the flat feet component:
base\characters\common\player_base_bodies\appearances\l0_000_base__full.app
base\characters\common\player_base_bodies\appearances\l0_000_base__cs_flat.app
The files below have been confirmed to work — make the changes stated above to each of them:
Test
After packing your project, check if the body tag registers by running the CET command.
If yes, you're good to go!
If not and you have used a component, you can check if the component is added to the playerPuppet by checking RedHotTools:
If you're using dynamic appearances, you don't need to register a suffix and can simply match or substitute for the body tag:
If no body mod is installed, the value will be base_body
, so make sure to name your files and folders accordingly!
If you're sticking to the classical approach, you need to add the following lines to your .yaml
:
Now, you can use the suffixes in your root entity just like camera states or body genders:
The following body mods support dynamic body switching.
If you know something that should be on the list, please edit The wiki!
As of 18th March 2024, Nim's More Body Meshes is compatible again with Gymfiend Body Mod.
Use only one main archive! [#_nim_more_body_meshes_Gymfiend_patch.archive]
Hides the whole arms, including hands. (There's , you would have to )
.app : change default appearance name
.app : add empty appearance yourself
from customization, e.g. 03_senna
from customization. e.g. black_liquorice
Mod | Tag name | substitution value |
---|---|---|
Lush
&body=lush
Lush
&body=lush
Ult
&body=ult
RB
&body=rb
EBB
&body=ebb
EBBP
&body=ebbp
EBBRB
&body=ebbrb
EBBPRB
&body=ebbprb
Gymfiend
&body=gymfiend