Porting 3d objects to Cyberpunk

How to replace an in-game item with your custom mesh

This page will give you information on how to get a 3d object into Cyberpunk.

Summary

written by manavortex, published on Oct. 14 2023

Wait, that's not what I want!

You can find other relevant guides scattered across this wiki, for example

Adding new items

Custom props

Textured items and Cyberpunk materials

Prerequisites

Wolvenkit >= 8.11.1

Wolvenkit Blender IO Suite>= 1.5.0

Blender >= 3.6 (or 4)

A Wolvenkit project, so that you can pack your mod

Step 0: Finding the right base mesh

To bring 3d data into Cyberpunk, Wolvenkit needs a .mesh file to import into. Read here why.

For the purpose of this guide, it doesn't matter if you are trying toReplace a player item with an NPC item, creating Custom props or Adding new items. You will overwrite an existing in-game mesh, the file path doesn't matter.

Static items

If you are creating props, you use a mesh from the template project or grab any static mesh from the game.

Do not take equipment item or weapon meshes — those include a bunch of extra data that you don't need (the armature). You don't need it, and it can have side effects.

As this guide will focus on equipment items, you can skip Step 3 and 4 completely.

Equipment items

If you want V to wear the item that you're currently porting, it needs to move with the player. For that, you need an armature. This guide will show you how to acquire one.

You will delete fewer meshes if you read all of the sections below before starting.

Why are we doing this?

Items move because they are tied to the armature's bones. For that to work, the armature you're working needs to have those bones in the first place. Most shoe meshes won't include head bones, which means that they won't work for sunglasses.

The default fallback mesh that people use in this case is the Netrunner Suit.

You can use the Wolvenkit search in the Asset Browser to find meshes.

The right slot

Begin by picking a game mash from the right slot. If you're porting shoes, pick a shoe mesh, if you're porting glasses, pick a glasses mesh – you get it.

The right shape

For the sake of future you, pick an in-game item that is as close to your new garment as possible. If you're porting boots, take boots and not slippers. If you're using a baggy sweater, pick one of those or a jacket rather than a skin-tight t-shirt.

The right body gender

Make sure to use an item with the correct armature. You can identify them by prefix in the path:

body gender	Player	NPC
male rigged	_pma_	_ma_
female rigged	_pwa_	_wa_

Wolvenkit search query suggestions

Search for something like this:

namespace > slot > gender > .mesh

player: player > torso > pwa > .mesh 
npc:    common > torso > pwa > .mesh 

For torso items, you can add t1 for inner torso items (tight-fitting) or t2 for outer torso items (worn above t1).

Step 1: Exporting your mesh from Wolvenkit

Export from Wolvenkit

For where to export a mesh, see Tools: Import/Export UI

For how to export a mesh, see Import/Export: Mesh (3d Model)

If your mesh won't export from Wolvenkit, try unchecking the following box(es) in the export settings (by unchecking the boxes):

• #export-materials
• #export-garment-support-experimental

Once you are done, you can find the exported glb in your project's raw folder (see #project-explorer-tabs or#file-structure-the-raw-folder for details).

Step 2: Importing your mesh into Blender

This part won't be documented here. If you don't have an entry in your import menu, hit up Google - get that thing into Blender somehow.

Step 2.5: getting a grip on the submesh count

The mesh count in Blender corresponds to the submesh/chunk count in Wolvenkit. In Cyberpunk, we have one submesh per material that we want to use.

If you don't know what that means, ignore the information for now - but few meshes use more than five. The current maximum is the player base body with a total count of ten submeshes per , so to be on the safe side, we need to stay below that.

If you want to get fancy, check out Step 2 in the guide about ported items and Cyberpunk materials. Otherwise:

1. Select all meshes but one by shift-clicking them in the Outliner at the topright of your viewport

9000 of these have to go

2. Select the last mesh

3. Join the meshes together (Shortcut: Ctrl+J)

Step 3: Parenting the mesh(es)

The end result

This section will show you how to get the following end result:

• one or more mesh(es) with names from submesh_00_LOD_1, consecutively numbered

• parented to the right armature

There are two strategies that you can use. Personally, I use Strategy 1: Replacing the 3d data, since it will retain most of the original mesh's properties.

Preparation

By the end of your section, you should have something like this:

