Compiling a model: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
(redone)
Line 1: Line 1:
{{template:toc-right}}
{{template:toc-right}}


This article will explain how to compile [[model]]s for use in-game with [[studiomdl]]. You will need some existing [[Studio Model Data|SMD]] files to compile before you begin; if you don't have any, see [[Exporting a model]].
[[Model]]s need to be compiled before they can be used in a game. There are three components of a compile:


{{tip|The name "studio" is a throwback to the development of [[Half-Life 1]], during which Valve used [[3D Studio Max]] to create their models.}}
# A set of '''[[Studiomodel Data|SMD]] files''' describing a model. See [[Exporting a model]] if you don't have any.
# A '''[[Qc|QC]] file''' that defines, in a manner not too dissimilar to a texture's [[VMT]], how the SMD files should be interpreted.
# '''[[Studiomdl]]''', the SDK program that consumes the QC and spits out (hopefully!) a compiled model.


== QC file ==
== Setting up ==


As well as SMD data files, you will need a [[Qc|QC]] file that defines in a manner not too dissimilar to a texture's [[VMT]] how the raw SMD data should be interpreted. This is where you will spend the majority of your time when setting up a compile.
The only step you need to take before compiling (assuming your SMDs have exported OK) is choosing the current [[VPROJECT]] folder. This is the game that is being compiled for, and defines where studiomdl will write out the compiled model. You can configure it:


A QC file is simply a text file with the <code>.qc</code> 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.
#Globally, by selecting your game/mod in the SDK launcher's drop-down list. {{bug|This won't work for studiomdl (or any other command-line tool) unless you have admin permissions.}}
#For studiomdl only, by running it with <code>-game "<full path to your [[gameinfo.txt]] folder>"</code> {{tip|Most SDK tools accept <code>-game</code>.}}


== Compile environment ==
=== Syntax highlighting ===


The most important step in setting your computer up for a compile is choosing the correct [[VPROJECT]] variable. You can do this:
Editing a QC file becomes much easier when you use an advanced text editor with support for [[Wikipedia:Syntax highlighting|syntax highlighting]]. There are two editors with QC highlighting rules at the moment:
 
#Globally, by selecting your game/mod in the SDK launcher's drop-down list
#For studiomdl only, by running it with <code>-game "<full path to your [[gameinfo.txt]] folder>"</code>
 
When it comes to editing your QC, you really, ''really'' want to use an advanced text editor which supports syntax highlighting and which can run studiomdl without any command line or batch file fiddling. There are two editors with such support at the moment:


*[[Notepadpp VDF languages|Notepad++]]
*[[Notepadpp VDF languages|Notepad++]]
*[[Highlighting and Compiling QCs with ConTEXT|ConTEXT]]
*[[Highlighting and Compiling QCs with ConTEXT|ConTEXT]]


Once you've downloaded the editor and highlighting rules and set up the execution command, you're all set!
== Creating a QC ==
 
=== The hard way ===


If you don't want to or can't use either of the above text editors, you will be compiling QCs by dragging them onto studiomdl.exe. You can find it in <code>sourcesdk/bin/orangebox/bin/</code> (replace orangebox/ with ep1/ if required).
A QC file is simply a text file with the extension <code>.qc</code>. 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.


You will find this process easier if you create a .cmd file somewhere more accessible to automate the process. This is simply a renamed .txt file containing something like this:
Inside it should be a list of [[:Category:QC Commands|commands]] that tell studiomdl about the location of the model's various SMDs, where the compiled files should be written to (relative to VPROJECT), how to process animations, and potentially much, ''much'' more. You will find all known commands listed at [[:Category:QC Commands]].


"%sourcesdk%/bin/orangebox/bin/studiomdl" %1
=== Example ===
pause


Drop your QC file on to it as you would with the executable itself - it's essentially a shortcut.
<div style="margin-left:1em;padding:1em;float:right;width:22em;border:1px solid #aaa;background:#EFEFEF;-moz-border-radius:.5em;-webkit-border-radius:.5em;">
<h4 style="margin:0;padding:0;">File locations</h4>


== QC commands ==
The default location for SMDs is the same folder as the QC file. You can access other locations:


:'''''For a list of all documented QC commands''', see [[:Category:QC Commands]].''
* With an absolute path (e.g. <code>C:\modelsrc\my_model\</code>)
* With a relative path (e.g. <code>.\subfolder</code> or <code>..\</code>) {{tip|A single period is the current folder. Two periods is the one above it. <code>..\..\</code> goes two levels up.}}
* With <code>[[$pushd]]</code> and <code>[[$popd]]</code>.</div>


