First let's talk about what this system is and why it exists in the first place. Source's animation system is both translational and rotational. This means that each animation frame tells the bone its location and rotation instead of only the rotation. As a result, the model size and proportions of a custom model are of no relevance whatsoever, rather the only thing that matters is the scale and proportions in each animation. The model's bones will be forced into whatever place the animation demands which means it may be squashed or stretched if necessary should the model not match the scaling needed.

How do we fix this then? You could technically ship a custom animation set for every single model but this is both time consuming and would nearly triple the size of any model you use which is extremely bad economically for servers using dozens or perhaps hundreds of models. Instead, we can cheat a little bit by using source's delta animation system. Animations in games are usually composed of several different layers. A walk cycle in GMod is usually a 9-way animation consisting of the 8 directions you can walk in and a centralized idle. If the player is armed, aimlayers, which are also 9-way animations may be blended with the walk animation so the walk will drive the lower half of the model (ex: pelvis and legs) while the aimlayer will control the upper half (ex: arms, shoulders).

Let's take a look at an example:

This sample shows the player walking with the shotgun aimlayer used. The animation can blend move_x with move_y for movements, aim_yaw and aim_pitch for aim direction, and additional head_yaw and head_pitch for look directions. Most animations likely don't use all at once but the engine is capable of it nonetheless.

With animation blending briefly explained, let's take a look at delta animations. Here's what one of the flinching animations looks like on its own.


It looks a bit strange, doesn't it? Let's first observe the collapsing bones. This is because the model shown uses the proportions system, so the bones are being moved. Let's instead take a look at what it looks like when it's blended with the correct t-pose animation.


Perhaps now it's a bit easier to see what's going on. In this animation, the player moves their head back while pulling part of their upperbody with it. The rest of the animation is t-pose though -- how on earth does that work? This is a delta animation so it's build as an additive animation instead. This animation isn't meant to be used on its own, instead it can be played on any other animation as a gesture. Let's look one last time at what the animation might look like when blended with a standard animation.


This looks a lot more reasonable now, doesn't it? This animation fits seamlessly on top of whatever current animation(s) are already playing. This is great for animations only meant to move a portion of the skeleton or meant to just be a small additive gesture on top of existing animations for things such as flinching when shot, fidgets, scratching a small itch, stretching, etc.

Now that you know what delta animations can be used for, let's take a deeper look into how they work. For this, we'll be looking at some of the code in the sample QC provided below rather than looking at a more complex example. These are the last 5 lines of the player QC provided:


Let's break it down. The first line defines the first sequence. This will be the model's original t-pose idle. For now, what that looks like isn't too relevant other than knowing it's just a standard t-pose. The next 2 lines aren't relevant for adjusting the player's proportions, they're only in that order to ensure 'reference' is the first animation. Instead, let's start from the 4th line. This is creating an animation that'll be used in the next line. $Sequences are the animations you see in-game while $animations are only used by the engine for handling advanced options. In this case, we're defining the animation and selecting the delta animation we'll want. It then subtracts the reference animation. The next sequence then defines the sequence using the $animation above and declares it as a delta animation. Let's break it down even further.


The first line will define the sequence, list its name, and list its path. We'll also set a low frame rate because the sequence we're using is only a single-frame t-pose. Standard animation systems usually have a global reference animation that all delta animations may subtract from. To adjust a player's proportions, we'll need our own which we can explain later. The second line will define the animation, list its name, list its path, then flag it as subtracting a sequence. The number following 'subtract $sequence-name$" is the frame to subtract from. Frame 0 is the first frame which works just fine for this instance. This $animation is never seen outside the engine. The next sequence will instead turn that $animation into a $sequence that can be used in-game and lists it as a delta animation. The autoplay flag will ensure the additive animation is always automatically played over every other animation which is essential to ensuring the sequence is actually used! This is only necessary for the proportions setup as standard delta animations typically shouldn't be autoplayed.

Since this is a bit of a repeat from before, let's instead talk about what this actually means. The animation we've just defined subtracts the first one listed. This means the differences between the 2 animations will be used as an additive animation. This will subtract the differences in both translation and rotation since that's how animations work. Assuming the bones are the same length and stay in the same rotation, the difference will be 0 which means the additive animation will also be 0. Let's instead assume we made an animation where the skeleton is identical to the one in the first sequence in every way but the $animation we're defining moves the head back a little bit and pulls the body with it. Since everything else lines up except for the short animation slight movements on the head and part of the upper body, this can now be overlayed as an additive animation that only moves the head and part of upper body similar to the flinch animation shown above. That may be a bit of a mouthful so let's see how we can exploit this.

