$jigglebone

$jigglebone is a QC command available in all Source games since Source 2007. It marks bones within your model’s skeleton as "jiggle bones" and tells the game engine to dynamically simulate them during runtime, allowing for realistic secondary motions such as wiggling antennas, bouncy flesh, floppy ears, and so on.

Warning:The simulated tip of jiggle bones extends in the +Z axis of the bone, bones intended to be jiggle bones should always be orientated to account for this fact when creating them in the model editor.

Warning:When the parent of the jigglebone has a procedural bone($proceduralbones), there may be unanticipated wobbling. Try to adjust the axis of the procedural bone to the same axis as its parent.

Important:If you want your jigglebones to be influenced by animations before jiggling, compile your animations to a seperate .mdl file and $include that .mdl in the compile. Do not compile the animations directly into your model file.

A tutorial for adding jigglebones can be found here.  For Blender users: here. It is important to understand the methodology of jigglebone axis alignment in order to achieve intended results. This video explains it in overly simplistic terms.

The assumed orientation of a Jiggle Bone.

Syntax

$jigglebone <name> {
	<property group> {
		<property> <value> [<value>]
		...
	}
}

Where <name> is the name of the joint tip.

There are currently four types of "property groups":

• is_rigid
• is_flexible
• has_base_spring
• is_boing (only in )

Each group is optional, but is_rigid and is_flexible cannot be used together. has_base_spring and is_boing also cannot be used together.

Examples

Here are a few examples:

$jigglebone "Floppy" {
	is_rigid {
		tip_mass 100
		length 20
		angle_constraint 60 
	}
}

$jigglebone "JigglyUpAndDown" {
	is_flexible {
		yaw_stiffness 100
		yaw_damping 3
		length 20
		yaw_constraint 0 0
	}
}

$jigglebone "Bouncy" {
	has_base_spring {
		stiffness 100 
		damping 1 
		left_constraint -20 20
		up_constraint -20 20
		forward_constraint -20 20
	}
}

$jigglebone "SubtleBounceWithALimit" {
	has_base_spring {
		base_mass 5
		stiffness 800
		damping 10
		left_constraint -0.5 0.5
		up_constraint -0.75 2.0
		forward_constraint -0.25 0.25
		left_friction 10
		up_friction 10
		forward_friction 10
	}
}

$jigglebone "FloppyAndBouncy" {
	is_rigid {
		tip_mass 100
		length 20
		angle_constraint 60 
	}

	has_base_spring {
		stiffness 100 
		damping 1 
		left_constraint -20 20
		up_constraint -20 20
		forward_constraint -20 20
	}
}

$jigglebone "ConstantBoing" {
	is_boing {
		impact_speed 0
		impact_angle 0
		damping_rate 0.0
		frequency 20.0
		amplitude 0.2
	}
}

From the Antlion Worker:

$jigglebone "Antlion.glasswingR_bone" {
	is_flexible {
		yaw_stiffness 700
		yaw_damping 6
		pitch_stiffness 700
		pitch_damping 8
		tip_mass 5
		length 30
		angle_constraint 37
	}
}

Tip:Utilize $definemacro to jiggle multiple bones that all need similar calculations. On complex models this will drastically reduce your setup and testing times, and save a lot of space in your QC. Bones renamed with $renamebone must be listed with their renamed names in jigglebone macros.

Macro example

$definemacro skirt_j bone stiffness damping mass length   \\
$jigglebone $bone$                                        \\
{                                                         \\
	is_flexible {                                     \\
		yaw_stiffness $stiffness$                 \\
		yaw_damping $damping$                     \\
		pitch_stiffness $stiffness$               \\
		pitch_damping $damping$                   \\
		tip_mass $mass$                           \\
		length $length$                           \\
		pitch_constraint -10 20                   \\
		yaw_constraint -25 25                     \\
	}                                                 \\
}
$skirt_j  skirt_F_1_R  50 12 550 25
$skirt_j  skirt_F_2_R  50 10 500 20
$skirt_j  skirt_F_3_R  50  8 450 15
$skirt_j  skirt_F_4_R  50  7 450 20
$skirt_j  skirt_F_1_C  50 10 600 20
etc..

Springs

Springs are simulated by specifying stiffness and damping values. Stiffness determines how stiff the spring is. A low value such as 10 is very loose and weak, whereas a value of 500 is very stiff and springy. Legal values range from 1 to 1000.

Damping is a kind of spring friction or resistance. A value of zero means the spring will oscillate forever. A damping of 10 causes the spring to stop vibrating almost immediately. Legal values range from 0 to 10.

is_flexible

If a Jiggle Bone is "flexible", a simulated mass is placed at a set distance to the bone in the +Z axis, and the bone acts like a springy, flexible rod. This spring creates rotational motion only, with the center of rotation at the base of the Jiggle Bone.

yaw_stiffness

How stiff the spring is in the local yaw rotational axis.

yaw_damping

Damping along the local yaw rotational axis. Small values result in dramatic jiggling. Larger values result in more subtle motions.

