Section Brief

UI/Workflow documentation

This section contains general information and workflow documentation about importing and exporting files with Wolvenkit.

• For a documentation of the UI, check Import/Export Tool:

  • Tools: Import/Export UI -> #import-tool

  • Tools: Import/Export UI -> #export-tool

• JSON export will generate a text file. If you don't know what that means, ignore this option, or read more about it under Import/Export as JSON

  • Import/Export as JSON -> #export-as-json

  • Import/Export as JSON ->#import-as-json

• For a detailed explanation of the different settings and their workflow, check the nested pages or use the "next" button at the bottom of the page.

File Structure: the raw folder

When exporting a resource, Wolvenkit puts the exported file into your project's raw folder. In the UI, you can find it in your project explorer:

The relative paths (starting under archive/raw) are the same, as will the file name (without extensions).

These files are connected:

source/archive/base/path/your_file.mesh
source/raw/base/path/your_file.glb

You can import your_file.glb via Import Tool.

These files are not connected:

source/archive/base/path/your_file.mesh
source/raw/base/path/your_file_mesh_export.glb

You can not import your_file_mesh_export.glb via Import Tool, because Wolvenkit won't know where to put it.

Exporting

Wolvenkit knows to ways of exporting files: to JSON, or via the Export Tool.

Exported files will be created in your project's raw folder. The relative path will be the same.

Importing

Unless importing from JSON, Wolvenkit can't create files.

