wolvenkit / wolvenkit

Community Mod editor/creator for REDengine games.

⚠️ This repository focuses on REDengine 4 for Cyberpunk 2077. For WolvenKit for The Witcher 3: Wild Hunt please see: https://github.com/WolvenKit/WolvenKit-7

WolvenKit is an open-source modding tool for Cyberpunk 2077. Our vision is to develop a standalone software which is capable of reading and writing all REDengine file formats. Additionally the WolvenKit application is designed to simplify and accelerate modding workflows. This repository was created to demonstrate how CDPR's proprietary REDengine reads and writes file formats.

This toolkit is being made solely for research and educational purposes, and the dev team is in no way responsible for any malfunctions that occur from its use. It's completely open source, licensed under the GPL-3.0, and in no way is it made to generate revenue.

---

Installation • Usage • Contributing • Screenshots • Credits • License

Installation

Wolvenkit requires the latest .NET 8.0 runtime:

1. Go to Microsoft's .NET download page
2. Find the ".NET Desktop Runtime 8.0.x" section and download the installer for your architecture (x64)
3. Run the downloaded installer

---

There are multiple ways to install Wolvenkit:

The WolvenKit.Installer app

The WolvenKit.Installer app is a simple program for managing (installing, updating, removing) different WolvenKit versions similar to the Visual Studio Installer app.

It is hosted on github and you can install it from there. Click here:

Portable or Installer

Download either the latest stable version or the current nightly (beta) version from here:

Package	Latest Release	Checks
WolvenKit Nightly
WolvenKit

To install the app quickly download WolvenKitSetup-x.x.x.exe and double click to run the installer.

You can also simply download WolvenKit-x.x.x.x.zip and extract it to a location of your choice

Usage

📑 Check out the wiki: https://wiki.redmodding.org/wolvenkit

Build instructions

If you want to build the app from source yourself:

1. Download and install Visual Studio 2022 Community Edition or a higher version.
2. Clone this repository.
3. Open the solution (All.sln)
4. Build the projects.

Contributing

• Join the Cyberpunk 2077 Modding Server for active development

Do you want to contribute? Community feedback and contributions are highly appreciated! It's a good idea to create an issue when implementing a feature so people don't work on the same feature/issue in an asynchronous manner.

For general rules and guidelines see CONTRIBUTING.md.

For any questions:

Developer	Role	Email
Seberoth	Project Lead / Core Development
Rfuzzo	Project Lead / Core Development	Email
Traderain	Project Lead	Email

Screenshots

Credits

WolvenKit is a direct result of the hard work and continuous support, financial and otherwise, of the many researchers, programmers, artists, contributors, and companies that have helped with this project. Without their outstanding work and generous support, we never would have been able to create WolvenKit for Cyberpunk 2077. A very special thank you goes out to...

• JetBrains who supplied open source licences for our developers
• Syncfusion who supplied an open source licence for the WPF controls we use
• Ab3d PowerToys
• Ab3d DXEngine

An ancestor to this tool was W3Edit, initially developed by Sarcen in 2015, around the time The Witcher 3 first came out. After Sarcen stopped working on it, a few of us picked it up and continued from there.

• Assimp
• Zenhax
• Xentax
• Lua Utils for W3
• TW3 Booster
• TW3 Converter
• VgmToolbox
• TW3 Mod Discussion
• Payday 2 Modding Information
• ModWorkshop
• W3 SaveGame Editor
• ffmpeg
• irrlicht

License

Copyright Disclaimer: Under Section 107 of the Copyright Act 1976, allowance is made for "fair use" for purposes such as criticism, comment, news reporting, teaching, scholarship, and research. Fair use is permitted by copyright statute that might otherwise be infringing. Non-profit, educational or personal use tips the balance in favor of fair use.. This project is solely made for research and in no way made to generate any revenue.

wolvenkit's Issues

Figure out all the unknown bytes and parse files properly

Status	Extension	Type	Progress
✓	XML	XML File	xml file can be opened in text editors.
½	XBM	CR2W file	Fully parsed altought some stuff is not yet correct?
✓	Wizdef	CR2W file	Parsed fully since there is only one of this and doesnt contain anything might be a test file
✓	W3Simplex	CR2W file	Parsed fully contains simplex data
½	W3Occulsion	CR2W file	Little stuff is missing contains occulsion data
X	W3Fac	CR2W file	Missing a lot contains skeleton and MimicFace
X	W3Dyng	CR2W file	Missing a lot contains dyng resource and sekeleton
✓	W3App	CR2W file	Parsed fully contains appearances
X	W2W	CR2W file	Missing a lot contains info about how a level is set up
½	W2Ter	CR2W file	Little stuff is missing contains terrain info
✓	W2Steer	CR2W file	Parsed fully contains movement and steering commands
✓	W2Sf	CR2W file	Parsed fully contains Switchable foliage
✓	W2Scene	CR2W file	Parsed fully contains conversation/scene
½	W2Rig	CR2W file	Contains rig
✓	W2Ragdoll	CR2W file	Parsed fully lot contains ragdoll data/begaviour
✓	W2Quest	CR2W file	Parsed fully contains a quest
✓	W2Qm	CR2W file	Parsed fully contains the pins a world
✓	W2Phase	CR2W file	Parsed fully contains quest progress
X	W2P	CR2W file	Missing a lot contains particle system
✓	W2Mi	CR2W file	Parsed fully contains material instance
✓	W2Mg	CR2W file	Parsed fully contains material graph
½	W2Mesh	CR2W file	Missing a lot contains a mesh(es?)
½	W2L	CR2W file	Little stuff is missing contains level data
✓	W2Job	CR2W file	Parsed fully contains an action/job for an NPC
✓	W2Je	CR2W file	Parsed fully contains collection of journal entries
X	W2Fnt	CR2W file	Missing a lot contains a font
½	W2Ent	CR2W file	Little stuff is missing contains entity data
✓	W2Em	CR2W file	Parsed fully contains map pins info
✓	VBrush	CR2W file	Parsed fully contains a vegetation brush(es)
✓	Usm	Multiplexed video file	Needs to be demultiplexed to view as a video file
X	Textarray	CR2W file	Missing a lot contains a textarray
✓	Subs	Text file	Can be opened with any ordinary text editor
X	Srt	Unknown	Can't parse it (Might be SRT Tree or Speedtree?)
✓	Spawntree	CR2W file	Parsed fully contains spawning data
✓	Sav	Save file	Parsed fully but not implemented yet and for some random reason there is one in game archives
X	Redwpset	CR2W file	Missing a lot of stuff contains waypoint collection
✓	Redswf	CR2W file	Swf stuff and dds images
✓	Redicsv	CR2W file	Missing a lot contains a 2d array of data
✓	Redgame	CR2W file	Parsed fully contains info about game resource
✓	Redfur	CR2W file	Parsed fully contains Hairworks info probably
X	Redexp	CR2W file?	Missing a lot of stuff contains Areas
✓	Reddlc	CR2W file	Parsed fully contains dlc info
½	Reddest	CR2W file	Little stuff is missing contains Apex destruction info
✓	Redcloth	CR2W file	Parsed fully contains Apex cloth
✓	Redapex	CR2W file	Parsed fully contains Apex destruction info
✓	Popup	CR2W file	Parsed fully contains info about a popup
X	Navtile	Unknown	Not parsed, not even listed by wcc_lite (no idea)
X	Navmesh	Unknown	Not parsed (Probably Navmesh info?)
X	Naviobstacles	Unknown	Not parsed (probably info about obstacles for NPCs)
X	Navgraph	Unknown	Not parsed (no idea)
X	Navconfig	Unknown	Not parsed (maybe pathfinder config for the ai?)
✓	Menu	CR2W file	Fully parsed contains info about a menu element
✓	Journal	CR2W file	Fully parsed contains info about a journal entry
✓	Hud	CR2W file	Fully parsed contains info about hud elements
✓	Guiconfig	CR2W file	Fully parsed contains info about hud elements
✓	Grassmask	CR2W file	Missing a lot of stuff contains grassmasks
✓	Formation	CR2W file	Fully parsed contains (ai preset? behaviour?)
✓	Flyr	CR2W file	Fully parsed contains tree info
✓	Env	CR2W file	Fully parsed contains enviroment info
✓	Csv	Csv file	Can be opened in Microsoft Excel
✓	Cellmap	CR2W file	Missing a lot of stuff contains Cellmap
½	Buffer	Unknown	Animation and model data

