# 3d objects: .mesh files ## Summary **Published:** ??? by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention")\ **Last documented edit:** Sep 19 2024 by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention") This page contains information on .mesh files, such as what they are, how the game loads them, and how their appearances are defined and selected. {% hint style="info" icon="question" %} #### Wait, that's not what I want! * To export/import meshes, see [wkit-blender-plugin-import-export](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/modding-tools/wolvenkit-blender-io-suite/wkit-blender-plugin-import-export "mention") -> [#meshes](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-tools/wolvenkit-blender-io-suite/wkit-blender-plugin-import-export#meshes "mention") * To stop copy-pasting so much, check [archivexl-dynamic-materials](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-dynamic-materials "mention") or [re-using-materials-.mi](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/materials/re-using-materials-.mi "mention") * To edit a mesh's appearance, check [changing-materials-colors-and-textures](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/editing-existing-items/changing-materials-colors-and-textures "mention") * If you just want to use a textured material, check [using-a-textured-material](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/editing-existing-items/changing-materials-colors-and-textures/using-a-textured-material "mention") * For a guided exercise, see [textured-items-and-cyberpunk-materials](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/textures-and-luts/textured-items-and-cyberpunk-materials "mention") * To hide parts of a mesh under different circumstances, check [submeshes-materials-and-chunks](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks "mention") or [first-person-perspective-fixes](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/first-person-perspective-fixes "mention") {% endhint %} Let's get started. ## What's a mesh? In the context of Cyberpunk, a mesh is the file that defines the topology[^1] and the materials[^2] 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](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks "mention"). 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](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/components "mention") (e.g. [#entgarmentskinnedmeshcomponent](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/components/documented-components#entgarmentskinnedmeshcomponent "mention")). Components are defined either in [mesh entity](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators/files-and-what-they-do/entity-.ent-files#mesh-component-entity-simple-entity) files or in an [.app file](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators/files-and-what-they-do/appearance-.app-files), where each [appearance](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators/files-and-what-they-do/appearance-.app-files#appearances) has its own [components](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators/files-and-what-they-do/appearance-.app-files#components) array. For more information on this, please check [submeshes-materials-and-chunks](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks "mention") -> [#chunkmasks-partially-hiding-meshes](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/submeshes-materials-and-chunks#chunkmasks-partially-hiding-meshes "mention") ## 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`. {% hint style="warning" %} Depending on your geometry, this can impact performance. {% endhint %} ### 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:

Materials must be defined for each LOD (level of detail — most modded items only have one)

With the boxes in the right panel, you can toggle submeshes on and off. {% hint style="info" %} Submesh numbers correspond directly to a component's [#chunkmask](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/components#chunkmask "mention") property. Changes you make here are **not persistent** — to hide parts of an item, see [#chunkmasks-partially-hiding-meshes](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/submeshes-materials-and-chunks#chunkmasks-partially-hiding-meshes "mention"). {% endhint %} ## Material assignment This section describes how you tell the game exactly how your mesh should look — the technical term for this is "material assignment". This section will hopefully remove all confusion about where those textures go, and how those pesky t-shirt appearances work. {% hint style="success" %} Understanding this will save you a lot of trouble in the long term, so grab a coffee or tea and understand the theory section. If you have questions, feel free to hit us up on [Discord](https://discord.com/invite/redmodding) in `#mod-development` or `#textures-and-models`. {% endhint %} * If you just want to know how to assign or add a new material, skip ahead to [#practice](#practice "mention") * This page only contains mesh-specific information. Find more details on materials under [materials](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/materials "mention") * To learn more about submeshes and chunkmasks, check [submeshes-materials-and-chunks](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks "mention") ### Theory #### Appearances A mesh file has one or more **appearances**, which are used by [components](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/components) to define how a thing looks. Think of an appearance as a skin for any given object: this shirt is black, it has red stitches, and there's an Arasaka logo on it. {% hint style="info" %} If a Netrunner sits next to an explosion, we simply change their suit's appearance from `netrunner_suit_clean` to `netrunner_suit_dirty` and call it a day. {% endhint %} The base game does **not** change these appearances after they have been set up. #### Appearance definitions Each appearance is defined by an entry in the `appearances` array at the top of the file. A meshMeshAppearance has one or more `chunkMaterials,` which correspond to the item's individual `submeshes` (the different parts it has in Blender). These entries are selected by **name**.

The dropdown menu was added in Wolvenkit 8.16.2. If that hasn't released yet, you can install a Nightly.

To see your chunks and their materials, you can switch to the **Mesh Preview** tab. Here is how it looks:

