View Full Version : Custom player models - how to pass the consistency test

02-08-2008, 12:32 PM
Theres been a bunch of threads floating around of late regarding modifying and creating new player models for Day of Defeat. Custom player models are certainly possible under Source, but many are falling foul of the consistency check and finding their models won't load. There's little solid information and a lot of mis-information on how to make custom player models work. Hopefully this post will clear some of this up.

This post was based on my experiments to port one of the Male NPC characters from HL2 to work in DoD Source. The goal was to have a custom model that would work with servers that allow them via sv_pure and sv_consistency set to 1.

http://img67.imageshack.us/img67/88/doddonner0000kz2.th.jpg (http://img67.imageshack.us/my.php?image=doddonner0000kz2.jpg) http://img212.imageshack.us/img212/3854/doddonner0002er6.th.jpg (http://img212.imageshack.us/my.php?image=doddonner0002er6.jpg) http://img212.imageshack.us/img212/5901/doddonner0005rh8.th.jpg (http://img212.imageshack.us/my.php?image=doddonner0005rh8.jpg) http://img236.imageshack.us/img236/4353/doddonner0007om1.th.jpg (http://img236.imageshack.us/my.php?image=doddonner0007om1.jpg)

My thanks go to Matt Boone (Mugsy) and Mike Durand at Valve for passing on some of the internal information from DoD and letting me look at the code for the consistency check mechanism so I could analyse it.

NOTE: This is not a guide on how to make a custom player model, just how to get it to pass the consistency check so you can use it on-line.

Some background on sv_consistency and sv_pure

Source uses two systems to allow and check the "legality" of custom player models.

The first, is the sv_pure server variable which allows certain custom content via a "whitelist" held on the server, or locks down the server to use the default models from the GCF. You'll find that unless the defauly whitelist has been editied, servers running sv_pure 0 or sv_pure 1 will allow custom player models. By default, the whitelist that ships with DoD:S allows custom content in the models/player and materials/models/player folders

Allied to sv_pure is sv_consistency which does the actual phsyical checking of files for their "legality".