Mod manager

So since Nexus Mod Manager (aka NMM) is pretty horrible with handling Witcher 3 mods I think we should create our own thing.
By looks and function I would say something like the Gta V mod manager would be good for us.

Features we definetely need:

• Virtual file system handling
• Calling script merger and Mod merger to check for conflicts when trying to install
• The installer package system needs to be upgraded a bit so version description etc. can be added into it.
• #33 needs to be finished so files can be inspected without reading bundles.
• We need to inspect how the Nexus API works in NMM (maybe ask for permission from them) and make NMM links to be openable in WolvenKit mod manager.

The basic layout is started in /.ModManager. Will require some work from both WolvenKit's side and ModManager's side before it can actually replace NMM but since we don't need to support multiple games it will probably be done in a couple weeks.

ModPackage

So since Nexus Mod Manager is a garbage in terms of Witcher 3 modding the least we should do if we don't make a full mod manager is a package creator/installer. I think the way OpenIV's oiv packages work is awesome and we should create something similar. Currently when you press create packed installer the program simply zips your stuff. This is nice and all but you can't really track mod versions and such with this.

So my suggestion is creating an xml file which would be filled with metadata + icon for the mod + the compressed&packed mod data into a zip file which then could be used to 1 click install mods. Some GUI for creating the package would be nice too. Something like this would do: https://www.gta5-mods.com/tools/openiv-package-manager

ps.: I contacted the OpenIV team for some details and stuff and permission. I hope they reply.

Multi purpose project (DLC&Mod)

We should have it so you can mark a file as a DLC file or as a mod file and when packing they will be installed to the appropriate folder. If we are updating mod explorer anyway we should probably track changed files and such so a "Please save dialog" can be made when closing the app or something.

Model renderer

Something like Noesis but a little more simple.

• Simple OpenGL scene
• Model renderer
• Texture loader for the models
• Bones
• Animations
• Import from DAE,FBX
• Export to DAE,FBX

pack wwise converted voicelines as w3speech file

As a voice asset modder I want to pack all wwise converted voicelines (wem files) and if available the corresponding lipsync animations as a w3speech file so it can be deployed in a dlc mod.

• load configuration from #24
• make sure for every file exists a wem file
• make sure files are named and located in a directory suitable for the w3speech tools
• give a warning if lipsync anims are missing
• encode lipsync csv files to cr2w files
• start the packer
• copy the created w3speech file to the appropriate dlc mod directory

for details see batch files in the w3speech tools.

Caching system

So since Asset browser is getting improved we face the fact that loading 3million files is kind of slow. So a caching system should be implemented.

For now something like this should be good:

• Get xxHash of file -> Load the stuff from it and save the contents and the hash to a json file.
• Next time when we start up we create a dictionary<hash,jsonfile> and if a file has its hash in there then we load it from there instead of reloading it again.

This should vastly improve performance. There might be a better solution. I am up for suggestions.

w3speech format

Hi together. Anyone here knows what the 8 bytes behind the wem bytes block in the .w3speech files are supposed to mean/how to decode/encode them?

CR2W Editing rework

So let's be honest, at the moment editing CR2W files is pretty cancer and really not user friendly.
So as a start I would suggest implementing a couple simple controls and such:

• Dumping all the enums the game has and making comboboxes ( @ali-alidoust or I have to dump them for this)
• Dumping all the CVectors of the game so types can be properly identified not just guessing if its really a CVector.
• Figuring out all the unknown bytes.

Other general improvements:

• Fixing the chunk copy's broken stuff.
• Search in chunks, by type,name etc.
• Not referenced string remain in the files as reported by @rmemr to me which should be checked and removed before writing the files.
• Generally reworking the whole way CR2W files are handled so if we ever finnaly dump the class layouts they can be read with reflection like in Gibbed.RED.

