Replace a player item with an NPC item

Put your item in place of a default game item. Supports variants.


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

Make sure that you replace an item that you can actually spawn โ€” not all items in V's folder are actually spawn-able =>Spawn Codes (BaseIDs/Hashes)

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

Example: Replacing the short-sleeved poser jacket with the monk shirt with the tied-back sleeves.โ€‹ For the male variant, replace _pwa_ with _pma_ and _wa_ with _ma_.

the old mesh


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.

If there are more entries than variants available, or if you're just curious which spawn code corresponds to which appearance, go here for a guide how to find out.

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.

For a full guide on Editing mesh appearances, follow the link (you don't have to).

For a more detailed explanation, you can check this page, but all we care about right now is this lookup chain:

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.

For a guide on how to edit an .mlsetup file (or to change an item's appearance in general), see here.


Last updated