SFM Compile Explained: Turning Raw Models Into Files Source Filmmaker Can Use

Short answer

• SFM compile is the step that turns a finished 3D model into files that Source Filmmaker can actually open. Source Filmmaker, often shortened to SFM, is the movie making tool Valve built and used inside the Source game engine. Because SFM uses the same assets as the game, it loads models in the Source engine compiled model format, not as a raw scene file from a modeling program and not as a generic export such as OBJ or FBX. Compiling takes three ingredients. First, source files, usually SMD or DMX exports that carry the mesh, skeleton, and animation data. Second, a QC file, a plain text script that tells the compiler the model name, the material folders, the body parts, the sequences, and the collision model. Third, the compiler itself, StudioMDL, Valve command line model compiler. Most beginners run StudioMDL through Crowbar, a free graphical tool that lets you pick the game, load the QC file, and read the log without typing commands. A successful compile produces a small set of linked files, led by the MDL model file, with vertex data, optimized mesh data, and, where a collision model is included, physics data beside it. Textures travel on a parallel track: images are converted to VTF texture files, and small VMT material files point to those textures. If any link in that chain breaks, the model may not appear at all, or it may appear covered in a purple and black checkerboard, the Source engine signal for a material it cannot find. Searches written as sf.compile or smf compile point to the same process. The first is a punctuation variant and the second is a simple letter swap. Both are best read as SFM compile, short for Source Filmmaker compile.

By Emma Hudson

A model can look finished in Blender or Maya and still be invisible in Source Filmmaker. The missing step is usually the compile. This article explains that step in plain terms: what it converts, which files it produces, how the QC script controls it, how to run it with Crowbar or StudioMDL, and how to read the errors that stop most first attempts.

Why Source Filmmaker Needs Compiled Models

Source Filmmaker runs on a version of the Source engine. Valve describes SFM on its Steam page as the movie making tool built and used at Valve to make movies inside the Source game engine, using the same assets as the game itself. That shared asset system is the reason compiling exists. The engine was built to load models that have already been converted into its own binary format, with geometry, bones, material references, and animation sequences organized the way the engine expects.

A modeling program keeps a working scene: editable meshes, modifiers, constraints, and preview materials. An OBJ or FBX export is a general exchange file, useful for moving a model between programs, but it is not the format SFM loads in a session. Compiling is therefore not an optional polish step. It is the bridge between your modeling software and the Source engine, and it also checks the work as it goes, reporting missing files, bad paths, and commands the compiler does not recognize.

That translation step is a normal part of how software works: a program can only open formats it was built to read, and everything else has to be converted first. Readers who make 3D models for other purposes, such as the projects in our guide to cool things to 3D print, meet the same rule in a different form, because a printer, like SFM, needs its own prepared file rather than the editable scene.

What a Compile Produces: The Output Files

A successful compile normally produces a set of linked files that must stay together, in the same folder, under the same base name.

• MDL is the main compiled model file. It holds the model structure, bone hierarchy, material references, sequences, and other header information the engine needs to load the model.
• VVD holds the vertex data for the model, including the per vertex information used to draw and skin the mesh.
• VTX holds optimized mesh data for graphics hardware. A compile can produce more than one VTX variant for different rendering paths, which is why a finished model folder can look busier than a beginner expects.
• PHY holds physics collision data. It is produced only where the QC file includes a collision model, so a simple character or a decorative prop compiled without one will not have this file, and that absence is not by itself an error.

Crowbar documentation makes the same point from the other direction: decompiling means converting the MDL, PHY, VTX, and VVD binary files back into QC and SMD text files that can be edited. If one of the linked output files is missing, moved, or renamed, the model may fail to load or behave strangely in a scene, even though the MDL file itself is present. When you copy a finished model to another computer or share it, copy the whole set, not just the MDL.

The Three Ingredients of a Compile

1. Source files: SMD or DMX exports

These are the exports from your modeling software, containing the mesh, the skeleton, and any animation data. SMD is the older text based format, generated by an SMD export plug-in for a given model editor package. DMX is the newer Source model format that has superseded SMD in much Source work. Either way, the principle is the same: one export carries the reference mesh, which is the model in its rest pose with its bones, and separate exports can carry individual animation sequences and a simpler collision mesh.

Check the export before you compile. Bone names should be consistent between the reference mesh and the animations, the scale should be sensible for a Source scene, and the model should face a consistent direction. A model that is far too large or far too small will look wrong in SFM even if the compile succeeds, because the compiler faithfully converts what it is given.

