Animation Tools¶

Manage AnimationClips, Timeline sequences, Animator Controllers, and Particle Systems. Use these tools for keyframe animation, cinematic authoring, state machine setup, and particle effects.

animation¶

Read or author keyframe animation on AnimationClips. Use this for per-object AnimationClips, not for Animator state machine control (use animator for that).

Parameters: - action (string) — "get" | "create" | "edit" | "preview" | "add_event" | "remove_event" | "get_events" | "set_wrap" | "set_framerate" | "get_clip_path" - path (string) — Scene path to target GameObject - clip (string, optional) — AnimationClip name (required for edit/preview) - clip_name (string, optional) — New clip name (used with create) - property (string, optional) — Property to animate (e.g., "localPosition.x", "scale.y", "m_Color.a") - keys (string, optional) — Keyframe data: t:0 v:(0,0,0); t:1 v:(0,2,0) (time in seconds, value). Also used for set_wrap ("loop"|"once"|"pingpong"|"clamp") and set_framerate ("30") - time (float, optional) — Time position for preview/add_event (seconds) - component_type (string, optional) — Unity component to animate (default: Transform). Examples: Light, Camera, Rigidbody - binding_path (string, optional) — Sub-object path for EditorCurveBinding (e.g., "Head/Jaw"). Default "" = root - tangent (string, optional) — Tangent mode for keyframes: "auto" (default) | "smooth" | "linear" | "constant" - function_name (string, optional) — Method name for add_event - int_param (int, optional) — Integer parameter for add_event - float_param (float, optional) — Float parameter for add_event - string_param (string, optional) — String parameter for add_event

Actions:

Example:

# Create animation clip
await animation("create", path="Player", clip_name="Jump")

# Add keyframes (0→1 second, position 0→10 on X-axis)
await animation("edit", path="Player", clip="Jump", property="localPosition.x",
                keys="t:0 v:0; t:1 v:10")

# Preview at 0.5 seconds
await animation("preview", path="Player", clip="Jump", time=0.5)

timeline¶

Manage Unity Timeline (PlayableDirector / TimelineAsset) for multi-track cinematic sequences. Use for mixing animation, audio, activation, and custom tracks.

Parameters: - path (string) — Scene path to GameObject with PlayableDirector - action (string) — "get" | "create" | "add_track" | "remove_track" | "add_clip" | "remove_clip" | "set_binding" | "set_timing" | "mute" | "unmute" | "lock" | "unlock" | "rename_track" | "reorder_track" | "duplicate_clip" | "add_marker" | "remove_marker" | "set_track_offset" | "set_duration" | "add_sub_track" | "set_clip_in" | "get_bindings" | "preview" - track (string, optional) — Track name for targeting specific track - track_type (string, optional) — Track type: "Animation" | "Audio" | "Activation" | "Signal" | "Control" | "Group" - clip (string, optional) — AnimationClip name - binding (string, optional) — Scene object path to bind track - start (float, optional) — Clip start time (seconds) - duration (float, optional) — Clip duration (seconds) - blend_in (float, optional) — Blend-in duration (seconds) - blend_out (float, optional) — Blend-out duration (seconds) - asset_path (string, optional) — TimelineAsset path (Assets/...) - director_path (string, optional) — PlayableDirector path - tracks (string, optional) — Track list (get action) - time (float, optional) — Scrub to time (seconds) - name (string, optional) — New name for rename_track, or marker name - clip_in (float, optional) — Clip-in time for set_clip_in - index (int, optional) — Target position for reorder_track - offset (float, optional) — Time shift for duplicate_clip - value (string, optional) — Offset mode for set_track_offset: "auto" | "transform" | "scene"

Actions:

Example:

# Create new timeline
await timeline(path="Director", action="create", asset_path="Assets/Intro.playable")

# Add animation track
await timeline(path="Director", action="add_track", track="PlayerAnim", track_type="Animation")

# Bind track to Player
await timeline(path="Director", action="set_binding", track="PlayerAnim", binding="Player")

# Place animation clip
await timeline(path="Director", action="add_clip", track="PlayerAnim", 
               clip="Walk", start=0, duration=2)

# Preview at 1 second
await timeline(path="Director", action="preview", time=1.0)

