# AnimState

> Talos 0.7 · Since 0.6

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `name` | `string` | yes |  |  |  |
| `clip` | `string` | no |  |  | The clip this state plays. Exactly one of `clip`, `blend` and `clips` is written; a state with two or none is refused as `animator-state-source`. |
| `blend` | `BlendTree` | no |  |  |  |
| `clips` | `string[]` | no |  |  | Several clips played one after another, each once, in place of one `clip` or a `blend`: the variants of an idle, or a cycle a model ships in pieces. Each hands over to the next just before its end; with `loop` the last hands back to the first, and without it the state holds the last clip's final frame. Exactly one of `clip`, `blend` and `clips` (`animator-state-source`), at least one name. |
| `order` | `AnimClipOrder` | no |  | `sequence`, `random` | How `clips` follow each other: `sequence` (the default) in the order written, `random` a different one each time, never the one that just played. The random order is seeded per entity, so two runs pick the same clips. Read only with `clips`. |
| `loop` | `boolean` | yes |  |  |  |
| `rootMotion` | `boolean` | no | `false` |  | Take the root joint's travel out of the pose and move the character by it instead, so a walk cycle authored to cover ground covers it rather than sliding. The root is pinned to its rest position while this is on. Default false. A character with a `controller` component is driven by the delta; anything else is left to a behavior, which reads it with `ctx.animator.rootDelta()`. |
| `rootYaw` | `boolean` | no | `false` |  | Also take the root's heading out of the pose, for a clip authored to turn. Default false, and separate from `rootMotion` on purpose: most in-place clips sway their root a few degrees per cycle, and reading that as a turn would rotate the character every step. Ignored unless `rootMotion` is true. |
| `transitions` | `AnimTransition[]` | yes |  |  |  |
| `once` | `AnimOnce` | no |  |  | Makes this a one-shot: its clip plays one time and then the state hands over by itself — to `once.then`, or back to the state that was playing before. `loop` must be false (`animator-once-invalid`). `ctx.animator.play` makes the same thing out of any state or clip from a script, without declaring it here. |
| `speed` | `number` | no |  |  | Playback rate of this state, a multiplier: 1 (the default) plays the clip as authored, 0.5 at half speed, 0 holds the current frame. Finite and 0 or more (`animator-speed-invalid`). Multiplied by `speedParam` when there is one, by the blend points' own `speed` on a tree, and by the script's `ctx.animator.speed`. What paces a single-clip enemy, or matches a clip to the speed its character moves at. |
| `speedParam` | `AnimSpeedParam` | no |  |  | Ties this state's playback rate to one of the animator's parameters, so the clip plays faster the faster the character goes: rate = `speed` × max(0, value × `scale`). This is the cure for foot sliding on a clip that is played at more than one ground speed. Bind the parameter to `inputSpeed` (or `speed`) and set `scale` to 1 ÷ the ground speed, in m/s, the clip was authored at. A walk authored at 1.5 m/s takes `param` "speed" with `scale` 0.667, and plays at 2× when the character moves at 3 m/s. |
| `sync` | `AnimSync` | no |  | `phase`, `markers` | Where this state's clip starts when it is entered from another: `phase` at the normalised phase the state it leaves was at, so a walk entered from a run stays on the same foot; `markers` between the same two animation `events` both clips carry (foot plants named alike), however each clip spaces them, falling back to `phase` when they share none. Absent, from the clip's first frame. |
| `inertial` | `boolean` | no | `false` |  | Enter by inertialization instead of a crossfade: this state plays alone from the first tick, and the difference from the pose being left, with the speed it was moving at, decays to nothing over the transition's blend time. A stop keeps the swing of the stride it cut instead of freezing it half-mixed with the idle, and only one clip is sampled. A change of `rootMotion` between the two states still crossfades. Default false. |
| `enterAt` | `string[]` | no |  |  | Animation `events` this state waits for: a `set` of it takes effect on the tick the playing clip next crosses one of them, or after one cycle of that clip if it has none of them. A stop that waits for a foot plant: `enterAt: ["footL", "footR"]`. Each name is an event the animator declares in `events` (`animator-event-invalid`). |
| `loopStart` | `number` | no | `0` |  | Where the loop of this state's `clip` begins, as a fraction of the clip's duration in 0..1 (like an event's `at`). The clip plays from its first frame once, then loops between `loopStart` and `loopEnd`: a run whose first frames are the step out of a stand, then a cycle. The loop-seam check measures the range's two ends. Default 0. Only on a `loop` state that plays one `clip` (a blend tree takes the range per point), finite, in 0..1 and below `loopEnd` (`animator-loop-range-invalid`). |
| `loopEnd` | `number` | no | `1` |  | Where the loop of this state's `clip` ends and wraps back to `loopStart`, as a fraction of the clip's duration in 0..1. Default 1, the clip's last frame (`animator-loop-range-invalid`). |

## See also

- `BlendTree`
- `AnimClipOrder`
- `AnimTransition`
- `AnimOnce`
- `AnimSpeedParam`
- `AnimSync`