Summary

Published: July 23 2024 by Last documented update: July 23 2024 by

This guide will teach you how to use ArchiveXL's Resource Patching feature to add/modify appearances of existing items without conflicting too much with other mods or even game's updates!

Prerequisites

• ArchiveXL >= 1.14 — this will not work with older versions

• WolvenKit project with new or modified appearance(s) in .ent/.mesh/.app file(s)

  • If you don't, you should check out Adding decals, Changing materials, colors and texturesor other guide for your case.

Step 1: Delete the work of others

For resource patching you only ship what you've made. Open your .ent/.mesh/.app files and delete appearances and materials that were there from vanilla. Keep your custom ones, make sure your appearances have a unique name!

You mostly can and probably should delete any other fields that you don't want to change. For example, in .mesh files, if you don't change the mesh itself, you should right-click renderResourceBlob and choose "Reset Object", same with lodLevelInfo. That way the files only contain your changes and the rest is taken from vanilla game.

Step 2: Move your files out of the way

You should make a special folder for your mod, outside of the vanilla structures. Common pattern is your_name\mod_name\ (e.g. zhincore\new_gun_appearance).

Move all your patch files to your folder, but remember where you took them!

Step 3: Configure ArchiveXL

Create an .archive.xl file in your resources folder if you haven't already (reuse it if you have one). It should be named your_mod_name.archive.xl (best if you match it with your project name so the normal .archive is named the same).

Open the file in your favorite text editor and add the following lines:

resource:
  patch:
    <source_file_path>:
      - <target_file_path>

Replace <source_file_path> with the relative path to your patch file, e.g. modder\mod_name\gun_appearance.app. And replace <target_file_path> with the relative path to the original file, e.g. base\weapons\firearms\rifle_assault\militech_ajax\w_rifle_assault__militech_ajax.app.

You can repeat these lines for all the files you want to patch (just don't duplicate the first two lines).

And you should be good to go! Install your mod and test it.

Summary

Published: Jan 29 2024 by Last documented update: May 04 2024 by

This guide will show you an example for adding a modifier to an existing game item; in this case, making David's jacket iconic.

It will point you towards further reading material in case you want to dig deeper.

How to mod it

Find The Cyberpunk 2077 Game Directory. Then, create the following text document (you can name it what you want):

r6/tweaks/my_improved_item.yaml

Paste the following contents into the text document and save it:

Items.MQ049_martinez_jacket:
  statModifiers:
    - !append Quality.IconicItem

That's it. When you start the game now, the item's quality will be iconic.

What the fuck did I just do?

You created a tweak edit.

Removing properties

If you want to safely delete a record property, set its value to None. For example:

Items.MQ049_martinez_jacket:
  displayName: None

You might not want to actually do it.

Adding attachment slots

To add attachment slots to an item, you would need to change its blueprint property by either using other blueprints or create a new one using this guide

Summary

Published: Jun 29 2022 by Last documented edit: Jun 29 by

This guide will teach you how to use a textured (also called PBR, which is a subtype of textured and will work) material in Cyberpunk. It is a part of Changing materials, colors and textures — if you are missing information, check the parent page.

Prerequisite

You have a CMaterialInstance that can use your textured material.

If you don't have one yet, follow the steps under Changing materials, colors and textures, or skip to #finding-example-material-configurations and copy the entire material.

The textures material

The default textured material in Cyberpunk can be found under

engine\materials\metal_base.remt

By setting it as the baseMaterial, you're telling your item to load anything you configure under the values array.

Which properties can I use?

Some of the most common properties for metal_base are:

But I have a texture for...

Tough luck, this is the only textured shader we have. Time to get converting :)

Finding example material configurations

Search for metal_base in your asset browser:

engine\materials\metal_base.remt

Right-click on the entry, and select "find files using this". That will get you every base item with a textured material.

With what you now know, you can dig through their material instances and find example parameters.

Summary

