> ## 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.

# Layered Blending: Combine Animator and Overlay Poses

> Configure Layered Blending to blend your Animator output with weapon overlays using per-bone curve weights for arms, spine, head, and legs.

The **Layered Blending component** is responsible for combining the output of your main Animator Controller with an Overlay Pose (weapon, item, or action pose). It does this using a set of per-bone chains, each driven by float curves embedded directly in the overlay animation clips. This design lets every clip define its own blending behaviour — a rifle idle can fully replace the arms while leaving the lower body to the locomotion system, while a full-body climb animation can take over the entire skeleton.

## Component Properties

<ParamField path="Global Weight" type="float">
  Master influence of the entire Layered Blending component. Set to `0` to disable all overlay blending and show the raw Animator output; set to `1` for full effect. Use intermediate values for debug purposes or for a fade-in/fade-out of the entire overlay system.
</ParamField>

<ParamField path="Always Animate Poses" type="bool">
  When enabled, Overlay playables are evaluated every frame regardless of whether they are visible. Disable this for characters that spend time off-screen to skip unnecessary pose evaluation and save CPU time.
</ParamField>

<ParamField path="Link Animator Parameters" type="bool">
  When enabled, float and bool parameters in the current Overlay Animator Controller are automatically synchronised from the values in the main Animator. Use this to keep locomotion state (speed, direction, crouching) consistent between both controllers without duplicating `SetFloat` calls.
</ParamField>

<ParamField path="Apply Root Motion" type="bool">
  Toggles root motion on the character. When enabled, root motion data from the Animator is applied to the character's transform each frame.
</ParamField>

### Accessing the Overlay Animator from Code

`LayeredBlendingComponent.OverlayAnimator` returns the active `Animator` for the current Overlay Animator Controller. Use it to set parameters, trigger transitions, or read state information at runtime:

```csharp theme={null}
private LayeredBlendingComponent _layeredBlending;

private void SetAiming(bool isAiming)
{
    _layeredBlending.OverlayAnimator.SetBool("IsAiming", isAiming);
}
```

<Tip>
  Call `OverlayAnimator` whenever you need to push gameplay state into the Overlay state machine — for example, toggling an aim pose or triggering a weapon-specific transition.
</Tip>

<Note>
  Click **Generate Layered Blends** on the component whenever you update the character's skeleton hierarchy. This regenerates the bone chain definitions to match the new rig.
</Note>

## Bone Chains and Layering

Layered Blends define which body parts a given layer controls and which float parameter curves drive the blend weights for that region. CAS generates the following bone chains by default:

* **Lower Body** — legs and pelvis
* **Spine** — vertebrae from the hip to the chest
* **Head** — neck and head bones
* **Left Arm / Right Arm** — shoulder to wrist on each side
* **Fingers** — all finger bones on both hands

<Tip>
  You can create custom bone chains by clicking **+** in the Layered Blends list, then clicking **Edit** to pick which bones belong to the chain.
</Tip>

### Per-Layer Weights

Each bone chain exposes three independent weights that are all driven by float curves baked into the overlay animation clip:

<ParamField path="Base Weight" type="float curve">
  Controls the mix between the Base Pose and the Overlay on this chain. At `0` the Animator's output is used unmodified; at `1` the Overlay fully replaces it.
</ParamField>

<ParamField path="Additive Weight" type="float curve">
  Scales how much additive motion is applied on this layer. Additive animations add on top of whatever the Base Weight blend produces.
</ParamField>

<ParamField path="Local Weight" type="float curve">
  Blends the Overlay in local space for this chain. Local-space blending is particularly useful for fingers, toes, and sometimes arms, where you want the blend to respect the parent bone's transform rather than world-space pose matching.
</ParamField>

All three weights are Animation Curves attached to overlay clips. At runtime, Unity evaluates these curves and forwards the values to the Layered Blending component, so each clip can define a completely unique relationship with the locomotion system underneath it.

## Overlay Parameters

Overlay Parameters let you propagate a float value from the base Animator into the Overlay Animator as an additive offset. CAS adds the float you specify to the current value of the matching parameter in the Overlay at runtime.

### Disabling IK While Climbing — Example

Suppose your character has a hand IK parameter called `Enable_HandL_IK` that normally sits at `1` (enabled). When a climbing overlay is active you want to force the IK off. To do this:

<Steps>
  <Step title="Add the curve to the climbing animation">
    In the Curve Property Editor, add a float parameter named `Enable_HandL_IK` to the climbing animation clip and set its value to `-1`.
  </Step>

  <Step title="Register the parameter in Overlay Parameters">
    In the Layered Blending component Inspector, add `Enable_HandL_IK` to the **Overlay Parameters** list.
  </Step>

  <Step title="Test at runtime">
    When the climbing overlay is active, CAS adds `-1` to the current `Enable_HandL_IK` value. If the base Animator has it at `1`, the result is `0` — IK disabled.
  </Step>
