Import/Export: Mesh (3d Model)
Last updated
Last updated
For the UI documentation, check Tools: Import/Export UI
For general information such as the file structure and output directory, check Import/Export
For a step-by-step workflow and troubleshooting, see -> ->
WolvenKit is capable of exporting Cyberpunk mesh files (with their armatures and materials) natively to glTF format, preserving Cyberpunk's separation into distinct submeshes with different materials.
We can import those .glb files into the following game files:
.mesh
.morphtarget
anims
After exporting, your files can be found in your project's raw section.
Morph targets are automatically included inside the glTF file. You can find the morphs as shapekeys within Blender or blendshapes with Maya.
If selected, models for LOD > 0 will not be included with the export.
Select to export in binary from as GLB rather than glTF format. (Recommended)
Turn this off if the file export fails.
Exports garment support to shapekeys for Blender.
Turn this off if the file export fails.
The default export is versatile enough for most use cases. Any mesh, static or skinned can be exported and imported with this setting. For skinned meshes the bone parenting hierarchy will not be included, however this does not matter for importing meshes. Meshes will be divided into submeshes by material.
Bone parents are not required for successful mesh imports
Using the WithRig export option allows us to export skinned meshes with parented bones. By default exported meshes are correctly skinned, but the skeleton contains no parenting information. Bone-parented rigs are especially useful for posing/animating using a 3d software.
Mesh files themselves do not contain the bone parents, so it's required to select a rig file to accompany each mesh export. To select a rig, in the WithRig Settings section of the right panel press the ... (Collections) button. This opens the collections menu where you will select your rig file.
Choose a rig file from the panel on the left side, then use the opposing left/right arrows to add or remove a rig. The selected rig will be added to the right panel. Only one rig can be used, so adding more than one rig will result in the 1st rig in the list being selected.
Generally for NPC heads, weapons, or vehicle meshes you can find the associated rig file similarly named to the mesh in the same or nearest directory. For other meshes such an NPC body, a more generic rig is used.
e.g. Johnny Silverhand is a man with average body proportion so his body uses the following rig:
base\characters\base_entities\man_base\deformations_rigs\man_base_deformations.rig
If the wrong/incompatible rig is used, an error will be displayed within the Log.
The MultiMesh export option is similar in functionality to WithRig, with the addition of support for multiple rigs and meshes. This option was implemented because some meshes use more than one rig.
e.g. Judy's mesh l1_001_wa_pants__judy uses the following rigs:base\characters\base_entities\woman_base\deformations_rigs\woman_base_deformations.rig
base\characters\main_npc\judy\l1_001_wa_pants__judy_dangle_skeleton.rig
Where the dangle rig is used in addition to the base rig to animate Judy's belt.
Navigate to the MultiMesh Settings and configure the export options for additional meshes and rigs. The functionality is identical to WithRig, so the same instructions should be followed.
WolvenKit is able to import custom mesh files. The Import/Export tool expects meshes to be in the glTF format, stored as a .glb file (binary format). The tool supports skinned (animated) or rigid (static) models.
You have to import your .glb into an existing .mesh file!
Be sure your mesh is triangulated and does not contain loose geometry
Submeshes are ordered by name and are called submesh01, submesh_02, submesh_03, etc.
Individual meshes have < 65535 triangles
Will re-import the Material.json file that has been generated on export, overwriting any changes you have made in the meantime. If you've exported from Blender via plugin, material changes may have been written back.
Will only import the Material.json, ignoring the .glb file. Handy for resetting material edits that you did by accident.
Skip: Will not validate
TryFix: Will attempt to fix issues with your file
Strict: Will not attempt to fix anything, but yell at you for anything that might cause issues.
Mesh: Imports over a mesh
Morphtarget: Imports over a morphtarget (the file that deforms a mesh). Necessary for e.g. custom body morphs.
Anims: Imports over an animation file. Necessary for custom animations.
Rig: Attempts to import the associated armature to a .rig
MeshWithRig: Combines the Mesh and the Rig option.
(experimental as of 8.9.1) Will ignore submesh names, instead using the order inside the armature to generate numbered submeshes.
(experimental as of 8.9.1) See Use selected base mesh
(experimental as of 8.9.1)
Instead of importing directly over the target file, this option will pull the .mesh file that you have picked in Select base mesh (e.g. if you run into bone problems).
Will treat the submesh LOD0 as having the lowest level of detail rather than the highest
(experimental as of 8.9.1) Will try importing Blender shapekeys as garment support.
(experimental as of 8.9.1) See Use selected rig
(experimental as of 8.9.1)
Instead of importing over the target file's associated rig, this option will pull the .rig file that you have picked in Select base rig (e.g. if you run into bone problems).
Useful for updating material information only, without disturbing the original geometry data.
Use the GLTF library to run some basic checks to detect bad geometry.
Select the desired destination format. (mesh/morphtarget)
Rebuild the existing mesh file. (Required)
Having trouble modifying a mesh file? Keep in mind WolvenKit always uses an existing mesh file for each import. Once a mesh file is corrupted, all subsequent imports will be corrupted as well. Try replacing the source mesh with the original!
Meshes can be imported with the pre-installed Blender glTF add-on with the default glTF import options. To learn about importing models with the Cyberpunk Blender add-on for shader previews, visit the Blender Integration page.
The following settings are recommended for using Blender with WolvenKit. Unlisted export options can use the Operator Default preset (no change). These options may not cover all cases, however it's a good baseline for getting started.
Geometry
Materials: No Export
Shape Keys
New to Blender and/or modding? Remember to remove all extra assets before exporting! Do not include lights, cameras, or other meshes such as the default cube.
Meshes are sorted and given materials based on the submesh index. LOD variants are numbered as 1, 2, 4, and 8 which corresponds to the REDengine value. These are not the distances at which the LOD is applied.
It's important to remember the submesh name is determined by the Data Block not the Object Name. The orange colored icon represents the Blender object name, while the green polygon represents the actual name of the mesh.
It's possible to reference the material structure of the original mesh file using WolvenKit to see how each submesh is mapped to a distinct material.
In the example above, you can see the material list which repeats after reaching glass1 meaning this is the final submesh. We now know this mesh has 12 distinct submeshes (0-11). It also contains four LOD's because each material list is repeated for a total of four lists.
For a detailed breakdown of each material, use the WithMaterials option for mesh exports.
WolvenKit supports importing and exporting REDengine material information in the form of a bespoke material json file. Learn more above
The material json file is necessary for previewing meshes with the Cyberpunk Blender add-on. The REDengine data written to json is interpreted by Python script to setup somewhat accurate representations of REDengine shaders.
Just looking to edit materials? WolvenKit can directly edit materials within .mesh or .mi files using the File Editor.
A bespoke json file will be generated from the material dependency stack and exported alongside the raw mesh file. The entire daisy chain of materials is analyzed and written to file top-down, meaning all properties are written as they appear in game. The material json file can be edited with any text-based editor. Any changes saved to the json file will be written to the mesh file upon each import.
We rely on the Depot (a local file cache) which contains all material dependencies for any given mesh.
For each WithMaterials mesh export, the material dependencies are analyzed and missing resources are dumped to the Depot.
The material json is generated by looking at the complete daisy chain of materials. Meaning every single dependency is reviewed and the top-most properties that REDengine sees are written to the material json file.
The REDengine values written into the material json file can be interpreted by the Blender Cyberpunk glTF importer to automatically set up shaders within Blender Cycles. Read more about Blender integration here.
Morphtarget I/O is highly experimental, some assets are not handled correctly
WolvenKit can export morphtarget files from the game to glTF format, these morphtargets files are used to morph a base mesh that exists in the game. For example, the character that you create in the game with different types of nose, eyes, and mouth is formed using the shape keys that exists in the morphtarget files. You can use Import/Export Tool to export them to glb/glTF, any morph texture(s) existing in file will also export along in dds format.
create a meshName.Material.json file for the
We strongly recommend the , which will automate the following checks for you:
