.qc scripts are simple text files, edited in Notepad, and are needed to compile a model. They tell studiomdl.exe where the mesh,
textures and animations are but more importantly sets up parameters that Half-Life will need.
Some of these interact with the monster's intelligence code, the animation engine, swap skins or body parts, play sound files,
spawn sprite animations or beam effects, and can even trigger events in a map. Keep in mind that your model may need code written to handle these features;
they can't just exist and work from the model. This describes the most common commands, and gives examples of script files that can be a basis for most others.
- = : EVENT COMMANDS : = -
{event <#> <frame> <options>} Animation events. These vary quite a bit, but are the most fun.
Events can call either a sound, sprite, map trigger, or a programming code event that can do whatever you'd like.
example 1: { event 5004 1 "weapons\shoot.wav" }
Event 5004 plays this sound on frame 1. Include the path starting from your mod folder.
example 2: { event 5001 1 "20" }
Events 5001, 5011 and 5021 are for sprites, particularly muzzleflashes for weapons.
This example plays the mp5 sprite, muzzleflash1.spr on frame 1. "20" indicates that sprite # 0 is scaled 20 times larger than normal.
Below is a chart of muzzleflash sprites with the number that they are assigned to and what they're used for:
sprite number: name - use
0: muzzleflash1.spr - mp5 1: muzzleflash2.spr - shotgun, pistols 2: muzzleflash3.spr - hornetgun
An attachment point needs to be defined for these to show up in Half-Life. Event 5001 has it's origin at $attachment 0, 5011's origin is at $attachment 1, and 5021's origin is at $attachment 2.
example 3: { event 5002 10 "5" }
Event 5002 is for sparks. Here it plays on frame 10 and is scaled up 5 times. It's origin is the lowest attachment number, zero, unless you don't define zero. Then it will be at $attachment 1.
example 4: { event 7 2 }
This simply plays event # 7 on frame 2. Event 7 can be anything. This needs to be defined in the monster's AI code.
example 5: { event 1003 20 "bigexplosion" }
Event 1003 actually triggers a sequence to happen in a map, this one called "bigexplosion", on frame 20. These are most likely going to be part of scripted sequences and only happen once.
Here are examples for $sequence:
example 1: $sequence crouch_shoot_mp5 "crouch_shoot_mp5"
This is as simple as it gets, and is the minimum needed for it to work. crouch_shoot_mp5 is the animation name, and "crouch_shoot_mp5" is the actual animation file, without the .smd extension.
example 2: $sequence crouch_shoot_mp5 "crouch_shootdown_mp5" "crouch_shootup_mp5" blend XR -30 40 fps 20 origin 0 0 18 loop ACT_RANGE_ATTACK1 2 { event 5001 0 "40" }
This is how complicated the same animation can get. crouch_shoot_mp5 is still the animation name, but "crouch_shootdown_mp5" and "crouch_shootup_mp5" smd files are being blended together to create it.
Therefore the blend command is used, with the parameters of XR -30 40 to set the X-axis rotation from -30 to +40 degrees. The fps is adjusted to 20 to slow it down from the original file's setting of 30.
Since this is a crouching animation, the origin is lowered to bring the model's feet to the ground. It's a looping animation so the loop flag is set, plus this is a range-attack so it's labeled as ACT_RANGE_ATTACK1.
It could've also been ACT_RANGE_ATTACK2 since there are two of these attacks automatically set up in code. This activity has a multiplier of 2 so if there are others to choose from, the game will randomly choose this one 2 times more often than the others.
And finally event 5001, which is a muzzleflash sprite, plays on frame 0. "40" indicates that sprite number 0, or muzzleflash1.spr, is scaled 4 times larger than normal.
example 3: $sequence shoot "shoot" { { event 5001 1 "20" } { event 5004 1 "hks1.wav" } }
This example uses events to show a muzzleflash sprite and play a sound for a weapon shooting.
Studiomdl Commands
First is a list of the common commands for studiomdl, with parameters, a description, and an example:
$modelname <path>
This tells studiomdl where to put the final compiled model.
example: $modelname "C:\Half-Life\valve\models\player\Gordon"
$cd <path>
This directs studiomdl to start in this folder when looking for files. It's the same as DOS' "change directory" command.
example: $cd "C:\Half-Life\valve\models\source\Gordon"
$cdtexture <path>
This tells studiomdl where the textures are if they're in a separate folder from the mesh.
example: $cdtexture "C:\Half-Life\valve\models\source\Gordon\textures"
$externaltextures
This tells studiomdl to save skin textures as a separate *t.mdl file. The reason is skins only have to be loaded into memory when this model is in the player's view.
example: $externaltextures
$cliptotextures
This tells studiomdl to compile the skin textures in with the model. It's most commonly used with player models.
example: $cliptotextures
$scale #
This resizes the model up or down. If you want it smaller, make it less than 1; or more than 1 to make it bigger.
example: $scale 1.2
$origin <X> <Y> <Z>
This offsets the model's origin so, for example, it's feet are really on the ground. This is an easy fix if it wasn't done correctly when the model was made.
It can also be put throughout the .qc file to offset a model or animations. It's mostly used for player models and weapons.
example: $origin 0 0 36
$eyeposition <X> <Y> <Z>
This is for monsters to tell the game where their eyes are in reference to their origin. The origin is usually taken from the model, or can be redefined in the .qc file.
example: $eyeposition 0 0 65
$body <smd name> [reverse]
This is the reference .smd file for the model; the basic model with a skin. It can include the reverse command,
which flips all of the face's normals around. Reverse is used -only- in case problems occur exporting and normals are reversed by 3D Studio Max.
example: $body studio "monster" reverse
$bodygroup <groupname> {smd groups}
This lets your model have interchangeable parts. This example has a monster that can hold a shotgun, mp5 or neither.
The same setup can be used for interchangeable heads. Don't include the .smd extension.
example:
$bodygroup weapons
{
studio "shotgun"
studio "mp5"
blank
}
$texturegroup <groupname> {bmp groups}
This lets your model have interchangeable skins. This example shows how the normal body skin and normal head skin is replaced by a pain skin for each. Be sure to include the .bmp extension.
example:
$texturegroup pain
{
{ "body_normal.bmp" "head_normal.bmp" }
{ "body_pain.bmp" "head_pain.bmp" }
}
$renamebone <old bone name> <new bone name>
Character Studio versions 2.x and higher used different names for some of the Biped's bones. If you mix models or animations
from earlier versions then they need to be called the same thing. This command let's you easily rename all of them during the compile, instead of having to rename them in each .max file.
example: $renamebone "Bip01 R Clavicle" "Bip01 R Arm"
$include <.qc filename>
This tells studiomdl to include another .qc file in the compile.
example: $include "C:\Half-Life\valve\models\player\player_shared.qc"
$attachment <#> <bone> <X> <Y> <Z>
These are points referenced from bones that sprite effects are spawned from, usually muzzleflashes for weapons.
See the event command for more details about sprites. The coordinates are offset from the bone, not the model's origin.
example: $attachment 0 "Bip01 R Hand" 20 2 5
$controller <#> <bone> <axis of Rotation> <limits of rotation>
This allows the game to control the rotation of bones. The most obvious example is a monster's head, in example 1.
This allows the game to rotate the head from -60 degrees to +60 on the X axis. Example 2 shows how the mouth controller is set up so that this monster can talk.
example 1: $controller 0 "Bip01 Head" XR -60 60
example 2: $controller mouth "Bone03" ZR 0 45
$hbox <group #> <bone> <X> <Y> <Z> <X> <Y> <Z>
These define hitboxes, which are invisible boxes around each bone used to determine where the model is being shot at.
They are divided into 8 different groups listed below. All bones belonging in each group are defined to that hitbox group. The two examples below show the leg and foot being assigned to the same group, # 7.
example: $hbox 7 "Bip01 R Leg1" 0.31 -3.97 -2.84 17.60 3.94 2.97
example: $hbox 7 "Bip01 R Foot" -0.56 -2.34 -2.19 3.81 8.00 2.66
Hitbox Groups:
0: Generic 2: Chest 4: Left Arm 6: Left Leg
1: Head 3: Stomach 5: Right Arm 7: Right Leg
The two sets of coordinates are for one corner point of the box, and the opposite corner point. An easy way to get these
coordinates is to run studiomdl with the -h flag and have it output to a text file like this >hitboxes.txt. Your .qc file only needs the path and filename of your reference model.
example: studiomdl.exe -h gordon.qc >hitboxes.txt
You can see the hitboxes with the model viewers, or in Half-Life using the r_drawentities 3 command described in my list of console commands.
$sequencegroupsize <# in KB>
This separates the animations from the mesh into smaller files. The reason is that animations can be loaded into
memory only when needed, instead of having to load everything in whether or not it's used. It's most useful for monsters with scripted sequences.
example: $sequencegroupsize 64
$sequence <name> "smd" [motion extraction] [fps <#>] [blend <axis> <start> <end>] [origin <X> <Y> <Z>] [scale <#>] [loop] [frame <start> <end>] [<activity> <multiplier>] {event <#> <frame> <options>}
This is just an animation file, but it's by far the most complicated command. It includes many other commands, which are detailed below. Then below those are examples using the $sequence command.
Here are the sub-commands for $sequence:
[motion extraction] This is to extract out motion from animations such as walking and running.
The most common options for this are: X, Y, LX, and LY, which are for movement along the x and y axis. LX and LY are for linear movement.
I've found that X and Y work equally as well as LX and LY. You can extract from one axis or combine them,
and even from the Z axis. This motion will be used in Half-Life to move the monster.
[fps <#>] This sets the frames per second that the animation plays at, if you want to adjust it here.
example: fps 15
[blend <axis> <start> <end>] You can list two .smd animations and blend them together.
This is useful for shooting because you can animate at two extreme angles and the game blends between them to aim and shoot in the right direction.
This example blends from -45 to +45 degrees on the X-axis. It seems the angles are very important but the axis is almost arbitrary.
example: blend XR -45 45
[origin <X> <Y> <Z>] Same idea as $origin but only applies to this animation.
example: origin 0 0 13
[scale <#>] Same idea as $scale but only applies to this animation.
example: scale 1.3
[loop] Indicates that this animation loops.
example: loop
[frame <start> <end>] This limits the frames that are used from the smd file, to make post-editing easier.
example: frame 5 10
[<activity> <multiplier>] AI-controlled activities. The game automatically runs these animations without extra code.
This example has act_range_attack2 chosen since there are 2 types of range attacks, with a multiplier of 3.
This means there can be several animations using this activity, and this one will be randomly chosen 3 times more often.
Valve's Modeling Tutorial has a complete listing of these actions.
example: ACT_RANGE_ATTACK2 3
$texrendermode "texturename.bmp" "<rendermode>"
render modes: masked / additive