📑 The Guide

In some ways this guide is outdated - it’s a lot of work to keep it up to date, so check things out on the modding server as well.

Requirements

Required tools to modify models:

 - Reduced CSDK 10 (Community Tools for Deadlock) - models are complex and require manual setup in this. Here you choose meshes, setup materials, setup physics and such.

 - Source 2 Viewer - Allows you to browse and export specific files such as models from the Deadlock installed files and then repack them into mod packs.

 - Blender 4.2 - Editing Deadlock models and exporting them as .fbx/.dmx which can then be imported into the Deadlock tools.

 - Source Tools Addon forked for Blender 4.1+ - edited by Amon. It’s a modified version of Source Tools for newer Blender versions and supports cloth proxy data to be handled - it allows for advanced cloth simulation setup for Modeldoc. Works only up to 4.3, including it? Unknown.

(only install this if you’re planning to do proxy cloth stuff. Also this guide doesn’t cover its usage)
 - Source IO Addon for Blender 3.6+ - this addon will allow you to import .vmdl_c models from Deadlock into Blender, to get their armature, primarily.

Behavior of addons with Blender is weird right now - I’m not sure which versions are compatible and which work with Deadlock, so use your best judgement and probably don’t jump towards newest Blender releases at the moment.
Also, it’s likely that .gltf export from Source 2 Viewer works better at the moment, as Source IO only imports the armature and not the mesh.

Very Useful - Very Important

Google Drive folder with every single hero ready for editing in Blender and compiling within CSDK made by Hoxdolum.

Highly-highly recommended now, as it basically skips some of the annoying parts of this guide and has fully remade cloth physics. (Only works for some heroes that were not completely changed during 6 hero update)

Correctly exporting from Blender and preserving the cloth physics will require Source Tools Addon from Requirements, following this process by Hoxdolum.

Some Other Links/Info

If you’ve encountered a vertex remapping crash or ASSERT: error when compiling the model, please scroll down or follow the link in this text.

If you’re here to figure out material editing, scroll to the very bottom or follow the link in this text.

This separate guide by Artemon121 can help you fix old models with broken camera.

Glossary

CSDK, CSDK 10, Reduced CSDK 10, Deadlock Tools, Community Tools - all the same, it’s just the first thing you download in requirements. It’s the core element of the process and will provide tools to edit Source 2 stuff.

Project8Staging - old name of Deadlock Steam folder. It is interchangeable with it. If you see Project8Staging, it’s where your modern Deadlock is.

ModelDoc - tool, which is a part of CSDK. It is required to edit model files.
Material Editor - tool, which is a part of CSDK. It is required to edit materials.

Addon, mod - it is whatever you’re working on. Interchangeable terms.

.vmdl_c - compiled file of any model. Cannot be edited, only for use in an addon or in Blender for importing.
.vmdl - working file of any model. Can be opened with ModelDoc. Must not be used in addons or Blender.

.vmat_c - compiled file of any material. Cannot be edited, only for use in an addon.

.vmat - working file of any material. Can be opened with Material Editor. Must not be used in addons.

.vtex_c - compiled file of any texture/image. Cannot be edited, only for use in an addon.

Directories

After unpacking CSDK remove spaces from the path with it, should end up with something similar to this:

{your_filepath_with_no_spaces}\Reduced_CSDK_10\Reduced_Deadlock\...

We will work in the following directories. Most of them are the CSDK that we installed, but Steam version of Deadlock is also involved and can be located in Steam by right clicking Deadlock and choosing Manage > Browse Local Files. These are examples and they might be different for you:

• Reduced_Deadlock\content\citadel\ - Mod sources/inputs. You will only be working here with tools. This is where you put your working files like models so they can be used in the CSDK Tools.

Example with some modded content already added:

• Reduced_Deadlock\game\citadel\  - Mod results/output. Don’t touch this place until you have a compiled model. After using CSDK Tools your compiled model file appears here (respecting the sub-folder it was in) with extension .vmdl_c. Materials and textures appear as .vmat_c and .vtex_c.
  You will be making the mod out of files from here.
  

• {some_working_directory}\models\heroes_staging\astro\ - Make some directory anywhere to work in. Example directory structure for making a Holliday replacement. Don't put any other files or folders in {some_working_directory} otherwise it will try and include them when you pack the compiled files using the Source 2 Viewer.

• SteamLibrary\steamapps\common\Deadlock\game\citadel\addons\ - Once you have made your mod pack .vpk, it goes in here so that Deadlock can use it.