* The first check it does is the CRC (http://en.wikipedia.org/wiki/Cyclic_redundancy_check) check of the model against that on the server to see if they match.

* The second check is a "bounds" check which compares the bounds defined in the model against a pre-defined set of maximums set in the game. The bounds stored in the model itself are calculated when it's compiled and cant be changed.

* The third and final check is that all the materials that the model uses are "simple". This means they dont use any exotic shaders or paramters which might result in the player having an unfair advantage over others.

NOTE: The use of sv_pure and a whitelist makes the first check pretty redundant as it will allow custom player models anyway. However, the bounds and material checks are still performed!

Figuring out your problem

The first part of solving consistency issues to to diagnose what exactly the problem you are having is. For that the console and observation are you friend. Heres a list of common scenarios and probably causes.

* I have a custom player model but all I see in game is the default mode/texture
The server is probably running sv_pure 2 or has an edited/custom whitelist. While you can't check the whitelist, if you type just sv_pure into your console while connected to the server, it will tell you what it's setting is.

* I get a message "Server is enforcing consistency for the following files: models/player/XXXX.mdl" and it dumps me back to the menu.
This message appears when you fail to pass one of the sv_consistency checks. To find out which test you failed, open the console and look for the message in red and compare with the list below:

Bad CRC for XXXX.mdl
You've failed the CRC check where the model is compared to the CRC on the server. This error *shouldn't* appear since sv_pure was introduced.

Model XXXX.mdl exceeds mins (X Y Z vs. A B C)
Model XXXX.mdl exceeds maxs (X Y Z vs. A B C)
You've failed the bounding volume check where the model internal bounding box is outside the maximum sized defined inside DoD:S. Basically this is caused by your model mesh having parts that are significantly larger than the default model which push it outside the bounds box.

Model XXXX.mdl has a bad texture YYYY
The named material on your model has failed the legality check. The message is a little misleading as it's checking the VMT and not the actual VTF file. This is probably the most common error and we'll cover in detail next.

Bad bounds - how and why

Fixing bad bounds is probably going to be the trickiest part of making a custom player model.

Inside DoD:S is a pre-defined "bounding box" which defines the maximum limit any part of your mesh can move to during any of the animation sequences. In theory, for all the animations, no part of your model should every break outside the "walls" of this bounding box.

The current bounding box for DoD:S is defined as follows:
const static Vector mins( -13.9, -30.1, -12.1 );
const static Vector maxs( 30.9, 30.1, 73.1 );
engine->ForceModelBounds( szPlayerModel, mins, maxs );

Unfortunately there is no magic formula to calculte what the maxium dimensions of your player model can be. Because the models bounding limits are calculated at compile time it's a little tricky to give a definate answer.

However, if you fail the consistency check and you look in the console, you'll see one of the Model XXXX.mdl exceeds mins/max messages with a set of numbers. The first 3 numbers, are the bounds for your model, the second three are the DoD:S defaults.

Theres no golden rule for fixing the issue, but in general, compare these numbers and how far off the maxium you are. That should give you some indication of how much you have to reduce the limits of your model to get it to work.

Bad textures - making them "legal"

As mentioned previously, one of the consistency checks looks to make sure that the materials your model uses don't use any special shaders or parameters to gain an advantage over others. This is done by allowing only the VertexLitGeneric shader type and with a limted set of paramters.

At time of writing, you may only use:


Using anything other than these will cause the texture to fail the consistencycheck with the Model XXXX.mdl has a bad texture YYYY message.

The Checklist

The following is a list of things you should avoid and check for when creating a custom player model. Hopefully it will solve consistency problems and let you play with and share your models with others.

AVOID player models that are significantly larger than the default models. Things like tall headgear or extrememly large equipment packs can cause a bounds check failure.

AVOID using the HL2 "Eye" or "Teeth" shaders. Using either of them will fail. As a result, setting up your model for eyes is a pointless exercise and you should probably just stick to regular textures.

AVOID using flex controllers for face/body morphing. This can in extreme cases cause changes in the models geometry which could cause it to fail the bounds check.

CHECK that all your models VMT and VTF files are under materials/models/player and that you're player models under models/player.

CHECK that your VMT files use only the VertexLitGeneric shader and parameters from the allowed list. Using anything else will fail the consistency check with bad texture messages in the console.


So as you can see, custom player models are possible as long as you comply with the checks. Most likely you'll fall foul of the material checks but you should check the console for any messages that might tell you what else is going on.

The actual process of making a custom player model, rigging and setting up the QC file is out of the scope of this article but may be covered at a later date in a seprate thread.

Well thats it for now. If any more information comes to light I'll update this article.

02-08-2008, 12:42 PM
Just a follow up...

No checks are done against the hitboxes or physics model.

This seems to be a populer belief and it is in fact, completely false.

02-08-2008, 12:43 PM
What about the ragdoll physics.

Do the objects ragdoll the same for every player, so for example when your are proned and you are facing a dead body on the ground, that will block _your_ view.
If it was calculated locally then only _you_ would have the problem of the physics ragdolling that body there.

Ragdolls are client-side so the ragdolls are never in sync between players. When you die the client just hides your player model and spawns a ragdoll in its place with whatever impulse is relevant. I think less that 0.5% of Source based games/mod use server-side ragdolls because there VERY expensive in terms of bandwidth.

And what about custom props or charaters.

For example if you replace the thompson world model for a grenade, then it will ragdoll differently in the world, and it will end up elsewhere, cause of the collision differences, is that true?

Logically, dropped weapons/grenades need to be handled server side so that everyone sees them in the same place. As the server is handling that, it should mean that the server uses it's local, default models to calculate collisions and physics.

And what about the size for your player model.

How can you determine the maximum size of parts beyond the default model, that pass the concistency check.

For example if I have a player model that has a backpack added to its back or has got a long hat on his head.
And how does that affect the ragdoll physics?

The consistency hull is pre-defined in game and the hull for your player model is calculated when you compile it. If you compile it and get one of the bounds errors, it will show you how much your model is exceeding the bounds limit.

The bounds hull is there to specifically prevent you doing stuff like putting big spikes on models. As long as you make a new model which conforms approximately to the original models dimension without any extreme differences it should work.

The player model itself has ZERO effect on ragdoll physics. That's all determined by the physics model and bone weight/constraints.

07-17-2008, 07:58 PM
Have you been able to look at this again since dods has gone to the orangebox engine?
My decompiler only works from sourcesdk\bin\ep1\bin, not from sourcesdk\bin\orangebox\bin :eek:

07-18-2008, 05:09 PM
Seems to be working fine again.

09-09-2010, 02:48 PM
i made some models, the work fine. But if one of my models gets a headshot, i can see the helmet fly away, but the model got still a helmet. How i can fix it?

09-23-2010, 01:40 AM
If you've modeled your model helmet seperately from the player, then reference it in the .qc with the line:

$bodygroup helmet
studio "yourhelmetname.smd"

See the .qc file sourcesdk_content\dod\modelsrc\player\blue\blue_pl ayer.qc for an example

See also http://developer.valvesoftware.com/wiki/Body_Groups

09-24-2010, 01:24 PM
If you've modeled your model helmet seperately from the player, then reference it in the .qc with the line:

$bodygroup helmet
studio "yourhelmetname.smd"

See the .qc file sourcesdk_content\dod\modelsrc\player\blue\blue_pl ayer.qc for an example

See also http://developer.valvesoftware.com/wiki/Body_Groups
my models got two bodygroups body & helmet.

09-24-2010, 11:32 PM
The helmet model attached to the head actually never leaves - the visibility of it just gets toggled on/off. If you look closely at a headsplattered player, you can see the outline of the helmet covered in blood. What you see flying off is a different model.

But if your helmet never gets toggled on/off, make sure you include the word blank as shown above. If you don't, it will remain visible.