Here is a QC file for a non-animated, static prop:
Here is a very simple QC file for a solid model without any animation or special properties (click on each command for details):


  [[$modelname]] "props_sdk/myfirstmodel.mdl"
  [[$modelname]] "props_sdk\myfirstmodel.mdl"
  [[$body]] mybody "myfirstmodel-ref.smd"
  [[$body]] mybody "myfirstmodel-ref.smd"
  [[$staticprop]]
  [[$staticprop]]
  [[$surfaceprop]] combine_metal
  [[$surfaceprop]] combine_metal
  [[$cdmaterials]] "models/props_sdk"
  [[$cdmaterials]] "models\props_sdk"
   
   
  [[$sequence]] idle "myfirstmodel-idle.smd" loop fps 15
  [[$sequence]] idle "myfirstmodel-idle.smd" loop fps 15
Line 52: Line 50:
  [[$collisionmodel]] "myfirstmodel-phys.smd" { [[$concave]] }
  [[$collisionmodel]] "myfirstmodel-phys.smd" { [[$concave]] }


{{tip|The default location for SMDs is the same folder as the QC file. You can specify relative or absolute paths with any command if something is stored in a different folder.}}
You will be able to use this as a template to compile your own model, so swap in your own SMDs and see what happens.
 
Here is a brief summary of what each of those commands does. For more detail, click on the names.
 
