> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinemation.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# How Motion Warping Works: Phases, Play Rate, and Root Motion

> Motion Warping's four mechanisms: warping phases, play rate scaling, total root motion, and the LateUpdate formula that applies warp offsets each frame.

Motion Warping adjusts character root motion using four interlocking concepts. Understanding all four gives you the mental model needed to configure assets correctly and debug unexpected behaviour.

The four concepts are:

1. [Warping Phases](#warping-phases)
2. [Play Rate Scale](#play-rate-scale)
3. [Total Root Motion](#total-root-motion)
4. [Post-Animation Update](#post-animation-update)

***

## Warping Phases

A **Warping Phase** is a segment of the animation during which the system actively warps the character's position and rotation. Inside the Motion Warping Asset editor, phases appear as purple draggable windows overlaid on the root motion curves.

### How many phases do you need?

The number of phases equals the number of **target points** the interaction requires.

A **vault** animation needs three phases because three points define the interaction:

1. Close obstacle edge
2. Far obstacle edge
3. Landing point

A **climbing / mantle** animation needs only **one** phase — the character moves from their current position to the single ledge top point.

### What each phase stores

Every phase carries metadata about its animation segment:

* **T Offset** — a translation offset applied on top of the target point. Use this to fine-tune where the character arrives within the phase, or to correct awkward poses caused by the original animation.
* **R Offset** — a rotation offset applied to the target point, useful for aligning the character's facing direction at each warp target.
* **Start Time / End Time** — the normalised or absolute animation times that define the boundaries of the phase window. You can drag and resize phase windows interactively in the asset editor.
* **Min Rate / Max Rate** — clamps on the computed play rate for this phase (see [Play Rate Scale](#play-rate-scale) below).
* **Total Root Motion** — the accumulated root motion for each axis across this phase (see [Total Root Motion](#total-root-motion) below).

<Note>
  The T and R Offsets are especially powerful for compensating for foot or hand placement differences that arise when the same animation is used at very different obstacle sizes.
</Note>

***

## Play Rate Scale

When the distance to a target point differs from the distance baked into the original animation, playing the animation at a fixed 1× speed produces unnatural motion — the character appears to glide or rush.

To compensate, the system scales the play rate for each phase based on the **ratio of actual distance to animation distance**:

* If the real obstacle is **twice as far** as the animation expects, the play rate is scaled **down to 0.5×** so the character takes longer to cover the extra distance.
* If the real obstacle is **half as far**, the play rate is scaled **up to 2×** so the character arrives on time.

You control the range of this scaling with the **Min Rate** and **Max Rate** values on each Warp Phase. These clamps prevent the play rate from becoming so extreme that the animation looks broken.

### Applying the play rate

The computed play rate is written to a **float parameter in the Animator Controller**. You connect that parameter to the animation state's speed multiplier in the Animator. If you are using a custom animation system rather than Unity's Animator, you read the value yourself and apply it to your playback speed.

<Tip>
  Always set sensible Min/Max Rate limits per phase. A play rate below 0.3× or above 3× often looks unnatural regardless of the distance difference.
</Tip>

***

## Total Root Motion

Every Warping Phase stores the **total accumulated root motion** for each translation axis across that segment of the animation. Think of it as the full distance the root bone travels in X, Y, and Z from the phase start to the phase end.

This value is calculated automatically when you open (or re-open) the Motion Warping Asset in the Editor.

<Note>
  If you edit an animation's root motion curves after setting up the asset, close and re-open the asset to refresh the Total Root Motion values.
</Note>

Total Root Motion is the reference the system uses to distribute the warping offset over time. Without it, the system would not know what fraction of the journey has been completed at any given frame.

***

## Post-Animation Update

All warping happens in `LateUpdate()`, **after** the Animator has evaluated for that frame. This ordering is deliberate:

* The Animator writes the root motion delta for the frame.
* Other systems (IK, constraints) run in their own `LateUpdate` passes.
* Motion Warping then reads the accumulated delta and applies its offset **on top**, without disturbing any IK or constraint results.

### Translation formula

At each frame the system computes an additional positional offset using:

```text theme={null}
offset = desiredHeightDelta * (accumulatedRootMotion / totalRootMotion)
```

Where:

* `desiredHeightDelta` is the difference between the target point position and where the original animation would place the character.
* `accumulatedRootMotion` is how much root motion has been applied from the phase start up to the current frame.
* `totalRootMotion` is the phase's full root motion for that axis.

The expression `accumulatedRootMotion / totalRootMotion` is always in the range **\[0, 1]** and acts as a weight or alpha — the warp offset starts at zero and builds up smoothly as the animation progresses, ensuring the character arrives precisely at the target by the time the phase ends.

### Rotation formula

Rotation warping does not use the root motion ratio. Instead, rotations are spherically interpolated from the character's rotation at the start of the phase to the target rotation, using the phase's normalised playback time as the alpha:

```csharp theme={null}
rotation = Quaternion.Slerp(startRotation, targetRotation, normalizedTime);
```

This produces a smooth, constant-speed rotation that finishes exactly at the target facing direction when the phase ends.

***

## Putting It All Together

1. You author an animation and define **Warping Phases** that mark the segments where alignment is needed.
2. At runtime, when an interaction is triggered, the system computes **target points** (from a Warp Provider) and compares them to the animation's built-in root motion.
3. **Play Rate Scale** adjusts the animation speed so the timing stays natural for the real obstacle size.
4. Each frame, the **Post-Animation Update** uses the Total Root Motion ratio to calculate and apply the translation offset, while SLERPing the rotation, until each phase end is reached.

The result is a single animation that works across a wide range of obstacle sizes and positions — no extra clips required.