# Animation commands

Author animation assets: AnimationClips (and their float curves), AnimatorControllers (parameters, layers, states, transitions), and Timeline assets. Create commands write under the authoring root and follow the shared `confirm`/`dry_run` convention.

## AnimationClips

### `create_animation_clip`
Create an empty .anim AnimationClip asset under the authoring root, with an optional frame rate and loop flag.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `path` | yes | `–` | Asset path ending in .anim, relative to the authoring root. The Assets/ prefix is optional. |
| `frameRate` | no | `60` | Sampling frame rate of the clip. |
| `loop` | no | `false` | If true, set the clip's loop-time flag in its AnimationClipSettings. |
| `confirm` | no | `false` | Required (true) only when overwriting an existing asset at the path. |
| `dry_run` | no | `false` | If true, validate inputs and report what would be created without writing anything. |

**Returns:** `AuthoringResult`

### `set_animation_curve`
Add or replace a single float curve binding on an AnimationClip (via AnimationUtility.SetEditorCurve). Replacing an existing binding overwrites it rather than duplicating.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `clip` | yes | `–` | Reference to the AnimationClip to edit (path / guid / globalId). |
| `path` | no | `""` | GameObject path relative to the animated root the property lives on. Empty string targets the root. |
| `type` | yes | `–` | Component type the property lives on, e.g. "Transform", "UnityEngine.Light". Resolved via the component TypeResolver. |
| `property` | yes | `–` | Curve property name, e.g. "m_LocalPosition.x", "m_LocalScale.y", "localEulerAnglesRaw.z". |
| `keys` | yes | `–` | Keyframes: `[{ time, value, inTangent?, outTangent?, weightedMode?: "None"\|"In"\|"Out"\|"Both" }]`. Omitted tangents default to 0 (flat); this is NOT Unity's Auto tangent mode. |
| `dry_run` | no | `false` | If true, validate type/property/keys without writing the curve. |

**Returns:** `SetAnimationCurveResult`

### `get_animation_clip`
Read an AnimationClip's metadata and all float curve bindings (optionally with keyframes).

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `clip` | yes | `–` | Reference to the AnimationClip to read (path / guid / globalId). |
| `includeKeys` | no | `false` | If true, include each binding's keyframes. |

**Returns:** `AnimationClipInfo`

### `remove_animation_curve`
Remove a float curve binding from an AnimationClip (SetEditorCurve(clip, binding, null)). Destructive: requires confirm=true.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `clip` | yes | `–` | Reference to the AnimationClip to edit (path / guid / globalId). |
| `path` | no | `""` | GameObject path relative to the animated root the binding lives on. Empty string targets the root. |
| `type` | yes | `–` | Component type of the binding to remove, e.g. "Transform". Resolved via the component TypeResolver. |
| `property` | yes | `–` | Curve property name to remove, e.g. "m_LocalPosition.x". |
| `confirm` | no | `false` | Must be true to actually remove the binding (destructive guard). |
| `dry_run` | no | `false` | If true, report the binding that would be removed without removing it. |

**Returns:** `SetAnimationCurveResult`

## AnimatorControllers

### `create_animator_controller`
Create an .controller AnimatorController asset (with a default Base Layer) under the authoring root.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `path` | yes | `–` | Asset path ending in .controller, relative to the authoring root. The Assets/ prefix is optional. |
| `confirm` | no | `false` | Required (true) only when overwriting an existing asset at the path. |
| `dry_run` | no | `false` | If true, validate inputs and report what would be created without writing anything. |

**Returns:** `AuthoringResult`

### `add_animator_parameter`
Add a parameter (Float | Int | Bool | Trigger) to an AnimatorController. A duplicate name returns code 'duplicate_parameter'.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `controller` | yes | `–` | Reference to the AnimatorController to edit (path / guid / globalId). |
| `name` | yes | `–` | Parameter name. |
| `type` | yes | `–` | Parameter type: Float \| Int \| Bool \| Trigger. |
| `defaultValue` | no | `–` | Default value for Float/Int/Bool (ignored for Trigger). |
| `dry_run` | no | `false` | If true, validate inputs without writing the parameter. |

**Returns:** `object`

### `add_animator_layer`
Add a layer to an AnimatorController.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `controller` | yes | `–` | Reference to the AnimatorController to edit (path / guid / globalId). |
| `name` | yes | `–` | Layer name. |
| `weight` | no | `1` | Layer weight. |
| `blendingMode` | no | `Override` | Blending mode: Override \| Additive. |
| `dry_run` | no | `false` | If true, validate inputs without writing the layer. |

