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

# 🔸 Animation system

> This page explains the animation controller, skeleton mapping, blending, and animation playback.

## Overview

**Gameplay Animation Controller** is the main animation component in Survival Pack. It combines the character's Animator output with weapon poses and action animations, then applies procedural motion and IK.

For example, your Animator can keep playing a walking animation while the upper body reloads a rifle. The reload clip controls how much of the walking motion remains visible in each body part. Procedural features then adjust the weapon and hands for aiming, recoil, and sway.

## Gameplay Animation Controller

Add `GameplayAnimationController` to the same GameObject as the character's `Animator`. [Character setup](https://docs.kinemation.xyz/survival-pack/unity/get-started/character-setup.md) configures it for you.

![Gameplay Animation Controller general settings](https://docs.kinemation.xyz/images/gameplay-framework/unity/gameplay-framework-components.png)

Gameplay Animation Controller settings on the character.

### General settings

* **Weight** controls the overall animation effect, from `0` to `1`. Use `1` for normal playback. Reducing it blends the layered result toward the original Animator pose.
* **Base Pose** is the reference clip used to calculate the difference between locomotion and the reference pose. It is not the current weapon's idle animation.
* **Procedural Asset** contains the active weapon pose, optional overlay Animator Controller, and procedural features. Equipping an item changes this reference to the asset assigned to that item's view.

The **Skeleton** tab maps the character's bones. The **Procedural** tab lets you inspect the features in the active procedural asset. The **Override** tab contains retargeted replacements for the pack animations.

### Animation inputs

Your gameplay controller updates these public fields. The procedural features read them to animate the character.

| Field | What to pass |
| - | - |
| `moveInput` | Movement input as a `Vector2`: sideways movement on X and forward movement on Y. |
| `lookInput` | View angles; the example controller stores vertical aim in Y. |
| `deltaLookInput` | The current look delta, used for mouse sway and turning. |
| `leanInput` | The desired lean angle in degrees. |
| `isAiming` | Whether the character is aiming down sights. |
| `isUsingItem` | Whether the use button is held, as tracked by the example controller. |

See [Character](https://docs.kinemation.xyz/survival-pack/unity/general/character-runtime.md) for the input callbacks and movement implementation.

## Character skeleton

The controller stores its skeleton in `GameplaySkeleton`. The skeleton records the character hierarchy and identifies which transforms represent the pelvis, spine, hands, fingers, feet, weapon, and IK targets.

![Gameplay Animation Controller Skeleton tab with humanoid, weapon, and IK mappings](https://docs.kinemation.xyz/images/gameplay-framework/unity/gameplay-animation-controller-skeleton.png)

The Gameplay Animation Controller skeleton maps body, weapon, and IK transforms.

### Bone groups

| Group | Bones and purpose |
| - | - |
| **Lower Body** | Pelvis, thighs, calves, feet, and toes. Used for lower-body blending and leg IK. |
| **Spine** | Up to three spine bones. Used for upper-body blending and procedural aim rotation. |
| **Neck** | Neck and head. These bones share the spine's blending weights. |
| **Arms** | Upper arm, lower arm, and hand on each side. Used for arm blending and two-bone IK. |
| **Fingers** | Thumb and finger joints. Each hand uses its arm's local blending weight. |
| **IK / Hands** | Hand targets that procedural features move before the arms are solved. |
| **IK / Feet** | Foot targets used by leg IK. |
| **IK / Weapon** | The weapon attachment transform and a separate transform for additive weapon motion. |

The weapon prefab is attached to **Weapon Bone**. Procedural weapon motion moves this transform and the hand targets so the hands continue following the weapon.

Bone fields use `GameplayTransform`, which can store a direct Transform reference or a bone name. A direct reference resolves to that Transform; a name resolves through the controller's skeleton. Keep names unambiguous when using name-based references.

### Rig presets and automatic mapping

Choose **Rig Preset** in the **Skeleton** tab to apply the naming pattern for your character. The available presets are **Humanoid**, **Mixamo**, **Synty**, **Unreal Engine**, **Character Creator**, and **Human (Generic)**.

**Humanoid** reads standard bones from the Animator's Avatar. The other presets match bone names. **Auto Map Bones** rebuilds the skeleton mapping and detects a matching preset. Mapping also creates the helper transforms used for the camera, weapon, and IK when needed.

After mapping, inspect the references for your character. If a bone is missing, expand the skeleton in the Hierarchy and drag its Transform into the corresponding field. An arms-only character will not have leg bones; check the groups that exist on your model.

### How mapping affects retargeting

Retargeting needs to know which source and target bones perform the same role. A correct mapping lets it transfer arm and finger motion to a character with different bone names and proportions. An incorrect hand or forearm reference can produce a twisted grip even when the animation itself is valid.

Check the mapping before adjusting retargeting offsets. Then use a target reference pose to correct differences in shoulder, wrist, and finger orientation. Follow [Retarget the animations](https://docs.kinemation.xyz/survival-pack/unity/get-started/character-setup.md#retarget-the-animations) to preview and bake the result.

## Blending locomotion and weapon animations

The character Animator normally handles locomotion. An **overlay** is the weapon pose or action animation that is blended with that locomotion.

The controller first captures the Animator pose, combines it with the overlay, and then applies any Full Body action. Procedural features and IK run afterward. This allows you to aim or apply recoil while an action animation is playing.

### Body weights

The current system has four groups of blending weights:

* `lowerBody` controls the pelvis and legs.
* `spine` controls the spine, neck, and head.
* `rightArm` controls the right arm and the local blending of its fingers.
* `leftArm` controls the left arm and the local blending of its fingers.

Each group has these properties:

| Property | What it changes |
| - | - |
| **Base Weight** | Blends between locomotion and the overlay. `0` keeps locomotion; `1` uses the overlay with the selected additive motion. |
| **Additive Weight** | Adds locomotion motion relative to the Base Pose onto the overlay. `0` removes that added motion; `1` keeps it at full strength. |
| **Local Weight** | Blends toward the overlay in each bone's parent space. `1` preserves the local pose authored in the overlay, which is useful for hand and finger poses. |

For a reload that must keep the arms in the authored position, start with arm **Base Weight** at `1` and **Additive Weight** at `0`. Increase additive motion only if you want movement from locomotion to affect the reload.

Fingers use local blending only. Their weight comes from `rightArm.localWeight` or `leftArm.localWeight`; they do not have separate finger-weight fields.

### Custom curve properties

Blending weights are float curves stored on the Animation Clip. Each animation can therefore define its own blending, and a curve can change that blending during the action.

1. Select the Animation Clip in the Project window.
2. Choose **Assets ▸ Edit Gameplay Curve Properties**.
3. Use **+** to add a property. Set a constant value or right-click the field to switch to **Curve Mode**.
4. Use **Value Mode** to return to a constant value, or **-** to remove the property.
5. Preview the animation while moving the character.

![Animation clip selected with the Edit Gameplay Curve Properties menu command](https://docs.kinemation.xyz/images/gameplay-framework/unity/click-overlay-pose-edit-curve-properties.png)

Select an overlay pose clip and open Edit Gameplay Curve Properties.

![Gameplay curve editor showing animation blending properties](https://docs.kinemation.xyz/images/gameplay-framework/unity/gameplay-curve-editor.png)

Edit constant blending values or animate them with curves.

For example, `spine.baseWeight` controls the spine's overlay influence. `rightArm.localWeight` controls the right arm's local blend, including its fingers. These are Gameplay Framework properties; CAS curve names belong to a different system.

**Weapon Bone Weight** controls hand-relative weapon alignment. Positive values blend toward the right hand, negative values toward the left hand, and `0` keeps the animated weapon transform. Animate this value when an action changes which hand should guide the weapon.

The curve editor also finds fields marked with `AnimatedProperty` on item views. The charge weapon's `charge` field is one example: an item animation can animate the charge effect while the character animation controls body blending.

## Gameplay Animation Asset

A `GameplayAnimationAsset` is a ScriptableObject that stores a clip and the settings used to play it. Select an Animation Clip or FBX, then choose **Assets ▸ Create ▸ KINEMATION ▸ Gameplay Framework ▸ Animation Asset** to create an asset beside it.

| Setting | Description |
| - | - |
| **Clip** | The Animation Clip to play. |
| **Slot** | Where the animation is applied: **Overlay** or **Full Body**. |
| **Mask** | An Avatar Mask that limits the bones affected by the action. Include custom weapon and IK transforms when the animation needs them. |
| **Blend Time** | Blend-in time, blend-out time, and easing. Times are in seconds. |
| **Play Rate** | Playback speed multiplier. `1` is normal speed; `2` plays twice as fast. |
| **Is Additive** | Adds the animation's motion to the pose below it. |
| **Auto Blend Out** | Starts blending the action out near the end of playback. Disable it when you need to stop the action explicitly. |

![Gameplay Animation Asset Inspector with clip and playback settings](https://docs.kinemation.xyz/images/gameplay-framework/unity/gameplay-animation-asset-example.png)

Configure the clip, slot, mask, and playback settings on a Gameplay Animation Asset.

Use [Modify Avatar Mask](https://docs.kinemation.xyz/survival-pack/unity/tools/modify-avatar-mask.md) when a mask is missing a custom transform.

### Animation slots

**Overlay** plays an action over the current weapon pose or overlay controller. Use it for weapon actions such as draw, reload, inspect, and fire. The body curves determine how that result combines with locomotion.

**Full Body** plays after layered blending. Use it for an action that should take over the character, such as a full-body interaction. Its mask still determines which transforms are affected, and procedural animation runs afterward.

A `GameplayProceduralAsset` sets the idle overlay through **Default Idle Pose**. Assign **Overlay Controller** when the overlay needs states, transitions, or blend trees. If both are assigned, the controller drives overlay playback while the idle pose remains the reference pose.

Matching float, integer, and boolean parameters are copied from the character Animator to the overlay controller. Triggers are not copied. Use `HasOverlayAnimator` before accessing `OverlayAnimator` to set an overlay trigger from code.

## Play animations from code

Call these methods on `GameplayAnimationController`:

```csharp wrap theme={null}
animationController.PlayAnimation(action);
animationController.StopAnimation(action);
```

Attach this example to your character, assign the controller and action asset in the Inspector, then call `PlayAction` from your gameplay code:

```csharp wrap theme={null}
using KINEMATION.Shared.GameplayFramework.Scripts.Runtime.Animation;
using UnityEngine;

public class CharacterAction : MonoBehaviour
{
    [SerializeField] private GameplayAnimationController animationController;
    [SerializeField] private GameplayAnimationAsset action;

    public void PlayAction()
    {
        if (animationController.HasActiveAction) return;
        if (!animationController.PlayAnimation(action)) return;

        float duration = animationController.ResolveAnimationAsset(action).GetPlayLength();
        animationController.StartAction(duration, duration > 0f);
    }

    public void StopAction()
    {
        animationController.StopAnimation(action);
        animationController.StopAction();
    }
}
```

`PlayAnimation` returns `false` if the graph is not ready or the asset is invalid. `GetPlayLength()` returns the clip length divided by Play Rate; it returns `0` for a missing clip or zero Play Rate.

`StartAction` sets `HasActiveAction`. With a timer, it clears the flag after the duration; without one, your code calls `StopAction` when finished. The flag lets the example controller prevent conflicting actions. Playing an animation does not set the flag automatically.

### Character and weapon animation pairs

`GameplayCharacterItemClip` stores a character animation asset, an item animation asset, and an optional sound.

![Character-item animation fields for character clip, item clip, and sound](https://docs.kinemation.xyz/images/gameplay-framework/unity/character-item-animation.png)

A character-item animation pairs character and weapon assets with a sound.

`GameplayItemView.PlayCharacterItemAnimation` starts both animations together and plays the sound. Its `GetLength()` method returns the longer of the two animation durations. See [Item View](https://docs.kinemation.xyz/survival-pack/unity/general/item-views.md) for the item-side setup.

## Retargeted animation overrides

The **Override** tab stores `GameplayAnimationOverride` assets. Each asset maps original animations, clips, or Animator Controllers to retargeted replacements. The controller checks the list in order and uses the first matching replacement. If none exists, it uses the original asset.

Pass the original pack animation to `PlayAnimation`; the controller resolves the replacement for your character. You do not need to replace every character animation reference on each weapon prefab after retargeting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.