# 7. Procedural Animation Pitfalls
Part of [[Procedural Animation and IK]]. Previous: [[6. Worked Example Grounded Guard with Knockdown]].
> [!warning] Code not compiled
> The snippets referenced here come from parts 2-6, which were not compiled in Unity.
## Foot IK
| Symptom | Cause | Fix |
|---|---|---|
| `OnAnimatorIK` never runs | **IK Pass** off on the layer, or script not on the Animator's GameObject | Tick IK Pass on the Base Layer; move the script |
| Feet jitter on flat ground | Probe hits the character's own colliders | Remove the character's layers from `groundMask`; ragdoll colliders count too |
| Feet jitter on stairs | Probe flips between step top and step face | Larger `probeRadius`, lower `maxSlopeDegrees` |
| Body sinks slowly into the floor | Pelvis offset applied twice (both `bodyPosition` and a model offset) | Use one pelvis method per character |
| Feet reach for the ground mid-jump | IK weight stays 1 while airborne | Set `HumanoidFootIK.Weight = 0` when not grounded |
| Animation Rigging feet lag one frame | Script reads last frame's post-IK pose in `Update` (part 1) | Expected; use plant curves, keep step heights small |
## Look-at
- **Head spins or tilts sideways:** wrong **Aim Axis** or **Up Axis** for that bone. Check the bone's local axes in the Scene view; Mixamo heads are usually Z forward, Y up, but not every rig.
- **Neck stretches or the chest twists 90 degrees:** limits too wide, or the chest has all three axes constrained. Constrain chest X/Y only and keep limits at ±30.
- **Adding a source at runtime does nothing:** constraint data is baked into the rig's jobs. Move one proxy target instead (part 3). If you truly must change sources, change them and call `RigBuilder.Build()`, and expect a hitch.
- **Look-at fights a cutscene:** Timeline animation on the head bone plus a Multi-Aim gives a mix of both. Fade `Rig.weight` to 0 during authored shots ([[Timeline Basics]]).
## Two systems, one bone
The most common procedural bug: hand IK from [[6.Worked Example Locomotion Look-At and Hand IK]], foot IK from part 2 and a Multi-Aim from part 3 are all fine alone, then someone adds a second system to the same bone. Make a table for each character: **bone → owner**. Mecanim owns feet and pelvis; Animation Rigging owns spine, neck, head and hands; ragdoll owns everything while active.
## Ragdolls
| Symptom | Cause | Fix |
|---|---|---|
| Body launches into the air on knockdown | CharacterController overlaps limbs | Untick **Ragdoll x Character** in the collision matrix; disable the controller first (the script does) |
| Limbs stretch or vibrate at rest | Mass ratio between connected bodies too large, or joints fighting a scaled hierarchy | Keep neighbouring masses within about 1:10; never non-uniformly scale bones |
| Limbs pass through the floor | Discrete collision at high speed | `ContinuousSpeculative` while ragdolling (script sets it) |
| Elbows/knees bend backwards | Character Joint Twist limits from the wizard | Adjust Low/High Twist on that joint ([[4. Joints]]) |
| Never gets up | Body keeps jittering above `settleSpeed` | Raise `settleSpeed`; `maxRagdollSeconds` forces the get-up |
| Gets up facing the wrong way | `backClipFacesFeet` / `frontClipFacesFeet` wrong for your clips | Look at frame 0 of each clip and flip the checkbox |
| Visible pop at the start of get-up | Root moved without restoring hips, or blend too short | Check the hips restore in `BeginGetUp`; blend 0.4-0.7 s |
| Gets up inside a wall | Root placed under hips without checking space | Add an overlap capsule check and nudge the root away from walls before playing the clip |
## Performance and culling
- **Animator Culling Mode:** with *Cull Completely*, off-screen characters skip animation and IK entirely, which is what you want for distant guards. Procedural scripts that read bones (stepper, ragdoll get-up) still run, so keep them cheap or disable them by distance.
- **Rig jobs are cheap but not free.** A Multi-Aim chain per character is fine for a few dozen characters. For crowds, profile first ([[Profiling and Optimization]]); for hundreds, look at [[DOTS]].
- **Ragdoll cost** is roughly 11 bodies and 10 joints per character. Limit how many can be active at once (pool the oldest back to animated or freeze them).
- **Quest / mobile:** foot IK raycasts are cheap; ragdolls on many characters are not. Budget them against the numbers in [[6. Quest Performance Budgets]].
## Design pitfalls
- **Ragdoll every hit.** If every hit ragdolls, nothing feels heavy. Keep knockdown for finishers and poise breaks (part 6), as Level 10 of [[Level Up! (Review)]] suggests with its "big finish".
- **Head tracking that never stops.** A guard that stares at the player constantly reads as robotic. Let interest decay (lower base priority, rely on pings) so the head returns to the animation sometimes.
## Sources
- See the Sources sections of [[Procedural Animation and IK]] and parts 2-5.