# 1. Procedural Animation Pipeline and Overlap
Part of [[Procedural Animation and IK]]. Next: [[2. Foot IK and Ground Alignment]].
> [!warning] Code not compiled
> The one script on this page was not compiled in Unity.
## 1.1 What is already covered (do not repeat it)
I checked the existing notes before writing this series. Here is the split:
| Topic | Already in | This series adds |
|---|---|---|
| Install Animation Rigging, `RigBuilder` + `Rig` hierarchy, Bone Renderer | [[5.Animation Rigging and Script IK]] 5.2 | Nothing; read it first |
| Two Bone IK on a hand, Auto Setup from Tip | [[5.Animation Rigging and Script IK]] 5.4, [[6.Worked Example Locomotion Look-At and Hand IK]] | Two Bone IK on **legs** with raycast targets (part 2) and procedural stepping (part 4) |
| Multi-Aim on the head toward one fixed target | [[5.Animation Rigging and Script IK]] 5.5, [[6.Worked Example Locomotion Look-At and Hand IK]] 6.5 | A spine/neck/head **chain**, limits, and a **director** that chooses targets (part 3) |
| `OnAnimatorIK` hand goals, IK Pass checkbox | [[5.Animation Rigging and Script IK]] 5.6 | `OnAnimatorIK` **foot** goals, `bodyPosition` pelvis drop, curve-driven weights (part 2) |
| Layers, masks, root motion, `MatchTarget` | [[Animation Advanced]] | Nothing; `MatchTarget` is still the right tool for vaulting and ledge grabs |
| Ragdolls | Not covered anywhere in the Unity notes | Part 5 |
| Damped Transform | Listed in the catalog in [[5.Animation Rigging and Script IK]] 5.3 only | A working tail/antenna setup (part 4) |
## 1.2 The frame, in order
Procedural animation bugs are almost always **ordering** bugs: you write a bone and something later overwrites it, or you read a bone and get last frame's value. Keep this table next to you.
| Phase | What runs | Read bones here and you get | Write bones here and |
|---|---|---|---|
| `Update` | Your gameplay, movement, target selection | **Last frame's final pose** (after IK and LateUpdate) | The Animator overwrites them in the next phase |
| Animator update | State machine, blend trees, clips | - | - |
| IK pass (`OnAnimatorIK`) | Humanoid IK goals, look-at, `bodyPosition` | `GetIKPosition` returns **this frame's animated** goal | Set goals and weights; do not write `Transform`s |
| Animation Rigging jobs | `RigBuilder` evaluates constraints as animation jobs on this frame's stream | - | Constraints write the stream |
| `LateUpdate` | Your post-animation code | **This frame's final pose** | Your writes stick for rendering this frame |
| `FixedUpdate` / physics | Rigidbodies, joints | - | Non-kinematic ragdoll bodies move bones |
Two consequences you will see in every part:
1. **A raycast for a foot must start from a pose you trust.** In `OnAnimatorIK`, `GetIKPosition(AvatarIKGoal.LeftFoot)` is this frame's animated foot, before IK. That is why part 2's humanoid path uses `OnAnimatorIK`. In `Update`, the foot bone is where last frame's IK left it, which is why the Animation Rigging path uses authored curves to decide when the foot is planted.
2. **Anything that must win goes in `LateUpdate`.** The ragdoll get-up blend in part 5 writes bone rotations in `LateUpdate`, after the Animator, so it wins for the blend duration.
> [!note] Mecanim IK and Animation Rigging on one character
> Mecanim's IK pass and Animation Rigging both modify the same animation stream. The relative order of `OnAnimatorIK` and `RigBuilder`'s jobs on a single Animator is **not something I could confirm in the docs (unverified)**. These notes avoid depending on it: if one character uses both, give them **different bones** (Mecanim for feet and pelvis, Rigging for spine/neck/head). Never let two systems drive the same bone, as [[6.Worked Example Locomotion Look-At and Hand IK]] 6.6 also warns for hands.
## 1.3 Mecanim IK or Animation Rigging?
| Question | Mecanim IK (`OnAnimatorIK`) | Animation Rigging |
|---|---|---|
| Rig type | **Humanoid only** | Humanoid or Generic (creatures, props, mechs) |
| Setup | Tick **IK Pass** on the layer, one script | `RigBuilder` + `Rig` + constraint GameObjects |
| Gives you the pre-IK animated goal | Yes, `GetIKPosition` | No (constraint reads the stream; your script only sees transforms) |
| Pelvis/body offset | `bodyPosition` | Move a model child, or an Override Transform on the hips |
| Chains longer than two bones | No | Chain IK, Multi-Aim per bone |
| Damping / secondary motion | No | Damped Transform |
| Authoring in Scene view | Code only | Effectors and Bone Renderer gizmos |
**Rule of thumb used in this series:** humanoid feet and pelvis in Mecanim (part 2), everything above the hips and every non-humanoid in Animation Rigging (parts 3 and 4).
## 1.4 Scene kit for the whole series
1. Unity **6000.5+**, URP 3D project.
2. **Window > Package Management > Package Manager > Unity Registry > Animation Rigging**, install (6000.5 resolves **1.4.1**).
3. A Humanoid character (Rig tab: **Animation Type = Humanoid**) with idle, walk and run clips, and a **CharacterController** mover from [[3. CharacterController Implementation]] or the driver in [[6.Worked Example Locomotion Look-At and Hand IK]].
4. A gray-box "IK gym" made with ProBuilder ([[ProBuilder Gray-Boxing and Landmarks]]): stairs with 15 cm and 25 cm risers, a 20 degree ramp, a 35 degree ramp, a row of uneven rocks, and a 40 cm ledge. Every part's checklist refers to this gym.
5. Physics layers: `Ground`, `Character`, `Ragdoll` (part 5). Set them up in **Project Settings > Tags and Layers**; layer matrix rules are in [[3. Layers Matrix and Queries]].
## 1.5 A debug helper used by later parts
Procedural systems are invisible until you draw them. This small static helper keeps gizmo code out of the real components.
```csharp
using UnityEngine;
/// <summary>
/// Tiny debug-draw helpers for procedural animation. Uses Debug.DrawLine,
/// so lines appear in the Scene view (and Game view with Gizmos on) in Play Mode.
/// Not compiled in an editor.
/// </summary>
public static class ProcDebug
{
public static bool Enabled = true;
public static void Cross(Vector3 p, float size, Color c)
{
if (!Enabled) return;
Debug.DrawLine(p - Vector3.right * size, p + Vector3.right * size, c);
Debug.DrawLine(p - Vector3.forward * size, p + Vector3.forward * size, c);
Debug.DrawLine(p - Vector3.up * size, p + Vector3.up * size, c);
}
public static void Ray(Vector3 from, Vector3 dir, float length, Color c)
{
if (!Enabled) return;
Debug.DrawLine(from, from + dir.normalized * length, c);
}
public static void Line(Vector3 a, Vector3 b, Color c)
{
if (!Enabled) return;
Debug.DrawLine(a, b, c);
}
}
```
## 1.6 Check
- [ ] You can say, for each part, which phase of the frame its script runs in.
- [ ] Animation Rigging 1.4.x shows in Package Manager.
- [ ] The IK gym scene exists, with `Ground` on every walkable surface.
## Sources
- `MonoBehaviour.OnAnimatorIK` (6000.5): https://docs.unity.com/en-us/engine/6000.5/script-reference/unityengine/monobehaviour/onanimatorik
- `Animator.GetIKPosition` (6000.5): https://docs.unity.com/en-us/engine/6000.5/script-reference/unityengine/animator/getikposition
- Animation Rigging 1.4 manual: https://docs.unity3d.com/Packages/
[email protected]/manual/index.html