# animator

> Talos 0.7 · Since 0.6; changed in 0.7

Use it in a scene entity's `components` list as `{ "type": "animator", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `asset` | `string` | yes |  |  |  |
| `states` | `AnimState[]` | yes |  |  |  |
| `initial` | `string` | yes |  |  |  |
| `parameters` | `AnimParam[]` | no |  |  |  |
| `events` | `AnimEvent[]` | no |  |  |  |
| `ik` | `AnimIk[]` | no |  |  |  |
| `pelvis` | `AnimPelvis` | no |  |  |  |
| `lookAt` | `AnimLookAt` | no |  |  |  |
| `retarget` | `AnimRetarget` | no |  |  |  |
| `layers` | `AnimLayer[]` | no |  |  | Extra playback layers over the animator's state machine, applied in order after it and before IK and look-at: an upper-body action over a locomotion blend, an additive lean. Names unique (`animator-layer-invalid`). See `AnimLayer`. |
| `rootMotionFrom` | `string` | no |  |  | Take root motion (`rootMotion` and `rootYaw` states) from this joint instead of the rig's root: a canonical name (`Hips`, resolved through `retarget.map`) or one of the rig's own. For clips whose travel lives in the hips while the root bone stays at rest, such as a third-party mannequin pack retargeted onto the canonical rig. That joint's ground travel (and heading, with `rootYaw`) is moved out of the pose and onto the character, so the body stays over its capsule; its height stays in the pose. Base layer only. Absent, the root is used and nothing changes. A name the rig does not have is reported once at load (`animator-root-motion-joint-missing`) and the root is used. |
| `feet` | `string[]` | no |  |  | The rig's feet, by joint name: the joints that plant on the ground, for the playtester's foot-slide check (GET /feel's feet). Absent, the engine picks the leaf joints nearest the ground contact in the bind pose. Two to four distinct, non-empty names (`animator-feet-invalid`); a name the rig does not have is reported on GET /feel. |

## Rules that can refuse it

- `animator-blend-parameters`
- `animator-clip-missing`
- `animator-damp-invalid`
- `animator-event-invalid`
- `animator-feet-invalid`
- `animator-ik-unknown`
- `animator-initial-undefined`
- `animator-invalid`
- `animator-layer-bone-unknown`
- `animator-layer-invalid`
- `animator-layer-unknown`
- `animator-look-at-missing`
- `animator-loop-range-invalid`
- `animator-loop-seam`
- `animator-morph-unknown`
- `animator-not-finite`
- `animator-param-unknown`
- `animator-play-unknown`
- `animator-root-motion-hips`
- `animator-root-motion-joint-missing`
- `animator-root-motion-source`
- `animator-speed-invalid`
- `animator-state-duplicate`
- `animator-state-source`
- `animator-stride-rate`
- `animator-transition-undefined`
- `animator-transition-unheard`
- `animator-unknown`
- `animator-window-unreachable`
- `attach-owner-no-animator`
- `attach-skeleton-missing`
- `character-unanimated`
- `face-invalid`
- `feel/action-window-unreachable`
- `feel/anim-bind-pose`
- `feel/anim-frozen`
- `feel/anim-loop-seam`
- `feel/anim-no-air-state`
- `feel/anim-no-handle`
- `feel/anim-pop`
- `feel/anim-run-in-place`
- `feel/anim-slow-response`
- `feel/anim-stuck`
- `feel/anim-unknown-name`
- `feel/response-dead`
- `feel/response-slow`
- `lipsync-invalid`
- `null-handle`
- `spring-bone-unknown`
- `spring-needs-animator`

## Example

From the contract's tested fixture `fixtures/contract/full20/scene.json#worker`.

```json
{
  "type": "animator",
  "asset": "worker",
  "initial": "idle",
  "states": [
    {
      "name": "idle",
      "clip": "Idle",
      "loop": true,
      "transitions": [
        {
          "to": "walk",
          "on": "moving",
          "blend": 0.2
        }
      ]
    },
    {
      "name": "walk",
      "clip": "Walk",
      "loop": true,
      "transitions": [
        {
          "to": "idle",
          "on": "idle",
          "blend": 0.2
        },
        {
          "to": "run",
          "on": "sprint",
          "blend": 0.15
        }
      ]
    },
    {
      "name": "run",
      "clip": "Run",
      "loop": true,
      "transitions": [
        {
          "to": "walk",
          "on": "moving",
          "blend": 0.25
        }
      ]
    }
  ]
}
```