Initial Setup

Add required data into CSDK

Setup some custom data that the tools will need for Deadlock specific stuff

Navigate to: Reduced_Deadlock\game\core\ and create a text file. Rename it to models_gamedata.fgd

Open it in a plain text editor. Add these fields to the file:

Enable mods for Deadlock

Enable mod loading for your Steam version of Deadlock (not CSDK) by editing gameinfo.gi in \game\citadel\ in a text editor:

Shortcut for CSDK 10

In order to easily start the tools, create a shortcut of \Reduced_Deadlock\game\bin\win64\Project 8 with tools.bat and put it on Desktop. Launching this .bat is how you will be launching the Source 2 tools.

Shortcut for Steam Deadlock

In order to keep working on materials and models while also testing your mod in the Steam version of Deadlock, create a shortcut of \Deadlock\game\bin\win64\project8.exe and put it on Desktop. You have to do it because Steam will recognize CSDK as Deadlock already being open and prevent you from launching up-to-date version.

Brief Overview

This is just a quick and rough overview of the process. Don’t use this directly for your workflow.

• Export copy of .vmdl_c model from Source 2 Viewer
• Setup a folder in CSDK \Reduced_Deadlock\content\citadel\
• Decompile and export .vmdl model from Source 2 Viewer into that folder
• Open that .vmdl in CSDK ModelDoc and re-name it something new. Delete original .vmdl
• Add and fix a dozen ModelDoc nodes and other random things
• Edit the mesh in Blender
• Export as .fbx
• Import .fbx as mesh in CSDK ModelDoc
• Compile to a .vmdl_c which then appears in \game\citadel\...
• Pack the .vmdl_c and _backup.vmdl_c in Source 2 Viewer to make a mod .vpk
• Put packed addon .vpk (overwriting) into your Steam Deadlock in \Deadlock\game\citadel\addons\ directory
• Launch Deadlock and test.
• Iterate if failed, done if succeeded.

Remapping Vertex Error Fix

Let’s say you did the standard process for importing models, tried to compile and it errors out.

To fix it, disable the mesh files of the hero - don’t delete them yet though.

You will keep them for name reference and for size and orientation reference.

ASSERT: CModelDoc... Error Fix

In order to fix this error, you need to open a new Model document in ModelDoc.

Now you have two ModelDoc active at the same time.

After that, copy all the nodes from the outliner of the model with the error and paste them into the outliner of the new model. It should be basically an exact copy.

Also, very importantly, transfer the Graph path.

Save that new model with some unique name afterwards.

Don’t re-enable the mesh, but try to recompile, it should work.

It probably works, but in Yamato’s case skeleton is facing the wrong way, let’s rotate it. Check if this is an issue for your model, might not.

Select pelvis bone and change third angle to -90, probably. It should fix it - this might be different in your model’s case.

That’s pretty much it, you can add your own custom meshes now. Delete the model file that was broken and keep working in the new one.

Keep the mesh files disabled too.

Double check that Graph file is linked.

Detailed Overview

Preparing Copies

First we need to get a few files from Source 2 Viewer.

Inside of Source 2 Viewer, find the hero model you want to edit and Export as is, export 2 copies.

One to import into Blender and another renamed {hero_name}_backup.vmdl_c. Later, we will automatically reference data in this, such as animations, so we don’t have to set them up ourselves. This second copy will be included later when packing the addon.

Creating Folders

You’ve seen the folder structure in which your hero lies in, so go into \Reduced_Deadlock\content\citadel\ and create a copy of the file structure by adding new folders, your editable model file will be there later.
For example this for Holliday \Reduced_Deadlock\content\citadel\models\heroes_staging\astro\ everything past \citadel\ is created by you. Don’t put .vmdl_c files in here.

Exporting editable .vmdl

Using Source 2 Viewer, use Decompile and Export on that same model and export it to that path you have just created in CSDK.

Opening model in CSDK

Remember that we created a shortcut for CSDK - launch it now. You will see Asset Browser, from there you can search for your model and open .vmdl file or launch ModelDoc separately.

After that you MUST re-save the file with a new name. For example astro1.vmdl. It’s a required step because it magically keeps the model’s skeleton from exploding in the final addon.

Setup nodes in ModelDoc

Now that you’re working in a renamed copy, before you move to Blender to edit the mesh, let’s do some initial setup in ModelDoc.

