Bodygroups, Gibs, Ragdolls and Decals tutorial - Underhell mod for Half-Life 2

Very early on in the development, I knew I wanted a dismemberment system, which is why for Prologue I relied on SMOD and made my own "Gib" models, the system was experimental and buggy, but it was okay.

But now that Carlos is on the team, I was able to design a more thorough system for said dismemberment, as well as a few other add-on along the way.

BODYGROUPS

Bodygroups are a part of a model that can be toggled on and off at will via ingame code, or a hammer input. There can be multiple and different "Bodies" within that group.
A perfect example is a Helmet Bodygroup, which can have multiple sets of helmets, and thanks to this you can change the helmet on an NPC with just changing the bodygroup "Helmet".

Unfortunately the Hammer input that came along with the Source Engine was very vague, see there are 2 ways to Identify bodygroups, either via the Group name and the Value of the bodygroup, or via a binary calculation code that will "add" each part of the bodygroup to each other and render it to a number, like the FLAGS system in hammer.

Unfortunately when you have over 5 bodygroups each with 2 or 3 models per group, this value can go over a thousand, since there has to be a number for each combination of any Group/Value.

This is why a String Parser was added to a Hammer Keyvalue we implemented, to facilitate BodyGroup selection via Hammer :
Say you have a Bodygroup named "Arms", a Bodygroup named "Legs" and a Bodygroup named "Helmet".
In Hammer, you want him to have Helmet number 2, Arms number 1 and Legs number 4.

The value to enter in hammer would be the following :

uh_bodygroup : Helmet2Arms1Legs4

The string parser "separates" strings and numbers to form the correct values, and reads them accordingly.
This is a VERY powerful and risky system, if you enter a wrong bodygroup, the game WILL crash.
Just double check your bodygroup names on the models you are using, and it should be fine.

Here is a quick list of Underhell's Soldiers Bodygroups :

COMBINE_SOLDIER.MDL :

Droppeable helmet model : models/items/helmet_visor.mdl < Has 4 bodygroups "HELMET" for NOVISOR, NOVISOR, VISORUP, and VISORDOWN respectively.
Droppeable riot shield model : models/items/riotshield.mdl
Droppeable ballistic shield model : models/items/ballisticshield.mdl
GIBS : models\Gibs\BodyParts\Soldier\

leftarm.mdl
rightarm.mdl
leftleg.mdl
rightleg.mdl
leftleg2.mdl
rightleg2.mdl


Skins : 0-3

0 : White arms
1 : Tanned Arms
2 : Black Arms
3 : Long sleeves

Head - 0 - Regular Head
Head - 1 - Destroyed Head

HELMET 0 = NO HELMET
HELMET 1 = HELMET - No visor
HELMET 2 = HELMET - Visor Raised
HELMET 3 = HELMET - Visor < - Protects Face

Armor - 0 - Regular Armor
Armor - 1 - Heavy Armor < - 50% damage on Torso and Stomach

ARMS - 0 - Both Arms
ARMS - 1 - No Left Arm
ARMS - 2 - No Right Arm
ARMS - 3 - No Arms

Legs - 0 - Regular Legs
Legs - 1 - No Left Regular Leg
Legs - 2 - No Right Regular Leg
Legs - 3 - No Regular Legs
Legs - 4 - Heavy Legs < - 50% damage on Legs
Legs - 5 - No Left Heavy Legs
Legs - 6 - No Right Heavy Legs
Legs - 7 - No Heavy Legs

COMBINE_SOLDIER_PRISONGUARD.MDL :

Droppeable helmet model : models/items/helmet.mdl < Unlike the other helmet, has no bodygroups for visors
Droppeable gasmask model : models/items/gasmask.mdl
Droppeable riot shield model : models/items/riotshield.mdl
Droppeable ballistic shield model : models/items/ballisticshield.mdl
GIBS : models\Gibs\BodyParts\Soldier_PrisonGuard\

SKINS:
NONE (Just Default one)

leftarm.mdl
rightarm.mdl
leftleg.mdl
rightleg.mdl

