Changing materials, colors and textures

Changing how an item looks in-game

Summary

Created by @manavortex Published November 05 2022

This guide will teach you how to change an item's appearance by editing its MultilayerSetup (*.mlsetup file), how to rename materials, and how add your own mlsetups (custompathing).

For a step-by-step walkthrough for a recolour of the Netrunner suit, check R&R: Colour Editing

If you want to edit emissive (glowing) material, check R&R: Emissive -> Changing the presets

It uses the following versions:

• WolvenKit >= 8.11 (Nightly | Stable)

• MLSetupBuilder >= 1.6.7 (get the latest release)

Most items in Cyberpunk are not textured, but use a procedurally generated material consisting out of an mlmask (a list of alpha masks) and an mlsetup (a list of material paths and -colours). There is a section on the exceptions below.

If you want to learn how mesh material assignment works in general, you can check the corresponding page.

For an overview of base materials and example files, you can check here.

If your changes do not become active, you will want to install Material and Texture Override from Nexus.

Video guide

Please keep in mind that video guides might be outdated, as they are much more difficult to update than a wiki page. Refer to the written guide below if you run into any troubles!

Step 1: Finding your item

This tutorial assumes that you already know which mesh and appearance you want to change. If you don't know that, you need to find the correct game file. If you only have a cheat code, see Spawn Codes instead.

We will use the female variant of the puffy vest (as I've already mapped and documented it):

base\characters\garment\player_equipment\torso\t2_002_vest__puffy\t2_002_pwa_vest__puffy.mesh

Add the item to your project and open it in WolvenKit. You want the original to look up material names, even if you overwrite it with your own mesh.

Step 2: Finding the correct appearance

If you don't know which appearance you want to edit, check here.

default is the fallback appearance that'll be used if anything can't be resolved by name or index. This is the reason why most item swap mods give you only a single appearance - people didn't set up the variants.

We will change the appearance bwstripes, which is used by Vest_17_basic_01:

find material bwstripes and remember the name of the chunkMaterial

chunkMaterials corresponds to the chunkMasks: For submesh_00, the material at array position 0 will be used, for submesh_01 the material at position 1, and so on.

This vest has only one chunkMask, so there's only one material.

Remember its name (ml_t2_002_ma_vest__puffy_bwstripes) and find the corresponding material definition:

Most meshes have their materials under localMaterialBuffer/materials. However, some of them (especially those with physics) use preloadLocalMaterialInstances instead.

It's ml_t2_002_ma_vest__puffy_bwstripes

You will (hopefully) see a material with three entries in values (order doesn't matter):

Key	Value (DepotPath)
MultilayerSetup	base\characters\garment\citizen_casual\torso\t2_002_vest__puffy\textures\ml_t2_002_ma_vest__puffy_bwstripes.mlsetup
MultilayerMask	base\characters\garment\citizen_casual\torso\t2_002_vest__puffy\textures\ml_t2_002_ma_vest__puffy_default.mlmask
GlobalNormal	base\characters\garment\citizen_casual\torso\t2_002_vest__puffy\textures\t2_002_ma_vest__puffy_n01.xbm

For the purpose of this guide, all that matters is the mlsetup, which determines all the individual material assignments in this CMaterial. For an explanation of the shader, check here.

This is the path to the mlsetup file. By editing this, you can change colours and surface materials.

If you have your own mlsetup file, this is where you need to set tohe path. See custompathing for further details.

Most materials in Cyberpunk use the engine\materials\multilayered.mt material and assign colours via an .mlsetup file. If you're used to textures, you are probably going to hate this. As somebody who has been where you are: the mlsetup system is cool. Genuinely. Give it a chance!

multilayered material

If you would rather use a textured material, check here.

A multilayered material consists of multiple layers of materials, projected on the mesh through the mlmask: white parts get affected, black parts are blocked out. (Again, for a full explanation, check here).

You can turn any multilayered material into its cyberspace variant by changing the material from engine\materials\multilayered.mt to base\characters\common\cyberspace\silverhand_overlay_cyberspace_mml.mi

Exporting the .mlsetup

We're going to edit the mlsetup file and then import it back, causing a global change in the appearances of every item which uses this particular material file. (If you don't want that, see Custompathing below).

We do that by editing the MultilayerSetup. Check the MLSetupBuilder wiki page for how to do that.

1. Find the file that you want to edit in the Asset Browser.
2. Add it to your Wolvenkit project.

3. In the project explorer under Wolvenkit's archive folder, right-click on am mlsetup file This folder will only be visible in the "source" or "archive" tab of your project explorer
4. Select "Convert to JSON"

Step 3: Editing the .mlsetup file

If you don't have MLSetupBuilder installed, you need to do that now. If you don't know how to use it, please check Using MLSB

1. Optional: If you don't see an mlsetup.json in your project, switch the Project Explorer to source or raw.
2. Right-click on the file and open it in MLSetupBuilder.

Optional: by hand

Open up MlSetupBuilder and load your .mlsetup.json file.

If you select WolvenKit's "Open in File Explorer" option, you can copy the path from the explorer's address bar and paste it into the MlSetupBuilder's address bar.

For a documentation of multilayer properties, see here. For a list of reference images, check Multilayered: Previews

3. Draw the rest of the owl and edit the mlsetup.

4. Export the file, overwriting the original .mlsetup.json

5. Switch back to Wolvenkit

6. Right-click on the .mlsetup.json and import it from json.

This is already working. You can pack the project and see it in action!

Since you haven't changed anything in the mesh itself, you can (and should) delete it from your mod. Only keep it if you want to do the steps below.

Step 4 (optional): Custompathing

If you want to put up your own .mlsetup, rather than overwriting the original one, you can do that. All you have to do is changing the DepotPaths to the relative path of your mlsetup.

Keep your folder and file names unique! If you have two mods adding a file at the same location, the second one will be unable to overwrite it and will use the first mod's file. That is, unless your mods are in REDmod format, which will be loaded even later and in order of their folder names.

Understood? No? That's fine. Just keep it unique. :D

Step 5 (optional): Renaming materials

You can rename a material by changing the "name" property inside the CMeshMaterialEntry in the materials array:

Inside the appearances block, the material assignment to the individual submeshes happens by name, so don't forget to change the chunkMaterial names!

Step 6 (optional): adding new materials

To add a new material to a mesh, you need to create two entries. The first of those needs to be in the materialEntries array:

Edit the new material's index and name. This is crucial!

Now, add an entry in the localMaterialBuffer.

If your mesh doesn#t have entries under localMaterialBuffer, use preloadLocalMaterialInstances instead.

The new material will have the name you defined in the CMeshMaterialEntry in the previous step.

You can now use your new material just like the regular, old materials.