# AnimatorPlayOptions

> Talos next · Since 0.6; changed in 0.7

How a one-shot started by {@link Animator.play} leaves.

Every field mirrors `once` on a scene state.

## Signature

```ts
export interface AnimatorPlayOptions {
  /** The state entered when the clip ends. Default: the state that was playing before. */
  then?: string
  /** Seconds to blend in. Default: the blend of the transition that reaches the state, else 0.2. */
  blend?: number
  /** World seconds before the clip's last frame the hand-over starts and blends (twice the clip time at speed 2). Default 0.2. */
  blendOut?: number
  /** The states that may cut it short. Default: any. `[]`: none — it always plays to the end. */
  interrupt?: string[]
  /**
   * Play on an animator layer declared in the component's `layers` instead of the base state
   * machine: `play("Swing", { layer: "upper" })`. A state with `loop: true` that is not declared
   * `once` plays on the layer and stays; any other plays once and then hands over to `then`
   * (a state, played on the same layer) or releases the layer, which fades out. Throws
   * `AnimatorLayerError` for an undeclared layer.
   */
  layer?: string
  /** The bus event raised when it ends. Default `"animation-end"`. */
  event?: string
}
```

Import: `import type { AnimatorPlayOptions } from "@argus/api"`

## Members

| Member | Signature | Description |
|---|---|---|
| `then` | `then?: string` | The state entered when the clip ends. Default: the state that was playing before. |
| `blend` | `blend?: number` | Seconds to blend in. Default: the blend of the transition that reaches the state, else 0.2. |
| `blendOut` | `blendOut?: number` | World seconds before the clip's last frame the hand-over starts and blends (twice the clip time at speed 2). Default 0.2. |
| `interrupt` | `interrupt?: string[]` | The states that may cut it short. Default: any. `[]`: none — it always plays to the end. |
| `layer` | `layer?: string` | Play on an animator layer declared in the component's `layers` instead of the base state machine: `play("Swing", { layer: "upper" })`. A state with `loop: true` that is not declared `once` plays on the layer and stays; any other plays once and then hands over to `then` (a state, played on the same layer) or releases the layer, which fades out. Throws `AnimatorLayerError` for an undeclared layer. |
| `event` | `event?: string` | The bus event raised when it ends. Default `"animation-end"`. |

## Example

The tested fixture `fixtures/app/agent.ts`.

```ts
import type { Behavior } from "@argus/api"

// Sends a nav agent to `props.target` once, then reports arrival through ctx.state so the
// test can read it without polling the crowd directly.
export default {
  init(ctx) {
    ctx.state.arrived = false
    ctx.nav?.goTo(ctx.props.target as [number, number, number])
  },
  update(ctx) {
    if (ctx.nav?.arrived) ctx.state.arrived = true
  },
} satisfies Behavior
```