• Delete AnimationList node

Model might not compile with it being present and we’ll put animations in with a different method.

• Delete PhysicsShapeList node

We will need it, but this one is broken, so delete it for now, we’ll remake it later.

• Modify Skeleton node

See if your model’s skeleton is slightly rotated, like in the picture below.

If it is, then select Pelvis bone

And modify weird angle

To be like this

Skeleton should now be fixed.

• Adding GenericGameData

Right click the node called GameDataList and press Add GenericGameData…


Add both of the entries from the list that has opened.

• Filling CCitadelHeroModelGameData_t

This tiny thing is responsible for making your character animate properly on selection and in the shop and a few other things.
Some fields are auto-filled, some are empty. Fill the first two, ignore the rest.

To fill them correctly, you can view the model’s folder in Source 2 Viewer.

Don’t export these files! We will just reference a path to them.

Copy their path with the highlighted button and fill them in.

REMOVE _C FROM THE END OF THE PATH, IT IS IMPORTANT

• Filling camera_settings

This tiny thing is responsible for controlling the in-game position of the camera for each character. Mess this up and it will be too low, too far, somewhere in the ground or on the other side. Please be careful with this.

To fill it correctly, open original hero model in Source 2 Viewer and navigate to DATA field, then scroll down a bit to find camera_settings:

Copy values 1-to-1:

• Filling Unit Status Settings
  
  Can copy the values from DATA field in the model like above. It fixes status effects and HP bar being offset for your character.

• Adding DefaultMaterialGroup

This node will be responsible for having materials on your model at all.

They need to reference files in the directory path as it appears in the game files, which you can view using source 2 viewer - chances are you don't even need to change anything. That is, unless you will have custom materials. But we’ll talk about it later.

Please notice how materials linked here don’t have _c on the end. It’s important, just like with CCitadelHeroModelGameData_t

• Adding AnimIncludeModel

This node will take animations from another model and assigns them to this one.

Remember that we made two copies of hero’s .vmdl_c and one was named _backup.vmdl_c - it will be used here.

You can copy the path from the original model again:

After you paste it in, add _backup to the hero name and remove _c from the end. It’s important.

In the final addon, the backup model will be sitting in that filepath.

Compile the model. It will likely fail with this error:

Refer back to the earlier section to fix this so that we can successfully compile the model. Fix includes disabling these mesh files, but not deleting them just yet.

Doing Blender edits

Initial Blender setup

By this point you should already have Blender and the addon for it installed, if not, do it now.

Import the model’s .vmdl_c file you exported in the beginning.
I expect you to have these settings during import

Successfully imported, she’s beautiful (and any other character of your choice, of course)

Before you do anything else, let’s do something. Export this as .fbx right now as a test.

Export the model to the same place your .vmdl is in. ModelDoc won’t accept files from your Desktop or other drives, etc.

Suggested Export Settings

These settings should be correct for the export. You can save it as a preset using Operator Presets at the top once you have set them up

Quickly return to ModelDoc and import this .fbx

Oops, your character is probably too big and facing the wrong way.

Let’s fix it in Blender and proceed.

Fixing Blender model size

Here’s a size cheat sheet

• Your model is gigantic - scale it down to 0.0254
• Your model is bigger - scale it down to 0.3937 (case on screenshot)
• Your model is smaller - scale it up to 2.540
• Your model is microscopic (almost invisible) - scale it up to 39.37

In the screenshot, it’s the 0.3937 case. You need to scale the armature (not meshes) by that amount.
(Blender rounds up decimals on preview)

It was also facing the wrong way, so let’s turn the character around.

Repeat the .fbx export after that. If you did everything right, characters will PERFECTLY overlap in ModelDoc. It’s gorgeous.

You can now also delete original meshes from the model and only keep your edit. You can also rename it in ModelDoc.

Having separate meshes

Some characters have parts of the model that are only sometimes visible, and these require the meshes to be in separate files - not as a single .fbx (most notably, Bebop requires it to look even remotely right). You’ll have to export those elements from Blender as separate .fbx files.

As an example, we can separate the gun and the body for Holliday, as it was initially:

This will only export the gun (note that the armature should also be selected)

This will only export the body with the barrel (note that the armature should also be selected)

Add them both in ModelDoc. Beautiful.

You are now free to start doing whatever edits you want to the model. This guide will not help you figure out Blender rigging, weight painting and such.

