home / skills / besty0728 / unity-skills / animator

animator skill

safe

/unity-skills/skills/animator

This skill creates and manages Unity Animator Controllers and parameters to streamline animation setup and runtime control.

npx playbooks add skill besty0728/unity-skills --skill animator

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

5.3 KB

---
name: unity-animator
description: "Create and manage Animator Controllers and parameters."
---

# Unity Animator Skills

Control Unity's animation system - create controllers, manage parameters, and control playback.

## Skills Overview

| Skill | Description |
|-------|-------------|
| `animator_create_controller` | Create new Animator Controller |
| `animator_add_parameter` | Add parameter to controller |
| `animator_get_parameters` | List all parameters |
| `animator_set_parameter` | Set parameter value at runtime |
| `animator_play` | Play animation state |
| `animator_get_info` | Get Animator component info |
| `animator_assign_controller` | Assign controller to GameObject |
| `animator_list_states` | List states in controller |

---

## Parameter Types

| Type | Description | Example Use |
|------|-------------|-------------|
| `float` | Decimal value | Speed, blend weights |
| `int` | Integer value | State index |
| `bool` | True/false | IsGrounded, IsRunning |
| `trigger` | One-shot signal | Jump, Attack |

---

## Skills

### animator_create_controller
Create a new Animator Controller.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | Yes | - | Controller name |
| `folder` | string | No | "Assets" | Save folder |

**Returns**: `{success, name, path}`

### animator_add_parameter
Add a parameter to a controller.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `controllerPath` | string | Yes | - | Controller asset path |
| `paramName` | string | Yes | - | Parameter name |
| `paramType` | string | Yes | - | float/int/bool/trigger |
| `defaultValue` | any | No | 0/false | Initial value |

### animator_get_parameters
Get all parameters from a controller.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `controllerPath` | string | Yes | Controller asset path |

**Returns**: `{success, parameters: [{name, type, defaultFloat/defaultBool/...}]}`

### animator_set_parameter
Set a parameter value at runtime.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | GameObject name |
| `paramName` | string | Yes | Parameter name |
| `paramType` | string | Yes | float/int/bool/trigger |
| `floatValue` | float | No* | Float value |
| `intValue` | int | No* | Integer value |
| `boolValue` | bool | No* | Boolean value |

*Use the appropriate value for paramType (trigger doesn't need a value)

### animator_play
Play a specific animation state.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | Yes | - | GameObject name |
| `stateName` | string | Yes | - | Animation state name |
| `layer` | int | No | 0 | Animator layer |
| `normalizedTime` | float | No | 0 | Start time (0-1) |

### animator_get_info
Get Animator component information.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | GameObject name |

**Returns**: `{success, hasController, controllerName, parameters, currentState}`

### animator_assign_controller
Assign a controller to a GameObject.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | GameObject name |
| `controllerPath` | string | Yes | Controller asset path |

### animator_list_states
List all states in a controller layer.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `controllerPath` | string | Yes | - | Controller asset path |
| `layer` | int | No | 0 | Layer index |

**Returns**: `{success, states: [{name, tag, speed}]}`

---

## Example: Complete Animation Setup

```python
import unity_skills

# 1. Create controller
unity_skills.call_skill("animator_create_controller",
    name="PlayerController",
    folder="Assets/Animations"
)

# 2. Add parameters
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="Speed", paramType="float", defaultValue=0
)
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="IsGrounded", paramType="bool", defaultValue=True
)
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="Jump", paramType="trigger"
)

# 3. Assign to character
unity_skills.call_skill("animator_assign_controller",
    name="Player",
    controllerPath="Assets/Animations/PlayerController.controller"
)

# 4. Control at runtime
unity_skills.call_skill("animator_set_parameter",
    name="Player", paramName="Speed", paramType="float", floatValue=5.0
)

# Trigger jump
unity_skills.call_skill("animator_set_parameter",
    name="Player", paramName="Jump", paramType="trigger"
)

# Play specific state
unity_skills.call_skill("animator_play", name="Player", stateName="Idle")
```

## Best Practices

1. Create controller before adding parameters
2. Use meaningful parameter names
3. Triggers reset automatically after firing
4. Set parameters before playing states
5. Use layers for independent animations (body + face)
6. States must exist in controller before playing

Overview

This skill provides programmatic control over Unity Animator Controllers: create controllers, add and list parameters, assign controllers to GameObjects, and drive playback at runtime. It streamlines common animation setup tasks and runtime parameter updates so you can automate character and object animation workflows. Use it to build, inspect, and control Animator assets without manual editor steps.

How this skill works

The skill exposes discrete operations to create Animator Controller assets, add parameters of types (float, int, bool, trigger), and list or inspect controller contents. At runtime you can set parameters on an Animator component, play specific states, and assign controllers to GameObjects. It returns structured results for queries (parameters, states, controller info) so calling code can react programmatically.

When to use it

When creating Animator Controllers programmatically for characters or props
When you need to add or audit parameters across many controllers
To assign a controller to a GameObject at import or initialization time
When driving animations from game logic by setting parameters or playing states
To list states in a controller layer for debugging or tooling

Best practices

Create the controller asset before adding parameters to it
Use clear, consistent parameter names (Speed, IsGrounded, Jump)
Pick the correct parameter type: float/int for numeric blends, bool for toggles, trigger for one-shot events
Set parameters before calling Play to avoid race conditions
Organize animations with layers for independent control (e.g., body vs face)

Example use cases

Automate creation of a PlayerController with Speed, IsGrounded, and Jump parameters during project setup
Assign a controller to an instantiated enemy prefab and immediately set its AI-driven Speed parameter
Query a controller to list states and build an editor tool that visualizes available animation states and tags
Trigger a one-shot animation (attack or jump) via a trigger parameter from gameplay code
Batch-update parameters across many controllers when renaming or standardizing parameter names

FAQ

How do I set a trigger parameter at runtime?

Use the set-parameter operation with paramType 'trigger'; no value is required and the trigger fires once.

What happens if I try to play a state that does not exist?

Playing a non-existent state will fail; first list or inspect the controller states and ensure the requested state exists in the specified layer.