**Returns:** `object`

### `add_animator_state`
Add a state to a layer, optionally with a motion (AnimationClip or BlendTree) and as the layer default. A layer name with no match returns code 'layer_not_found'.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `controller` | yes | `–` | Reference to the AnimatorController to edit (path / guid / globalId). |
| `layer` | no | `0` | Layer index (int) or name (string). Default 0 (Base Layer). |
| `name` | yes | `–` | State name. |
| `motion` | no | `–` | Optional AnimationClip or BlendTree asset to assign as the state's motion. |
| `isDefault` | no | `false` | If true, set this state as the layer's default state. |
| `position` | no | `–` | Optional [x, y] node position in the graph (cosmetic). |
| `dry_run` | no | `false` | If true, validate inputs without writing the state. |

**Returns:** `object`

### `add_animator_transition`
Add a transition between two states (or from AnyState/Entry, to Exit) on a layer, with optional conditions. Validates that the states exist and each condition's parameter exists and its mode matches the parameter type.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `controller` | yes | `–` | Reference to the AnimatorController to edit (path / guid / globalId). |
| `layer` | no | `0` | Layer index (int) or name (string). Default 0 (Base Layer). |
| `fromState` | yes | `–` | Source state name, or the special "AnyState" / "Entry". |
| `toState` | yes | `–` | Destination state name, or the special "Exit". |
| `conditions` | no | `–` | Optional conditions: `[{ parameter, mode: "If"\|"IfNot"\|"Greater"\|"Less"\|"Equals"\|"NotEqual", threshold? }]`. |
| `hasExitTime` | no | `false` | If true, the transition uses exit time. |
| `exitTime` | no | `0` | Normalized exit time (0..1) when hasExitTime is set. |
| `duration` | no | `0.25` | Transition duration in seconds. |
| `hasFixedDuration` | no | `true` | If true, duration is in seconds; otherwise normalized. |
| `dry_run` | no | `false` | If true, validate everything (states, parameters, mode/type) without writing the transition. |

**Returns:** `object`

### `get_animator_controller`
Read an AnimatorController's full structure: parameters, layers, states (with motion / default), and transitions (with conditions).

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `controller` | yes | `–` | Reference to the AnimatorController to read (path / guid / globalId). |

**Returns:** `AnimatorControllerInfo`

## Timeline

The Timeline commands require the `com.unity.timeline` package.

### `create_timeline`
Create a .playable TimelineAsset under the authoring root (optional frame rate).

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `path` | yes | `–` | Asset path ending in .playable, relative to the authoring root. The Assets/ prefix is optional. |
| `frameRate` | no | `60` | Timeline frame rate. |
| `confirm` | no | `false` | Required (true) only when overwriting an existing asset at the path. |
| `dry_run` | no | `false` | If true, validate inputs and report what would be created without writing anything. |

**Returns:** `object`

### `add_timeline_track`
Add a track (Animation | Audio | Activation | Control | Playable | Signal | Marker) to a TimelineAsset, optionally nested under a parent group/track.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `timeline` | yes | `–` | Reference to the TimelineAsset to edit (path / guid / globalId). |
| `trackType` | yes | `–` | Track type: Animation \| Audio \| Activation \| Control \| Playable \| Signal \| Marker. |
| `name` | no | `–` | Optional track display name. |
| `parentTrack` | no | `–` | Optional name of an existing group/track to nest the new track under. |
| `dry_run` | no | `false` | If true, validate inputs without writing the track. |

**Returns:** `object`

### `add_timeline_clip`
Add a clip to a named track on a TimelineAsset. For Animation tracks pass an AnimationClip asset; for Audio tracks an AudioClip.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `timeline` | yes | `–` | Reference to the TimelineAsset to edit (path / guid / globalId). |
| `track` | yes | `–` | Target track name. |
| `start` | yes | `–` | Clip start time in seconds. |
| `duration` | yes | `–` | Clip duration in seconds. |
| `asset` | no | `–` | Source asset: for Animation tracks an AnimationClip; for Audio tracks an AudioClip. Required for those track types. |
| `dry_run` | no | `false` | If true, validate inputs without writing the clip. |

**Returns:** `object`

### `get_timeline`
Read a TimelineAsset's structure: frame rate, duration, and its tracks with their clips.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `timeline` | yes | `–` | Reference to the TimelineAsset to read (path / guid / globalId). |

**Returns:** `object`

See [Creating commands](../creating-commands.md) and [Connectivity](../connectivity.md).