</Steps>

<Tip>
  This additive mechanism lets the base Animator retain full ownership of the parameter value while any overlay can locally cancel or boost it.
</Tip>

## Curve Property Editor

### Adding and Removing Curves

To add layering properties to an Animation Clip, right-click the clip in the Project window and select **Edit Curve Properties**. Use the **+** button to add a new property and the **−** button to remove one.

The toggle next to each property switches between two editing modes:

**Value Mode** represents the property as a constant curve. The value you type in the slider or float field is held for the entire duration of the clip. This is the right choice for most static blending weights.

**Curve Mode** represents the property as a full AnimationCurve that you can edit in the Animation window. Use Curve Mode when a weight needs to change over the course of a clip — for example, ramping the arm weight in from `0` to `1` at the start of a reload animation to create a smooth blend-in effect.

<Note>
  The toggle checkbox switches between the slider/float field (Value Mode) and the curve editor (Curve Mode). The free-range float field in Curve Mode is useful when a value must go outside the `[0, 1]` range — for example, setting `Enable_HandL_IK` to `-1` for the climbing override described above.
</Note>

## Default Blending Parameters

Layered Blending ships with these float properties pre-registered. Add any of them to your overlay clips via the Curve Property Editor to control blending per-bone-chain:

| Parameter            | Controls                                  |
| -------------------- | ----------------------------------------- |
| `Layering_LowerBody` | Base/Overlay mix for the Lower Body chain |
| `Layering_Spine`     | Base/Overlay mix for the Spine chain      |
| `Layering_Head`      | Base/Overlay mix for the Head chain       |
| `Layering_Arm_R`     | Base/Overlay mix for the Right Arm chain  |
| `Layering_Arm_L`     | Base/Overlay mix for the Left Arm chain   |
| `Layering_Fingers`   | Base/Overlay mix for the Finger chain     |

## Procedural and IK Parameters

The following float parameters are available for use with the [Procedural Animation](/cas/core/procedural-animation) component and IK modifiers. Add them to clips or set them as Overlay Parameters to enable or weight procedural features:

| Parameter                   | Purpose                                                |
| --------------------------- | ------------------------------------------------------ |
| `Mask_Procedural_Animation` | Global mask for all procedural animation modifiers     |
| `Weapon_Bone_Weight`        | Weight of the weapon bone attachment modifier          |
| `Mask_Look_Rotation`        | Enables/disables look-at rotation on the head or spine |
| `Mask_Attach_Hand`          | Enables/disables hand attachment to a target point     |
| `Enable_HandR_IK`           | Enables right-hand IK                                  |
| `Enable_HandL_IK`           | Enables left-hand IK                                   |
| `Enable_FootR_IK`           | Enables right-foot IK                                  |
| `Enable_FootL_IK`           | Enables left-foot IK                                   |

### Preventing Stale Values with `Curves_Default`

Unity does not reset curve-bound float values each frame. If a clip sets `Enable_HandR_IK` to `1`, that value persists in the Animator even after the clip stops playing. This can cause IK or blending to remain active when it should be off.

To prevent stale values:

<Steps>
  <Step title="Create a default layer in your Animator Controller">
    Add a new layer and place it first in the layer stack (index 0). Set its weight to `1`.
  </Step>

  <Step title="Add the Curves_Default clip">
    Drag the `Curves_Default` clip from the CAS package into that layer as the default state. This clip resets every registered float property to `0` each frame.
  </Step>
</Steps>

<Tip>
  With `Curves_Default` running as a base layer, every blending parameter starts at `0` each frame. Only clips that are actively playing will raise them above zero, which eliminates lingering-value bugs entirely.
</Tip>

## Custom Properties

### From a Character Prefab

Assign your **Character Prefab** to the Curve Property Editor's prefab slot. CAS will inspect the prefab, enumerate all public `float` fields and properties on every component, and present them in a dropdown. Click **Add Custom Parameter**, choose the desired property, and CAS adds it to the parameter list and registers it in the Animation Clip automatically.

Once added, the parameter works exactly like the built-in ones — you can set it to a constant value or author a curve directly in the Animation window.

### From an Animator Controller

Assign an **Animator Controller** to the controller reference slot in the Curve Property Editor. CAS will list all `float` parameters defined in that controller, letting you select one to use as a custom blending parameter. This is useful when you already have a well-named float in your locomotion controller and want to drive layering weights from it directly.