3d objects: .mesh files

Documentation on .mesh files and their properties.


Published: ??? by manavortex Last documented edit: May 01 2024 by manavortex

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

Wait, that's not what I want!

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 Submeshes, Materials and Chunks.

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

How the mesh is loaded

Meshes are loaded via Components (e.g. ). Components are defined either in mesh entity files or in an .app file, where each appearance has its own components array.

For more information on this, please check Submeshes, Materials and Chunks -> Chunkmasks: partially hiding meshes


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.

Depending on your geometry, this can impact performance.

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.

Submesh numbers correspond directly to a component's chunkMask property. For technical reasons, the chunkmask dropdown supports up to 64 entries โ€” just ignore the missing numbers.

Material assignment

This section describes how materials are assigned inside each mesh. To learn more about submeshes and chunkmasks, check Submeshes, Materials and Chunks.

This page only contains mesh-specific information. Find more details on materials under Textures, Materials and Shaders.

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:

The index property in materialEntries will finally point at the material's instance, where you can find its properties. Depending on isLocalInstance, that can be one of several places โ€” find a list in Step 3: Material definition.



  1. Assign material for submesh in appearance -> chunkMaterials

  2. Register the material by name in materialEntries

  3. Define the material in either localMaterialInstances.materials or externalMaterials

Here's an overview:


You can find more information on this under Submeshes, Materials and Chunks.

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:

While you can mix external and local materials, you can not mix preloaded and non-preloaded ones. For details, see below.



numerical index of corresponding material in target list (as defined by isLocalInstance)


Selects the material target list. True: local material in localMaterialBuffer.materials or preloadLocalMaterialInstances False: material reference inexternalMaterials or preloadExternalMaterials For more information on this, see the page for local/external materials.


unique name of material, used to select the material via chunkMaterial

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

A material's actual definition (instance) can be in a CMaterialInstance inside the mesh or in a .mi file in the project. Wolvenkit will display material names as defined in the materialEntries, making it easier for you to see what's what.

MaterialInstance: The local material

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

You can't go wrong by using those. However, if you don't have any properties that are unique to your mesh or appearance (for example a custom normal map), you might consider creating and using an external material instead.

A material instance looks like this:

You can find a guide about texture editing and adding custom textures in the section.

For an overview of materials that you might want to use for something, check here.

For how to find out which properties a material has, check here.

Material reference: reusing materials

A relative path to an external material, usually encapsulated in a .mi file. Use this if you don't need to add extra properties.

Last updated