# AnimLayer

> Talos 0.7 · Since 0.7

A playback layer over the animator's state machine, on the masked bones: an upper-body action over locomotion, or an additive lean.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `name` | `string` | yes |  |  | How a script names the layer. Non-empty and unique in the animator (`animator-layer-invalid`). |
| `mask` | `string[]` | no |  |  | The bones the layer acts on, each with all its descendants, at weight 1. Absent, all of them; present, at least one (`animator-layer-invalid`). An upper-body mask names the spine and not the hips: the legs hang off the hips and are left alone. |
| `maskExclude` | `string[]` | no |  |  | Bones, with their descendants, taken back out of `mask`: the spine without the left arm. |
| `maskWeights` | `object` | no |  |  | A weight, 0..1, for a bone and its descendants within what the mask covers, in place of 1: `{ "Spine": 0.5 }` for a half-strength spine under a full-strength arm. A deeper bone's entry wins over its parent's. Each in 0..1 (`animator-layer-invalid`). |
| `additive` | `boolean` | no |  |  | False (the default): the layer replaces the pose below on the masked bones. True: it adds the playing clip's change from its reference pose on top of it, so a lean or a breathing clip can be laid over any base animation. |
| `weight` | `number` | no |  |  | How strongly the layer applies, 0..1, default 1; a script moves it with `ctx.animator.layerWeight`. Finite and in 0..1 (`animator-layer-invalid`). |
| `weightParam` | `string` | no |  |  | A parameter, declared in the animator's `parameters`, whose value (0..1) multiplies the weight every tick, so a layer can follow a stick or a script's number (`animator-layer-invalid`). |
| `blendIn` | `number` | no | `0` |  | Seconds the layer takes to come to full weight once something plays on it. Default 0.2; 0 is at once. Finite, 0 or more (`animator-layer-invalid`). |
| `blendOut` | `number` | no | `0` |  | Seconds the layer takes to fade out once what played on it has ended or been stopped; it keeps playing, on its last frame if it was a one-shot, while it does. Default 0.2; 0 is at once. Finite, 0 or more (`animator-layer-invalid`). |
| `reference` | `string` | no |  |  | For an additive layer: the clip whose pose is the reference, in place of the first frame of the clip playing. Refused on a layer that is not additive (`animator-layer-invalid`); a clip the asset lacks is the critic's `animator-invalid`. |
| `referenceAt` | `number` | no | `0` |  | Where in `reference` the pose is taken, as a fraction of its duration in 0..1. Default 0. Only with `reference` (`animator-layer-invalid`). |
| `initial` | `string` | no |  |  | A state of this animator the layer plays from the start, held for as long as nothing else is played on it (use a looping state): a breathing or lean layer that is always on. Absent, the layer is empty until a script plays something on it (`animator-layer-invalid` for a name that is not a state). |