HomeDiscordGitHub
Edit

Porting 3d objects to Cyberpunk

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

Summary

Published: Oct. 14 2023 by manavortex Last documented Update: Mar. 20 2024 by manavortex

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

If you'd like to watch a video about the whole process, feel free to address the video version of this guide - https://www.youtube.com/watch?v=r3nyFm-9h9o

Alternative workflow, shorter video tutorial by CyberVesna - Importing Custom Clothes

Wait, that's not what I want!

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

Prerequisites

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 AMM: 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.

Every piece of equipment needs its own armature, or it will just vaguely float around V's position.

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 WKit Blender Plugin: Import/Export -> Meshes -> Export from Wolvenkit

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

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

For how to import a mesh into Blender see WKit Blender Plugin: Import/Export -> Meshes -> Importing into Blender

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

  1. Select the last mesh

  2. 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 this 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)

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

  1. 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 the original mesh

  2. Select your mesh

  3. Select "Object -> Link Mesh Data" (Hotkey: Ctrl+L) alternatively: the Weight Transfer menu in the Weight Painting perspective

  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:

    1. Data Type: Vertex Group(s)

    2. Vertex Mapping: Nearest Face Interpolated

    3. Source Layers Selection: By Name

  6. Repeat that process for all of your meshes.

Step 4.5: Weight Painting

Nobody likes weight painting.

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. Pray that you don't have to do it, because it sucks.

If you're unfortunate, you can find a guide on Weight Painting for Gonks!

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, you now have replaced an original Cyberpunk item. Since this is probably not what you want, check out the following guides:

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

  • AMM: Custom Props will show you how to add props for AMM and entSpawner

Here are a few more guides that could interest you?

PreviousRunning Python ScriptsNextReducing vertex counts

Last updated

Was this helpful?