Troubleshooting your mesh edits

Summary

Last documented update: Jan 31 2025 by manavortex

This page will help you troubleshooting your mesh edits.

Wait, this is not what I want!

• For texture trouble, check Textures: Importing, editing, exporting -> Troubleshooting

• For a guide on exporting and importing meshes, check WKit Blender Plugin: Import/Export

• If you don't know how to begin editing, check one (or all) of the following:

  • R&R: Refitting (step by step)

  • Blender: Getting Started

This page

Importing

Wolvenkit finds too many vertices, but Blender export is fine!

The Wolvenkit Blender IO Suite will check all your meshes against the vertex limit (~65k) before exporting. However, under certain circumstances, Blender's default export shatters your plugin into a million parts. This is not the plugin's fault!

Delete custom normal split

You can check if your mesh has any custom split normal attributes, and delete them.

Check your UV splits

The GLTF algorithm really doesn't like it if two vertices have the same UV coordinates (see this ticket).

Here's how you can fix it:

1. Select the overlap

2. move the overlap out of the UV editor's box (it will tile, so everything is fine) Shortcut: g -> x -> 1 or g -> y -> 1

3. Profit

My import won't show up in-game!

We need to troubleshoot your import.

Does the Wolvenkit preview update?

Yes: The problem is somewhere else, the mesh import works fine.

No: Is there an error message in the console?

Is there an error message in the console?

Yes: Here's where your problem is. Make the error message go away by checking the rest of this guide.

No: Do you have extra shapekeys?

Do you have extra shapekeys?

In Blender, check your shapekey section. It should look like the green box (or be empty).

If it does not, you need to apply any extra shapekeys, because Wolvenkit will ignore them on reimport. Expand the box below, or check here to find out how.

Tangents

You get an error message like this:

Message: One or more Geometry in provided GLTF doesn't contain Tangents data. Tangents must be included within glTF files.

Use the Cyberpunk Blender IO Plugin to export

Quick, easy, recommended: the plugin will tell you exactly what's broken and how to fix it. Download it here.

Alternatively, you can check by hand:

Importing: bone troubles

Bones not found in import mesh(es)

The armature you created in Blender has more bones than the mesh you're trying to import into. Since Wolvenkit can't create these bones (yet? Mesh import/export is hard), you're seeing an error message.

To get rid of it, delete the bones in Blender, or import into a different mesh (see Fixing bone troubles as for how)

Bone: neutral_bone not present in export Rig(s)/Import Mesh

The neutral bone is created by the glb export plugin when there are vertex groups without a parent bone. WolvenKit will not let you import if there is a mismatch.

Fixing bone troubles

The following two scripts help you finding and/or fixing the problem. Switch to the Blender Scripting perspective and create a new, blank text file. Then, toggle the Blender system console to see their output (Blender: Window -> Toggle System Console)

Missing bones

Optional: To find which bones you're missing, you can use this script, which will print their names to console. You can also skip this step and try the troubleshooting below.

Vertices without weights

You can use the Wolvenkit Blender IO Suite's Mesh Tools to Group Ungroup Verts — if you're lucky, that will solve the problem.

Option 1: Fuck those bones: Python

You can find a Python script on mana's github that will drop unused bones and vertex groups. Run it in Blender's Scripting Perspective with your meshes selected.

Option 1: Fuck those bones: Noesis

You can import the mesh with Noesis, which will not do any of these checks. For that, you need to import/export via .fbx.

Option 2: The Netrunner suit

The armature from the following mesh has a lot of bones and will often resolve most of your issues:

t0_005_pwa_body__t_bug.mesh
t0_005_pma_body__t_bug.mesh

Try using the Netrunner body as a base for import. You can use Wolvenkit's #select-base-mesh feature for this.

If you end up with missing bones,

Option 3: Transferring bones

It's time to play 3d puzzle and assemble bones from multiple sources. Unfortunately, there is no simple solution for this yet. You need to

• find the bones that your armature is missing in other meshes