The system was originally conceived as a way to deal with complaints regarding a certain stretched torso.


Since then, however, it's been useful in many other places from changing player height with no programming required to simply ensuring the best rig on your character. Even if your character is very close in proportions to the target animation set and you're fine with the default height, it can be a big help in rigging areas with small, condensed bones like fingers.


Left: first rig attempt (no proportions)
Middle: extensive clean-up to the rig (no proportions)
Right: a far easier speed-rig (with proportions)

It was originally common practice to squash and stretch your model to fit the skeleton which could result in some very strange looking models that were also common. Not only is that no longer necessary but simply ensuring better looking rigs can be a bit easier as well! This is particularly only recommended for playermodels and NPCs where you might want more control over your model's rig without needing to use a custom animation set.

Also note that although this can be great for things like rigging fingers, it usually won't work with first-person arms models due to how they're handled.

Before you begin you'll need to know a few things. First, you'll need to know what animation set you'll be replacing. This is vital since you'll be building your delta animation partly from the animation skeleton. If you're using GMod then you may want to know whether it'll use the male or female animation set. Whether it uses player or NPC animations isn't too relevant since each gender's player skeleton is basically the same as the NPC skeleton.

You'll want the standard biped for whichever target skeleton your model will be built on. I'll include a sample male and female Valve biped below in the resources section. If you need to decompile a model to obtain its skeleton, ensure you use a vanilla model rather than a custom one as they may have modifications to their skeleton and models using the proportions system do not decompile properly and may need their proportions files rebuilt.

The skeletons included below come with meshes, however the reference and proportions files ideally should have no mesh in their exported version. They also come with Valve's standard set of $proceduralbones which can be removed. The only bones necessary in the reference and proportions files are the standard biped bones (spine, arms, legs, head, etc). Any $proceduralbones or $jigglebones do not need to exist in the reference or proportions files and having them may make no difference other than in file size.

This system should work on just about any source game which means you can apply these same rules to just about any other source game such as L4D2 for instance. You may need a separate reference sequence for each survivor the model is compiled to.