;<code>[[$modelname]]</code>
:Defines the name and location of the  model's core output file relative to <code><mod folder>/models/</code>. Several other files will be created as well, with variations of this value as their name.
;<code>[[$body]]</code>
:Defines the SMD that contains the [[vertex]], [[UV map]], [[skeleton]] 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 [[npc_metropolice|metrocop]], who has one with a [[npc_manhack|manhack]] attached and one without.
:{{tip|More complex models use <code>[[$model (QC)|$model]]</code> instead of $body.}}
;<code>[[$staticprop]]</code>
:Tells studiomdl that the model has no moving parts, allowing it to perform several important optimisations. It is required if the model is to be used with [[prop_static]], but does not prevent it from being used elsewhere! (Indeed, most models that are to be physically-simulated use the command as well.)
;<code>[[$surfaceprop]]</code>
: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 [[material]]s. Should they clash on a model, the QC version is chosen. It isn't clear why this functionality is duplicated.}}
;<code>[[$cdmaterials]]</code>
: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. The value is relative to <code><mod folder>/materials/</code>.
;<code>[[$sequence]]</code>
:Even though this model is <code>$staticprop</code> and therefore not animated, Source needs an empty 'idle' animation to correctly handle it. If the animation is truly idle it will only have one frame, rendering the <code>fps</code> property meaningless (but it's included anyway in demonstration).
;<code>[[$collisionmodel]]</code>
: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).
:{{tip|If your collision model needs to be animated, use <code>[[$collisionjoints]]</code> instead.}}
;<code>[[$concave]]</code>
:A collision model must be [[Wikipedia:convex|convex]], but you can create [[Wikipedia:concave|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 instead be merged into one shape that wraps them all around.


You will be able to use this sample to compile your own model (minus any animations), so swap in your own SMDs and see what happens.
{{note|All models must have at least one <code>$sequence</code>, even if they aren't actually animated.}}


== Compiling more advanced models ==
=== Tutorials ===


*For physically-simulated objects, see '''<code>[[Prop Data|prop_data]]</code>'''
*For physically-simulated objects, see '''<code>[[Prop Data|prop_data]]</code>'''
Line 87: Line 62:
*For general help with compiling models, see '''[[:Category:QC Commands]]'''
*For general help with compiling models, see '''[[:Category:QC Commands]]'''


== Samples ==
== Compiling ==
 
=== With your text editor ===
 
The easiest way to compile a model is with the built-in launch features of advanced text editors.
 
*[[Notepadpp VDF languages#Compiling QC files|With Notepad++]]
*[[Highlighting and Compiling QCs with ConTEXT|With ConTEXT]]
 
=== With a batch file ===
 
If you can't (or don't want to) use an advanced text editor, you will be compiling QCs by dragging them onto studiomdl in Windows. You can find the executable file in <code>sourcesdk/bin/[orangebox|ep1]/bin/</code>.
 
The process will be easier if you create a .cmd file somewhere more accessible to automate it. This is simply a renamed .txt file containing something like this:


Valve provide numerous sample models in the SDK for you to learn from, including several fully-articulated characters and players. They can be found at:
"%sourcesdk%/bin/orangebox/bin/studiomdl" "%1"
pause


*<code>sourcesdk_content\cstrike\modelsrc</code>
Drop your QC file onto the CMD as you would studiomdl itself; it's essentially a shortcut to the executable.
*<code>sourcesdk_content\hl2\modelsrc</code>
*<code>sourcesdk_content\hl2mp\modelsrc</code>
*<code>sourcesdk_content\generic\modelsrc</code> (a walking animation for Valve's default skeleton)


== Common errors ==
== Common errors == <!-- linked to from [[studiomdl]] -->


*<code>Error opening <model>! (Check for write enable)</code>
*<code>Error opening <model>! (Check for write enable)</code>
Line 105: Line 91:
*<code>[[WARNING: (4768124) : ERROR: 'EXCEPTION ACCESS VIOLATION' (assert: 1)]]</code>
*<code>[[WARNING: (4768124) : ERROR: 'EXCEPTION ACCESS VIOLATION' (assert: 1)]]</code>
*:If you receive <code>EXCEPTION_ACCESS_VIOLATION</code> without an error code, try compiling with [[HLMV]] running.
*:If you receive <code>EXCEPTION_ACCESS_VIOLATION</code> without an error code, try compiling with [[HLMV]] running.
== SDK samples ==
The SDK has numerous sample models, including several fully-articulated characters and players. They can be found at <code>sourcesdk_content\<game>\modelsrc\</code>.
; <code>cstrike</code>
: "Urban CT" player model
: Several static props
; <code>generic</code>
: A tweaked [[ValveBiped]] rig (no meshes)
; <code>hl2</code>
: [[Airboat]] and [[Buggy]]
: [[Antlion Guard]]
: Male citizen (only has a few animations)
: Some CS stuff that is probably a duplicate of <code>\cstrike</code>'s content
: Viewmodels for all HL2 weapons
; <code>hl2mp</code>
: ''All with multiplayer animations only:''
: Combine soldier
: Metrocop
: Male rebel


== See also ==
== See also ==

Revision as of 08:00, 7 January 2009

Models need to be compiled before they can be used in a game. There are three components of a compile:

  1. A set of SMD files describing a model. See Exporting a model if you don't have any.
  2. A QC file that defines, in a manner not too dissimilar to a texture's VMT, how the SMD files should be interpreted.
  3. Studiomdl, the SDK program that consumes the QC and spits out (hopefully!) a compiled model.

Setting up

The only step you need to take before compiling (assuming your SMDs have exported OK) is choosing the current VPROJECT folder. This is the game that is being compiled for, and defines where studiomdl will write out the compiled model. You can configure it:

  1. Globally, by selecting your game/mod in the SDK launcher's drop-down list.
    Icon-Bug.pngBug:This won't work for studiomdl (or any other command-line tool) unless you have admin permissions.  [todo tested in ?]
  2. For studiomdl only, by running it with -game "<full path to your gameinfo.txt folder>"
    Tip.pngTip:Most SDK tools accept -game.

Syntax highlighting

Editing a QC file becomes much easier when you use an advanced text editor with support for syntax highlighting. There are two editors with QC highlighting rules at the moment:

Creating a QC

A QC file is simply a text file with the extension .qc. 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.

Inside it should be a list of commands that tell studiomdl about the location of the model's various SMDs, where the compiled files should be written to (relative to VPROJECT), how to process animations, and potentially much, much more. You will find all known commands listed at Category:QC Commands.

Example

File locations

The default location for SMDs is the same folder as the QC file. You can access other locations:

  • With an absolute path (e.g. C:\modelsrc\my_model\)
  • With a relative path (e.g. .\subfolder or ..\)
    Tip.pngTip:A single period is the current folder. Two periods is the one above it. ..\..\ goes two levels up.
  • With $pushd and $popd.

Here is a very simple QC file for a solid model without any animation or special properties (click on each command for details): 

$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 15

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

You will be able to use this as a template to compile your own model, so swap in your own SMDs and see what happens.

Note.pngNote:All models must have at least one $sequence, even if they aren't actually animated.

Tutorials

Compiling

With your text editor

The easiest way to compile a model is with the built-in launch features of advanced text editors.

With a batch file

If you can't (or don't want to) use an advanced text editor, you will be compiling QCs by dragging them onto studiomdl in Windows. You can find the executable file in sourcesdk/bin/[orangebox|ep1]/bin/.

The process will be easier if you create a .cmd file somewhere more accessible to automate it. This is simply a renamed .txt file containing something like this: 

"%sourcesdk%/bin/orangebox/bin/studiomdl" "%1"
pause

Drop your QC file onto the CMD as you would studiomdl itself; it's essentially a shortcut to the executable.

Common errors

SDK samples

The SDK has numerous sample models, including several fully-articulated characters and players. They can be found at sourcesdk_content\<game>\modelsrc\.

cstrike
"Urban CT" player model
Several static props
generic
A tweaked ValveBiped rig (no meshes)
hl2
Airboat and Buggy
Antlion Guard
Male citizen (only has a few animations)
Some CS stuff that is probably a duplicate of \cstrike's content
Viewmodels for all HL2 weapons
hl2mp
All with multiplayer animations only:
Combine soldier
Metrocop
Male rebel

See also

Template:Otherlang:en Template:Otherlang:en:ru

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Compiling_a_model&oldid=92018"