You have seen this picture before ( #mesh-preview)

More examples Our random example file `t1_029_wa_full__swim_turtleneck.mesh` has 16 appearances: `default`, `blue`, `golden`... Each of these appearances has three chunks per LOD. We'll look at the first three: **Blue** submesh\_00: ml\_t1\_029\_wa\_full\_\_swim\_turtleneck\_blue\_masksset\ submesh\_01: ml\_t1\_029\_wa\_full\_\_swim\_turtleneck\_blue\_masksset\ submesh\_02: lambert1 **Golden** submesh\_00: ml\_t1\_029\_wa\_full\_\_swim\_turtleneck\_golden\_masksset\ submesh\_01: ml\_t1\_029\_wa\_full\_\_swim\_turtleneck\_golden\_masksset\ submesh\_02: lambert1 The first two layers are different, the third one has
Now, how are the materials getting into the dropdown menu? #### Definitions These materials are **defined** in the `materialEntries` list:
Each `materialEntry` holds the following properties: * the material's name (which you can use to assign **chunkMaterials**), * whether this is a **local** or an **external** material (more about this in [#material-instances](#material-instances "mention") below!), * the index of the material instance in the corresponding list You will have noticed by now that these entries **do not hold materials**. They are only **definitions** — the actual information is somewhere else. #### Material instances A **material instance** holds the things you are actually interested in: how the mesh should look. They define the following properties: * `baseMaterial`: which [shader template](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/materials/shaders) (`.mt`/`.remt`) will be used. Sometimes, this happens through a `.mi` file — this is an **external material** (more about this below) * `values`: a list of properties which pass information to the shader, for example which **diffuse texture** to use, or that the entire t-shirt should be [tinted red](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/materials/configuring-materials/tinting-textures-in-wolvenkit). {% hint style="info" %} Properties you define in the `values` array will always overwrite properties from the baseMaterial - if your base material is blue and the mesh says that it should be red, then the item will be red. {% endhint %} Material instances come in two flavours (that's what the `isLocalInstance` checkbox in the material definition is for): #### Local materials These are right there in your .mesh file, and you can edit them directly. You'll find them either in `localMaterialBuffer.materials`, or in `preloadMaterialInstances`. {% hint style="info" %} If `preloadMaterialInstances` is empty, the list will be hidden in the easy [editor mode](https://app.gitbook.com/s/-MP_ozZVx2gRZUPXkd4r/wolvenkit-app/editor/file-editor/editor-difficulty-mode). {% endhint %} #### External materials This is the same as a local material **inside an external file** so they can be used in multiple places. If a material is defined as external, it will be pulled in via **file path** through either `externalMaterials` or `preloadExternalMaterials`. For an example of this, take a look at hairs (e.g. `ep1\characters\common\hair\hh_201_wa__dawn\hh_121_wa__dawn.mesh`) — they do not use local materials at all. You can also use these [`.mi` files](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/materials/re-using-materials-.mi) as a base material and overwrite their properties in the **values** array. This process is called **daisy chaining** and can save you a lot of work. #### Mesh file: diagram Here's an overview:

Example: A mesh with two materials, one of them a local instance, one of them an external .mi file

### Practice Now that you've learned how everything hangs together, let's take an actual look at this. #### TL;DR: I just want to add a new material! {% hint style="success" %} Summary: 1. **Register** a material in `materialEntries`. Here's where you give it a name. 2. **Define** the material in either `localMaterialInstances.materials` or `externalMaterials` 3. **Assign** material for submesh in appearance -> chunkMaterials {% endhint %} #### 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](#step-3-material-definition "mention"). #### ChunkMaterials {% hint style="info" %} You can find more information on this under [submeshes-materials-and-chunks](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks "mention"). {% endhint %} 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.

You may have to create additional entries in "chunkMaterials": Either duplicate an existing entry from the right-click menu, or select the array and use the yellow (+) in the side panel.

#### Step 2: Material registry Materials are **registered** in the array **`materialEntries`** inside your mesh:

For a detailed example, see re-using materials

{% hint style="warning" %} While you can mix external and local materials, you can not mix preloaded and non-preloaded ones. For details, see [below](#preload...-what). {% endhint %}
PropertyDescription
indexnumerical index of corresponding material in target list (as defined by isLocalInstance)
isLocalInstanceSelects 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.
nameunique 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: | local | external | | ------------------------------- | -------------------------- | | `localMaterialBuffer.materials` | `externalMaterials` | | `preloadLocalMaterialInstances` | `preloadExternalMaterials` | 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](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/materials/re-using-materials-.mi) in the project. Wolvenkit will display material names as defined in the `materialEntries`, making it easier for you to see what's what. For more details on material instances, check [materials](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/materials "mention") -> [#definition-material](https://wiki.redmodding.org/cyberpunk-2077-modding/materials#definition-material "mention") #### MaterialInstance: The local material The materials themselves are inside the array `localMaterialBuffer.materials` (or `preloadLocalMaterials` in case of older meshes). {% hint style="success" %} 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](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/materials/re-using-materials-.mi). {% endhint %} A material instance looks like this:

baseMaterial picks the material (shader), while "values" contains properties to adjust it.

{% hint style="info" %} You can find a guide about [texture editing](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/editing-existing-items/changing-materials-colors-and-textures) and [adding custom textures](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/editing-existing-items/changing-materials-colors-and-textures#step-4-optional-custompathing) in the **Modding Guides** section. For an overview of existing materials, check [here](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/references-lists-and-overviews/cheat-sheet-materials). For how to find out which properties a material has, check [here](https://wiki.redmodding.org/cyberpunk-2077-modding/materials#checking-material-properties). {% endhint %} #### Material reference: [reusing materials](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/materials/re-using-materials-.mi#maximally-lazy-external-materials) A relative path to an external material, usually encapsulated in a [.mi file](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/materials/re-using-materials-.mi#.mi-files-to-the-rescue). Use this if you don't need to add extra properties. [^1]: vertices, edges – everything that makes up the 3d object's surface information [^2]: the surface shader and its properties --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.