Hero swap part 1: rig your model in Blender

Export the hero

Use the hero you picked in the overview. This guide uses Vyper, whose model sits at models/heroes_staging/viper/viper.vmdl_c. Other heroes are in Hero names and file paths.

You need the hero twice: as a model file for ModelDoc, and as a glTF for Blender.

1. Open Source 2 Viewer and open Deadlock/game/citadel/pak01_dir.vpk.
2. Go to models/heroes_staging/viper/.
3. Right-click viper.vmdl_c and choose Decompile & export.
4. Pick the model format (.vmdl). Save it into your addon at the same path: content/citadel_addons/<addon>/models/heroes_staging/viper/.
5. Export the glTF as Import a Deadlock model into Blender shows. Save it in a work folder outside your addon.

The decompile writes a .vmdl file plus DMX files for the hero's meshes. Part 2 opens that .vmdl.

Load the hero in Blender

1. Import and clean the glTF with the same Blender import guide. Follow route 1 up to and including Fix size and facing.
2. Check the result. The hero faces +X, has no animations and no $cloth bones, and the armature is in rest pose.
3. Scale the hero to Source 2 size. Select the armature and every mesh, press S, type 39.37, and press Enter.
4. Press Ctrl+A and choose All Transforms.
5. Save the .blend file.

The 39.37 scale turns meters into inches, the unit the Source 2 tools use. Do it once, here. Then you fit your character at the final size.

Doing the dry run? The overview suggests one full run with the unchanged hero first. Skip to Sort meshes into collections, export the hero's own meshes, and follow parts 2 to 4. Come back here once the plain hero works in game.

Fit your model to the hero

1. Import your character into the same Blender file.
2. Delete your character's own armature. Your mesh uses the hero's skeleton from now on.
3. Move and scale your mesh until it lines up with the hero's body: head, shoulders, elbows, hips, and knees.
4. Keep the overall height and width close to the hero's.
5. Select your mesh, press Ctrl+A, and choose All Transforms.

Never edit the hero's bones. Do not move, rename, or delete them. The game plays the hero's animations on those exact bones. You may add new bones for cloth chains, such as a tail or long hair.

Rig your mesh to the skeleton

1. Select your mesh, then Shift-click the hero's armature.
2. Press Ctrl+P and choose Armature Deform.
3. Copy the weights from the hero's body mesh to your mesh. Use Blender's Data Transfer modifier, or the Mesh Data Transfer add-on.
4. Switch to Pose Mode and rotate a few bones. Your mesh should follow them.
5. Fix the bad spots with weight painting. Strange bending in game almost always comes from weights.
6. Move the hero's original meshes into a separate collection. You do not export them.

Rigid parts, such as a helmet or an armor plate, should follow one bone only. In Edit Mode, select the part's vertices, pick that bone's vertex group, and click Assign. Weight small accessories to the nearest bone.

Limit weights to 4 per vertex

Keep each vertex at four bone weights or fewer. The exporter warns you when a vertex has more.

1. Select your mesh.
2. Switch to Weight Paint mode.
3. Choose WeightsLimit TotalWeights, then Limit Total. Check that the limit is 4.

Sort meshes into collections

The exporter writes one DMX file per collection. In ModelDoc, each DMX file becomes one mesh.

1. Make one collection for each mesh the original hero has. Vyper has a body and a gun, so make viper and gun.
2. Put your meshes into the matching collection.
3. Put the armature in the body collection.
4. Move everything else out of these collections: the hero's old meshes, reference objects, and lights.

Keep these names the same on every export. ModelDoc finds each DMX file by its name.

Check before you export

• Every mesh is parented to the armature and weighted to at least one bone.
• No name ends in .001. Check meshes, materials, and vertex groups.
• Every face has a material. Use short, plain material names. Part 2 matches them by name.
• All transforms are applied.
• The armature is in rest pose.
• The file has exactly one armature.
• No $cloth bones are left.

Export DMX

1. Open Scene Properties and find the Source Engine Export panel.
2. Set Export Format to DMX.
3. Set the DMX version to Binary 9 and the model format to Model 22, the ModelDoc format.
4. Set Export Path to a dmx folder inside the hero folder of your addon: content/citadel_addons/<addon>/models/heroes_staging/viper/dmx/.
5. In Source Engine Exportables, untick the animations. Leave only your mesh collections ticked.
6. Choose ExportScene ExportExport, then Scene Export.
7. Read the warnings. Fix missing materials and too many weights. Most other warnings are harmless.

The separate dmx folder keeps your files apart from the decompiled ones. Heroes use DMX, not FBX: DMX keeps the scale and supports cloth.