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.

Section Brief

Formerly part of the ELI5 guide, this has been moved to the general section.

The depot is where wolvenkit stores accessible copies of basegame assets that are needed for editing/viewing project assets. With the current version of wolvenkit, you DO NOT need to do anything other than specify a folder for it. Everything else happens seamlessly in the background as and when needed. The only reason to generate a depot now is for using MLSB. If your not doing that, just skip this.

There are three methods of creating and maintaining a depot:

1. Adhoc Depot is the manual process of creating the asset files as you need them. The general idea is that almost all the files you need are already accessible to WolvenKit. The biggest benefit is the minimal disk space usage.

2. Partial Depot is mostly uncooked and unbundled, and it's only missing the GLB files. Unless you are needing that specific file type, this depot has everything you will need. The biggest detractor is that it requires 120GiB of disk space. It will let you access the microblends and masks in MLSB, but wont have meshes available.

3. Full Depot (outdated as of 2023!) is every asset available to us. The biggest benefit is that everything is ready to use and MLSB can work with the assets. The biggest detractor is that it requires 160GiB of disk space.

Steps: Adhoc Depot

1. Add the asset to your project which also adds the asset to the Import/Export Tool.
2. Open the Import/Export Tool, right click on asset, and click on Show Settings. Most of the time the default settings will provide you the output you're needing, but for DDS files from MLMASK and if you need the rig files, then you'll need to get into the settings to make those alterations.
3. Once you have the settings to what you need, either select the files you want to export and click the Process Selected button, or click the Process All for everything on the list.

Steps: Partial Depot

1. Launch WolvenKit application and click on Tools then Depot Generator.
2. Click into the field next to Depot Path and select the folder C:\Cyberpunk2077Mod\Depot
3. Select PNG and then click the Generate Materials button. While the program is running, the button will deactivate and once the program is complete File Explorer will automatically open at the location of your Depot.

1. You do not need to unbundle anything else, since the Wolvenkit exports will do that for you. If you want, you can stop reading now.

2. To unbundle the following list of extensions click on the Unbundle Game button: gradient, w2mi, matlib, emt, sp, hp, fp, mi, mt, mlsetup, mltemplate, and texarray.

Steps: Full Depot

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 texture files. 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:

How do I use the Blender integration features?

If the Export Materials checkbox in the mesh export settings is enabled, WolvenKit will create a Material.json file under raw. You can find it in the same directory as the mesh.

You can use the search bar at the top of the asset browser to search the game files:

To search in your currently installed mods instead, switch to Mod Browser:

Operators

You can chain the search operators below with the > character, which will run the results of the first search through the second search.

Examples:

// find all .mesh files in mod archives matching ArchiveXL_Netrunner
archive:ArchiveXL_Netrunner > .mesh

// find all textures with "steel" outside of "Characters"
// (have negative matches last, as they're expensive)
.xbm > steel > !characters

Let's get to the meat of the matter.

By archive

This is mostly useful for the mod browser, as it allows you to e.g. retrieve files from your other mods without switching projects or digging through your mod directory.

Use the archive switch to show only files in a certain archive (name or path):

a:ArchiveXL_Netrunner
archive:ArchiveXL_Netrunner

By full / partial path

Full

This is the default search behaviour, and you don't need to include these operators.

Search will only show you files under this path.

path:base\characters\common\player_base_bodies\player_female_average\t0_000_pwa_base__full.mesh
@base\characters\common\player_base_bodies\player_female_average

Partial

To limit your search to a certain folder, you can put the folder path and the search term:

base\characters\common\player_base_bodies\player_female_average t0_000_pwa_base

You don't need to include slashes. These search terms below will yield the same results:

base\characters\common\player_base_bodies\player_female_average arms
base characters common player_base_bodies player_female_average arms

// or simplify it to
player_base_bodies player_female_average arms

File Extension

You can limit your search to certain file extensions:

player_female_average .mesh
player_female_average .xbm

Hash

If you only know a file's hash, you can still search for it:

hash:9872775577851133397

Or

You can search for multiple terms by using the | operator:

player_base_bodies\player_female_average > .mesh|.xbm

Not

You can exclude terms from the search by prefixing them with !:

player_base_bodies\player_female_average arms > !morphtarget

Regular Expression

Wolvenkit lets you search for regular expressions. The main limitation is that you can't use spaces:

regexp:^.*main_npc.*judy.*\.mesh
r:^.*main_npc.*judy.*\.mesh

.* will work by default.

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

Audio

Voice-overs & music

Voice-overs and most music are stored as .wem files – you can use the search to filter by extension.

When you select an audio file in your Project Explorer or the Asset Browser, the File Information widget will turn into an audio player:

Sound effects

You can import and export sound effects stored in .opuspak files using the Import and Export tools respectively. See this page for a walk-through:

Video

In the past, Wolvenkit used to be able to view videos. However, due to license issues, we had since to remove the plugin.

However, it was only a wrapper around RADTools, which you can also install as external tool.

Wolvenkit is scriptable using javascript and its internal API. With it you can automate tasks such as exporting, as well as make changes to files programmatically.

Adding Scripts

See Script Manager -> #adding-scripts

Script file path

Any .wscript files you have created or edited will be stored in the following location:

%APPDATA%\REDModding\WolvenKit\WScript

You can delete or edit them via Script Manager.

Editing Scripts

The editor shows your source code with code formatting and includes code suggestion for the Wolvenkit api.

For questions or suggestions about the scripting interface please visit the #wolvenkit-scripts channel on the Discord server.

API Commands

Documentation of the API can be found at https://wolvenkit.github.io/WolvenKit/index.html

This documentation is generated by Doxygen from the codebase so will update as the API evolves.