(Legs 2 are in the main soldier folder, since they are the same as original's soldiers LEGS2)

Head - 0 - Regular Head
Head - 1 - Destroyed Head

HELMET 0 = NO HELMET (For when Gasmask and Helmets are shot off)
HELMET 1 = HELMET - Simple Helmet
HELMET 2 = HELMET - Simple Helmet
HELMET 3 = HELMET - Simple Helmet

GasMask - 0 - No Gas Mask
GasMask - 1 - Gas Mask

Armor - 0 - Regular Armor
Armor - 1 - Heavy Armor < - 50% Damage on Torso and Stomach

Legs - 0 - Regular Legs
Legs - 1 - No Left Regular Leg
Legs - 2 - No Right Regular Leg
Legs - 3 - No Regular Legs
Legs - 4 - Heavy Legs < - 50% Damage on legs
Legs - 5 - No Left Heavy Legs
Legs - 6 - No Right Heavy Legs
Legs - 7 - No Heavy Legs

More BodyGroup lists will be added soon...

GIBS

The gibs are engine generated ragdolls, that do not enter the same category as usual ragdolls.
When a body part is shot off, the Bodygroup of the original model is changed to "remove" that part on it, and a "gib" is spawned at the correct body attachment to make it look like it was "detached" from there.
The gibs models were carefully "severed" from their original models at the exact same location where the original model's bodygroup is cut.

The following console commands allow to set the desired effects :

uh_gibhealth (80): How much damage to inflict to gib a bodypart (This value is for legs, Arms is 50% that value)

uh_headhealth (21): How much damage to inflict to destroy the head.

uh_helmethealth (30): How much damage should a helmet take before being "shot off" the head of the NPC.

uh_maxsergibs (8): How many Server Side gibs can there be in the level before the oldest one is turned into a clientside ragdoll.

RAGDOLLS

The Ragdolls in Underhell aren't just "neat visual effects" they are real entities that can be interacted with.
If specified, NPCs will fire an OutPut when a ragdoll is spotted, triggering any desired effect.
Players can therefore pick up any "limb" on a ragdoll like a physic object and drag them around to hide the ragdolls, therefore avoiding detection in some situations where "discretion" is important.
Dragging ragdolls will leave a "Blood_Drop" decal specific to this behavior, it looks lighter and different than other blood decals.

Ragdolls can also be "dismembered" completely (head, arms and legs).

The following console commands allow to set the desired effects :

uh_ragdollcollisiontype (11): What collision rules should the ragdolls follow. 
0 = Everything, including other Ragdolls, NPCs and Player
1 = Doesn't collide with anything (Debris ragdoll for heavy battles)
11 = Everything, except NPCs and Players.

uh_maxseragdolls (16): How many Server Side Ragdolls can there be in the level before the oldest one is turned into a clientside ragdoll.

uh_bodymousedamper (4): A speed divider for when Player is dragging a ragdoll, the Mouse's sensitivity is temporarily reduced by this divider to give an illusion of "weight"

Hammer placed prop_ragdolls are excluded from any of those rules, they will not be turned to clientside.

The Keyvalue to add to an NPC to make them find bodies is the following:

uh_SpotBodies (0-1)

An input can also be called to toggle this function On and Off

SetSpotBodiesOn
SetSpotBodiesOff

When the SpotBodies is on, the NPC will fire the following outputs when they spot a body:

OnSpotSoldierBody : Fires when a Soldier body was found
OnSpotI******dBody : Fired when a SPOILERS body was found
OnSpotDefaultBody : Fired when any other type of npc ragdoll was found

In this output link "!caller" is the body itself, and "!activator" is the NPC who spotted the body.

Here's a way it can be used :

OnSpotSoldierBody !Activator WalkToEntity !caller

This output will make the person who found the body (!activator) Walk to the dead body (!caller)

DROPPED OBJECTS

Some enemies will drop random objects upon death.
This "loot" is not only randomized but dynamic, an enemy with a helmet will drop it if you shoot his head, an enemy with a riot shield will drop it, ect...

There are functional items, such as the helmets that give the player "Armor" points when picked up, but there are also "Cosmetic" objects, like gibs that detach when shot.
GasMasks or respirators is a good example.

The following console command allows to limit these "dropped objects" for optimization purposes.

uh_maxitems (16) : Limits the number of enemy dropped items and objects.

DECALS

Underhell's Decal system has received a bit of a overhaul as well.
Here are the new Decals :

Blood: Default Blood Decal, used for bullet wounds, and strong ragdoll impacts.

Blood_Drop: Used when dragging bodies or limbs around.

Blood_Trace: Used only for headshots or "destroyed head" events, looks "thicker" and "brainy" bloody matter.

AceBlood: Oily Brown blood, for a new type of NPC.

New decals isn't the only change that has been made to the decal system.
The "Blood" decal's shader has been modified to receive better lighting.The shader type has been split into 2 types :

1. "LightMappedGeneric" lighting when sprayed on brushes (wall, floor, ect..)
2. "VertexLitGeneric" lighting when sprayed on models (Npcs, props, shields, vehicles, ect...)

This gives a unique look to the blood, that reacts to the flashlight's light, instead of just "disappearing" when lit, which is a common Source Engine glitch.