godot-animation

# AnimationTree & Tween reference (Godot 4.7)

Depth companion to `godot-animation`.

## AnimationPlayer essentials

- Author clips in the editor's Animation panel; each clip keys node properties over time.
- Track types: **Property** (most common), **3D Position/Rotation/Scale**, **Method**
  (call a function at a keyframe), **Call** track, **Bezier** (curved value), **Audio**,
  **Animation** (play another AnimationPlayer's clip).
- Playback: `play("name")`, `play_backwards("name")`, `stop()`, `pause()`,
  `seek(time, true)`, `speed_scale`, `queue("next")`.
- Signals: `animation_finished(name)`, `animation_started(name)`,
  `current_animation_changed(name)`.
- Set a clip's loop mode in the panel (None / Linear / Ping-Pong).

A **method track** calls a function on the keyed node — great for spawning a hitbox at the
exact attack frame. A **call track** is similar via the editor's "Functions" track.

## AnimationTree nodes

Set `AnimationTree.tree_root` to one of:

- `AnimationNodeStateMachine` — named states with transitions. Drive via the playback
  object:
  ```gdscript
  var sm: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
  sm.travel("attack")          # finds a path through transitions to "attack"
  sm.start("idle")             # jump immediately, ignoring transitions
  sm.get_current_node()        # current state name
  ```
  Transitions can be set to **Immediate**, **Sync**, or **At End**, and gated by
  **advance conditions** (booleans you set: `tree.set("parameters/conditions/is_dead", true)`)
  or an advance expression.
- `AnimationNodeBlendSpace1D` / `BlendSpace2D` — place clips at points; set
  `"parameters/<name>/blend_position"` to blend between them (e.g. directional locomotion).
- `AnimationNodeBlendTree` — a graph of blend/add/one-shot nodes with named outputs.
- `AnimationNodeOneShot` — fire a one-off (e.g. a hit reaction) over a base animation:
  ```gdscript
  tree.set("parameters/Shot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE)
  ```

Parameter path rule: `"parameters/" + node_name + "/" + property`. The playback for the
root state machine is always `"parameters/playback"`.

## Root motion

For animations that move the character via the skeleton: set
`AnimationTree.root_motion_track` to the motion track, then each physics frame apply
`tree.get_root_motion_position()` (and rotation) to the body. Useful for cinematic,
animation-driven locomotion.

## AnimatedSprite2D (sprite sheets)

```gdscript
@onready var spr: AnimatedSprite2D = $AnimatedSprite2D   # uses a SpriteFrames resource

func face(dir: float) -> void:
    spr.flip_h = dir < 0.0
    spr.play("walk")          # animation names defined in the SpriteFrames editor
    # spr.frame, spr.speed_scale, signal animation_finished, frame_changed
```

`SpriteFrames` holds named animations, each a list of texture frames with an FPS and loop
flag. Alternatively, keyframe `frame` / `region_rect` in an `AnimationPlayer`.

## Tween (create_tween) details

```gdscript
var tw := create_tween()
tw.tween_property(obj, "position", target, 0.5)        # interpolate a property
tw.tween_property(obj, "modulate:a", 0.0, 0.3)         # sub-property
tw.tween_interval(0.2)                                 # wait
tw.tween_callback(func(): print("done"))               # call a function
tw.tween_method(_set_progress, 0.0, 1.0, 1.0)          # call setter over time

tw.set_parallel(true)        # subsequent tweens run together (default is sequential)
tw.set_loops(3)              # repeat (0 = infinite)
tw.set_trans(Tween.TRANS_SINE)
tw.set_ease(Tween.EASE_IN_OUT)
await tw.finished            # signal when complete
tw.kill()                    # cancel early
```

Transitions: `TRANS_LINEAR/SINE/QUINT/QUART/QUAD/EXPO/ELASTIC/CUBIC/CIRC/BOUNCE/BACK/SPRING`.
Eases: `EASE_IN/OUT/IN_OUT/OUT_IN`. Chain methods on the returned `PropertyTweener`:
`.set_delay(0.1)`, `.from(start)`, `.from_current()`, `.as_relative()`.

A tween created with `create_tween()` is bound to the node's tree and is killed if the
node leaves the tree. Use `get_tree().create_tween()` to outlive a specific node.

---
name: godot-animation
description: >
  Animate in Godot 4.7 three ways: AnimationPlayer for keyframed clips (incl. call
  and signal tracks), AnimationTree with state machines and blend spaces for
  character animation, and Tween for short procedural/UI tweens via create_tween().
  Use when working with AnimationPlayer/AnimationTree nodes in a .tscn, blending
  character states, sprite-sheet animation, or code-driven Tweens.
---

# Godot Animation (4.x)

Choose and drive the right animation tool: `AnimationPlayer` (clips), `AnimationTree`
(blending/state machines), or `Tween` (short procedural moves). Targets **Godot 4.7**.

## When to use

- Use when playing keyframed animations, blending walk/run/idle states, animating a
  sprite sheet, or tweening UI/objects in code.

**When *not* to use:** the movement *logic* that decides which state to play →
`godot-2d-movement`; UI layout (vs. UI tweening) → `godot-ui-control`; shader-driven
effects → `godot-shaders`.

## Core workflow

1. **Pick the tool:**
   - `AnimationPlayer` — author keyframed clips (transforms, properties, method calls,
     audio, even other animations). The source of truth for clip data.
   - `AnimationTree` — blend and transition between those clips at runtime with a state
     machine and/or blend spaces. Needs an `AnimationPlayer` to pull clips from.
   - `Tween` — fire-and-forget procedural interpolation in code (`create_tween()`); ideal
     for UI pops, fades, and one-off moves.
2. **For 2D sprite sheets:** use `AnimatedSprite2D` + `SpriteFrames`, or keyframe the
   `frame` property in an `AnimationPlayer`.
3. **For characters:** build clips in `AnimationPlayer`, then add an `AnimationTree`
   (`active = true`), set its `anim_player`, and design an `AnimationNodeStateMachine` or
   `AnimationNodeBlendSpace2D` as the tree root.
4. **Drive transitions from code** via the playback object (`travel`) or by setting blend
   parameters.
5. **React to clip events** with the `animation_finished` signal and call/method tracks.

## Patterns

### 1. AnimationPlayer: play a clip and await it

```gdscript
@onready var anim: AnimationPlayer = $AnimationPlayer

func attack() -> void:
    anim.play("attack")
    await anim.animation_finished     # resume after the clip ends
    anim.play("idle")
```

### 2. AnimationTree state machine: travel between states

```gdscript
@onready var tree: AnimationTree = $AnimationTree

func _ready() -> void:
    tree.active = true                # the tree drives animation; AnimationPlayer is the source

func set_state(state: StringName) -> void:
    # The playback object controls an AnimationNodeStateMachine root.
    var sm: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
    sm.travel(state)                  # transitions using the graph's connections

func _physics_process(_d: float) -> void:
    set_state(&"run" if velocity.length() > 5.0 else &"idle")
```

### 3. Blend space: blend run direction by a 2D parameter

```gdscript
# Root is an AnimationNodeBlendSpace2D named "Move" with idle/run points placed in it.
func update_locomotion(input_dir: Vector2) -> void:
    # Parameter path = "parameters/<node name>/blend_position".
    tree.set("parameters/Move/blend_position", input_dir)
```

### 4. Tween: fade and scale a UI element (code-driven)

```gdscript
func pop_in(node: Control) -> void:
    node.scale = Vector2.ZERO
    node.modulate.a = 0.0
    var tw := create_tween()                          # bound to this node's tree
    tw.set_parallel(true)                             # run the two tweens together
    tw.tween_property(node, "scale", Vector2.ONE, 0.2) \
      .set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
    tw.tween_property(node, "modulate:a", 1.0, 0.2)   # sub-property via ":"
```

## Pitfalls

- **`AnimationTree.active` left false** → nothing animates and `travel()` appears to do
  nothing. Set `active = true` and assign the `anim_player` path.
- **Wrong parameter path.** Blend/condition paths are `"parameters/<NodeName>/..."` and
  must match the node names in the tree exactly (e.g. `"parameters/playback"`,
  `"parameters/Move/blend_position"`). A typo silently no-ops.
- **AnimationPlayer and AnimationTree fighting.** When an `AnimationTree` is active, don't
  also call `AnimationPlayer.play()` for the same tracks — let the tree own playback.
- **3.x Tween node is gone.** There is no `Tween` node to add in 4.x; create tweens in
  code with `create_tween()` (which returns a `Tween`). They auto-start and free themselves.
- **Reusing a finished tween.** A tween is one-shot; call `create_tween()` again for a new
  animation. Use `set_loops()` for repetition.
- **`yield`/`yield(anim, "...")` is gone.** Use `await anim.animation_finished`.
- **Sub-property tweens** use a colon: `"modulate:a"`, `"position:x"`. Tweening the whole
  property instead overwrites siblings.

## References

- For state machine transitions/conditions, root motion, one-shot/blend nodes, method &
  call tracks, `SpriteFrames`/`AnimatedSprite2D`, and Tween easing/chaining/callbacks,
  read `references/animation-tree-and-tween.md`.

## Related skills

- `godot-2d-movement` — supplies the velocity/state that selects animations.
- `godot-ui-control` — UI that Tweens animate.
- `godot-3d-essentials` — 3D character scenes driven by AnimationTree.
- `game-ai` — state machines that mirror animation states.