epic: add a new 3d asset to the game

As a 3d asset modder I want to add a new 3d asset to the game to use it in my mod

• asset must not overlay existing assets
• add mount point automatically to reddlc (either dir or file)
• before adding check in preview

Zoom&updates for flowtree

There needs to be a way to zoom because complex scenes are hard to inspect this way.

• Mouse drag
• Zoom
• Proper context menu to edit the nodes

Redscripts files

• Parser for them https://gist.github.com/Traderain/aa1be1844011c6d36b6b89303bee151f
• Investigate usages

In theory the engine recompiles it every time its deleted so might not be usefull but might worth to take a look.

see a list of all 3d assets from the game

As a 3d asset modder I want to see a list of all 3d assets from the game to get an overview of the available assets

• a list should contain only 3d assets
• total number of found assets
• pageable list if there are too many (one list is too slow)

Sound files

So this is probably gonna be one of the hardest tasks.

• Unpack the soundcache files
• soundbank rebuilder
• Repacker

An in-editor sound player would be a nice adition probably.

Investigate .w2l files

CGameplayEntity - Its in the rttidump, kinda implemented but not fully
CTriggerAreaComponent - Its in the rttidump but its complex REALLY complex
CSectorData - Its in the rttidump but its not straight forward
W3MinimapZoomScaleTrigger - no idea
W3TrapSpawnEntity - no idea
CEntity - only missing 2 bytes probably some bool
CRiftEntity - no idea
CWayPointComponent - its in the rttidump but needs more investigation probably read incorrectly atm

epic: extract 3d asset from the game

As a 3d asset modder I want to extract a specific entity from the game to edit it in a 3D modeling software

• see a list of all 3d entities from the game
• search by keyword
• preview selected in 3d
• extract into a directory of my choosing

Folder structure in DLC

Currently upon loading assets to "DLC" and the packing the DLC doesn't produce working DLC.

Currently kit creates
files\DLC\Bundle\[files]

Upon packing the metadata path points to [files]
While the game need DLC files to be:
\dlc\[DLCNAME]\[files]

The workaround now is to add the assets:
Create the folders:
files\DLC\Bundle\dlc\dlcname\[files]

and copy the assets to needed to be used to [files]

[files] can be any structure one wants to use.

Discord link

Discord link in the description is not valid.

XBM converter + Image Preview

b798c48 does the basic converting however converting form images into CBitmapTexture is not supported yet

• Converting xbm to dds
• Export as (dds/tga/png/bmp)
• Import
  

Implement proper graphs for easier editing of complex files.

This library seems to be able to server our needs for editing behaviour files and complex w2l and such https://github.com/panthernet/GraphX

---

• Implement the basics of GraphX
• Replace the current cutscene editor
• Create a behaviour editor
• Create a flexible general CR2W graph editor which work with reflection
  ... etc. (Everything else should be discussed after these are done)

More costum editors:

• HSL Color picker - This is coded but doesn't work for some reason.
• CCurve editor.
• Also somehow rework the hex editor so it's easier to edit not explored stuff. Not sure about this how yet.

Speech files

• Fix W3Edit.W3Speech so it parses the files properly
• Create a repacker

Everything should be done in memory with byte arrays!

Journal editor

We need a way to properly edit/create journal files.
As a start a simple editor would be nice + a preview.

I kinda already started it at https://github.com/Traderain/Wolven-kit/blob/master/W3Edit/frmJournalEditor.cs but still needs more checks and it only previews doesn't let you edit yet.

Typos, grammar errors etc.

There are many grammar error and typos in the project. If you find any please comment them here.
Also here we can track stuff related to this.

Cache file parsing

• Texture
  • Reading
  • Writing
• Collision
  • Reading
  • Writing
• Shader
  • Reading
  • Writing
• Sound
  • Reading
  • Writing
• Dep
  • Reading
  • Writing
• Streaming
  • Reading
  • Writing
    There needs to be a bundleexplorer like browser for these files to or somehow unify it with bundleexplorer.

