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.



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:

$basetexture
$bumpmap
$model
$nodecal
$phong
$phongexponent
$phongboost
$phongfresnelranges
$phongexponenttexture


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.

Conclusion

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.

- Jed

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.

good read :)
now this should get the custom guys rolling!

I get light headed from reading this... ;)

Well I expect to see combine soldiers to go with the orange maps now.. lol :D

Good read Jed!

By default, the whitelist that ships with DoD:S allows custom content in the models/player and materials/models/player folders

That's interesting too, all that info may be enough to get some interest back in custom player models? I would love to see some conversions to other countries like brits... well anything really :)

Thanks for taking the time to explain those two issues.

I have been looking at the design of the GUI stuff and how to tidy it up so it is custom on some servers... but when it strikes a sv_pure problem it defaults to the standard images instead of ending up with a heap of crossed out white boxes.

Like your post, it's a matter of using correct technique for the game you are customizing.

Thanks a lot.

Good info.

The check for bad materials is also performed on player models in non-default directories if that's how you compiled them. You'll still need to specify crc in the whitelist though for the .mdl and textures. We use about 12 custom player models in addition to the standard ones by utilizing the mani model changer.

SourceMod has a model changing plugin as well now, although it's not finalized yet.

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.

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?

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?

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?


I may be horribly wrong but i think weapon physics is server side.

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.

Updated the first post with some info on bounds.