Difference between revisions of "QC Commands"

From Valve Developer Community
Jump to: navigation, search
(Standard Commands: $proceduralbones)
(Language templates)
Line 388: Line 388:
       $makeidlenoise idleNoise04 "Idle04_v32"
       $makeidlenoise idleNoise04 "Idle04_v32"

Revision as of 10:54, 16 September 2005

Standard Commands

$poseparameter (name) (min) (max) [[

$attachment (name) (bone name) (X) (Y) (Z) [[[

$hierarchy (child bone) (parent bone)

  • This forces a specific bone hierarchy on the model, regardless of what's in the reference file. Normally, the bone hierarchy is generated based on the first occurrence of a parent child relationship. This commands allows you override it with any arbitrary hierarchy.

Note: The model builder will now allow the animator to change the bone hierarchy between animations, at least in the source. The hierarchy is unified into a single fixed hierarchy for playback, but it’s often easier to change this for certain hand animation tasks. The hierarchy is defined by the first instance of the parent->child relationship.

$definebone (name) (parent) (X) (Y) (Z) (xr) (yr) (zr) (fixup XR) (fixup YR) (fixup ZR)

  • Defines a bone outside of any .smd source. This is useful when building animation only mdl’s that would otherwise optimize out all the bones since none of them are connected to any geometry or attachment points. You can get studiomdl to dump this out using the “-

$animation (name) (file) [(options)...]

  • Use this when you're creating a sequence that uses multiple source animations, but where you may need different options - such as frame numbers, alignment, etc. - on each of the different animations. When creating your sequence, refer to the animations by name instead of by filename.

$declaresequence (name)

  • Forward declares a sequence. This useful when sequence that want to add other sequences as layers that aren’t locally declared, such as when they’re actually part of an external mdl file. $declaresequence makes a empty sequence entry so that the local sequence pointers can get set, and at run time these references are overwritten with the actual sequence index.

$bonemerge (name)

  • Serves as a hint to the game code that the named bone will be used for bone merges (see Attachments) during the game. If this flag is not present, the bone can still be used but you'll get performance warnings.

$includemodel (filename)

  • Adds a .mdl file that this .mdl will include at run-time, and all new sequences and animations will be appended to the model. Animations and sequences are processed in-order, and subsequent animations/sequences that have name conflicts will be ignored, and any references to .mdl local entry by the same name will be overwritten with the reference to a first one declared.

Included .mdl’s can have different bone ordering, but they need to have the same bone hierarchy and ikchain declarations. Currently there’s no run-time checking to verify they match.

Only animations and sequences are used from included .mdls. Currently models, textures, faces, attachments, etc. are ignored.

$animblocksize (size in K)

$weightlist (name) (bone name) (weight) [[(bone name) (weight)] ....]

  • This creates a named list of boneweights that can be used by animations that are intended to be blended on top of other animations. The weightlist is built assuming that the root bone has a weight of 0, and that all child bones inherit the weight of their closest specified parent bone. This means that you only have to specify weights when they change, not for each and every bone in the list.

$scale (scale)

  • Scales the model by the given scale amount. A scale of 1.0 makes the model normal sized, 0.5 is half sized, and 2.0 is double sized. Note that the $scale command must be given before any .smd file references, else it will not be applied.


  • Causes all bones to be collapsed in the object; this can only be used when there’s no animation associated with the object. You want to use it wherever possible though, because it will make the models render more quickly.


  • This forces all the bones to reorient themselves – if possible - so that their longest axis is along their X axis. This helps with building both hit boxes, quite often child bones are at some diagonal to their parent and the axis-align-bounding-box that gets connected to their parent bone is often badly shaped for models that are mostly made of long tubes, as well as making IK possible since the IK system requires that the child bones are always along the X axis of their parent.

Bones with multiple children, such as the pelvis, are not realigned and cannot be used as part of an IK system (i.e. the hip bone can’t change position in relation to the pelvis).

$surfaceprop (name)

  • Applies a particular surface property to the entire model. The surface property affects a number of parameters for the model: it’s physics properties (weight, etc), what sounds it makes when it collides, what particles it emits when you shoot it, etc. To add or change surface property types, edit the file hl2\scripts\surfaceproperties.txt. HLMV can be used to generate blocks of .QC file that sets the surface properties correctly.

$jointsurfaceprop (joint name) (name)

  • Applies a surface property to a particular joint and all of its children. HLMV can be used to generate blocks of .QC file that sets the surface properties correctly.

$contents (list of names of content types)

  • Specifies the contents to use for contents-mask tests during non-hitbox traces. This feature was specifically added to allow us to make things like fences out of props instead of brush models.

The current contents types you can use are:

  • "grate" Makes it be a grate (not solid to bullets, solid to everything else)
  • "monster" Makes it be marked as an NPC
  • "notsolid" Makes it be not solid to anything
  • "solid" Makes it be solid (usually useful only for the $jointcontents command to make a solid child of a non-solid parent)
  • "ladder" Make it be a ladder

For example,

$contents "monster" "grate"

$jointcontents (joint name) (list of names of content types)

  • This command is just like contents, but it applies the contents to the specified bone and all child bones of that bone.


  • Causes the model to be assumed to be opaque with respect to its sorting against all other objects in the scene. Use this in cases where only a small portion of the model is translucent (hair, eyes, glasses, etc.) so if there are any sorting issues, it won’t matter.


  • Causes the model to be rendered in two passes: The first pass renders only the opaque portions of the model, and the second pass renders only the translucent portion of the model. Good for improving translucency sorting for things like trees.


  • This allows you to add an arbitrary block of keyvalues into the .mdl file. For example,
                          "obj_manned_plasmagun" 1
                          "obj_resourcepump" 1
                          "obj_shieldwall" 1

$definemacro (macroname) [arg_name1] [arg_name2] […] \\

  • Defines a string substation macro. The macro definition begins on the next line, and all subsequent lines that end with \\ (two backslashes). Arguments are referenced by surrounding them with $’s (i.e. $arg_name1$ ), and can be embedded inside of other words. To use the macro, type $macroname and the next N tokens will be taken as arguments.
      $definemacro testmacro seqname filename endframe \\
      $sequence $seqname$01 $filename$ { \\
           frames 0 $endframe$ \\
           subtract $seqname$ 0 delta \\
           weightlist justbody \\
     Then to use to do:

$lod (distance) { (lod commands here) }

  • Begins a block of commands to describe how to perform LOD on the model. The distance parameter represents that this particular set of LOD commands should be run when the camera is farther than distance away from the model. The commands allow you to replace various materials, textures, etc. The commands you can include in the lod block are shown in the Level of Detail section.

$proceduralbones (helper bone configuration file)

  • Helper bones help controling bone orientation/position. Default helper bone configuration files are found in sourcesdk_content\hl2mp\modelsrc\humans_sdk.

Level of Detail Commands

replacebone (original bone) (replacement bone)

  • Causes a bone to be used in place of the original bone in the reference model. This can be useful for collapsing all of the bones in the hand together. Instead of using the ‘finger’ bone, the finger could just be tied to the ‘hand’ bone.

bonetreecollapse (bone name)

  • Causes all child bones of the specified bone to use the specified bone instead of whatever they currently are attached to. It’s a simpler way to use replacebone in the case where you want to collapse a large number of bones; hands especially can use this feature.

replacemodel (model name) (replacement model) [reverse]

  • Causes the source model to be replaced with a different model. If reverse is specified, the normals of the replacement model are reversed. If the replacement model name is ‘blank’, then the source model is not rendered at all. This is used to replace the model with lower polygon-count versions.

removemodel (model name)

  • Causes the model to not be rendered at this lod.

replacematerial (original material name) (replacement material name)

  • Replaces all instances of a particular material on a model with a different material. This can be used to cause lower LODs to use a smaller version of the texture, for instance.

removemesh (material name)

  • Removes all the triangles attached to the named material from this LOD.


  • Causes facial animation to be deactivated for this LOD.

New $model Option

eyeball (name) (bone name) (X) (Y) (Z) (material name) (diameter) (angle) (iris material) (pupil scale) -4 degrees walleyed. Not setting this correctly will result in your either characters appearing cross-eyed, or if you’ve compensated by misplacing the ball of the eye, them not tracking side to side. (iris material)Material to use as the iris texture. (pupil scale)World scale of the iris texture

eyelid (name) (expression file) lowerer/neutral/raiser (frame) (height) split (distance) eyeball (name)

  • flex (name) [(expression file)]
  • frame (frame) position split (distance)
  • defaultflex
  • flexfile (expression file)
  • localvar (name) [(name) …]
  • mouth (flexcontroller name) (bone name)
  • spherenormals (material name) (X) (Y) (Z)

See also

New $animation Options

fixuploop (pre loop frames) (post loop frames)

  • This finds the difference between the last frame and the first frame in the animation and blends the difference across the boundary. The range from some negative value (number of frames back from the last frame) to 0, and ranges from 0 to some positive number of frames after the first frame.

This is useful when building a looping animation out of a portion of a non-looping animation, or even cleaning up a animation that is supposed to loop but has a slight hitch.

alignto (goal animation)

  • This will shift the current animation so that the root position of the first (local) frame matches the root position (X and Y axis only) of the first (local) frame of another animation. This is useful when animations don't start on the origin, or when you're cutting out just a small piece of a longer source animation and you need a quick way to get it aligned to a shared origin.

align (reference animation) [X Y Z XR YR ZR] (reference frame) (to match frame)

  • This is similar to alignto, except that you can specify how the two animations are to match, and that the (to match frame) on the animation is aligned with the (reference frame) of the (reference animation). This is useful when aligning animations with vertical motion.

alignboneto (bone name) (goal animation)

  • Same as alignto, but will match the specified bone instead of the root.

startloop (local frame)

  • This resets the starting frame of a looping animation. This is useful when creating sequences that have multiple animations and the animations need to all run together in phase, but the source animations don't all quite match.

All animations default to a weightlist that assumes all bones have a weight of 1.0. QC specified weightlists

      $weightlist no_hands "Bip01" 1.0 "Bip01 L Hand" 0.0 "Bip01 R Hand" 0.0
      $weightlist head_n_arms "Bip01 Spine 2" 1.0

Only the bones with a weight > 0 will have any influence over the animation.

fudgeloop -frame movement, skipping the definition of the overlap can cause a hitch or foot slide during playback if studiomdl guesses wrong.

If for some serious reason the animator can't create the last frame overlap, then this option tells studiomdl to assume the movement is the average per-frame motion seen so far in the animation, and that it needs to create the overlapping frame itself.

weightlist (weightlist name)

  • This copies a predefined list of bone weights to the current animation. You can do this any number of times per animation, which can be useful since subsequent options subtract, match, and fixuploop options only operate on bones with weights > 0. The last specified weightlist option is the one the animation system uses when doing blending. Sequences that use multiple animations need to have all their source animations use the same weightlist or the results are undefined.

subtract (animation) (frame #)

  • This subtracts the specified frame of the specified animation from all the frames of the current animation and creates an animation that is the differences between the two, effectively converting the animation to just be the changes from a reference frame of another animation.

presubtract (animation)

  • This subtracts all the frames of the current animation from the first frame of the specified animation and creates an animation that is the differences between the two.

match (animation)

  • Makes the first frame of the animation match the first frame of the specified animation, and then applies the difference between the two frames to all subsequence frames. This is mainly used to correct animations that are supposed to start at a common pose but don’t for some uncontrollable reason.

walkframe (frame) [LX LY LZ LXR LYZ LZR]

  • You can set up to 16 of these per animation to specify linear piecewise movement. Matches root bone from the previous walkframe command – defaults to frame 0 – to the specified frame of each segment, extracting linear motion between each.

walkalignto (frame) (reference animation) [LX LY LZ LXR LYR LZR]

  • Like walkframe, but at extracts motion such that at (frame), the model is aligned to the specified (reference animation). This is useful when trying to extract the motion inside a animation that’s used to transition between two existing animations.

walkalign (frame) (reference animation) [LX LY LZ LXR LYR LZR] (reference frame) (to match frame)

  • Like walkalignto, but motion is calculated such that the (to match frame) matches the (reference frame) of the (reference animation). This is useful when the last frame being used to extract motion over doesn’t quite match a goal animation, but a subsequent frame does.

rotateto (angle)

  • Finds the current direction of movement (uses the first movement if there are multiple pieces), then rotates the animation so that the resulting movement is in the specified direction.


derivative (scale)

  • Turns the animation into the derivative of itself by simply subtracting the previous frame from each frame in the animation. The derivative can be automatically scaled to compensate for any fps issues.


  • Turns the animation into a delta animation, by subtracting a linear blend of the first and last frames from each frame of the animation.


  • Turns the animation into a delta animation, by subtracting a spline (s-curve) blend of the first and last frames from each frame of the animation.

compress (skip)

  • Turns a animation into a lower fps version of itself by only using every Nth frame. Automatically converts specified fps values into new equivalent.

numframes (frames)

  • Forces an animation to be a specified number of frames, either by clipping the animation or by duplicating the last frame until it has been padded with enough.

New IK Options

$ikchain (name) (end bone) [height (units)] [pad (units)][floor (units)]

  • Declares a named set of bones that are used to form an IK chain. Chains are specified by naming the bone farthest down in the chain, the next two bones are automatically found by walking the hierarchy.

Ikchains are used exclusively with ikrule and iklock animationoptions. Depending in the specific rule used, the end bone is moved into the needed position, the top most bone is assumed fixed in place, and the position of the middle bone is moved so that that the distance from the end-to-middle and middle-to-top bones remain constant. An example would be a IK chain of the ankle-knee-hip chain, where the ankle is adjusted to hit to relative to the ground, the hip is locked in place, and the knee is bend such that the leg remains its original length.

iklock (chain) (lock position) (maintain local rotation)

  • For this sequence, keep track of the position/orientation of the specific chain before the sequence is applied, then after it’s applied, do a local IK rule to move it back into position/orientation. The weights are floating point values form 0.0 to 1.0.

This is used to keep the specified IK chains from moving during this sequence, which can be useful when applying pelvis or body motion to a model but you want the hands or feet to remain in place.

ikrule (chain) touch (bone) [options...]

  • Adds an IK rule where a bone needs to be needs to be positioned relative to another part of the body. This is useful when the hand needs to touch some other part of the model, such as the face, hip, other hand, etc., and that other body part may be not in the original animated location due to additional animation layers, bone controllers, or other IK rules.

ikrule (chain) footstep (slot #) [options…]

  • Adds an IK rule where a subsequent body part – such as a foot – needs to be moved relative to the ground.

Ikrule Options

range (start) (peak) (tail) (end)

  • Sets the fade-in, hold, and fade-out frame numbers for the ikrule.

height (units)

  • Used by footstep rules, specifies how high to start the search above the desired ground height.

floor (units)

  • Used by footstep rules, specifies where the actual ground is ground height.

pad (radius)

  • Used by footstep rules, specifies how big the ground contact check should be.

contact (frame)

  • Used by footstep rules, specifies what frame use use when checking for ground position.

radius (units)

  • Used by attachment rules, specifies how out to search.


  • Use the original animation source to determine the IK goals. This is use useful if the current sequence is a composite that is different from the source animation and you want to get the movement back to its original form.


  • Run all the sequence rules, including blendlayer and addlayer rules to determine the IK goals.

New $sequence Options

activity (activity_name) (weight)

  • This command binds the sequence to an activity name. An activity name is an alias for one or more sequences that the code can use.

The advantage to using activities is that the modeler can bind multiple sequences to one activity name, thus getting some variation in the animations the model plays without programmer intervention. For example, the modeler could create three idle animations and bind them all to ACT_IDLE. The programmer only has to write code saying to play ACT_IDLE, and one of the three idle sequences will be chosen.

The second parameter, activity_name, must be an activity in the programmer's activity tables (in ai_activity.cpp and activitylist.cpp).

The third parameter, weight, controls how often this sequence will be chosen versus other sequences bound to the same activity name. Sequences with higher weights will be chosen more often. For example, if you had a sequence called "idle1" with a weight of 1 and a sequence called "idle2" with a weight of 2, then "idle2" would have twice the chance of being played when the model is told to play ACT_IDLE.

If you only have one sequence for an activity, you can set the weight to -1 for a slight preformance boost.


The easiest way to think of these are that they’re just fancy bonecontrollers, but ones that have multiple bones. Autoplay sequences are only played at a cycle/frame index of 0.

addlayer (sequence)

  • Automatically composites another sequence on top of the current sequence, before it’s composited on top of the current bone setup. The cycle index of this new sequence is the same as the current sequence.

blendlayer (sequence) (start) (peak) (tail) (end) [spline] [xfade]

delta -fade weighting scheme.

predelta -fade weighting scheme.


  • Remove all blending when transitioning to this animation. This is useful for reaction animations that are the result of sudden and violent changes in the models state such as flinching for creatures or shooting for weapons.


  • Ignore the cycle clock, play the sequence off of the real-time system clock. Useful when adding layers that need to not be cycle locked to their parent sequence.

fadein (time)

  • Override default 0.2 second blend with specified time when transitioning to this animation.

fadeout (time)

  • Override default 0.2 second blend with specified time when transitioning from this animation.

blendwidth (width)

  • Instead of just 1x1, 2x1, 3x1, 2x2, and 3x3 blends, by blending width, you can now have any size rectangular blends such as 7x1, 3x4, 2x9, etc.

blend (name) (min) (max)

  • You can have up to 8 unique parameters.

node (name)

  • Tags the sequence as belonging to a point on the sequence transition graph table. This is for animations which don’t change graph state, such as looping animations. Multiple sequences can be at the same entry in the graph table, at which point they won’t need transition animations be move between each other. Alternatively, you can have them at different points and expressly skip transitions (see $skiptransition). Sequences with no declaration are assumed at the root node and the transition graph assumes any sequence can move from the root node or to the root node without a intermediate transition.

transition (from) (to)

  • This specifies that the animation enters from one point on the node graph and exits at another point. This is used to play transitional sequences such as walk_to_stand, run_to_crouch, etc.

rtransition (name1) (name2)

  • Same as transition, but flags the sequence as able to be run in reverse order. This was used by the tentacle in HL1 but I don’t recommend it be used expect in special cases.

exitphase (phase)

$skiptransition (name1) (name2) [(name3) …]

keyvalues { [stuff] }

  • Add a keyvalue block (see $keyvalues) to a specific sequence.

New Macro Commands

$definemacro (macroname) [named parameters …]

  • Defines a named macro that can be use as a short hand way to specify other QC commands. The macro creates a block a named block of text, that when referred to will virtually insert that text into the QC file, along with replacing the named parameters with the specified values.


      $definemacro makeidlenoise idleNoiseName fileName \\
      $sequence $idleNoiseName$ {\\
           $fileName$ \\
           subtract $idleNoiseName$ 0 \\
           iklock lfoot 1 0 iklock rfoot 1 0 \\
           delta \\
           hidden \\
           realtime \\

      $makeidlenoise idleNoise03 "Idle03"
      $makeidlenoise idleNoise04 "Idle04_v32"