# playAnimation

Import from `@pibbl/core/machines/animation` or `pibbl/machines/animation`.
`playAnimation(factory, options?)` returns a task for `invoke.task`. The factory
receives the entry's context, event, input, abort signal, and send function, and
returns an ordinary Pibbl animation program.

Finite playback resolves after the scheduler's finish event and can select
`invoke.onDone`. Infinite playback runs until cancellation. On state exit the
adapter disposes only its owned controller. Cancellation does not select completion
or error transitions. Animation sampling still uses Pibbl's shared scheduler.

Options provide an optional debug name and the existing animation writer-conflict
policy. The default rejects conflicts; simultaneous states/tasks do not silently
blend shared signal outputs or cancel unrelated writers.

See [machine animation](/guides/machine-animation/) and
[machine types](/reference/types/machines/).

Related types: [MachineAnimationOptions](/reference/types/machines/#machineanimationoptions), [MachineAnimationProgramFactory](/reference/types/machines/#machineanimationprogramfactory), [MachineTask](/reference/types/machines/#machinetask).

## API details from source

<span id="api-playAnimation"></span>

Adapts a Pibbl animation program into state-owned cancelable machine work.

A finite program resolves the state invocation after the animation scheduler
delivers its `finish` event, allowing the invocation's `onDone` transition to
run. Repeating programs remain active until their state exits or the actor
stops. Cancellation disposes only this adapter's playback and never sends a
completion or error transition.

```ts
playAnimation: <Context, Event extends MachineEvent, Input>(program: MachineAnimationProgramFactory<Context, Event, Input>, options?: MachineAnimationOptions) => MachineTask<Context, Event, Input, void>
```

Related API: [playAnimation](/reference/functions/play-animation/), [MachineEvent](/reference/types/machines/#machineevent), [MachineAnimationProgramFactory](/reference/types/machines/#machineanimationprogramfactory), [MachineAnimationOptions](/reference/types/machines/#machineanimationoptions), [MachineTask](/reference/types/machines/#machinetask).

### Type parameters

- **`Context`** — Context captured when this state entry began.

- **`Event`** — Event type accepted by the owning machine.

- **`Input`** — Input captured by the owning machine actor.

### Parameters

- **`program`** — Factory that creates the program for this state entry.

- **`options`** — Playback conflict policy and diagnostic label.

### Returns

A task suitable for a state's `invoke.task` field.

### Examples

```ts
running: {
  invoke: {
    task: playAnimation(({ input }) =>
      repeat(drive(input.frame, input.animations.run), { iterations: Infinity }),
    ),
  },
}
```

### See also

[MachineAnimationOptions](/reference/types/machines/#machineanimationoptions)

[View source — packages/core/src/features/machines/animation.ts:80](/source/packages/core/src/features/machines/animation-ts/#L80)

## Implementation guidance for agents

Read the [Animation and scheduling companion](/agents/topics/animation/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [State-owned animation](/minimal-examples/machines/animation/): Move a circle with a machine-owned animation task that completes into the next state. [Plain source](/minimal/machines/animation.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.