Utility Functions

There is also a utility library called Logger.wscript shipped with wolvenkit that assists with writing messages to the wolvenkit Log. It can be included with the following statement:

import * as Logger from 'Logger.wscript';

it provides the following functions:

Logger.Info(obj)

Prints the supplied object or text in yellow in the log window.

Logger.Warning(obj)

Prints the supplied object or text in purple in the log window.

Logger.Error(obj)

Prints the supplied object or text in red in the log window.

Logger.Success(obj)

Prints the supplied object or text in light blue in the log window.

Logger.Debug(obj)

Prints the supplied object or text only to the log file.

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.

2. Export the xbm file: this adds a png file with the same name to your project's raw folder.

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

By default advanced XBM options are hidden. This can be changed by modifying WolvenKit Settings. (Is this still the case? Double-check)

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

Should MipMaps be created?

IsStreamable

???

PremultiplyAlpha

Should the image consider transparency?

Created: Dec 03 2024 by manavortex Last documented update: Dec 03 2024 by manavortex

This page will tell you about keyboard shortcuts and nifty tricks that make working with Wolvenkit easier.

Project Browser

The context menu in the project browser reacts to Shift and Ctrl, making other operations available. Check it out!

Drag and drop

You can drag and drop files and folders to move them. Hold the Ctrl key to copy them instead.

Rename and refactor

You can call up the rename dialogue by pressing f2, as long as you have a node in the project browser selected.

If you check the Update in project files? box, Wolvenkit will automatically try to update all references in your project to the new file path.

Copy relative path

The context menu's Copy Relative Path action will show you other options if you hold Shift and/or Ctrl:

Collapse/expand a folder and its children

By holding the Ctrl key when you click on a folder, you can collapse or expand the whole folder and its children.

File Editor

The file editor's context menu and menu bar react to Shift and Ctrl, making other operations available. Check it out!

Difficulty mode

Check Editor Difficulty Mode for the full documentation.

Delete all but selection

Holding the Shift key while an array element is selected will offer you Delete all but selection instead of Delete selection.

Overwrite with selection

Holding the Shift key while pasting into an array will let you overwrite the current selection with your clipboard.

Holding down the Ctrl key as well will let you overwrite the entire array with your clipboard.

Shift: Recursively fold/unfold

By holding Shift while expanding a node, you can fold/unfold all of its children (and their children) according to specified rules for the most common node types:

Double-Click: Fold/unfold all siblings

Double-clicking a node in an array will toggle the expansion state of all siblings to the expansion state of the node.

f2: Search and replace in selection

You can search and replace in selection by using the context menu or pressing the f2 key.

Clean up

Especially in mesh files, the Clean Up menu is your friend.

Clean up empty submeshes will delete extra chunks from old templates.

Delete unused materials will drop any material entries that aren't used by any of your appearances.

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

Converting files to JSON will 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:

What is a WolvenKit project?

To access most WolvenKit features, it's necessary to create a Project first. Projects are primarily used to separate and organize source and game files into distinct directories. Each project can be thought of as the source code for any given mod.

Create a new WolvenKit mod project

You have two means of creating one:

• From the : ->

• From Wolvenkit's view via the Create New Project button

You will see something like this:

How it looks like:

Opening an existing WolvenKit mod project

2. Select a .modproj file to open with WolvenKit

File structure explained

Your project will contain the following folders:

Subdirectories in source

Your Wolvenkit project will have several folders inside of source.

As of 8.9.1, these are:

Archive

Location: your_wolvenkit_project/source/archive

Everything in this folder will be packed into your mod's .archive file.

Raw

Location: your_wolvenkit_project/source/raw

This is your working directory. Keep any files here that you don't want to end up on Nexus.

customSounds

A directory for custom sound files.

Resources

Location: your_wolvenkit_project/source/resources

This folder contains other files for your mod.

Project naming and mod load order

If your mod contains an .archive file, then it will have the same name as your Wolvenkit project. Since .archive files will be loaded in alphabetical order (ASCII):

If you are creating a compatibility mod (something that modifies the files of another installed mod), then yours needs to load first.

Building a mod project

See also

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

MultiMesh

MultiMesh usage

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

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.

• 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

Use selected base mesh

Contains LOD8 named LOD0

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

Import Garment Support

Select Rig

Use selected rig

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

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

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.

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

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 full depot extracts every asset available to us. It will use ~160GB of disk space, and in October 2023, it is not required for any single workflow.

If you want to extract it anyway, you need to use .

1. Run CMD.EXE
2. Change directory to WolvenKit.CLI
3. Run the following command to unbundle all assets. You can ignore any red failures and purple warning message. Just wait for 99% and press Ctrl+C

   WolvenKit.CLI unbundle -p "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077\archive\pc\content" -o "C:\Cyberpunk2077Mod\Depot"
4. Run the following command to uncook all normal map assets. You can ignore any red failures and purple warning message. Just wait for 99% and press Ctrl+C

   WolvenKit.CLI uncook -p "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077\archive\pc\content" -o "C:\Cyberpunk2077Mod\Depot" --uext png
5. Run the following command to uncook all mask assets. You can ignore any red failures and purple warning message. Just wait for 99% and press Ctrl+C

   WolvenKit.CLI uncook -p "C:\Program Files (x86)\Steam\steamapps\common\Cyberpunk 2077\archive\pc\content" -o "C:\Cyberpunk2077Mod\Depot" --uext dds
6. Run the following command to delete all the failed uncook attempts. This commend will delete all the buffer files without prompting you and will recursively search in all subfolders for more buffer files that need to be deleted.

   del /s /q C:\Cyberpunk2077Mod\Depo*.buffer