Implement a quest designer

Search 2.0

It would be neat to have a way to search in xml files and such to find stuff easier search needs to be reworked amyway in Asset browser so this should be a good occassion.

Scripthook,SBUI,EnvUI,etc. Integration

Once @ali-alidoust is done with scripthook or at least progressed a little more we should kinda integrate it into WolvenKit like the guys for OpenIV did for the GTA V Scripthook. Adding other community made tools and some slight integration would be nice.

For example:

• Parsing the scriptlog and loading it into an ent.
• Debugging a scene made with SBUI something like what @erxv made in unity but more polished and much easier to use.
• etc.

This is a long term goal but it should be a thing I think. Also an installer for these would be nice (and if some similar tools come out in the future) would be nice. So if any noob wants to mod the game he has all the tools right there with tutorials and everything.

ps.: this should be an optional feature so if someone doesn't want to use these mods its not required

adjusting of phoneme timings for better lipsync generation

As a voice asset modder I want to adjust the lipsync timings of new voicelines to tune the results.

Automatically extracted phoneme timings need to be adjusted most of the time before generating the lipsync animations. This is a time consuming process (see https://www.youtube.com/watch?v=oI6PvgqE-wM)

• load configuration from #24 and show the list with info about available phoneme timings
• on selection of one voiceline, backup the original timings and show a "adjust timings" view with:
  • audio wave form
  • associated timings (from the csv file)
  • used text (see below for ascii art)
  • optional: the originally extracted timings
• in timings view:
  • playback of audio with play position cursor
  • zoom of waveform (+/- keys as most simple solution)
  • scrolling of position
  • timings line must be linked with zoom and scrolling operations
  • interactive moving/shrinking/expanding of phoneme blocks (which adjusts the timings)
• save updated to timings in the same csv format for the generation of lipsync

Apex files (redfur,redcloth)

So in theory according to @erxv redfur files could be converted to apx. Since there are no unknownbytes in it. All we need to do is figure out that hashing algorythm used by apx so the files are recognized by apex and serialize the values to the weird xml apex recognizes. There needs to be an exporter and in importer as well.

• Exporter
• Importer

generate lipsync animations from audio

As a voiceline asset modder I want to add lipsync animations to new voicelines so the game actors are animated while speaking.

• load configuration from #24
• rename/generate 18khz files with names required for the w3speech tools (see requirements of the tools) and save them in the appropriate folder
• run the phoneme extractor (provide a csv file with the strings)
• run the lipsync generator
• show the currently executing step (phoneme extraction/lipsync generation) and a progress bar
• show the results in a separate log window

see details in the batch files from the w3speech tools

BundleExplorer overhaul

• Rename to asset browser
• Different view modes
• Add cache files,w3speech etc.
• Asset preview
  • 3d models
  • Sounds
  • Images
  • text files
  • movies
• Convert it to be purely event based so it can be kept open and import stuff as you need it.

Cooking needs to be eleminated to implement this so texture.cache/soundspc.cache etc. writers need to be implemented for this.

USM Video Player

A way to play replace and export videos.

• Play video
• Sound
• Subtitles
• Import-Export
  

select and prepare voiceline audio files for a dialog scene

As a voice asset modder I want to pair voiceline audiofiles to specific dialoglines so they are played when the dialog text is displayed as subtitle.

assuming the dialog scene is already done and the w3speech tools are to be used):

• load the strings + ids (either from a strings csv or directly from the scene) and display in a list (id + string)
• ability to hide uninteresting lines (for example select options or other lines)
• select for every line a 44khz audio file
• save pairing (as configuration)
• show info about wwise conversion

Fix resetting windows

Close windows reset modexplorer and such when loading/creating a new project

Clickonce

The application should be converted to a clickonce application so an installer and a portable version can be distributed.

• It would allow automatic updates.
• Displaying first time run stuff like readme
• Associating with the w3modproj and such files

Add the ability to set global variables using the debugging protocol

The packet format for setting a variable is as follows (w3net style):