pitch_stiffness

How stiff the spring is in the local pitch rotational axis.

pitch_damping

Damping along the local pitch rotational axis. Small values result in dramatic jiggling. Larger values result in more subtle motions.

along_stiffness

How stiff the spring is along the axis of the spring. This is only used if "allow_length_flex" is specified for this bone.

along_damping

Damping along the axis of the spring. This is only used if "allow_length_flex" is specified for this bone.

allow_length_flex

Normally, jiggle bones keep their length rigid. Specifying this allows that length to flex as well.

length

How far the simulated mass is from the base in inches. This value should match the length of the bone; values larger than the bone length can result in odd and unpredictable movement in the jiggle bone if you don't know what you're doing.

tip_mass

How much the simulated mass is affected by gravity. Zero disables gravity effects, whereas 1000 would be a heavy mass.

is_rigid

If a Jiggle Bone is "rigid", a simulated mass is placed at the end of the bone, and the bone acts like a rigid stick. This spring creates rotational motion only, with the center of rotation at the base of the Jiggle Bone.

length

How far the simulated mass is from the base in inches. This value should match the length of the bone; values larger than the bone length can result in odd and unpredictable movement in the jiggle bone if you don't know what you're doing.

tip_mass

How much the simulated mass is affected by gravity. Zero disables gravity effects, whereas 1000 would be a heavy mass.

Angular constraints

The following parameters can be used within either is_rigid (rigid) or is_flexible (flexible) parameter groups. Note that none or all of these constraints can be used, and that each constraint incurs nontrivial computations.

angle_constraint

Specify the maximum angular deflection allowed, creating a conical boundary the jiggle bone cannot penetrate.

yaw_constraint (min max)

Specify the minimum and maximum angular deflection allowed along the local yaw rotational axis. Angular values should not exceed +/- 90 degrees.

Note:When using "yaw_constraint", setting angular values greater than or equal to +/- 90 degrees causes unwanted flipping of jiggle bone. To avoid this, rotate jigglebone such that "pitch_constraint" can be used instead.

Todo: Check to see if this applies to other property groups other than "is_rigid"

yaw_friction

Nonzero values create frictional forces when the jiggle bone is sliding against the plane defined by the yaw limit. Friction should not exceed 20 units.

pitch_constraint

Specify the minimum and maximum angular deflection allowed along the local pitch rotational axis. Angular values should not exceed +/- 90 degrees.

Todo: Check to see if angle constraint rule for "pitch_constraint" applies to other property groups except "is_rigid"

pitch_friction

Nonzero values create frictional forces when the jiggle bone is sliding against the plane defined by the pitch limit. Friction should not exceed 20 units.

has_base_spring

If a Jiggle Bone has a "base spring", a simulated mass is placed on the base of the bone. This spring creates translational motion only, moving the whole Jiggle Bone in X, Y, and Z.

stiffness

How stiff the base spring is.

damping

The damping of the base spring.

left_constraint

The maximum amount the bone is allowed to move along the local X axis.

left_friction

The amount of friction applied in the up/forward plane when the spring is rubbing against the left constraint.

up_constraint

The maximum amount the bone is allowed to move along the local Y axis.

up_friction

The amount of friction applied in the left/forward plane when the spring is rubbing against the up constraint.

forward_constraint

The maximum amount the bone is allowed to move along the local Z axis.

forward_friction

The amount of friction applied in the left/up plane when the spring is rubbing against the forward constraint.

base_mass

How much the base spring is affected by gravity.

is_boing

Creates a simple squash and stretch sinusoidal "boing" effect. When the bone moves, it triggers a scaling and stretching effect once it reaches a speed threshold, giving the bone a dynamic and elastic appearance as it moves around.

Note: In , it sometimes vanishes randomly while performing the boing effect (size becomes 0).

impact_speed

The velocity threshold required to trigger the boing effect. When the bone's velocity exceeds this value, the boing animation is activated. Example: 20. This doesn't seem to work as intended, as the effect appears to trigger during any kind of movement despite using high values, at least in .

impact_angle

Determines the sensitivity of the boing effect to the direction of movement relative to the bone's orientation. Only movements aligned with the specified angle will trigger the effect. Example: 90. Logically, values can range from 0 to 180.

damping_rate

Controls how quickly the boing effect diminishes over time. Lower values result in a longer-lasting animation. A value of 0.0 means the boing effect will not stop animating; it will grow and revert indefinitely after triggering. Using a value like 1.0 will make it fade quickly, and values like 3.0 and above can cause it to return to normal almost immediately.

frequency

Higher frequency results in faster movements, while lower frequency creates slower movements. A value of 0.0 prevents it from animating entirely, whereas values like 40.0 can make it animate extremely quickly.

amplitude

Controls the extent of the bone's scaling during the boing effect. Higher values produce more exaggerated scaling and stretching. The perceived amplitude may vary depending on the bone's speed relative to the impact_speed threshold. Within , this seems to always trigger at max amplitude, even when the max threshold speed is not reached.