Published: Jan 21 2024 by Last documented update: Mar 21 2024 by

This guide will teach you how to add decals to existing items.

It will walk you through the following:

#step-1-cutting-the-decal-mesh

1. Adding it to the mesh entity

2. Setting up the material

Wait, this is not what I want!

• To add new items to the game, check Adding new items

• To learn about materials, check the Shaders section or follow the links from there.

Prerequisites

Software versions

The rest

This guide assumes that you have an existing Wolvenkit project with your item and just want to add the decal mesh. If you don't have one, you can grab the template project from ItemAdditions: Dynamic Appearances.

Inside your Wolvenkit project, you need an .xbm texture for your decal, and its .png export that we'll use for Blender. If you don't have a texture yet, you can

1. add any .xbm to your project (and put it in a custom path)

2. export it to png

3. Replace this png with your decal

4. import the png again (premultiplyAlpha must be checked)

Step 1: Cutting the decal mesh

For this guide, I will be using a sock mesh.

Start by exporting your mesh from Wolvenkit and importing it into Blender. You should see something like this:

1. In the viewport, click on the submesh that you want to have the decal.

1. Switch to Edit Mode (shortcut: Tab)

2. Turn the viewport to the side (shortcut: Numpad 3)

3. Turn on X-Ray mode (shortcut: Alt+Z). This lets you select right through the mesh, in my example, on both sides of the leg.

4. Use the selection tool (shortcut: W, it should be active) to select your decal mesh. It should look something like the left side of the screenshot below.

1. Duplicate these vertices (Shortcut: Shift+D)

2. Split them into a new submesh or new submeshes (Shortcut: P -> Selection)

3. You should now have something like the right half of the screenshot.

Step 2: Renaming our new submesh

If you take a look at the outliner, you will notice a new submesh in the scene collection. This is your decal mesh. We need to change its name to register it as a new chunk.

1. Switch back to Object Mode (Hotkey: Tab)

2. In the Outliner, click on your meshes until your decal mesh lights up

3. Change the name: it needs to be the submesh with the highest number (see the red box in the screenshot below). Double-click the name, then change it to (in this example)submesh_04_LOD_1.

Step 3: Fixing up the decal

With your new submesh selected, it's now time to clean up.

1. Switch back to Edit Mode (Hotkey: Tab)

2. Cut away all vertices that you don't need. (Hotkey: X)

1. After cutting away everything that you don't want/need as part of your decal, select the rest (Hotkey: A)

2. The decal should be one piece, so let's make sure to merge by distance now (hotkey: M).

Now, let's make sure that our decal is above the surface of the original mesh by using the Shrinkwrap Modifier.

1. Switch back to Object Mode (Hotkey: Tab)

2. Duplicate your mesh (Hotkey: Shift+D)

3. Select just one of the two meshes, and switch to the Data tab

4. Delete all shapekeys (starting at the bottom).

1. Now, switch to the Modifiers tab. Leave the Armature modifier alone.

2. Add a Shrinkwrap Modifier (Deform -> Shrinkwrap).

