Colliders are added via .phys files. For cars, those get added by the chassis component:

For more information on car collision, see Boe6's vehicles: Interaction collider .phys files

Definition

Serves as the top-level container for entities and their properties within the game. Most things that you can see, touch, or interact with have an .ent file somewhere in their hierarchy. Examples are player equipment, weapons, NPCs, interactables (doors, vending machines…)

For the purpose of modding, we distinguish between two different kinds of entity files.

Mesh/Component entity (simple entity)

The minimal way of adding something (e.g. meshes) to the game. This entity can be directly spawned (e.g. via AMM) or referenced from within Appearance: .app files.

For player equipment (weapons and armour), you can use mesh entities to encapsulate parts of your item. You load such .ent files via partsValues, which will be added to the corresponding appearance as if the components had been in the .app file itself.

This is good practice to avoid repetition, and also to make it easy on yourself if you want to change paths later in your project (imagine having defined 20 appearances with 5 components each, and then wanting to rename your mesh folder…)

Root entity

The entry point for the game to display an NPC or prop. This kind of entity only defines those components that are shared among all appearances. Meshes are defined in the app file, where they can be assigned different properties (e.g. materials) per appearance.

From ArchiveXL item additions, this kind of file is usually called a root entity.

• An entity file can define multiple appearances, which can point to different .app files.

• For creating props, root entities are used as the defining key (one entity => one item, which can have multiple appearances)

• Names support suffixes, allowing you to load different appearances based on body gender or camera mode. These are only used for player equipment and look like &FPP

• How you split your .app files is largely a matter of taste. At CDPR, they usually shove everything into one file.

What are suffixes?

In a root_entity file, you can give the game a list of appearances and have them mapped to an Appearance: .app files by entry name. While that's pretty good already, have you ever wanted to be more specific — for example, "for a male character, use this appearance, but for a female use this other one?"

This is where suffixes come in. You append them to an appearance's name in the root_entity, and the game will pick the correct appearance (and the correct app file, and the correct mesh!) based on the best match.

If you are registering an item via ArchiveXL, you can define suffixes via appearanceSuffixes: [ … ] in the .yaml file.

appearanceSuffixes: [ 
  itemsFactoryAppearanceSuffix.Gender, 
  itemsFactoryAppearanceSuffix.Camera ]  

What can possibly go wrong?

appearanceSuffixes: []

Which suffixes exist?

Appearances

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

appearanceResource

• baseEntityType: name that exists in the base type map and mapped to the correct .ent file

• commonCookData: the .cookedapp file that stores a copy of the data for faster loading

appearanceDefinition

A list of appearance definitions to be called from a root entity file. The definitions are independent from each other (unless parentAppearance is used? Confirmation needed) and load meshes and effects via components.

• name: the appearance's name that is listed in its .ent file

• parentAppearance: the appearance this one inherits information from

• proxyMesh: the .mesh file loaded for rendering the vehicle at a distance (confirmation needed)

• resolvedDependencies: pre-loaded resources. You will usually want to delete these if you're adding items from scratch.

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

partsValues

Allows you to add one or more component entities into your appearance. They will be treated as if the components were part of the appearance's components array.

partsOverrides

Overrides component definitions via name. They can be defined in the appearance's own components array or loaded via component entity.