2. The QC file: the instruction script

The QC file is a text script that tells the compiler what to build. The next section covers its commands in detail. For now, the key idea is that the QC file, not the modeling program, decides the final model name and folder, where the engine will look for materials, which mesh becomes the body, which animations become named sequences, and whether the model gets collision.

3. The compiler: StudioMDL, usually through Crowbar

StudioMDL is Valve command line compiler, normally provided with each game, in the bin folder of that game installation. Crowbar does not do the actual compiling itself. As the Crowbar guide puts it, Crowbar compiles models through a graphical interface to studiomdl.exe, and it calls the game StudioMDL tool to do the work. That distinction matters, because different games compile different MDL versions. Using the StudioMDL that belongs to your SFM installation matters for the same reason: a compiler from another Source title can produce files that look fine but misbehave inside SFM.

Textures Run on a Parallel Track: VTF and VMT Files

A model compile alone does not finish the materials. Textures follow their own short pipeline, and most visible compile problems are actually material problems.

An image is first converted to a VTF file, Valve Texture Format, which holds the actual texture image data. Texture dimensions need to be powers of two, such as 256, 512, or 1024 pixels on a side. A VMT file, Valve Material Type, is then a small text file that defines the material: it names a shader and points to the VTF. For models, the shader is generally VertexLitGeneric, and the line that points to the texture is $basetexture, written as a path relative to the materials folder, without the .vtf extension.

The chain the engine follows is worth memorizing, because troubleshooting is just checking it link by link. Each triangle in the SMD file carries a material name, which is the VMT file name without its extension. The QC file lists the folders where those VMT files can be found, through its $cdmaterials lines. Each VMT then points, through $basetexture, to its VTF. If the model finds the VMT but the VMT cannot find the VTF, the texture still fails. If the VMT is in a folder that $cdmaterials does not list, the texture also fails. Both failures look the same on screen: the purple and black, or pink and black, checkerboard.

The QC File in Detail

A QC file is a plain text file, saved with a .qc extension and usually kept beside the SMD files it references. Every command starts with a dollar sign. Paths and file names that contain spaces need quotation marks, and only straight quotation marks should be used, because curly quotation marks copied from a word processor will break the parser. A QC file works much like a small program: it is a set of written instructions carried out in order, which is why readers who have read our explainer on how do you program will find the habit familiar. Change one instruction, run it again, and read the result.

The commands a first SFM compile usually needs are these:

• $modelname sets the final model name and its path under the models folder, for example $modelname “mycharacter/mycharacter.mdl”. This line decides where the compiled files belong and what the model will be called in SFM.
• $cdmaterials defines the folders in which the game will search for the model materials. Each path is relative to the game materials folder, and subfolders are not searched, so every folder that holds a VMT for the model needs its own listing. By default, a model can have no more than 32 different material search paths.
• $body names the reference mesh, for example $body “Body” “body.smd”. The material file names the model will look for are defined by this reference mesh, so the names baked into the export and the VMT file names on disk must match.
• $sequence turns an animation export into a named sequence SFM can play, for example $sequence “idle” “idle.smd” fps 30. Every model needs at least one sequence, even a model with no real animation, which is why a simple idle sequence appears in almost every QC file.
• $collisionmodel names the simpler collision mesh and adds physics data, with options inside its block for properties such as mass. The collision mesh should share the model origin, or the physical shape will sit offset from the visible model.
• $surfaceprop sets the surface type the engine should assume for the model, which affects sounds and impact effects.
• $staticprop marks a model as a static prop, with no moving parts. Use it for scenery objects, not for characters or anything that needs to bend or animate.
• $scale multiplies the model size at compile time. It is a fix for a consistently wrong export scale, not a substitute for exporting at the right size.

A minimal QC file for a simple animated model, using those commands, looks like this:

$modelname "mycharacter/mycharacter.mdl"
$body "Body" "body.smd"
$cdmaterials "models/mycharacter/"
$surfaceprop "flesh"
$sequence "idle" "idle.smd" fps 30
$collisionmodel "body_phys.smd" {
    $mass 10
}

Keep the QC file simple on a first attempt, and add complexity only after a basic compile works. Save one working QC file as your template for the next model, and change only the names and paths. When a line fails, fix that line first and leave everything else untouched, so you always know which change made the difference.

A Practical Compile Workflow, Step by Step

Step 1: Set up clean folders. Keep source files, QC files, textures, and materials in clearly named folders, and avoid spaces in paths where the tools are known to struggle. Decide the model final folder under models and its matching folder under materials before you compile, because the QC file, the $cdmaterials line, and the finished files all have to agree on those names.

