10 KiB
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 and Connectivity.