1. Configure it. Try the standard parameters below — if you have clipping, you can play around with the modifier after.

   1. target: The mesh you originally cut from (you can use the eyedropper symbol)

   2. Wrap Method: Select Nearest Vertex

   3. Offset: 0.0005 m (sometimes it's necessary to increase it to something like 0.002 m)

2. Your decal should be floating directly on the surface of your mesh, with just enough offset that it's not clipping. When you're satisfied, apply the shrinkwrap modifier:

1. Now let's merge it with the original submesh with the garment support. Select the duplicate that you made in Step 6.

   1. Switch to Edit Mode (Hotkey: Tab)

   2. Select all vertices (Hotkey: A)

   3. Delete them (Hotkey: X)

   4. Switch back to Object Mode (Hotkey: Tab)

   5. First, select your decal mesh (with the offsets) by clicking on it in the Outliner

   6. Second, select your empty mesh (with the shapekeys) by shift-clicking on it in the Outliner

   7. Now, join them together (Hotkey: Ctrl+J)

You now have a decal mesh with an offset and garment support shapekeys. Awesome! Let's take care of the material now.

Step 4: Material assignment

With your new submesh selected in Object Mode, switch to the Shading perspective. Delete the existing material assignment and create a new material:

1. Click the X above the node browser to delete the existing material assignment

2. Create a new material

1. In the node browser, add a new image texture (Hotkey: Shift+A, Texture -> Image Texture)

1. Click on "open" in the orange node and point the path to your decal png

2. Drag-and-drop the "Color" dot on the orange box to the "Base Color" dot on the green one

3. If your mesh's surface hasn't changed yet, you need to assign the material:

   1. Open the Material tab

   2. Switch to Edit mode (Hotkey: Tab)

   3. Select all vertices (Hotkey: A)

   4. Assign them to your new material

Step 5: UV projection

Our decal is now showing our new material. Make sure that it has exactly one UV map by checking the Data tab:

Time to change to the UV Editing perspective. You should be in Edit Mode (Hotkey: Tab if not) and have all pixels of your decal mesh selected (Hotkey: A if not).

You will see something like this (to learn more about UV maps, look up our theory page):

We will now unwrap our decal. I'll do both UV islands at once - if you have only one (because your decal is on a jacket or something), then your life will be easier.

1. With everything selected in the UV Editor on the left, select UV -> Unwrap -> Unwrap (Hotkey: Ctrl+U)

2. This will unwrap the mesh. Hopefully, you get nice and clean UV islands. If not, you may have to play puzzle

At the end, we want a nice and straight grid over the full width and height of the decal, with the correct orientation. Let's start by fixing up the UV islands.

1. Select a row or column. From the right-click menu, select one of the following:

   1. Straighten: Will put them all in a line

   2. Align Auto, which does one of the following:

      • Align Horizontally: Will put them all on the same Y-axis

      • Align Vertically: Will put them all on the same X-axis

2. Keep doing that until you have a nice grid.

1. If you have multiple UV islands, you can move them on top of each other.

1. Check the individual decals in your viewport and fix up any that are flipped/rotated:

   1. Click on a vertex in the viewport

   2. Select linked (Hotkey: Ctrl+L)

   3. Fix the UV mapping (Right-click: Flip horizontal/vertical, or rotate)

2. When you are done, export your mesh from Blender to glb. Include all submeshes.

Now it's time to head back to Wolvenkit and activate our new decal chunk.

Step 6: Adding a new material

After successfully importing your new submesh into Wolvenkit and open it.

Appearances

First, we need to add your new chunk to each of your appearances. For this example, we will use the material decal.

1. Find the appearances array at the top of the file and expand it.

2. Under each appearance, find the chunkMaterials array and expand it.

3. If you already have an entry for your new submesh, change its value to decal. If you don't, right-click on the last entry to duplciate it. You should now have something like this:

Material definition

If you save your mesh now, file validation will complain that the decal material doesn't exist. It's right; we haven't added a material definition yet. Let's do that.

1. Find the materialEntries array inside your mesh and duplicate the last entry

2. Change its name to decal

3. Make sure that isLocalInstance is checked

4. Increment its index by one (e.g. 29 -> 30)

Material instance

Now that our chunk knows which material it's supposed to look up, we need to provide the actual material.

1. Find the array localMaterialBuffer

2. Find the array materials (directly underneath)

   1. If it's empty, go back up and find preloadMaterialBuffer instead

3. Duplicate the last entry. This is your new decal material. Now we need to make sure it behaves like a decal, too.

   1. Change its baseMaterial to base\materials\mesh_decal.mt. This will tell the game which shader to use, and mesh_decal is for exactly this.

   3. As of now, your decal will be completely transparent. Let's change that.

4. Now we need to get the right material properties. The easiest way is to find another material that uses mesh_decal and steal them from there:

   3. Sort the results by file type by clicking on the column, then find and open a .mi or .mesh

   5. Switch back to your own mesh and copy these values into your mesh_decal material's values array (the one from step 3.3)

5. 1. If you don't have one, go back to #prerequisites -> #the-rest

6. The other properties should be numbers only. If you don't know what they do, you can delete them for now.

Time to test!

Troubleshooting

Issues with your texture

See Textures: Importing, editing, exporting -> #troubleshooting

Issues with the mesh

See Troubleshooting your mesh edits

Issues with the material

See Materials: troubleshooting

Video

Summary

Created & Published: November 05 2022 by @manavortex Last documented edit: Feb 28 2024 by @manavortex

This tutorial will teach you how to switch a player mesh for an NPC garment and map its variants to the existing colours.

Other relevant know-how for this process (you don't need to read them if you already know which item you want to replace):

For a guide how to import meshes into Cyberpunk, check .

Step 1: Replace the mesh

Perquisite: You need a Wolvenkit project.

Find the mesh that you want to use ("the old mesh") and replace it with the one that you want to switch in ("the new mesh").

1. Find both files in the Asset Browser and add them to your project.

2. Move the replacement mesh to the original mesh's folder.

3. Rename the old mesh (e.g. "t2_084_pwa__short_sleeves.mesh" -> "original.mesh").

4. Rename the new mesh to replace the old mesh (e.g. "t2_135_wa_jacket__monk_shirt.mesh" -> "t2_084_pwa__short_sleeves.mesh")

5. Open both meshes in WolvenKit by double-clicking them in the Project Explorer — we will now transfer the appearance names to enable variants.

Step 2: Enabling variants

The game looks up appearances in a mesh file by name. If none can be found, then game meshes will fall back to the default appearance, which is how the early replacers worked — every variant (base_01, old_01, rich_01) would simply spawn the default appearance.

We can simply transfer the names from the old mesh to the new mesh by renaming the entries in the appearances array.

Now that we have done that, we can start recolouring.

Step 3 (optional): Find the .mlsetups

Each appearance in the appearances array has a list of chunkMask entries (one per submesh), which are assigned a material by name.

Step 4: Success!

You can now save your mesh, then install your mod by clicking on the green arrow in Wolvenkit's toolbar. Once you have started up the game, the old item will now look like your new mesh — including its variants.

Enjoy!

Summary

Published: November 05 2022 by Last documented edit: Jun 29 by

This guide will teach you how to edit an item's material, changing its appearance.

Wait, this is not what I want!

• For a step-by-step walkthrough for a recolour of the Netrunner suit, check

• If you want to edit emissive (glowing) material, check ->

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

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

• For details on changing materials, check .

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

• You can find a video guide on (It's also embedded below)

Prerequisites

• Wolvenkit's most recent version ( | — guide has been written with 8.11)

• A

• Most likely >= 1.6.7 (get the )

• If you are editing a basegame material, you need to install from Nexus.

Overview

Estimated time

For a complete noob, including setup of the tool(s): ~1h Once you know what you're doing: <5 minutes and as much time for fine tuning as you want

Steps

This guide will take you through the following steps:

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 0: Finding the .mesh and the appearance

Estimated time: ~5 minutes for total noobs, unless you get side-tracked badly

Find the item's mesh file path and appearance in the .app file:

mesh.DepotPath:

One per body gender (m/w), this is shared by all appearances (basic_01, basic_02, rich_01, rich_02). For the female vest, it's

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

meshAppearance:

This picks the appearance from the mesh file, which you'll need for the next step. Here's how they connect:

Add the mesh to your project

2. Add it to your Wolvenkit Project (double-click or right-click -> Add to Project)

Step 1: Finding the correct material name

1. Open your mesh file in Wolvenkit by double-clicking it.

2. Find the array appearances at the very top, and expand it.

3. Find the appearance by the name that you found in Step 0 (example: bwstripes), and expand it

4. Find the chunk material names. These define the material:

1. Starting with Wolvenkit 8.15, you can right-click on a chunk and click on "Select Material" from the context menu. For earlier versions, you have to find the material yourself - proceed to the next step.

Step 2: Finding the material instance

Depending on your mesh, the material instance will be in one of two places: either under localMaterialBuffer.materials, or under preloadLocalMaterialInstances.

(If you don't see preloadLocalMaterialInstances, that means it's empty and has been hidden.)

Inside the array, find your material by name:

Step 4: Changing the material properties

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

Exporting the .mlsetup

First, add the .mlsetup to your project. You can either expand the CKeyValuePair and click the yellow button, or copy the depot path and use the Asset Browser.

Step 3: Editing the .mlsetup file

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

3. Switch back to Wolvenkit

Step 4: Being done

Congratulations! You modded an item! If that's all you wanted, you can now go and do whatever you want. You can even delete the mesh from your mod and pack only the .mlsetup!

Of course you have only changed an in-game texture, which may cause side effects — especially if other mods do the same. To change that, keep reading!

Step 5: Custompathing

Instead of changing an in-game file, you can also replace it with your own.

1. Rename your file to something nobody else will touch, e.g. manavortex\mlsetups\my_custom_vest_appearance.mlsetup

2. Copy the new relative path (right-click), and update your mesh:

Step 6: Renaming materials

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

Step 6 (optional): adding new materials

To add a new material to a mesh, you can simply right-click on the materials array:

This tutorial will teach you how to swap player's clothing items with NPC's that requires blender editing.

Without mesh editing, some NPC meshes will clip quite badly, because they don't have as many poses and animations as V. Some are even worse, since they'll be flying around rather than following V's movements.

In this guide, we'll fix up a coat by transferring weights from a different item. Prerequisites: - - - Wolvenkit

Step 1: Finding a player item of the same size

Prerequisite: you have the mesh that you want to fix already in your project. For this tutorial, we'll want Maman Brigitte's jacket: t2_001_wa_jacket__maman_brigitte.mesh

1. Use the to find a player mesh of roughly the same size/length/cut. For this tutorial, we'll use River's coat: t2_087_pwa_jacket__river_short

   • For female body gender, search for _pwa_

   • For male body gender, search for _pma_

2. Add it to

3. both meshes

Step 2: Import Meshes in Blender

1. Open Blender

2. delete the standard objects from the scene (Shortcut: A -> X)

3. Import the player mesh (File -> Import -> Cyberpunk GLTF)

4. Import the NPC mesh

Step 3: Editing meshes in Blender

1. Delete or hide the NPC item's armature

2. Delete the NPC item's armature modifier (or make sure that it points at the player item's armature)

Step 3.1: Weight transfer

Repeat the process for each submesh.

1. Select the player item's mesh

2. Select the NPC item's mesh

3. Switch to Weight Paint mode in the dropdown on the top left of your viewport

4. Select "Transfer Weights". Use the settings from the second screenshot.

1. Make sure that the NPC mesh's armature modifier is targeting the player armature:

Step 4: Exporting your edit and importing it to project

1. Select all submeshes under the NPC's armature

2. Use the Wolvenkit Blender plugin to export them over the player item's mesh (overwrite it)

1. Switch to Wolvenkit

2. Import the player item's mesh via Import Tool

3. Optional: copy the NPC's appearances, materials and material definitions to the player mesh

4. Optional: rename the appearances to match those in the original player item

Sometimes you will need to do a bit more of editing but that is not a topic for this tutorial.

Step 5: Success!

Now you have functional clothing attached to the player and not flying arround.

This section contains guides how to alter or overwrite already existing items (please see the page tree in the navigation menu on the left).

If you want to look up , find the corresponding page in .