However, please note that you shouldn’t be messing with the original armature at all. Don’t touch the bones at all.
You can, however, add new bones for cloth physics or jiggle bones.

Here are some silly edits I made. Model should also compile with no hesitation now.

Last ModelDoc nodes

Reassigning materials

Oh no! Chances are, that after you replaced the mesh, materials in DefaultMaterialGroup got reset and lost folders from the path.

To fix it, go into Source 2 Viewer and copy the path of those materials of the hero and paste them into the fields

One of them is not here, where do I look? Open the character model and go to External Refs. There’s the material I couldn’t find!

(If you click on the Name and see it highlighted blue, you can press Ctrl+C to copy the path)

Ah, material paths are back. Please note how there is no _c at the end. It’s intended and very important.

Setting up ragdoll

First of all, compile your model right now. It’s required before setting up a ragdoll, for some reason. Compilation should have no errors if you did every step before this one.

Add Create Biped Ragdoll node in ModelDoc.

You will be greeted with an automatically filled menu. And capsules will appear over your model. I advise you to play around with the sliders a little bit. Definitely decrease the Scale Factor a little bit, from what I’ve seen.

Then - after you’re done tweaking sliders, just press Create Ragdoll.
(Keep checkmark on the setting above it)

Recompile the model after that. If you want to preview how the ragdoll looks, select any node except RenderMeshList and click on these boxes. It will run a simulation of your radgoll. Press again and the model will return it to its default state.

Generated ragdoll might be a bit weird, but if it doesn't completely explode, it’s good enough.


Again, the model should be compiled now.

Packing mod for Deadlock

There are some quirks with this process. It’s all very important though.

Remember how we were working in \models\heroes_staging\astro\... this whole time? It’s because this is how the final structure will be for Deadlock mod. It’s useful to keep it this way if you’ll have new materials later and just in general.

This was mentioned in Creating Folders step, but if you didn’t do it, do it now.

You can create a new folder for your mod in Steam Deadlock addons folder or anywhere else on your computer. Let’s say, you did it elsewhere.

You will recreate the folder structure again inside this new one.

In the hero’s folder, you drop your _backup.vmdl_c (from the Preparing Copies step) and in your CSDK Asset Browser you locate your edited model, right click and Open Folder of .vmdl_c

There’s the file we need. Grab it and drop it into that folder we created recently.

We end up with these two files.

Rename your hero file to its original name. In this case it will be astro1.vmdl_c -> astro.vmdl_c

Open Source 2 Viewer if you closed it. Click on File and Create VPK from folder. You will be met with an empty VPK template.

Right click new.vpk and Add existing folder

Select the root folder of your entire mod (folder called models should be inside the one you’re selecting)

(If you had a popup window after selecting a folder, click either Yes or No, it currently doesn’t do anything)

This will be your final file structure, if it’s not like this, please repeat the process until you make it this way.

(astro.vmdl_c file being duplicated is intentional display of the program, don’t touch it)

Now right click new.vpk and Save VPK to disk. You will be saving it to \Deadlock\game\citadel\addons\ named as pak01_dir.vpk - up to pak99_dir.vpk if you already have mods installed with a conflicting name.

When iterating on your mod, just save over the same name, overwriting the old file in the process.

Testing in Deadlock

Now that the mod is in the files and you have enabled mods for Deadlock in Initial Setup, launch the Steam version of Deadlock (use shortcut that we made if your CSDK is still open).

Ah, there she is, modded and beautiful.
This is the finale of the modding process to replace the mesh of the character, you’ve succeeded if you’ve followed it precisely and the model is changed in game.

Chances are that you’re seeing the character animate at a seemingly lower framerate or jitter slightly when looking around. It’s, unfortunately, expected. I can’t provide a solution to it in this guide as of now, it might even be a sacrifice that has to be made in order to make this work at all.

It is unknown.

Creating Custom Materials

Changing mesh is only part of the fun, let’s change or add the materials as well.

Adding a mesh and a material in Blender

Of course you need that material to be UV mapped and assigned on your model in Blender, I’ll quickly demonstrate it. You 3D artists know what you’re doing with this step more or less.

Select mesh first then Armature while holding Ctrl and then press Ctrl+P and assign With Automatic Weights 

It’s now parented to the original armature.

Create a new material and assign it to that object. Do UV mapping, etc. then re-export as a separate .fbx or as a part of some existing .fbx of the character.

Tools will recognize that .fbx was updated automatically. Now in ModelDoc inside of your model’s DefaultMaterialGroup node a new material has appeared!

