Source Filmmaker (SFM) remains a staple for 3D animators working within the Valve ecosystem, yet its reliance on the aging Source Engine creates a significant barrier to entry for custom model imports. Unlike modern engines that accept .FBX or .OBJ files directly, SFM requires a multi-stage compilation process that converts raw geometry into a series of proprietary binary files (.mdl, .vvd, .vtx). This guide outlines the technical pipeline for transforming a 3D mesh into a functional SFM asset using the industry-standard Crowbar compiler and Blender Source Tools.
Preparing Your Source Assets in Blender
The compilation process begins with the export of Reference and Physics meshes. Before exporting, ensure your model is scaled correctly for the Source Engine. A standard human character in SFM is roughly 72 units tall. If your model is exported at a standard metric scale from Blender, it will often appear microscopic in the SFM viewport.
Best for: Ensuring geometric integrity and bone-weight accuracy before the engine sees the data.
To prepare the mesh, you must install the Blender Source Tools addon. This tool handles the conversion of Blender’s internal data into the .SMD (Studio Model Data) or .DMX (Digital Model Exchange) formats. While .SMD is the legacy standard, .DMX is preferred for modern SFM workflows because it supports complex flex controllers (shape keys) and more robust bone weighting. Ensure all transforms are frozen (Ctrl+A in Blender) and that the model has a single "Root" bone at the origin (0,0,0) to prevent animation drifting.
Exporting SMD and DMX Files
- The Reference Mesh: This contains the actual geometry and vertex weights. Export this as
model_ref.smd. - The Physics Mesh: A simplified, convex hull version of your model used for collision detection. Export this as
model_phys.smd. If the model is purely for cinematic use and won't interact with physics, this can be omitted, though a basic box hull is recommended for selection visibility. - Animations/Idle: Source requires at least one sequence to compile. Export a simple 1-frame "idle" animation.
Structuring the QC File for Successful Compiles
The .QC file is a plain-text script that acts as the blueprint for the compiler. It tells the Studiomdl.exe (the engine's compiler) where to find the meshes, which textures to apply, and how the skeleton should behave. A single syntax error in this file will cause the entire compile to fail.
Pro Tip: Always use relative paths in your QC file. The
$modelnamecommand should point to a path relative to the "models" folder of your SFM directory, not your Windows desktop. For example:$modelname "props_custom/my_model.mdl".
Essential QC Commands and Syntax
A functional QC file must contain several mandatory blocks. The $cdmaterials command is particularly critical; it defines the folder path within the materials directory where SFM will look for your .VMT files. If this path is incorrect, your model will appear with the infamous purple and black checkerboard "missing texture" pattern.
Example of a standard QC structure:
$modelname "your_folder/your_asset.mdl"
$body "body" "mesh_reference.smd"
$cdmaterials "models/your_folder/"
$sequence "idle" "idle_anim.smd" fps 1
$collisionmodel "mesh_physics.smd" { $concave }
The $concave flag in the collision block is vital. Without it, the engine will wrap a single shrink-wrap "hull" around your entire object, filling in gaps (like the space between a character's legs) and making it impossible for other objects to pass through those spaces.
Using Crowbar to Generate the MDL
Crowbar is the essential graphical interface for the Source SDK's command-line tools. It automates the hand-off between your QC file and the studiomdl.exe compiler. To set it up, navigate to the "Set Up Games" tab and point the executable path to the studiomdl.exe found in your SFM game/bin folder.
When you are ready to compile, switch to the "Compile" tab. Select your QC file and ensure the "Output to" setting is directed to the "Game's models folder." This ensures that the resulting .mdl, .vvd, and .vtx files are placed directly into the SFM file structure where the engine can see them immediately without a manual move. If the compile log shows "Completed" without errors, your model is technically in the game, but it still requires material definitions to be visible.
Material Configuration and Folder Hierarchy
Compiling the model geometry is only half the battle. Source models do not "embed" textures. Instead, the .MDL file looks for a .VMT (Valve Material Type) file, which in turn points to a .VTF (Valve Texture Format) file. This two-step system allows for real-time adjustments to material properties like glossiness, transparency, and self-illumination without re-compiling the entire model.
The folder structure must be exact. If your QC file used $cdmaterials "models/custom_assets/", your .VMT and .VTF files must reside in game/usermod/materials/models/custom_assets/. The .VMT file is a text document that defines the shader. For most SFM models, you will use the VertexLitGeneric shader, which supports dynamic lighting and shadows.
Troubleshooting Common Compile Errors
Even experienced technical artists encounter compile failures. The most common error is "Too many bones used in model," which occurs if your rig exceeds the 128-bone limit of the older Source branches. If you hit this limit, you must either simplify the rig or split the model into multiple body groups that are compiled separately and toggled within SFM.
Another frequent issue is the "Mismatched Parentheses" error in the QC file. This usually happens in the $collisionmodel or $eyeball blocks. Source is extremely sensitive to syntax; a missing closing bracket or a space in a file name that isn't wrapped in quotation marks will terminate the process. Always wrap file paths in double quotes to avoid issues with folder names containing spaces.
Moving Models into the SFM Workflow
Once the compile is successful and the materials are in place, open SFM and create a new session. Open the "Model Browser" and filter by "Mod" to find your specific folder (e.g., usermod). If the model appears but is invisible, check your .VMT file for a $translucent 1 tag that might be misbehaving, or verify that the $basetexture path points to a valid .VTF file. If the model is visible but static, verify that your $sequence in the QC file was correctly mapped to an exported animation file. From here, you can begin rigging with standard IK scripts or manual bone manipulation.
Frequently Asked Questions
Why is my model covered in purple and black squares?
This indicates a material path error. The model found the .VMT file, but the .VMT file cannot find the .VTF texture, or the model is looking in the wrong directory entirely. Check the $cdmaterials line in your QC and the $basetexture line in your .VMT.
What is the maximum vertex count for an SFM model?
SFM generally handles models up to 10,000–15,000 vertices per mesh fairly well, but the engine limit is technically around 65,535 vertices per sub-mesh. If your model is high-poly, you should split it into multiple $body parts within the QC file to avoid vertex buffer overflows.
Can I import models with PBR textures into SFM?
Source 1 does not natively support Physically Based Rendering (PBR). You must convert your PBR maps (Metallic, Roughness) into the Source-friendly Specular/Exponent workflow. Use the $phong commands in your .VMT to simulate metallic and glossy surfaces.
How do I fix "Error: Model has no sequences"?
Source requires at least one animation to compile. Add $sequence "idle" "yourmesh.smd" to your QC file. This tells the compiler to use the base mesh as a static, one-frame animation, satisfying the engine's requirement.