Step 2: Prepare and export the model. Finish the mesh and skeleton in your modeling program, then export the reference mesh as SMD or DMX, plus one export per animation and one for the collision mesh if you need one. Check the skeleton, bone names, and scale before you compile, and make sure every part of the collision mesh has a material assigned and shares the main model origin.

Step 3: Convert the textures. Convert each texture image to VTF, at a power of two size, and write or generate a matching VMT for it, with the model shader and a $basetexture path that matches the real VTF location relative to materials. Put the VTF and VMT files together in the material folder the QC file will name.

Step 4: Write the QC file. Include the model name, the material folder, the body mesh, an idle sequence and any other animations you need, and a collision model if the model should interact physically. Read the file once as a checklist: does every file name in it exist, spelled exactly that way, in the folder the compiler will search?

Step 5: Compile with Crowbar. Open Crowbar, go to the Set Up Games options and confirm that the Source Filmmaker setup points to the StudioMDL in your SFM installation, because Crowbar does not detect those tool locations automatically. Then, on the Compile tab, choose Source Filmmaker as the game, load the QC file, set the output folder, and run the compile. The same job can be run directly, by dragging the QC file onto StudioMDL or by running StudioMDL from the command line with the QC file as its argument and the SFM game folder given through its game option.

Step 6: Read the log before you celebrate. Read the log line by line. Find the first genuine error and fix that, because later messages are often noise caused by the first failure. Warnings about missing textures or bad paths are the log telling you exactly what to fix. Confirm that the MDL, VVD, and VTX files, and the PHY file if you included collision, were actually written, and note their time stamps, so you know you are testing the new compile and not an older one.

Step 7: Test in a model viewer, then in SFM. Crowbar can open the compiled model in Half-Life Model Viewer, the viewer provided with the game, through its View options. The viewer is the fastest place to check the shape, the bones, the material folders the model expects, and the material file names it is asking for. Then place the compiled model files in the models folder and the VTF and VMT files in the materials folder, add the model to an SFM scene, and check the shape, the textures, the bones, and any animation. If something is wrong, fix the source or the QC file and compile again. Recompiling is a normal part of the process, not a sign of failure.

Common Errors and What They Usually Mean

Keep two kinds of problems separate. A compiler error stops StudioMDL before it writes a finished model. A loading problem appears after a clean compile, when SFM or the model viewer cannot find or cannot use something. The fix, and the place to look, are different.

Purple and black checkerboard textures

This almost always means a broken material path, not a broken model. Work through the chain in order. First, check that a VMT exists with exactly the material name the mesh asks for. Second, check that the VMT $basetexture line points to a VTF that exists at that relative path. Third, check that the folder holding the VMT is listed by a $cdmaterials line in the QC file and matches the real folder under materials. A recompile is often not needed for this problem at all, because the compiled model may be fine and only the material files need to move or be renamed. Restart SFM after fixing materials, because SFM caches asset information during a session, so a model that failed once may not refresh cleanly in the same session.

The model does not appear at all

The compile may have failed before writing the MDL file, or the files may have been written to the wrong output folder, so SFM never sees them. Read the end of the log first to see whether the compile completed, then work backwards to the first error. Then confirm that the full output set sits in the folder named by $modelname, under models, in the SFM installation or mod folder you actually load content from.

The compiler cannot open an SMD file

The name or path in the QC file does not match the file on disk. Match the QC line to the file exactly, including its folder, its spelling, and its extension, and check for a doubled extension such as .smd.txt left by a text editor saving with the wrong type.

Unknown command, or a compile that behaves like a different game

An unrecognized command, or output that loads badly in SFM despite a clean log, points to the wrong compiler branch. Check the game setting in Crowbar and confirm that the StudioMDL being called is the one in the SFM installation bin folder. Different games compile different MDL versions, and a file built for the wrong branch is not a reliable SFM model.

Crashes on load

Crashes can point to a bad skeleton, a corrupt export, mismatched bone names between the reference mesh and an animation, or a compiler from the wrong Source game. Simplify to isolate the cause: compile the reference mesh with only an idle sequence, confirm that version loads, and then add animations and collision back one piece at a time.

The model is the wrong size, or its physics shape is offset

A consistent size problem is an export scale problem. Fix the scale in the modeling program, or apply a deliberate $scale value in the QC file, and recompile. An offset collision shape usually means the collision mesh was exported with a different origin from the reference mesh. Re-export it from the same scene origin and compile again.