• transfer them into your import target mesh (guide on xbae's page)

• export all the extra meshes into Blender

• merge their rigs, which you should do with the linked Python script

• and finally reimport everything back into Cyberpunk.

Importing: Everything else

WolvenKit will not import a mesh that has any kind of issues. Those include, but are not limited to:

• non-flat faces

• zero faces/edges

• loose vertices/edges

There is no guarantee that any of the steps below will actually solve your problem.

Edit Mode

In Edit Mode, you can find a few commands in the Mesh -> Clean Up menu:

• Delete Loose

• Split Non-Planar Faces

• Split Concave Faces

• Merge By Distance

It's still broken

Your last option is the 3d print tool to (hopefully) find out what is wrong with your mesh.

Fortunately, the tool is free, easy-to-use and already included in your Blender.

• Zero Edges: Those are bad, fix them (click on them, then press X and just delete them)

• Non-Flat Faces: Those are even worse, as they can make the game crash. You need to split them up until they are flat, or investigate the surrounding edges/vertices to see what's going wrong here.

• Zero Faces: Only fix if you have <100 of them — the tool doesn't always identify them correctly (the mesh analyzed above was h0_000_pwa_c__basehead, which is absolutely fine).

In-Game

My mesh won't show up

In Blender

• make sure that you have exactly one UV map

• check Face Orientation — most materials won't show backfaces (red). You can import submeshes with the suffix _doubled to make WolvenKit generate them for you, like it does with hair.

In Wolvenkit

When saving your mesh, check the console for errors. In version >= 8.9.0, a basic material validation is taking place. If you don't see any warnings, make sure that the resource paths in your mesh are correct and that you aren't loading invisible textures.

Parts of my mesh are missing

Do they show up in the Wolvenkit preview?

• No: you probably forgot to select them when exporting from Blender. Make sure that you get them all into Wolvenkit.

• Yes: There's either an issue with your material assignments or with your chunkmasks. Refer to the corresponding guides to learn how you can debug this.

If that's not it, check My mesh is inside-out! below.

My mesh won't move at all

Some meshes require an entAnimatedComponent along with the garment's component. Check here for details.

Changes from Blender are missing in-game

For example, you have moved something, but the change doesn't show in the game: this most often happens when you change things around in edit mode, since they are stored as object properties rather than applied immediately.

1. Select the object in edit mode

2. Press Ctrl+A

3. Select "All Transforms" to apply all transformations.

My mesh is moving weirdly

E.g. you've changed a shape, but now everything moves at an offset.

As stated in the importing/exporting guide, it is easy to fuck up the mesh's properties, and this is most likely what happened. The easiest way to "fix" this is to apply your shape deformation to the original object.

Replacing the vertices

1. Import the original object into Blender, without any of your changes. If you have to, reexport the working file from Wolvenkit.

2. See #strategy-2-replacing-the-vertices on the Porting 3d objects to Cyberpunk page

My mesh is completely warped

If you have added the item via ArchiveXL or swapped out an in-game item with something that belongs in a different slot (e.g. a jacket on the head slot), you might have to fix the corresponding entity file.

My shadow mesh is always visible

Check the renderMask attribute inside heder / renderChunkInfos / index. For shadow meshes, there shouldn't be anything but MCF_RenderInShadows.

My mesh ignores my texture edits!

The textures are most likely embedded. Here's how you can force your material to pull in external textures instead:

My textures are black and shiny!

That's a problem with your materials, not with the mesh itself. Check Textures: Importing, editing, exporting -> Troubleshooting

Garment Support

My mesh is string cheese/exploding vertices/a puddle on the floor

This section will tell you how to delete garment support. If you don't want that (you shouldn't! It's cool!), check the next section.

Option 1 (likely to work): Import your mesh with garment supports

On the .glb import setting, check the #import-garment-support box.

Option 2 (guaranteed to work): delete GarmentSupport from the mesh

I'm doing everything right, but garment support still explodes!

Component IDs

Check the component's id in the mesh .ent or .app appearance's components array:

If any given ID is equipped twice, it can break garment support in the way you're observing.

Import settings

Make sure to import your mesh with garment support enabled. If that doesn't do the trick, you can try re-creating the garment support shapekeys in Blender.

My mesh is inside-out!

Check the Face Orientation and make sure that all the faces you see are blue. If not, you have to flip them – see the link for how.