Compiling a model

This article will explain how to compile models for use in-game with studiomdl. You will need some existing SMD files to compile before you begin; if you don't have any, see Exporting a model.

Tip:The name "studio" is a throwback to the development Half-Life 1, during which Valve used 3D Studio Max to create their models.

QC file

As well as SMD data files, you will need a QC file that defines how the raw SMD data should be interpreted in a manner not too dissimilar to a texture's VMT. This is where you will spend the majority of your time when setting up a compile.

A QC file is simply a text file with the .qc extension. You can create it anywhere and name it anything, but it's best to be organised and store it with your SMDs in a folder with the same name as the destination model file.

Compile environment

While you can edit your QC with Notepad, you really ought to use an advanced text editor that supports syntax highlighting and can run studiomdl on the file without any messing about at the Windows command line. There are two editors with such support at the moment:

• Notepad++
• ConTEXT

Once you've downloaded the highlighting rules and set up the execution command, you're all set!

QC commands

For a list of all documented QC commands, see Category:QC Commands

Here is a QC file for a non-animated, static prop:

$modelname	"props_sdk/myfirstmodel.mdl"
$body mybody	"myfirstmodel-ref.smd"
$staticprop
$surfaceprop	combine_metal
$cdmaterials	"models/props_sdk"

$sequence idle	"myfirstmodel-idle.smd" loop fps 1

$collisionmodel	"myfirstmodel-phys.smd" { $concave }

Here is a brief summary of what each command does (for more detail, click on the names):

$modelname

Defines the core output model file. Several other files will be created as well, with variations of this value as their name.

$body

Defines the SMD that contains the vertex, UV map and envelope data for the model. Without this, your model will have no physical appearance.

A name ('mybody') is given because it is possible for a model to have several bodies - like the metrocop, who has one with a manhack attached and one without.

Tip:More complex models use $model instead of $body.

$staticprop

Tells studiomdl that the model has no moving parts, allowing it to perform several important optimisations. It does not have anything to do with prop_static!

$surfaceprop

How the object's surface reacts to other entities in the world. Also helps define the weight of the object, if the QC command to calculate it is used.

Note:An identical command is used in materials. Should they clash on a model, the QC version is chosen. It isn't clear why this functionality is duplicated.

$cdmaterials

The folder to load the model's material(s) from. Remember that the materials must be the same name as the ones you applied in your modelling package.

$sequence

Even though this model is not animated, Source needs an empty 'idle' animation to correctly load it. By setting it to one frame per second, we eliminate a small amount of overhead.

$collisionmodel

Defines the SMD that will be used to calculate physics collisions by the engine. Without a collision model, physical objects will simply fly through the model (which in some cases may be what you want).

$concave

A collision model must be convex, but you can create concave shapes by combining more than one of them into the same model. This command tells studiomdl that this is what you intend - without it, all of your collision SMD's meshes will be merged into one shape that wraps them all around.

You will be able to use this sample to compile your own model (except any animations), so swap in your own SMDs and see what happens.

Common errors

Costly collision model

A costly collision model is one of over 20 convex parts. You will receive this error when going over it:

WARNING: COSTLY COLLISION MODEL!!!! (30 parts - 20 allowed)
WARNING: Error with convex elements of physmodel.smd, building single convex!!!!
Model has 31 convex sub-parts
Collision model completed.

The appearance of "error with convex elements" is itself an error, so ignore it. Your meshes are (probably) fine.

The solution to this is either to decrease the number of convex meshes, or if you really do need that many of them (usually only excusable on very large models), to use the $maxconvexpieces command to override the limit to one of your own preference. For instance:

$collisionmodel	"myfirstmodel-phys.smd" { $concave $maxconvexpieces 40 }

(Episode One engine users must run studiomdl with the -fullcollide parameter when compiling instead.)

Duplicate weightlist pelvisonly

If Studiomdl displays the error "duplicate weightlist pelvisonly" when compiling the male_06_sdk model, the problem may be the inclusion of the file Male_Animations_sdk/WeaponsAnims_Shared_sdk.qci.

That file contains a $weightlist pelvisonly line identical to a line in the included file male_shared_XSI_sdk.qci.

• In the Male_Animations_sdk folder, make a copy of the WeaponsAnims_Shared_sdk.qci file.
• Rename the copy to WeaponsAnims_Shared_sdk_X.qci (or other unique name).
• Edit the WeaponsAnims_Shared_sdk_X.qci file and comment out the $weightlist line by inserting // at the beginning of the line.

//$weightlist pelvisonly ...

• Open for editing the file male_06_sdk.qc.
• Change the line $include "../male_animations_sdk/WeaponAnims_shared_sdk.qci" to

$include "../male_animations_sdk/WeaponAnims_shared_sdk_X.qci" //(or as otherwise renamed above)

• Save the male_06_sdk.qc file.
• Recompile male_06_sdk.qc to determine if the error was corrected.

Short conversion out of range

Generating optimized mesh "c:\steam\steamapps\SourceMods\mod\models/your/model.sw.vtx":
ERROR: short conversion out of range XXXXX
ERROR: Aborted Processing on 'your/model.mdl'

The problem is that studiomdl.exe is trying to write out a triangle strip with more than 32767 vertices, which is more than Source supports (and also more than any model should ever need). You have run into a engine limitation and you need to reduce the complexity of a portion of the model.

As an example, Valve's highest LOD .SMD for dog is only 1.72 MB and contains 17,433 vertices. Which then divides down to a little less than 6,000 polygons. 10,000 polygons is kind of an informal maximum for the Source engine, hence the maximum vertices being roughly 10,000 x 3 (32767).

Error codes

* WARNING: (4768124) : ERROR: 'EXCEPTION_ACCESS_VIOLATION' (assert: 1)

This is caused by having the $shadowlod's curly bracket in the same line as the command. Change:

$shadowlod {

to

$shadowlod
{

Also without the "WARNING: (4768124)":

* ERROR: 'EXCEPTION_ACCESS_VIOLATION' (assert: 1)

If getting this error while compiling with Studiomdl try compiling models with the HLMV running. (18/11/07) - Laz84

See also

• QC
• studiomdl
• Studiocompiler, a graphical interface for studiomdl
• GUIStudioMDL, another graphical interface
• Highlighting and Compiling QCs with ConTEXT
• Notepad++ VDF languages