Your model should not break the skeletal hierarchy of its target animation skeleton (for GMod and L4D2 for instance, you can't remove any of the spine bones or change the names). Your model should also have the same general orientation for each bone. This means that the angles don't need to match up perfectly but the correct axis needs to be facing the correct direction since the animation axis is set in stone for each animation. Bones facing incorrect directions may not animate properly.

For this part we'll assume you have your model rigged and ready to compile. We'll also assume you're following the rules listed in the preliminary setup above. Let's quickly go over some things you may run into and expand on what we discussed above. Note that I may need to simplify certain things so you can translate them into your own model editor.

The model is already rigged to a Valve biped but uses its own proportions and bone locations. Remember to ensure that the bone orientations also match up!


For this example I've isolated the spine. Let's say the animation expects the spine to bend forward:


For this, everything matches up and there are no problems. Rotations can differ slightly so long as the general orientation matches up. If the orientation doesn't match up and the spine expects to bend forward, you may get some undesired results!


Instead of the spine bending forward, it simply breaks because it's still expected to move on a certain axis which is now facing the incorrect direction. Ensure all orientations match your target skeleton's orientations!

Let's also quickly discuss hierarchy. Your model cannot under any circumstances remove bones in the middle of the hierarchy! You can however cheat a little bit if you have to. For this example, let's look at skeleton with 2 spine bones instead of 4 (kind of).


This skeleton may look like it uses 2 spine bones, but it actually uses all 4.


What we're doing is simply nesting the undesired spine bone(s) within its child. Seen here is the "Pelvis" bone (the bottom-most bone, positioned horizontally). Directly above it is the Spine bone (starting the vertical chain and containing a taper pointing downward). It's nested in its only child, "Spine1" (shown with the taper pointing upward).


Next we have "Spine2", the longest bone with a taper also pointing upward. The last bone, "Spine4" is nested within the neck and is shown with the taper pointing downward. This particular model is only rigged to the Spine1 and Spine2 bones while the Spine and Spine4 bones hold no weights and are "collapsed" into their child bone, however the model does not remove them. Note that although this works, it will double up rotations on the spine and can create undesired weight blending and as such it's better to simply use all 4 spine bones if when able.

Now that we've gone over some of the things you may encounter, let's assume you have the skeleton set up to your liking and start by creating our proportions file.

Here's what our model looks like currently:

The proportions file doesn't need to contain a mesh. You can use your model's reference file as the proportions file but for this we're going to make our own instead since it gives us more control which we can discuss further down. For now, let's remove the mesh and look at the skeleton alone.


Next, we can remove any of the non-standard biped bones such as those used as $jigglebones or those used as $proceduralbones. Attachment bones are also unneeded for this.


Our model has now about 53 bones for the core biped. A pelvis, 4 spine bones, a neck/head, 4 in each arm chain, 15 fingers, 4 in each leg chain (including toes). Any additional bones can be removed as well. Before progressing too far, now's also a good time to ensure the skeleton is lined up with itself and properly pointing at its children. Note that these changes must exist in the model's biped as well since at this stage the proportions skeleton should be identical. I see far too many skeletons with crooked bones such as this below!


Ensure the bones are lined up properly and instead look like the following:


Now that this skeleton has been isolated, it can be saved as proportions.smd (any name works so long as the changes reflect that in your QC later on)!

Now that the first pass of the proportions file is set up, we can set up the reference file. Remember that this skeleton should be the target skeleton of the desired animation set you plan on using. For this we're using the standard GMod female biped since we'll be using f_anm.mdl as our source of animations. We're basically going to treat it the same way as the proportions file initially. Remove any meshes and remove any bones other than the primary ~53.


Now that the core biped's been isolated, we can do some quick clean-up if necessary. This is mostly visual clean-up I need to do on my own end due to the modeling program I'm using and may not be required in your own.


The reference skeleton is now prepped. Let's talk once more about delta animations real quick. The difference between this skeleton and the proportions skeleton will be turned into an additive animation. This means we want to ensure we have no rotational differences between the skeletons at this stage. You'll want to match one skeleton's rotations with the other. The one used doesn't technically matter but for this example we're going to match the reference skeleton's rotations with the proportions skeleton's animations.

In 3DS Max I've saved the proportions file as an animation which I can import onto the reference file , then delete the translation and scale frames so it basically only carries over the rotational frames. If you don't know how to do this in your own model editor, manually rotating the bones should be fine, just ensure each bone of the reference skeleton is matched to each bone of the proportions skeleton. Let's take a look at what the difference will look like.

This is the original reference skeleton with no changes other than the clean-up.

This is the same skeleton with the rotations applied. Notice that things such as bone length, bone location, or general proportions on this skeleton do not change, only the rotations change. This will let us compile the model with changes only to the bone lengths since that is the only difference between these skeletons at present. We can take advantage of differences for our own benefit later on.

At this stage, we now need to make use of source's $definebones feature to ensure all of our bones are defined and in the correct positions. For this you can use Crowbar or GUIStudioMdl. While I personally perform standard compiles just using whichever branch of studiomdl and a batch script, The process of handling $definebones is a bit convoluted so I'd recommend either of the programs above. Neither are actually compilers but rather just add a GUI to the specified branch of studiomdl. Regardless, they'll both make defining bones far easier.

First, let's go back to either your model's standard skeleton or the proportions skeleton. We won't be using the reference skeleton. You basically just want to generate a short dummy animation that just moves all the bones. Viewing the QC Sample files provided below, this is the define_ref.smd file in the animations folder. The animation doesn't need to look pretty at all. I usually just create a frame with the standard t-pose set, then another frame created by selecting all bones and rotating them all on each axis.

For this, we really just want to ensure that we're starting using either of the modified skeletons that fit your model's proportions and use that to show the engine that they're all animated and thus necessary for the model. It might be helpful to create a separate minimalist QC such as the DEFINE.qc in the sample QC's directory provided below. This QC really only needs to have the directories, the model's meshes, and should only have a single animation with that being the one you create above. Remember, just ensure it's a simple animation that rotates each bone (ideally on each axis just for extra measure) and like the proprtions file, you only need to define the core bones. Jigglebones don't need to be run through the define stages, however, please note that $proceduralbones often need to be defined to ensure they aren't collapsed instead!

Once you've created your animation and QC for definition, you'll want to run it through Crowbar or GUIStudioMdl with the Define Bones option checked. The result should be a little something like this:


If you're having trouble with the definitions you can try generating this set with different engine branches if need be. Once these are generated, select the table it generated and ensure you have all instances of $definebones.


When you have them all selected, you can copy and paste them into your QC file and ensure all previous instances of $definebones are removed. If you're still using the sample QC provided you can paste this code over the existing instance in the commonbones.qci file located within the QCIs folder. Before proceeding, also note that some engine branches seem to generate anomalies within the generated definition table. Double-check to see whether you have them and clean it up. All of these anomalies are the same so you can even use something as simple as Windows Notepad or your Mac / linux equivalent so long as it has a replace function. Because all of these instances look the same (if it occurs), just select whichever is the easiest one for you to find. For my example, one was generated partially within the $definebone command which made it far easier to deal with.


Once you've selected it, use whatever replace function in your text editor to replace all instances and just leave the "Replace With" field blank to delete all instances instead. In most Windows text editors, Ctrl + H will open the Find and Replace function. Opening it with the text highlighted will automatically put it in the "Find" field and just use "Replace All" to clear all instances, then double-check to ensure everything's cleaned up with no remaining text anomalies.


I personally haven't run into an engine branch yet generated different anomalies each time so as long as you properly selected one instance of the text anomaly and replaced all, you should've successfully gotten them all. Some of the newer branches may not have this problem at all and Crowbar doesn't seem to have in the GMod or SFM branch other issues may arise instead so experiment if you must! If no anomaly appears you can just leave the test as is.

At this stage, the model can be compiled for your initial testing.


Remember to view your compile log and diagnose any problems that may occur if necessary as well. In the event your model fails to compile and returns "ERROR: 'EXCEPTION ACCESS VIOLATION' (assert 1)" you've probably run into a generic engine limitation. This error may occur if you have too many $bodygroups, too many polygons, etc. Limitations may vary based on the branch of the engine you compile to. Some can be [partially] bypassed, some can't be.

I personally tend to compile to SFM first so I can use SFM's hlmv tool which is a bit more advanced than GMod's is. Let's take a look at how we did.


This particular compile worked nearly flawlessly but does have one issue worth visiting. The second issue, the tearing around the elbows, is actually due to the elbows needing new values in our $proceduralbones VRD file. This isn't related to the proportions setup we did so we'll ignore that for now.

At this stage your own model may be done. If, however, like me your model has any clipping (in this case the issue worth visiting I mentioned above is the hands clipping with the pelvis), we can deal with that now. If your model is really tall, has a dress, or has a similar issue that may cause clipping, let's move to the first stage of polish.

There's usually a couple things you may want to look at in this stage. Let's go over delta animations one last time. The reference sequence is defined, the proportions animation is defined and subtracts the reference sequence, then the additive proportions sequence is defined and autoplayed. We've built the first pass ensuring the only differences between the reference and proportions animations are the bone lengths. With that out of the way though, we can talk about using the differences to our advantage.

In this particular case I'm going to push each arm out about 10 degrees. This will unfortunately modify every animation so remember to use it sparingly, but this will ensure the arms don't clip with the pelvis. Here's what the end-result for that would look like:


This particular instance is nearly done, however also note that for larger models you may want to push the pelvis up or down to ensure the player's feet properly connect with the ground or to ensure their legs don't clip with eachother. Here's an example of a larger model:


Creating massive models is a bit more difficult but if we push the pelvis up in the proportions file, the difference between heights of that and the reference file will result in the pelvis being pushed up in-game so the player won't have their legs half in the ground. This can also be used for shorter models to push them a bit further back into the ground.


Doing this can let us create a model that's properly ~8 feet tall, however for this particular case we'll also need to push the arms and legs out from the body a little bit to reduce clipping.


We can now utilize the differences to our advantage. Remember that this will affect all animations for this model so use it sparingly!

We're nearly at the end, now!

There isn't a whole lot that needs to be said here thankfully. Once everything is set up to work with the proportions system, the ragdoll can be built on the modified proportions skeleton, the same one the meshes are rigged to. For the ragdoll sequence you can just recycle the reference.smd as the source. Thanks to Kilburn's efforts when he was with the Facepunch team, changes to the way ragdolls were handled in GMod allow them to support this system far easier. Other than building a ragdoll on your modified skeleton and ensuring you still define the ragdoll animation, the rest is largely handled the same way you'd normally handle it.

Playermodels (as well as NPCs and similar models) use IKChains to help connect their feet to the ground. This lets the player stand on uneven surfaces by pushing the feet up and bending the knees. For this particular instance we'll be taking a look at the sample QC file's ikchains.qci file (located in the QCIs folder). Let's take a look at the lines you may need to modify for this.


The code above contains the feet IK values used for the first model we've been working with. Of the two values listed, the first is the value for the position of the foot and the second is for the angle. Models with drastic changes in height may need to modify the angle a little bit but most models may only need to modify the position. While 0.5 works for this model, your own model might work better with 0.25, 1.0, or 0.1 for instance. Experiment and see what works best.


For best results use hlmv with the ground toggled on and ensure the position value is adjusted so the foot sits as close to the ground as possible with as minimal clipping as possible. I personally use the animation "menu_walk" for ease of use. Animations such as walk_all will also work if you adjust the move values but refreshing the view when you recompile the model will reset the move values each time! You can also slow the animation down with the slider directly below the 5 boxes you can use to set animations to ensure it's easy to see where the feet connect.



Once the feet connect properly you may also want to adjust the pelvis height so it sits just low enough that the legs no longer snap while trying to connect with their IK Target on the floor.

It's worth noting that L4D2 and GMod don't make use of your model's bounding box values and have no way to change the view height. L4D2 will instead change these depending on the survivor used. GMod supports changes via lua that are actually pretty easy to handle and implement but be mindful in your uses as it could give a player an advantage or disadvantage based on model.

I'll include the GMod parameters below should you wish to change them anyway. Without changing these values, the view height will remain default meaning your height shown in first-person may not line up with your model's eye position. The same applies to the player hull which is the player's collision bounding box while active and alive (not a ragdoll). Should this not match up, players given a significant increase in height might clip through things like doorways while players given a significant height decrease might not fit into smaller crevices that their height suggests they should fit into with no issue.

NOTE: If you change the player's view height or hull, ensure you change their values for their equivalent duck function as well and reset it when the player changes models!

As one last reminder, the proportions system can work in just about any Source game. Just ensure the reference animation starts from the target animation biped. For GMod note that this method cannot be used on c_arms and cannot be used with L4D2's v_arms as both of these models are bone-merged onto the weapon's animations. For best results you may need to squash and stretch the model to fit as close to the target mesh as possible.

It's also worth noting that this system is a pretty hacky way of doing things in general. Models can for the most-part be as exaggerated as you like but models that are too small may have trouble with crouching animations resulting in them being partially or completely buried. Weapon models are also automatically bone-merged onto your hand and are always the same size so playermodels with heavy exaggerations in one way or another may have trouble with their hands properly holding weapons. I've experimented with fixing this by moving the proportions system into the animation instead which seems to work (even without manually adjusting all of the animations), but doing so defeats a large reason for using this system in the first place.

Also note that decompiling models with custom proportions may require that you rebuild them and decompiling animation files is strongly discouraged due to things like animation macros being completely truncated on compile.

As long and menacing as this guide may be, most of it was me trying to compile years of experiments to cover as many possibilities and errors you may run into. I'm not the best at explaining things which is partly why I've held off on writing this guide for so long (along with not expecting this to blow up so much and being seemingly the only one in the world that doesn't use Blender). Once you understand how the system works it's actually pretty darn easy to do just about anything with, though it's certainly worth understanding any issues or problems that this system has or can't fix.

Lastly, if you can't understand my convoluted explanations I accept just about all friend requests and would be happy to help you, though unless you use 3DS Max, I probably can't help you with anything specific to your model editor! I'll try to clean this guide up to make things easier to understand or add anything I may have missed if necessary. Thoughts and criticism are always welcome.

Sample QC (used extensively in guide)[www.dropbox.com]

GMod Male Player Skeleton (FBX)[www.dropbox.com]
GMod Female Player Skeleton (FBX)[www.dropbox.com]
GMod Male Player Skeleton (SMD)[www.dropbox.com]
GMod Female Player Skeleton (SMD)[www.dropbox.com]

Various examples of c_arms as well as GMod's animation sets' source[source.maxofs2d.net]

Valve's Sample QC Files from the pre-steampipe era[www.dropbox.com]

Crowbar

$definebone documentation
$sequence documentation
$animation documentation
$ikchain documentation
Additional QC documentation

Player:SetViewOffset (GMod only)[wiki.facepunch.com]
Player:SetViewOffsetDucked (GMod only)[wiki.facepunch.com]
Player:ResetHull (GMod only)[wiki.facepunch.com]
Player:SetHull (GMod only)[wiki.facepunch.com]
Player:SetHullDuck (GMod only)[wiki.facepunch.com]