Skip to main content
The Model Editor — also known as ModelDoc — is the tool for creating and editing model files (.vmdl). It is the modern equivalent of Source 1’s .QC text-based model compilation pipeline. Open it from the Tools menu in the editor. Instead of text commands, ModelDoc uses a node-based system. Nodes can be nested inside one another and are automatically organized into categories.

​
Nodes

All nodes are organized into categories visible in the Model Editor’s left panel. Click Show empty categories to display all available categories. Right-click a category to see the nodes that belong to it. Most nodes automatically sort themselves into a category and will not work if placed outside it.

​
Opening example models

s&box ships with model source files you can inspect and learn from. For example, the Citizen character model is at: 
sbox\addons\citizen\Assets\models\citizen\citizen.vmdl
Open this file in ModelDoc to explore its node structure. First-person weapon models often include source files as well, since their authors have opted to share them.

​
Supported formats

ModelDoc can import:
  • Valve formats: DMX (version 22), SMD (deprecated but still functional)
  • Standard 3D formats: FBX, OBJ, VOX
The following are not supported:
  • Source 1 and GoldSrc MDL files (support was removed)
  • Meshes with more than 4 bone weight influences per vertex (weights are automatically culled and normalized)

​
Best practices

  • Always include at least one animation sequence on non-static models. A simple AnimBindPose node is enough. Without it, morph targets may not work and IK data may be lost.
  • Do not create bones directly in ModelDoc unless absolutely necessary. Use your 3D software to define bones in the source file. Only use ModelDoc-created bones as a last resort for simple rigid props that need exactly one attachment.
  • Export FBX files as binary, not ASCII. Binary FBX is compatible with more tools, including Blender.
  • Watch your addon download size. Compress textures and files appropriately before publishing.
  • Name materials clearly. If a material name contains a period, everything after it is omitted during import. Multiple materials with the same effective name collapse into one (a common issue with Blender’s default .001, .002 suffixes).

​
Frequently asked questions

Use Add Simple Animations. Access it by clicking the star icon next to Add, or by right-clicking AnimationList in the node tree.
You need a character model with its own animgraph that responds correctly to the Animation Controller inputs. This involves the full model creation pipeline: modelling, rigging, animating, and building the animgraph.Alternatively, you can extend the existing Citizen character using the Base Model feature, or fork the Citizen VMDL by referencing its prefabs.
The recommended approach is to not decompile. If you want to modify someone else’s model, ask them for the source files first.If you must extract something, open the VMDL in ModelDoc and use Export As… to export meshes as FBX or OBJ. For animations, try Valve Resource Format, though the results may need cleanup.
Modify position and rotation in your 3D modelling software when possible. For scale, use the ScaleAndMirror node.If your mesh is fully static (not skinned to any bones), you can change its position, orientation, and scale directly in the RenderMeshFile node.
For animated models, use the ScaleAndMirror global modifier node for scaling. Scaling a mesh without scaling its animations will break them.
By default, bones that do not influence any geometry are discarded. Prevent this in one of two ways:
  1. Add a BoneMarkup node for the bone and enable Do Not Discard.
  2. Set Bone Cull Type to Leaf Only or None on the root BoneMarkupList container.
Check the compiled hierarchy in the Compiled Preview Outliner → Skeleton panel to see what was discarded.
  • Make sure the material used by your mesh has morph enabled in its material properties.
  • Morph target names must not contain underscores. In the DMX specification, underscores are reserved for corrective shapes. See the Valve Developer Community wiki on flex animation for details.

​
What is Base Model?

Base Model is similar to Source 1’s $includemodel, but it works in reverse. In Source 1, the main model would reference animation-only models. In s&box, your new VMDL references the existing model as its Base Model. For example, to extend the Citizen character with new animations, your new VMDL (citizen_my_custom_version.vmdl) references citizen.vmdl as its Base Model.
When using Base Model, your new VMDL should contain only new animations and nothing else.