Read on to find out how to get there

No matter which strategy you use, we need to get the prerequisites done first. We need an original Cyberpunk armature.

1. Import the result of Step 1 into Blender (see the Wolvenkit Blender IO Suite's documentation about Importing into Blender)

Clean up any residual modifiers and transforms (we don't want them):

1. If your mesh has an armature modifier with a non-Cyberpunk armature, delete it

   1. (click on the x in the modifier panel)

2. If your mesh is parented to anything that is not a Cyberpunk armature, unparent it:

   1. Select the mesh(es)

   2. Select Unparent (Hotkey: Alt+P)

   3. Select the second option "Clear Parent and Keep Transforms"

Strategy 1: Replacing the 3d data

If you are doing this, you can skipStrategy 2: Parenting the meshes.

We start by deleting the original's vertex data.

1. In , select all of the original meshes.

2. Switch to Edit Mode (Hotkey: Tab)

3. Make sure that all vertices are selected (Hotkey: A)

4. Delete all vertices (Hotkey: x, option: Vertices)

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

We'll merge our new meshes into the empty containers now:

1. Click on your new mesh

2. Click on the empty original mesh in the Outliner (yes, order matters)

3. Join them (Hotkey: Ctrl+J)

The new mesh should be from the Outliner and its data should be in one of the original meshes. If it's the other way around, Undo (Hotkey: Ctrl+Z) and select them in the right order. (You could've listened!)

Repeat the same for all meshes that you want to import to Cyberpunk.

If you need more submeshes, simply duplicate an existing one (Hotkey: Ctrl+D, ESC) and change its name by incrementing the number. Make sure it still ends in LOD_1, not in LOD_2 — that will tell the game it's low-poly, and cause it to be hidden until you're further away.

That's it. All your meshes are parented to the armature now.

Strategy 2: Parenting the meshes

If you are doing this, you can skip Strategy 1: Replacing the 3d data.

We can simply parent the meshes to our existing armature:

1. Click on your mesh

2. Click on the Armature object in the Outliner

3. Select Parent (Hotkey: Ctrl+P)

4. Select "Armature Deform"

5. Make sure to rename your mesh: Wolvenkit doesn't know what to do with meshes that aren't part of the sequence starting at submesh_00_LOD_1. (Blender's .000 suffixes will be ignored) You can delete the original meshes, or you keep them for Step 4.

Step 4: Weight Transfer

Start by deleting all vertex groups from your new mesh, as we will now replace these and don't want anything funky to stick around to destroy our re-import:

You now need to transfer the weights from your original game mesh. If you deleted or overwrote the armature's original meshes during Step 3: Parenting the mesh(es), you can simply import it again for a second copy.

The Wolvenkit Blender IO Suite has a function to do this for you. For the sake of completeness, the box below contains the full manual process, but we recommend using the plugin's Mesh Tool panel to do this.

Transferring weights by hand

1. Select your mesh

2. Select the original mesh

3. Select "Link Mesh Data" (Hotkey: Ctrl+L)

4. Select "Transfer Mesh Data" (second from the bottom)

5. Open the little popup at the bottom left of your viewport. Select the following options:

   • Data Type: Vertex Group(s)

   • Vertex Mapping: Nearest Face Interpolated

   • Source Layers Selection: All Layers

6. Repeat that process for all of your meshes.

Step 4.5: Weight Painting

Nobody likes weight painting.

This is where you pray that you don't have to do this (and I pray that nobody will have to actually write this section), because weight painting sucks. you can find some general information on Meshes and Armatures: Rigging.

This is what you need to do if your mesh moves unevenly or if parts of it are clipping through the body although things are fitting correctly.

Step 5: Exporting from Blender

See the Wolvenkit Blender IO Suite's documentation about Exporting from Blender

Step 6: Importing into Wolvenkit

See the WolvenKit wiki about #importing-mesh-files

Step 7: Success!

… or maybe not. Maybe you should try Troubleshooting your mesh edits now.

If everything worked, here are a few more guides that you might want to look into:

• R&R: Refitting (step by step) will teach you how to refit for a certain body mod

• Adding new items will walk you through the steps of adding your mesh as a new piece of equipment

• Textured items and Cyberpunk materials will tell you more about Cyberpunk's material system