You can use them to change the appearance or visibility of components outside of the current .app file (for usage instructions, see #partsoverrides-changing-other-meshes).

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

Summary

Last documented update: Apr 06 2024 by

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?

Texture files

.xbm files are simply CR2W (REDengine) representations of .dds files. Regardless, you still need to .

Header

Any CR2W file includes a section telling the engine how to read it, the header. Most of the file encodes texture data, but the header for textures includes:

• size

• mipmapping (lower-resolution versions of the same texture for LOD and streaming)

• texture format

• dimensions (e.g. if your texture data is 1024x1024, but the header says it's 512x512, then the engine will resize it)

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, such as:

• bit depth

• texture type

• format

• gamma correction

• streamability

• mip chains

Summary

Published: January 06 2024 by

Why are submeshes?

In Cyberpunk, you can assign one material per submesh.

At first, this seems a bit counter-intuitive, but keep in mind that Cyberpunk's entire material system is geared for flexibility. By altering a single submesh material, a black Arasaka helmet with red lights and a Hello Kitty hologram can become a black Militech helmet with red lights and a Hello Kitty hologram!

Submeshes in Blender

In Blender, our helmet would look like this:

You can create more submeshes by splitting off parts of a mesh, and incrementing the submesh index.

Example:

You want red and blue glowing tubes on the example helmet.

2. Re-name submesh_04_LOD_1.001 to submesh_05_LOD_1

4. Your mesh will now have six submeshes instead of its previous five

5. For each appearance that you have defined, add a chunkMaterial entry. If you skip this step, the new submesh will have no material assigned, and be invisible.

Chunkmasks: partially hiding meshes

Imagine you want to hide the helmet's glowing parts (because you are being stealthy). You could just define another appearance where the glowing tubes are turned off — but you would have to add one for every variant you make. arasaka_hellokitty_glow and arasaka_hellokitty_noglow, the same for Militech, NightCorps and NCPD… ain't nobody got time for this.

That's why CDPR came up with chunkmasks.

The numbers in the dropdown correspond to the submeshes: unchecking an entry will hide it, regardless of the assigned materials.

How to see chunkmasks in-game?

ACM

With ACM installed, make sure that the target is under the cursor in the middle of the screen (you can use photo mode to look at V). Then, find the correct mesh/component in the UI and click on the correct button:

RedHotTools

Level Of Detail (LOD)

If a submesh does not end in LOD1, that means it's intended for lower resolutions (for example, if an object is far away).

Summary

Published: ??? by Last documented edit: Sep 19 2024 by

This page contains information on .mesh files and their properties.

Wait, that's not what I want!

• See -> for a guide on export/import

• To edit a mesh's appearance, check

  • If you just want to use a textured material, check

• To learn about mesh materials, see

• To hide parts of a mesh under different circumstances, check

• To stop copy-pasting so much, check

What's a mesh?

In the context of Cyberpunk, a mesh is the file that defines the and the of an object in the game world.

A mesh can have several submeshes, each of which has own material assignments. You can learn more about this on the sub-page for .

Mesh files for inanimate objects also tend to contain extensive physics parameters governing their physical weight and general behavior.

How the mesh is loaded

Shadows

There are two ways of adding shadows to meshes:

Component property

To make a mesh cast a real-time shadow, set the component's property castShadows to Always.

Shadow mesh

Many meshes have dedicated shadow meshes, which have a much lower level of detail and will be hidden by default. You can open any clothing item's mesh entity to see this in action.

Mesh Preview

You can see which submesh is which in the Mesh Preview tab after opening the mesh file:

With the boxes on the left, you can toggle submeshes on and off.

Material assignment

Step 1: Appearances

An appearance is the entry point into a mesh.

One appearance has a number of chunkMaterials, which tell Cyberpunk how they are supposed to look:

Wolvenkit will follow these entries to materialEntries, where they are defined:

TL;DR

Here's an overview:

ChunkMaterials

You assign materials based on the "chunks" (the individual submeshes) inside a mesh. Open the mesh file in Wolvenkit and open the "appearances" array, then make sure that each of your submeshes has an entry inside the array.

Step 2: Material registry

Materials are registered in the array materialEntries inside your mesh:

Preload… what?

Many of CDPR's early meshes use preloadLocalMaterialInstances instead of localMaterialBuffer.materials. As far as we are concerned, you can use the two interchangeably, but:

If you are using a mix of local and external materials, you must use the corresponding lists:

If you mix the two, the materials outside of preload… will appear as transparent the first 1-2 times you trigger your item's appearance.

Step 3: Material definition

MaterialInstance: The local material

The materials themselves are inside the array localMaterialBuffer.materials (or preloadLocalMaterials in case of older meshes).

A material instance looks like this:

Summary

Published: ??? by Last documented update: May 13 2024 by

This page collects basic information about hair profiles.

Wait, this is not what I want!

• Check -> for a guide on importing/exporting

• Learn more about ->

What's a hair profile?

Via hair profiles, it's possible to quickly and easily create a large variety of hair colour variations without the need of having colour textures. That happens via two arrays:

gradientEntriesId

Determines the strand to strand colour by using the Strand_Gradient texture. The gradient serves to empathize/de-empathize contrast among the black/white scale.

Together with the gradientMap, this is used to generate varieties of unique hair materials.

gradientEntriesRootToTip

Is applied to the Strand_Gradient texture to determine the hair colour from start to top. Via gradientStops, the colour positions from root to tip of the strands are determined.

Summary

Published: ??? by Last documented update: May 01 2024 by

This guide will teach you how .mi files work

What is a material instance?

A .mi file encapsulates a material in a reusable template file, which you can use a .mi file as base material in a .

It is possible to use multiple .mi files in a row. For an example of this, check the player's .

Why do I need this?

Put yourself in the shoes of a hypothetical modder.

• You are creating a mod that offers multiple versions of the same item (e.g. toy props or hair)

• You have created a base material

• You duplicate and re-duplicate the material for each of your variants, changing the properties that defines the colour

• You wish that there was less copy-pasting involved

.mi files to the rescue

Take any of them from the game, move them to your custom directory, and group all the properties that you keep copy-pasting into the .mi.

Then, in your material, you can now use your .mi file as baseMaterial, and only change the properties that are actually different!

Instead of copy-pasting six properties, you now copy-paste only two.

Making material templates

For this, I first created a plastic_base.mi with all the common properties, and then created one additional .mi file for each shade of plastic, setting plastic_base.mi as baseMaterial, leaving me with the following folder structure:

If I decide that my plastic is too shiny, I can edit _plastic_base.mi instead of touching every template individually. Pretty neat, isn't it?

And if one of my items happens to have a custom normal map and/or texture, then I just add them in the values array of my material and call it a day.

Maximally lazy: external materials

But we can take this approach even further! If you don't have any properties, your mesh doesn't even need materials! You can simply use the externalMaterials list instead. You do this by unticking the isLocal property in the materialEntries definition:

Warning

You can of course mix and match local and external materials! Just make sure that the materialEntries indices are pointing at the correct material.

However:

env has extra feature, it controls weather probability, the .envparam is the exact same as .env but only contains lighting changes, so it works with any weather rebalancers without compatibility patches, since the lighting part is overridden by envparam, but not the weather probability

Quote: someone on Nexus

Summary

Published: Mar 02 2024 by Last documented update: Mar 02 2024 by

This page explains how meshes are casting shadows.

Wait, this is not what I want!

• Find information about shadows in the environment under Environment: Shadows

• To learn more about Level of Detail (LoD), check the corresponding wiki page.

How to cast shadows

There are two different ways to cast shadows: real-time (generated) shadows, and proxy shadows.

Generated shadows: Component properties

Your mesh casts an actual shadow.

You activate real-time shadows by checking the following properties in your mesh component (which you can find in your .app or .ent file):

Proxy shadows: Shadow mesh

The proxy shadow, by contrast, will use an invisible mesh to cast a shadow (the shadow mesh). It has a lower Level of Detail than the original and often features a simplified geometry or even a proxy mesh.

Due to the less complex geometry, a shadow mesh is much less prone to raytracing glitches, and it will be much eaiser on performance.

Shadow meshes are usually added as entMeshComponents.

Configuring a shadow mesh

Your average shadow mesh has only one default material with a blank local instance of engine\materials\metal_base.remt. If the shadow mesh is loaded in a scene, it will lead to white, marshmallow-y overlays.

To make sure that it's only used for shadow generation, check the renderMask:

Creating shadow meshes

To create a low-poly mesh, you can build a cage, subdivide it a few times and use a Shrinkwrap modifier to shape it like your mesh. Then, you can reduce the poly count by decimating.

Troubleshooting

My shadow mesh is always visible!

Check #configuring-a-shadow-mesh and make sure that RenderInScene is unchecked.

Components are not a file type but an internal data structure and part of .ent or .app files.

Components are how the game adds anything to the in-game world, from pag3d data over player interaction prompts to explosion sounds. Entities and Appearances use components in order to slim down what data each game object has to carry, adding or removing them as needed.

Component names

Body and clothing component prefixes

Body component prefixes affect how the game calculates garment support and you're strongly encouraged to stick to those naming conventions to make use of it. Please see the corresponding wiki page for a list.

Component Properties

Common component properties explained. For a more detailed list, please see Documented Components.

chunkMask

Only used for mesh components.

For documentation of this, see the ChunkMasks section on Submeshes, Materials and Chunks.

depotPath

Relative path to a resource within the game files. Used to load dependencies — meshes, rigs, animations, effects.

Summary

Published: Mar 02 2024 by Last documented update: Mar 02 2024 by

This page explains what Level of Detail is and how it works.

Wait, this is not what I want!

• To learn about Level of Detail (LoD), check the corresponding wiki page.

What is a proxy appearance?

When displaying a complex object, the game loads between 1 and e^x components, each of which includes extra logic. That's all fine and dandy as long as you're up-close — but as soon as you're far away and the details vanish in the distance, it's a complete and utter waste of processing power.

That is where proxy appearances come in: instead of all the complex components and the complex shaders, you will see a single mesh with a bunch of baked-in textures.

I hate it, how do I kill it?

If a proxy appearance fucks up your NPV, here's how you can disable it:

1. Open the appearance's components array

2. Find and delete the AppearanceProxyMesh component (it will be of the type entSkinnedMeshComponent)

3. Find and delete the AppearanceVisualController component (it will be of the type AppearanceVisualControllerComponent)

4. For each component with a mesh, set the forceLodLevel property to 0

Inside the communityTemplate, this file defines appearances for crowd pools:

How can I find a specific file?

You can use Find Files Using This from the context menu of the corresponding .app or .ent file and follow the daisy chain until you find the .community file.

(as of October 02 2032, this is still broken)

Is there another way?

As of 8., Wolvenkit only lets you search for files, not in them. For that reason, we'll have to use a workaround.

3. Delete the original .community files (you'll re-add them later)

4. Use Notepad++ to search inside the directory for your appearance name

   • If nothing shows up, try partial matches

5. Note the names of the files under .raw

6. search for the file name in Wolvenkit, then add it back and make your edits

How can I change a spawn?

This page explains the .inkatlas file and its logic.

Wait, this is not what I want!

• Learn how to make Your own inventory preview icons

• Make a custom Atelier icon

• Find templates (by ) in the wiki github's file section

• Make your own inkatlas with Python: find the script on The Magnificent Doctor Presto's github. Check Running Python Scripts if you don't know how to use this.

• Make your own inkatlas with Photoshop CC (Adobe Creative Suite required): find the plugin on deadlymustard's github

Summary

The .inkatlas is a map file that slices textures into sprites (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.

Unlike other games, Inkatlas files don't slice by pixel coordinates but by percentage as a float value between 0 and 1 . The starting point is the TOPLEFT corner, the ending point is the BOTTOMRIGHT corner.

Each slot (inkTextureAtlasMapper) has four coordinates. This is a single slot across the entire inkatlas:

For example: two sprites in column will be written as: (y 0,5; x 0) X (x 1; y 0) for upper sprite and (y 1; x0) X (x 1; y 0,5) for lower

inkTextureSlots

Each inkatlasa has three different inkTextureSlots, which support different texture resolutions. For the purpose of modding, it is enough if you work with inkTextureSlot 0 (the first one in the list).

If an existing xbm is hooked up, the Part Mapping tab will appear, where you can check which parts of your image correspond to each slot name.

Inkatlas: Slot names

You target sprites (slots in the inkatlas) via the atlasPartName property:

UIIcon.clothing_my_custom_shirt_factory_name_appearance_root_entity_white_red_Female_:
    $type: UIIcon
    atlasResourcePath: tutorial\path\subfolder\preview_icons_pwa.inkatlas
    atlasPartName: slot_01

Any atlasPartName in the yaml must correspond with the name of a part in the inkTextureAtlasMapper. If the corresponding entry can't be found, an empty icon will be displayed.

You can see which sprite is targeted by any given entry in the Part Mapping:

Last documented update: January 27, 2024 by

StreamingSectors are the files that define the world in Cyberpunk, they tell the engine what goes where, and define everything from the meshes you see and how you can interact with them, to the locations of lights, sounds and fx. They call up the NPCs, they define the minimap.

The fundamental bits of the structure are 2 main lists, the nodes, and the nodeData. The nodes define the assets that make up the sector, and the nodeData tells the engine where to put them. Theres a nodeRef list as well, which seem to be the link that quests use to tie in to triggers etc via the .scene files. Theres also some bits that define variants, that seem to be how sectors change after missions, not worked those out yet.

Theory

Streaming Sectors contain the world's data, holding a node tree that includes all its models and entities.

LOD data and grid sizes

The world is broken up into a grid, with several sizes of squares available (bit like graph paper with major and minor grid lines). The size of the grid in use is dependent on the Level of Detail (LOD) of the sector file your looking at, which is the last digit of the filename.

Chunk sizes are as below.

For every location, there can be multiple overlapping levels of LOD sectors with progressively more detail as you go down the levels.

For instance, Lizzies bar is located at approximately -1200, 1562, 22:

Filenames are structured as sectortype_X_Y_Z.streamingsector . If you preview a sector in wkit, the axes are shown as Z=-Y and Y=Z.

Calculating the files

I've left the detail of the process below for record, but if you just want a list of sectors I've created a python script to find the ones that a set of co-ordinates are in. You can find it HERE. Simply enter the co-ordinates in the player_loc dict in block 3 then run all blocks. You'll be given 2 lists containing of all the interior and exterior sectors which contain the co-ords within their bounding boxes. The list also shows the distance from the centre of the sectors to the co-ords given.

From those co-ordinates we can calculate the sector files for interior/exterior sectors by dividing by the grid size for the LOD and rounding. (ie 1200/32=38 etc)

At the level 0 files the whole building isn't covered by 1 sector, so you end up needing 4, conversely the exterior level 2 is several city blocks.

Some locations are partially defined in quest sectors, where parts of the location are locked away behind story triggers (for example half of V's apartment, as a lot of decoration will only be shown after completing quests). The exact process isn't fully understood as of May 2023.

Block and sector's variants

A steamingsector can split its nodes into ranges called variants. A variant is used to display/enable an amount of nodes in a specific situation (like during or after a quest). All sectors and their variants need to be declared somewhere; this place is the streamingblock.

We will see how they are declared and how they are linked together.

Streamingblock

The game contains only 3 streamingblocks that gather more than 26300 sectors. We will focus on the main one and take a look at the first sector inside (exterior_-18_3_-12_0).

This sector has 10 variants, in this case, each one is related to a quest state.

numNodeRanges indicate the number of node ranges the sector contains; it always corresponds to the number of variant + sector's default range (so here 10 variants + 1 default).

When opening a variant definition, we can find the range index (to find the right range inside the sector file). rangeIndex cannot be 0, 0 is used as sector's default range.

Variant's name is only used to identify the variant within the streamingblock.

enableDyDefault is self-explanatory; it indicates whether it should be enabled by default.

Sector variants and ranges

The sector file uses 2 arrays to define ranges: variantIndices and variantNodes.

variantNodes contains as many empty arrays as variants (in this case, 10).

variantIndices contains as many values as ranges needed (10 variants + 1 default range)

A variant indice indicates the range starting nodeData index. This range goes from the index specified to the start of the following range. If we look at variant indice #7, the range starts at node index 14 (included) and ends at node index 46 (excluded).

A sector always has a default range (variant indice 0); this default range indicates which nodes must always be visible/enable, whatever are the variants state. In our example, the default range goes from 0 to 1, so only the first node is always enabled.

Global overview

Here is an overview of files relations:

Summary

Published: Feb 09 2024 by Last documented edit: Mar 4 2024 by

This page will tell you how effect components work and how they interact with each other.

Wait, that's not what I want!

For an overview on existing effect materials, check FX Material Properties

For a guide on how to use effects, check AMM: Light Components

Effect component types

You will see two kinds of effect component types, which always occur in pairs.

entSlotComponent

Usually called fx_slots, this component allows you to place your effects in the world. It requires the definitions in the #enteffectspawnercomponent to work.

If you want the position of your effects to follow the movement of parts of the object you can set the boneName an existing bone of your object

In this case the relativePosition will be relative to the bone's position

entEffectSpawnerComponent

Usually called fx_whateverTheEffectIs, this component defines and registers effects which can then be placed via slots.

Adding and deleting effect slots

Deletions

In the entEffectSpawnerComponent, delete:

1. the placementTag entry that you want to get rid of

2. the corresponding entry in placementInfos (see the yellow arrows on the screenshot under #enteffectspawnercomponent)

In the entSlotComponent, delete:

1. The entry in slots referencing the previously deleted component by name.

Additions

In the entEffectSpawnerComponent, add:

1. a new placementTag at the end of the array with the name of your new entry (e.g. fx_candle_slot_04)

2. a new entry under placementInfos (by duplicating the last entry), setting the placementTagIndex to the numeric index of the placementTag you created in step 1

In the entSlotComponent, add:

1. a new entry in slots with the name that you created in Step 1

autoSpawnTag

If you are making effects into equipment, having the same autoSpawnTag will make it so equipping one will despawn the other one.

eventRUID

eventRUID in the ent component must be the same as the effect particles ruid, and ideally should be unique across everything. You can right click on a RUID field and choose "Generate new CRUID" to generate a semi-random new CRUID and then copy it across so they match.

Placing effect components

Please check AMM: Light Components -> #placing-your-light-components for a detailed guide!

Mesh components: Equipment/Hair

Shared properties of mesh components

Documented mesh component types

Effects

Please see Effect components for details

entEffectSpawnerComponent

entSlotComponent

NPCs

Generic

Summary

Published: Mar 02 2024 by Last documented update: Mar 02 2024 by

This page explains how shadows are configured for nodes in streamingsectors.

Wait, this is not what I want!

• To learn how components (equipment) casts shadows, check Meshes, Shadows, and Shadow Meshes

Shadows

The shadow properties of the environment are configured in the properties of each node inside the .streamingsector file:

Shadows are only cast as long as a mesh is visible.

Global and local shadows

A global shadow will not render small details — these will only be included if the castLocalShadows property is active.

Written & Published: April 10 2023 by @manavortex Game version: 2.1

.app (Appearance definition)

This file contains a list of appearances with their associated components. To load them, you require a .ent. The .app files also contain extensive parameters for wounds and dismemberment, determining which meshes to use for different types of garment an NPC might be wearing, and even the physics behavior of these meshes.

Holds a list of components.

.ent (Entity)

Root entity

The entry point for the game to display an or . It is a collection of components that the entity is comprised of, determining their parameters or referencing the files that have said parameters. For instance, NPC .ent files have over a hundred components each, such as entAnimatedComponent (references the correct .anims, .animgraph and .rig files), entTemplateAppearance (references all .app files that are applicable to the entity) and entEffectSpawner (references all .effect files for decals or particles that the entity can spawn). Many of these components have configurable parameters, and the .ent file itself has many under the "entity" section. Many of these parameters, however, are merely the initial state of the entity and are modified in gameplay (such as the boolean isRagdolling).

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

.inkatlas (Texture mapping)

.mesh (3d object)

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

Relevant properties:

.opusinfo/.opuspak (audio)

OpusPaks are collections of opus audio files, they are described by the sfx_container.opusinfo file. For more info see the Audio Files page:

.streamingsector (world data)

This file holds world environment information and -properties. Due to its complexity, information is grouped on its sub-page.

.wem (audio)

A Wwise audio file, usually containing a voice-over or music. You can find more info on the Audio files page:

.xbm (Texture)

A regular texture file. Can be exported to .png via WolvenKit, edited, and imported back into the game. The type of texture is often indicated at the end of the filename. For instance, diffuse textures are specified as "_d" and normals are specified as "_n".

Normal maps

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.

Texture Atlases

Texture atlases contain multiple textures that the game may choose at random (such as blood splatters, as seen in fx_blood_splatter_2x2_01_d.xbm) or play sequentially (as seen in splash_texture.atlas_n.xbm, used by the game for the blood puddle animation). Texture atlases won't always have "atlas" in their filename, but can still be quickly identified by the size of the grid. For instance, "3x3" in the filename means a grid of nine textures. In the asset browser, right-clicking on the file and selecting "Find Files Using This" will take you to files that allow further customization of how the game interacts with the grid.

Relevant properties:

W2RC File Format Table

Generic Format

<explanation>

Generic FIle Format Table

Archive Format

File Structure

Header

Custom Data (WolvenKit)

The following data only applies for archives created with WolvenKit

File List

File Record

File Segment

Published: Jan 19 2024 by Last documented update: Jan 19 2024 by

How do Occluders work?

Occluders hide stuff from you. I haven't understood this well enough to document it, but I've been begging people for months and nobody writes anything, so I'm dumping the corresponding Discord posts here in case anyone wants to clean them up.

Assuming that the PVS system (a whole other element) is loading whatever is on the other side of that door way, just removing the door isnt enough, if there's an occluder over the whole thing, everything behind it is being ignored (like on the right)

Everything in the game is already inside something, those somethings are the sectors The game only loads sectors relevant to where the player currently is: The Potential Visible Set, PVS

And it then only tries to render what it needs to, so even if its loaded, if it's hidden behind the player, or behind an occluder it wont bother

Once it's ignored all the stuff it doesnt care about because it's determined you cant see it, it can start to question if you're even close enough to see it, and if so, what LOD?

Some objects/entities might have their own occluder meshes for visibility testing (testing if something else behind it is hidden or not), because testing behind an actual model is more complicated then a basic shape, similar to having lower poly shadow casting meshes

Objects that are being tested, to see if the camera can see it behind an object/occluder probably dont use their actual mesh for the test either, way too complicated So it will probably just use a bounding box This is why sometimes, in games, moving characters can pop-in when moving from out of cover, if the bounding box wasnt big enough, and a limb (or maybe they dive/slide) comes out of the bounding box, the box might still be occluded, but the whole character isnt, so they effectively enter frame and are kept invisible until the BB enters the frame too and thats when you'd get the pop

How to add an occluder

You have to add a node to the world sector:

Summary

Published: Feb 09 2024 by Last documented edit: Feb 09 2024 by

This page gives you an overview about lights at a glance.

Wait, this isn't what I want!

• To learn about shadows in the world, check

• To learn about shadows for equipment items, check

• For a guide how to add lights to AMM props, check

• For a quick overview on lights and their properties, check (currently WIP)

• If you want to learn more about blocking light, check

How do lights work?

Directional lights

Cyberpunk uses three types of lights:

Point light

The light is a sphere and is equally bright in every direction

Spot light

The light is a cone. The sharpness is defined by its inner and outer angle.

Area light

The light is a square (like a light panel).

Summary

Published: Mar 02 2024 by Last documented update: Mar 02 2024 by

This page explains how the level of detail is handled in environment files.

Wait, this is not what I want!

• To learn how components (equipment) casts shadows, check

Auto-hiding

Many world objects are automatically hidden if you move away from them, freeing the engine resources that had been used to render them.

The distance at which this happens is controlled by the forceAutoHideDistance property of each world node:

This probably corresponds directly to the nearAutoHideDistance in the proxy mesh ndoes below?

Proxy meshes

There is a specialized node type for world proxy meshes: the worldGenericProxyMeshNode. (Which raises the question if there are specialized / extended worldXXProxyMeshNodes?)

Summary

Written & Published: Dec 9 2023 by manavortex Last documented update: Apr 7 2024 by Deceptious

What are quest facts?

Quest facts are just a value (signed integer) and a name (string).

Quest facts are chosen by the developer/designer/modder.

While you are moving through the world of Cyberpunk, the game will track your progress in your save game via these quest facts and their values.

How do quest facts work?

Quest facts do not exist until they are explicitly set. Until they are set they are assumed to be 0.

Any/all quest facts can be 'read' at any point. They can then be tested against a set value [<, <=, ==, >=, >] and this test can form a Pause or Condition. [If they havent been set/defined yet they will return as 0.]

There is no strict naming convention, but typically quest related facts start with the quest code [Ex: mq055_... sq027_...]

Facts that are used in a similar way will also have a similar naming sceme [Ex: radio_on, tv_on; judy_default_on, panam_default_on]

Cyberpunk's quest facts don't actually do anything, they simply store a value that can be checked later - it is this later check, and logic that is set to follow, that actually does something. For an example, check the box below.

Which files are associated?

Quest facts are most often set and used in .questphase (and .quest) and .scene files. They can also be manipluated in scripts [Ex: Changing cyberware at a Ripperdoc sets certain facts] and also directly in the code.

Which quest facts influence each other?

None of them, they are independent entities. However they can, in some are cases, be compared to each other [<, <=, ==, >=, >]

For a json dump of facts grouped by .quest, .questphase and .scene, follow this Discord Link.

Summary

Published: Oct 01 2024 by manavortex, based on research by Cindefalla

The game measures FOV horizontally on foot while it's measured vertically for vehicle first person.

I figured this out after setting the FOV for vehicles, as well as the enter and exit animation to 90, while setting on-foot to 120. And there was no FOV shift. 120 Horizontal = 89 vertical based on a 16:9 aspect ratio.

If you were to set all vehicle FOV values to the same as on-foot, e.g., 120. the FOV shifts to a wider horizontal FOV, which should be 144 in this example.

Aspect ratio doesn't affect vertical FOV in cyberpunk so I presume it uses Hor+ scaling like most games

Summary

Published: Jan 05 2023 by manavortex

How are dependencies resolved?

rRef

Strongly recommended flags: Default

Represents a mandatory dependency that will be loaded together with the reference holder and is stored together with it. If reference fails to load, the resource holding it also fails to load.

If you use Soft flag, you risk causing game crashes. The only acceptable use of Soft flag in combination with rRef is for dynamic paths used in ArchiveXL that start with * character.

to understand the problem, you need to know that although resources can be requested by any thread, only the main thread can use the wait function, which blocks the current thread until the resource is ready

all other threads must use async callbacks to wait for resources and are not allowed to block 

the resource fetch function uses the wait function to make sure the resource is loaded before returning the data

this means that if the game tries to fetch a resource that is not ready in any thread other than the main thread, it's a crash 

usually when resource is requested, the engine runs a specific for the current scenario chain of async callbacks to pre-load all necessary dependencies (other resources) 

when the loading chain is completed, the requester can fetch the resource with its dependencies without blocking on any thread (the blocking wait function will be skipped, since all necessary resources are already loaded) 

if you add an invalid dependency or something that the engine doesn't expect, it will be loaded without async waiting and hence there's a chance it will be accessed before it's ready (which leads to a blocking wait call and a crash) 

but accidentally it might just load in time, which is why this crash is so random and cane be hard to troubleshoot

raRef

Compatible flags: Soft

Represents a dependency where the reference holder is only pointing at a resource.

Flags

Default

Used by: #rref

Indicates that the engine should load the requested resource together with the reference holder.

Embedded

Used by: #rref

When a resource is flagged as embedded, it is directly included in the holder resource. However, resources flagged as embedded might not work as expected if they live in inplace resources.

Soft

Used by: #raref

This flag is used for resources that are not immediately mandatory. It seems to be a more flexible reference that does not load the resource immediately but points to where it can be found when needed. It's used in root entities for referencing .app files, for example.

Obligatory

Unknown, but probably a legacy artifact from Witcher3

Template

Unknown, but probably a legacy artifact from Witcher3

Inplace

Unknown, but probably a legacy artifact from Witcher3

Summary

Published: Feb 11 2024 by manavortex Last documented edit: Feb 11 2024 by manavortex

Wait, this is not what I want!

• See Effects modding for a hands-on list of changing effects in Cyberpunk

• See Effect components for effect explanations by component

• See FX Material Properties for animated materials

• While explosions are definitely effects, lights are something else => Lights explained

• To position effects, see AMM: Light Components -> #placing-your-light-components

Effect registry

All effect files are registered in static_effects.csv. Since that file can only be edited once, you have to merge your own .es files by script.

For instructions on how to do that, check ->

Effect duration

An effect's duration is defined in the .effects file:

Particle lifetime

You can find a particle's lifetime for the individual entries in the modules array:

These are probably (?) overwritten by effect durations?

Summary

Published: Mar 02 2024 by manavortex Last documented update: Mar 02 2024 by manavortex

This page explains what Level of Detail is and how it works.

Wait, this is not what I want!

• To learn more about Proxy Appearances, check the corresponding wiki page.

Level of Detail

The further away something is, the higher it's LOD will be (the less detail you will actually see, and the less detail will be rendered).

What controls LOD?

.streamingsector: forceAutoHideDistance

But my modded items only have LOD0!

That is due to Wolvenkit: the property will drop any submeshes for lower resolutions.

For equipment and weapons, that is completely fine, because you don't need them (melee weapons aside, read on).

For NPVs, you'll want to get rid of proxy appearances as well — we really can't be arsed to create custom ones.

So let's get rid of all these high LOD submeshes!

Please don't.

First of all, the high LODs occasionally store other properties. For melee weapons, they are used to calculate the hitbox (or so we think, Mar 2024). For vehicles, they're needed for damage deforms.

And second of all, without proxy meshes, your GPU will catch fire if you look at Night City's skyline. Yes, even the Tesseract.

lodLevelInfo

As of May 2024, we don't know for certain what the numeric properties stand for (maybe the distance from player at which the level of detail gets activated?).

Proxy meshes

A proxy mesh is used as an extremely low-level stand-in to be loaded for distant objects. They will almost always have proxy in their path or file name, and use a PBR material such as metal_base with low-resolution textures.

Example: Take a look at Johnny's proxy mesh under

base\characters\appearances\main_npc\proxy\silverhand_default\silverhand_default.mesh

Shadow meshes

Shadow meshes are used to generate shadows at low performance cost. You can find more detailed documentation on the page about Meshes, Shadows, and Shadow Meshes.

Component property: forceLODLevel

This lets you override the level of detail

Behavior files are node graphs (currently browsable only in list form) responsible for determining A.I. responses to various stimuli based on specific conditions. For instance, the hit_reaction.behavior file works in tandem with other files to establish how NPCs react to certain kinds of hits, and determines which NPC types are excluded from which behaviors.

Here is an example of the GuardbreakReactionTask node being established in state 4 of hit_reactions.behavior.

That node can be replaced with any other node compatible with the script slot, so you can make something else happen, or make the game crash, or an exciting combination of both.

The .behavior files can also point to different .behavior files. Here we see state 5 of hit_reactions.behavior referencing wounded_entry_se.behavior, which details some of the wounded actions such as walking with an injured arm. State 5 also calls the PainReactionTask script:

Navigating these files in list form can be confusing, so let's go step-by-step into state 2, which is the Knockdown state:

This goes down quite a few layers. The task node is what happens in that particular layer, and the child nodes take you into the deeper layers. In this case, the knockdown animation is being cached for potential ragdoll. Here's what that looks like:

When the child node is uncollapsed, it shows its own nodes, which may contain a condition for its task to occur:

This particular condition calls a TweakAIActionCondition node, which connects to a TweakDB record. The record being used checks if the victim of the knockdown is a civilian not currently engaged in combat. Remember that conditions may be set inverted, so that the opposite condition is what triggers the task. TweakDB records may also contain their own conditions inside them, inverted or uninverted, so it's good to uncollapse them and take a look.

When you open the child node affected by this condition (above it), it uncollapses into a TweakAIAction node which connects to a TweakDB record. The actual record requires that you scroll down quite a bit to get to it. You will come to hate this node.

The record seems to determine that if a civilian is knocked down while out of combat, they should stay down indefinitely, which is consistent with how it works in the game:

You may have noticed that the record itself contains an activationCondition entry. That's one place in which you'll find conditions set by TweakDB records, so again, you should verify those on every TweakDB record you see, regardless of whether it is under a task node or a condition node. And remember to also check if any of those conditions are inverted, and if there are sub-conditions elsewhere in the record. This is your life now.

Now we go back to the other child node of state 2, which determines what happens if the knocked-down NPC is anyone other than an out-of-combat civilian. When this child node is uncollapsed, it disgorges two more child nodes, and the Inception theme starts playing.

The first of these great-grandchild nodes just calls the KnockdownReactionTask, which you can replace with any other compatible task to see what happens.

The other great-grandchild node is another TweakAIAction node. The TweakDB record it connects to is seemingly what makes armed NPCs shoot aimlessly during the knockdown animation. This record has several other conditions inside it with sub-conditions so let's not make the mistake of uncollapsing it.

Instead let's go back one layer, because there was still one child node next to the child node whose child node we were just checking. The following image will hopefully clarify that cursed sentence:

This child node, which is mercifully the last of its dynasty in state 2, leads to a TweakAIAction node. If you scroll down to about the depths of the Mariana Trench, you will find the TweakDB record it's connected to. It deals with how NPCs stand up from being knocked down.

Out-of-combat civilians are excluded from this behavior, tragically condemned to remain forever horizontal should they be sucker-punched by a player wanting to test their new gorilla arms. This exclusion was determined in the first child node of state 2, in case you understandably forgot by now.

It is important to note that .behavior files do not exist in isolation; the hit reaction system, for instance, is reliant on multiple files and functions. This synergy has to be taken into consideration when editing or replacing nodes in .behavior files, and the conditions established in these nodes or in the TweakDB records they use must be verified. They may, for example, exclude bosses from certain behaviors, so deleting those nodes can cause considerable issues.

This wiki page is about the .bk2 file format used in the game.

TL;DR

The .bk2 file format is used in many games including Cyberpunk 2077. It stands for Bink 2 and can be played and/or converted to regular video format or single frames using RAD Video Tools.

How did I get there ?

I wanted some screenshot of a Cyberpunk ad to print as a poster for a friend. That's how I ended up on this journey to find how to get a readable video from the game files.

Prerequisites

• WolvenKit (obviously)

• RAD Video Tools (available here, 2mo)

Getting the video files

For example in this wiki page, I'll use the NiCola ad as an example. You will want to have a WolvenKit project created for easy access to the video file.

In Cyberpunk, all the video files have the .bk2 extension. Thus, you can just search .bk2 in the search bar of the asset browser. Since I want the NiCola ad, I'll here search for nicola > .bk2 (See this wiki page for more about searching files).

Then add the file to your project for easy access

Playing the video

Assuming you have installed RAD video tools correctly (see Prerequisites), you should be able to open the file and it will play

Converting to a common file format

For this, you will have to open RAD video tools from the search bar/start menu/whatever if you don't use Windows.

Then, navigate to the .bk2 file and press on Convert a file (see screenshot)

Then, in the opened window, you can configure the output, file format and location. You can then press convert on the right side of the screen.

And now you have the video you want in the format you desire. You can also export individual frames if you want to!

Closing words

Now you have everything, if you want to know more about the Bink Converter you can watch this video. Everything here have been found in the Discord community after a quick search in there.

Summary

Published: Oct 12 by Last documented edit: Oct 12 by

This page contains theory about Cyberpunk's armature files.

Wait, this is not what I want!

• To find out how armatures and meshes are connected, check

• To edit an armature, check

• For a hands-on guide, check

What's a rig?

A rig (also armature, the terms will be used interchangeable) is the skeleton structure used to control and animate .

Each armature is a hierarchical connection of bones (similar to a meatspace skeleton — the foot bone's connected to the leg bone).

Control

Via rotation and translation of individual bones, the armature controls the pose of the connected mesh. You can read more about this on the page.

Deform

Via scale, the armature deforms the connected mesh. This is how custom rigs are used to change V's body shape.

Summary

Published: Nov 20 2024 by Seberoth Last documented edit: Nov 20 2024 by

This page contains ínformation about base\razer_chroma\animation_mappings.chromaset

Importing buffers

In theory, it should be possible to import regular .chroma files into a buffer:

Editing buffers

When changing the Device type of an entry, these frames need to be adjusted:

Buffer values

Summary

Published: Jun 28 2024 by Last documented update: Jun 28 2024 by

This page explains how animations in Cyberpunk work.

Wait, this is not what I want!

• For practical guides, check in the Modding Guides section.

What is an animation?

The process of binding (weapons, clothes, body parts) to an armature is called .

The armature (also rig - think "skeleton") is made of pose bones. For every frame, these pose bones will be in a certain position (keyframe). Here lies the only difference between static photo mode poses and animations:

• A static pose (photo mode) has a and a pose keyframe. Some custom poses have more, but these are not necessary.

• An animation has up to two . All of its keyframes will be played in sequence.

Fallback frames

The keyframe at index 0 will be used while the animation resets, and acts whenever something in the pose can't be loaded, for example when the .anim file defines more frames than the pose in Blender.

This may lead to twitching and will hopefully be resolved in a future Wolvenkit version.

Summary

Published: June 9, 2024 by Zhincore

Cyberpunk uses Wwise audio system, which uses mostly proprietary ("secret", non-opensource) formats. But thanks to the community we have the tools to dig into them. This page explains the technicalities behind audio.

Wait, that's not what I want!

Perhaps you only care about how to find or replacing audio:

Primary file types

There two main ways Cyberpunk 2077 stores audio:

WEM files

The game stores voice-overs and most music as .wem files which are directly in the game's .archives and their exporting/importing is handled as any other asset.

Opuspaks and bnks

On the other hand sound effects, grunts, and some music are packed together in files ending with .opuspak. Those paks are mapped by a single .opusinfo file. If you want to manipulate them, check out .

Some sounds do not exist are handled differently. For example generated (noise, sine wave, etc.), or generated by CDPR's custom Wwise plugins. This might require more research, but you most probably don't need those sounds anyway.

How are SFX handled by the engine

The aforementioned .bnk files are primarily for other purpose than storing audio. They describe how and which the audio should be played.

The process of playing a sound when something happens goes something like this: The game sends an event to Wwise, those are described in eventsmetadata.json file in the game's archives. Those events are connected to a tree of nodes described in .bnk files, this may include random selection of next node, layering, volume modification, switching between the next nodes according to a condition, etc. At the end is a node that points to an audio file (or a plugin) and that sound is played. Or multiple sounds are played at once, according to the previous nodes.

How are voice-overs connected to subtitles