Request()
    .utf8("Config")
    .int32(0xCC00CC00) # magic number
    .utf8("set")
    .utf8(section)     # Section
    .utf8(name)        # Variable Name
    .utf16(value)      # Variable Value
    .end()

I think a PropertyGrid filled with all vars received by using the "list" command and ability to change the values using this command could be really useful.

extract a 3d asset into a directory

As a 3d asset modder I want to save a selected asset from the game in a directory to edit it in a 3D modeling software

• ability to mark one or more 3d assets in the list
• button to export all selected
• on export choose a directory

Particle preview

Preview particle emitters and such. Something like shadertoy but more simpler.
Something like this would be nice:

---

• Unknownbytes of w2p
• CFX
• Basic implementation of mercury engine
• Preview in mercury engine
• Save the edited w2p file

Metadata.store parser

We need a way to parse&write metadata.store files so we don't have to use wcc_lite for it which is slow

• Parser
• Writer

Mod renaming and changing settings

Currently if you change the name of your mod or tick/untick dlc etc. your mod will break. This needs to be fixed.

Debug protocol

• Connect to the game
• Send data to the game
• Recieve data from the game

Thanks to Nightingale most of it is done only there is a bug left to solve with callbacks but essentially it can do nearly everything script studio can do. For reference check: 5c688d7

Also a video demonstrating how it works:

search by keyword for 3d asset

As a 3d asset modder I want to search by keyword for a specific 3d assets so I can select it for further usage (e.g. 3d preview, export, etc.)

• search should be integrated in the overview list
• case insensitive
• number of found vs total number should be always visible
• key for resetting the search

epic: add new voicelines to the game

As a voice asset modder I want to add new voice lines to the game so I can use them in my scenes/mod.

• pair dialoglines and audio voicelines to add
• create lipsync animation
• pack as w3speech file to add in a dlc

meta: define supported user roles to concentrate on the benefits of new features and to confine their scope

The kit is a tool for modders. But there are different kind of modders with different goals and different level of experience. It's important to keep this in mind.

To help defining new features and prioritize them according their value it's helpful to define a set of usage roles and assign every feature to a role along with it's intended value. From the top of my head all/a subset of the following roles could be considered as target audience for the kit. Meaning: new features should support their modding goals (unordered):

• 3d asset artist
• 2d asset artist (= texture modder)
• scene creator
• quest creator
• sound asset modder
• voice asset modder
• terrain creator
• experienced low level tinkerer
• reverse engineer
• ...?

So far the kit is mostly targeted for the low level tinkerer.

Fix build target

Currently Irrlicht and VLC.net doesn't really like each other so the whole project has to be x86. This needs to be fixed so we can switch of the prefer 32bit and go back to anycpu.

xml menu creator gui

GUI for generating menus.

preview a selected 3d asset

As a 3d asset modder I want to preview a selected 3d asset to decided if it's the one I am interested in

• preview activated by selecting in the overview list
• list should still be open while previewing
• selection of different asset updates the preview
• preview window does not need to be big
• optional: rotate selected asset

Assets browser crash

Steps to reproduce bug:
Right click on any folder in Mod explorer -> Add file

It opens empty Asset browser window (so it is not possible to add files to chosen folder directly) which crashes when you click on that top text edit field.

System.NullReferenceException: Object reference not set to an instance of an object.
in WolvenKit.frmAssetBrowser.pathPanel_Click(Object sender, EventArgs e)
in System.Windows.Forms.Control.OnClick(EventArgs e)
in System.Windows.Forms.Control.WmMouseUp(Message& m, MouseButtons button, Int32 clicks)
in System.Windows.Forms.Control.WndProc(Message& m)
in System.Windows.Forms.NativeWindow.Callback(IntPtr hWnd, Int32 msg, IntPtr wparam, IntPtr lparam)

Nexusmods API

So I was thinking about implementing the basics of nexusmods since it wouldn't really be hard so you can upload your mod after you are done and would be nice for the mod manager too I guess. It should be discussed if its worth the time it takes to implement it.

Dark Mode

Introduce Dark Mode - interface

Lots of editing is done in shady environments.