When using the Import Tool, we can only import into already existing containers (see #file-structure for more information)

The easiest way to do that is:

1. export an existing file

2. overwrite the new file in raw with your changes

3. import the file

Import from JSON

This option is in the right-click menu.

Converting files to JSON will serialize their content to a .json file in your project's raw folder.

Importing them back will re-create the corresponding file under archive.

This is easiest way to and a perquisite for several modding workflows.

Export as JSON

This option is in the right-click menu:

Import as JSON

This option is in the right-click menu:

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

Exporting mesh file

Morph targets are automatically included inside the glTF file. You can find the morphs as shapekeys within Blender or blendshapes with Maya.

Default Export Settings

LOD Filter (default)

If selected, models for LOD > 0 will not be included with the export.

Is Binary (default, recommended)

Select to export in binary from as GLB rather than glTF format. (Recommended)

Export Materials (default)

Export Garment Support (default)

Exports garment support to shapekeys for Blender.

Export types

MeshOnly

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.

WithRig

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.

WithRig usage

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.

Choosing rigs correctly

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.

MultiMesh

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.

MultiMesh usage

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.

Importing mesh files

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.

Guidelines for successful imports

• 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

Import Settings

Import with Material.Json

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.

Import Material.Json Only

Will only import the Material.json, ignoring the .glb file. Handy for resetting material edits that you did by accident.

GLTF Validation Checks

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

Target File Format

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

Preserve Submesh Order

(experimental as of 8.9.1) Will ignore submesh names, instead using the order inside the armature to generate numbered submeshes.

Select base mesh

(experimental as of 8.9.1) See #use-selected-base-mesh

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

Contains LOD8 named LOD0

Will treat the submesh LOD0 as having the lowest level of detail rather than the highest

Import Garment Support

(experimental as of 8.9.1) Will try importing Blender shapekeys as garment support.

Select Rig

(experimental as of 8.9.1) See #use-selected-rig

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

Import Material.json Only

Useful for updating material information only, without disturbing the original geometry data.

GLTF Validation Checks

Use the GLTF library to run some basic checks to detect bad geometry.

Import As REDengine File Format

Select the desired destination format. (mesh/morphtarget)

Use existing file

Rebuild the existing mesh file. (Required)

Blender glTF Settings

Import

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.

Export

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

  • Apply Modifiers

  • Tangents

  Materials: No Export

• Shape Keys

  • Shape Key Tangents

Submeshes

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

Material JSON I/O

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.

Technical Details

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.

MorphTargets

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.

The following formats are supported by WolvenKit for imports and exports

• mesh ↔ glb/glTF Rigged and static 3d models can be converted to and from REDengine. For a detailed guide, see . Our I/O supports simple non-targeted skinned meshes for extreme efficiency. Advanced methods support multi-mesh, multi-rig, and material embedded meshes. Meshes with embedded morph targets are automatically included as shapekeys. WolvenKit can also export to virtually any 3d format (non-natively) through the built-in renderer Ab3d. You can read more about Ab3d here.\

• xbm ↔ png, tga, dds, jpg, bmp, tiff Textures can be converted to and from REDengine. For a detailed guide, see .\

• mlmask ↔ png, tga, dds, jpg, bmp, tiff REDengine mlmask files can be exported as an array of textures. These texture arrays can be encoded as a new mlmask with a bespoke masklist helper file. For a detailed guide, see .\

• wem ↔ wav, mp3 Audio files can be converted to and from REDengine. Use the Sound Modding Tool to import new audio.\

• morphtarget ↔ glb/glTF (experimental) REDengine morphtargets can be exported to glTF format. The morphs can be viewed as shapekeys/blendshapes with a 3d package. glTF files can be used to recreate morphtarget files, however only one morph is preserved.\

• anims ↔ glb (experimental) Animation files can be exported to glTF format. To import a .glb file as animation, switch Target File Format to anims in the export settings. You can find a detailed guide about this process . \

WolvenKit is capable of exporting Cyberpunk XBM files to common formats like png. It will try and automatically determine the correct import settings based on the file name.

Exporting a texture from Wolvenkit

1. Add the xbm file to your project

2. Open the Export tool (Tools -> Export Tool)

3. Select your texture

4. Click "Export Selected"

This will generate a png file in your project's raw folder.

Export Options

XBM Export Type

Choose a common image format for exported textures. Possible options (as of 8.9.1):

• png

• dds

• tga

• bmp

• jpg

• png

Flip Image

Vertically invert textures for convenience

Importing textures

WolvenKit is capable of importing custom images as Cyberpunk XBM files. The Import/Export Tool can replace an existing XBM or generate new standalone XBM.

The easiest way to go about it is this:

1. Add an existing xbm file of the same type that you want to import to your Wolvenkit project.

3. Overwrite the png with your edited texture.

4. Open the Import tool, and select your png file. The correct settings should be applied automatically.

5. Click "Import Selected".

Import Options

Advanced Options

Texture Group

Select a preset for import. This will preselect the options below, so pick the right one for your use case!

Possible values are:

• TexG_Generic_Color

• TexG_Generic_Grayscale

• TexG_Generic_Normal

• TexG_Generic_Data

• TexG_Generic_UI

• TexG_Generic_Font

• TexG_Generic_LUT

• TexG_Generic_MorphBlend

• TexG_Multilayer_Color

• TexG_Multilayer_Normal

• TexG_Multilayer_Grayscale

• TexG_Multilayer_Microblend

isGamma

Sets isGamma boolean upon import. Color textures (such as diffuse) must be set as true, or they will appear blown-out or too bright in-game.

VFlip (Default: True)

Should the image be v-flipped?

RawFormat

as of 8.9.1

Raw format for export. Possible values are:

• TRF_Invalid

• TRF_TrueColor

• TRF_DeepColor

• TRF_Grayscale

• TRF_HDRFloat

• TRF_HDRHalf

• TRF_HDRFloatGrayscale

• TRF_Grayscale_Font

• TRF_R8G8

• TRF_R32UI

• TRF_Max

Generate MipMaps

IsStreamable

???

PremultiplyAlpha

Should the image consider transparency?

MultilayerMask

You can export and import MultilayerMasks via Wolvenkit.

Exporting MLMASK files

Mask files can be exported with the Import/Export tool in a similar fashion to . Additionally, WolvenKit will automatically create a custom masklist file, which can be used for importing modified mlmask files.

Importing MLMASK files

Use the import tool to select any masklist file within the raw directory of the Project Explorer. If you don't have one, export an MLMask first.

MultilayerSetup

You can export and import MLSetup files via JSON and edit them with the MLSetupBuilder.

Export:

Import:

Unlike music and voice-overs, sound effects in Cyberpunk 2077 are stored inside .opuspak files, which are described by a single sfx_container.opusinfo file.

Exporting sound effects

In order to export sound effects, you need to have the sfx_container.opusinfo file in your project. Find it in the Asset Browser and add it to your project.

With the opusinfo selected in the Export tool (if you don't see the file, press Refresh), you should now see the export options on the right.

The important field for us here is "Selected for Export". Click the three dots on the right to open a selection window where you can choose which hashes to export. Click the hash you want and press the arrow button pointing right to add it to selection.

Once you've selected what you want, press Finish to confirm the selection and back in the Export tool press "Export Selected". The sounds you've chosen should now be in the raw folder of your project. You will find two files for each of the sounds, one is origin .opus and the other is .wav. You can usually ignore the .opus file.

Importing sound effects

To import back a sound effect, all you need is the sound file in .wav format with the exact same filename it had when you exported it. It should also be in the same folder (base).

You can usually leave the default settings as they are. After pressing "Import selected", your project's archive folder should now contain a new modified sfx_container.opusinfo and one or more sfx_container_XXX.opuspak (XXX being a number). The opuspak contains your new sound (and other sounds too).