animator¶

Manage Animator Controller state machines. Add states, parameters, and transitions.

Parameters: - action (string) — "get" | "add_param" | "add_state" | "add_transition" | "set_default" | "remove" | "add_blend_tree" | "edit_blend_tree" | "get_blend_tree" | "add_layer" | "remove_layer" | "rename_layer" | "set_layer_weight" | "set_layer_blending" | "set_state_speed" | "update_transition" | "set_avatar" | "rename_state" | "rename_param" - path (string) — Scene path to GameObject with Animator - state (string, optional) — State name - states (string, optional) — State definitions: "Idle:Idle.anim; Walk:Walk.anim; Run" - params (string, optional) — Parameters: "Speed:float:0; Jump:trigger; IsGrounded:bool:false" - source (string, optional) — Transition source state (use "*" for AnyState) - target (string, optional) — Transition target state - conditions (string, optional) — Transition conditions: "Speed>0.1; IsGrounded" - duration (float, optional) — Transition duration (seconds) - exit_time (float, optional) — Exit time threshold (0-1) - has_exit_time (bool, optional) — Whether transition has exit time - type (string, optional) — Parameter type (float|bool|int|trigger) - name (string, optional) — Parameter or state name - blend_type (string, optional) — Blend tree type: "1d" | "2d_simple" | "2d_freeform" | "2d_cartesian" | "direct" - param (string, optional) — Blend parameter (auto-created as float if missing) - param_y (string, optional) — Second blend parameter (for 2D blend trees) - children (string, optional) — Blend tree children: "(1D) Idle:0; Walk:0.5; Run:1" or "(2D) Idle:0,0; Walk:0,1" - edit_action (string, optional) — Blend tree edit: "add_child" | "remove_child" | "set_thresholds" | "set_param" | "set_type" - layer (int or string, optional) — Layer index for add_state/add_transition/set_default, or name/index for CRUD ops - weight (float, optional) — Default weight for add_layer/set_layer_weight (0.0-1.0) - blending (string, optional) — Layer blending: "Override" | "Additive" (for add_layer/set_layer_blending) - value (string, optional) — Speed multiplier for set_state_speed - avatar_path (string, optional) — Asset path for set_avatar

Actions:

Example:

# Create parameters
await animator("add_param", path="Player", type="float", name="Speed")
await animator("add_param", path="Player", type="bool", name="IsGrounded")

# Add states
await animator("add_state", path="Player", state="Idle")
await animator("add_state", path="Player", state="Walk")
await animator("add_state", path="Player", state="Run")

# Add transitions
await animator("add_transition", path="Player", source="Idle", target="Walk",
              conditions="Speed>0.1", duration=0.2)
await animator("add_transition", path="Player", source="Walk", target="Run",
              conditions="Speed>2.0", duration=0.3)

# Set default state
await animator("set_default", path="Player", state="Idle")

particle¶

Create and configure Particle Systems with preset or custom modules.

Parameters: - action (string) — "get" | "create" | "set" | "apply" | "play" | "stop" | "pause" - path (string) — Scene path to target GameObject - name (string, optional) — Particle system name - module (string, optional) — Module: "main" | "emission" | "shape" | "colorOverLifetime" | "sizeOverLifetime" | "velocityOverLifetime" | "noise" | "renderer" | "trails" | "collision" | "rotationOverLifetime" - prop (string, optional) — Module property name - value (string, optional) — Property value - preset (string, optional) — Preset type: "fire" | "smoke" | "sparks" | "rain" | "snow" | "explosion" | "magic" | "dust" | "blood" | "trail"

Actions:

Example:

# Create particle system with preset
await particle("create", path="Effects", name="ExplosionFX", preset="explosion")

# Customize emission
await particle("set", path="Effects/ExplosionFX", module="emission", 
              prop="rateOverTime", value="100")

# Customize renderer
await particle("set", path="Effects/ExplosionFX", module="renderer",
              prop="maxParticleSize", value="10")

# Reset the system to the named preset when needed
await particle("apply", path="Effects/ExplosionFX", preset="explosion")

Common Patterns¶

See also: Scene Tools for playback control, Runtime Tools for Play Mode state inspection.