Material Setup

Images that will be used for materials have to have dimensions power of 2 (256, 512, 1024, etc.)

To start, open Material Editor from Asset Browser. Either of the two highlights will launch it.

Create a new material. Instantly press Ctrl+S to save it.

Save it to the same spot your .vmdl is in. Create a folder called \materials\.

If you’re NOT replacing existing hero material and making a new one, name it something unique.

If you ARE replacing existing hero material, copy its file structure and name.

Click on Shaders… button and untick Show Preferred Shaders.

Select Pbr shader and accept.

Scroll down in the new menu and tick Use Npr Lighting, Self Illum and Use Status Effects Proxy. NPR enables cel shading for models, Self Illum allows them to glow a little (some Deadlock characters do), Use Status Effects Proxy supposedly fixes invisibility for new materials.

You scrolled past some other settings that you might find useful for your specific material:

If your material is intended to be translucent - like Viscous - check Translucent.

If your material is intended to have completely see-through parts - hair, 2D eyes, cloth with holes, etc. then check Alpha Test.

Just for this example I will tick Alpha Test.

This whole time material was a checkerboard error pattern, it’s because we didn’t assign any textures.

To assign them, you have to drop them in the same folder as the .vmat.

Include all of the textures you need, be it albedo, normal, roughness, translucency, metalness, etc.

Now, you can actually start assigning textures. Import them with either of the two buttons.

It will not accept textures from anywhere except \content\ folder of CSDK

I don’t have a Tint Mask so I press Change To Slider underneath the path field - same can be done with any other texture.

Fill all the texture slots that are highlighted red for you - for me most are turned into slider or color, because I don’t have a fitting texture.

If you have the corresponding texture, assign it instead of creating a default.

Okay, I’ve assigned everything and the material finally displays - I also checked Render Backfaces since I want it to be like a floating 2D texture.

This material now exists and works. Let’s assign it in ModelDoc for our model. Open DefaultMaterialGroup and assign it to the material slot.

After you recompile the model, it will be displayed. It is displayed because it actually exists in files, while the rest of the model is a red wireframe and expects Steam Deadlock materials - all of it is intended.

Packing Mod with Material

Repeat steps from Packing mod for Deadlock, use new recompiled .vmdl_c that features new material reference.

Before packing the addon again, include this material in it. Open Folder of its .vmat_c

Copy all of the files into your working directory for addon packing. You must copy the structure they were in, as usual. I had to create \materials\ folder in here.

Replace hero .vmdl_c with the newly recompiled one like in step Packing mod for Deadlock.

Repack that as an addon. Look how we have the new material here! All correct. Do all the usual mod file stuff from the previous steps and launch the game.

She’s here.

You’re done! Good job.

FAQ - Frequently Asked Questions

• My model in-game is a red glowing wireframe! Materials are gone!

You’ve made a mistake in DefaultMaterialGroup node.
Either file ends with _c, or it doesn’t have the full path, or the path is incorrect. The path should usually start with \models\ and very rarely maybe \materials\. Never include system folders in there or _c at the end.

• My model is looking at the ground in menu and in the shop!
  
  You’ve made a mistake in CCitadelHeroModelGameData_t node.

You should fill two empty fields for UI Animation and UI Shop Animation. Either file ends with _c, or it doesn’t have the full path, or the path is incorrect. Usually it’s the same path as the hero itself. Never include system folders in there or _c at the end.

• My model is T-posing, doesn’t rotate and moves very slowly!
  
  You’ve made a mistake in AnimIncludeModel node OR didn’t put a _backup.vmdl_c model in your addon.

Either file ends with _c, or it doesn’t have the full path, or the path is incorrect. Usually it’s the same path as the hero itself. Never include system folders in there or _c at the end.
If that is correct, please check your addon again and see if _backup.vmdl_c is there.
Maybe it is there, but has .vmdl extension instead of .vmdl_c. If that’s the case, update that file according to the guide.
Another issue is that you might be missing Graph path to hero’s .vanmgrph file.

• My model was fine, but after an update, animations are broken!
  
  Hero’s _backup.vmdl_c must be updated inside the addon. To do it, simply export hero .vmdl_c from the up-to-date version of Deadlock, replace the _backup.vmdl_c with this new one and repack the addon. You can do this to skins that other people made as well, if they got broken.

Information on custom sounds and icons to be added… Possibly…