Decompiling, and Where Compiling Fits

Compiling also has a reverse. Crowbar can decompile an existing compiled model, converting its binary files back into QC and SMD text files that can be studied, edited, and recompiled. That is a common way to learn how a working model is put together, and to compare a broken QC file with one that works. Decompiled animations are not always perfect for editing or recompiling, so treat a decompile as a reference and a starting point, not as a guarantee.

Once the compile, test, and recompile loop feels familiar, custom models stop being a mystery and become a repeatable part of making films in Source Filmmaker. The same pipeline sits behind much of the machinima and short film culture around Source games, which is part of the wider gaming coverage readers can explore in our Library 7 companion on Uggworldtech gaming trends, and, for readers who want to study the field formally, in our guide to a video game design degree.

Frequently Asked Questions

Can I compile without Crowbar?

Yes. StudioMDL works on its own from the command line, and a QC file can also be dragged onto StudioMDL to run it. Crowbar simply makes the same process easier to set up and easier to read when something goes wrong, by collecting the game setup, the QC file choice, and the log in one window. Crowbar does not replace StudioMDL. It calls it.

Do I need to compile textures too?

Yes, in effect. Texture images become VTF files, and VMT material files link to them. That conversion is separate from the model compile itself, but a model compile without correct materials will load with missing textures and show the checkerboard. Prepare the VTF and VMT files before, or alongside, the model compile, and keep their folder and names in step with the $cdmaterials line.

Why does my model look right in Blender but not in SFM?

Because Blender and SFM read different data. Blender shows your source scene, including its preview materials and modifiers. SFM shows only what the compile produced. Export errors, scale problems, bone mismatches, and material path errors therefore only become visible after compiling, which is why testing in a model viewer and then in SFM is part of the workflow and not an afterthought.

Can SFM open an FBX or OBJ file directly?

No. SFM loads compiled Source models. An FBX or OBJ file is a starting point for your modeling program, not an input SFM accepts in a scene. Import it into your modeling software, prepare the mesh and skeleton, export SMD or DMX, write a QC file, and compile. There is no shortcut that skips the QC and StudioMDL step for a custom model.

What is the difference between SMD and DMX?

Both are export formats that carry model, skeleton, and animation data to the compiler. SMD is the older, plain text format, produced by export plug-ins for model editors. DMX is the newer Source model format, and the Valve Developer Community notes that SMD has been superseded by DMX in Source and Source 2 work. For a straightforward SFM compile, either can work, as long as your exporter, your QC file, and StudioMDL all agree. Consistency matters more than the choice itself.

Does every model need a collision model and a PHY file?

No. A PHY file is produced only when the QC file includes a $collisionmodel. A character you pose and animate by hand, or a background prop that nothing needs to collide with, can compile and work without one. Add a collision model when the model needs a physical shape in the scene, and keep that mesh simple and aligned to the same origin as the visible model.

Why did my compile produce several files instead of one model file?

That is the normal result. The MDL file is the main file, but it works together with the VVD vertex data file and the VTX optimized mesh files, plus a PHY file when collision was included. Keep the set together, with the same base name, in the folder $modelname specified. Moving only the MDL file is a common reason a model that compiled successfully then fails to appear somewhere else.

Sources & references

• Valve Developer Community, Compiling a Model. https://developer.valvesoftware.com/wiki/Compiling_a_model
• Valve Developer Community, QC. https://developer.valvesoftware.com/wiki/QC
• Valve Developer Community, StudioMDL (Source). https://developer.valvesoftware.com/wiki/StudioMDL_(Source)
• Valve Developer Community, $cdmaterials. https://developer.valvesoftware.com/wiki/$cdmaterials
• Valve Developer Community, Source Filmmaker. https://developer.valvesoftware.com/wiki/Source_Filmmaker
• Valve, Source Filmmaker on Steam (Valve description of SFM as its movie making tool inside the Source game engine, using the same assets as the game). https://store.steampowered.com/app/1840
• ZeqMacaw, Crowbar (Modding Tool) Guide, Steam Community (Crowbar compiles through a graphical interface to studiomdl.exe; different games compile different MDL versions; Preview tab lists the material folders and material file names a model expects). https://steamcommunity.com/sharedfiles/filedetails/?id=791755353
• ZeqMacaw, Troubleshooting Missing Texture (material name in the SMD, VMT shader for models, $basetexture pointing to the VTF, and $cdmaterials listing the VMT folders). https://sites.google.com/view/zeqmacawstidbits/tutorials/troubleshooting-missing-texture