State machine AnimationTree
in Godot 4

1. Introduzione

AnimationTree è il sistema di Godot 4 per il blending complesso delle animazioni e le transizioni di stato. Se hai mai provato a gestire più animazioni con chiamate a AnimationPlayer.play() sparse in tutto il codice, sai quanto rapidamente diventi ingestibile. AnimationTree risolve il problema con un grafo visivo di stati e transizioni.

Nonostante sia incredibilmente potente, la documentazione ufficiale di AnimationTree è scarna e spesso lascia gli sviluppatori a tirare a indovinare. Questa guida ti accompagna attraverso tutto – dalla configurazione di base ai blend tree avanzati – con codice GDScript reale che puoi copiare direttamente nel tuo progetto.

2. Prerequisiti

Prima di configurare il tuo AnimationTree, ti serve:

• Un nodo AnimationPlayer con almeno le animazioni Idle, Walk, Run e Jump già create
• L'AnimationPlayer deve essere un fratello o un figlio del nodo a cui aggiungi l'AnimationTree (di solito entrambi sono figli del nodo radice del tuo personaggio)
• Godot 4.x (questa guida usa l'API di Godot 4 — l'API di AnimationTree è cambiata sensibilmente rispetto a Godot 3)

3. Configurazione di base

La configurazione di un AnimationTree avviene in quattro passi:

1. Aggiungere un nodo AnimationTree — Aggiungilo come figlio del tuo personaggio (es. CharacterBody2D o CharacterBody3D) accanto al tuo AnimationPlayer.
2. Impostare anim_player — Nell'Inspector, punta la proprietà "Anim Player" al tuo nodo AnimationPlayer.
3. Impostare tree_root — Clicca sulla proprietà "Tree Root" nell'Inspector e crea una nuova AnimationNodeStateMachine.
4. Impostare active = true — Attiva la casella "Active" nell'Inspector oppure impostala da codice.

Il tuo albero della scena dovrebbe apparire così:

CharacterBody2D (or CharacterBody3D)
  +-- Sprite2D (or Sprite3D)
  +-- CollisionShape2D
  +-- AnimationPlayer      <-- has Idle, Walk, Run, Jump animations
  +-- AnimationTree         <-- points to AnimationPlayer above

# Minimal code setup (usually done via the editor instead):
@onready var anim_tree: AnimationTree = $AnimationTree

func _ready() -> void:
    # If you set these in the Inspector, you don't need this code
    anim_tree.anim_player = ^"../AnimationPlayer"
    anim_tree.tree_root = AnimationNodeStateMachine.new()
    anim_tree.active = true

4. Fondamenti delle state machine

Una state machine in AnimationTree si basa su un concetto semplice: gli stati rappresentano le animazioni e le transizioni definiscono le condizioni per passare dall'una all'altra.

Aggiungere gli stati

Una volta che il tree_root del tuo AnimationTree è una AnimationNodeStateMachine, fai doppio clic su di essa nell'Inspector per aprire l'editor della state machine:

1. Fai clic con il tasto destro nell'area del grafo e seleziona Add Animation
2. Scegli un'animazione dal tuo AnimationPlayer (Idle, Walk, Run, Jump, ecc.)
3. Ripeti per ogni stato di animazione che ti serve

Aggiungere le transizioni

Per creare una transizione tra due stati:

1. Clicca sul nodo dello stato di partenza
2. Trascina verso lo stato di destinazione per creare una freccia di transizione
3. Clicca sulla freccia di transizione per configurarla nell'Inspector

Proprietà delle transizioni

Una configurazione tipica per un personaggio da platform:

Start --> Idle
Idle  --> Walk   (condition: is_moving)
Walk  --> Idle   (condition: is_idle)
Idle  --> Jump   (condition: is_jumping)
Walk  --> Jump   (condition: is_jumping)
Jump  --> Fall   (condition: is_falling)
Fall  --> Idle   (condition: is_on_floor, switch_mode: Immediate)

5. Controllare la state machine da codice

Ci sono due modi principali per pilotare la state machine: impostare i parametri di condizione (transizioni automatiche) e chiamare travel() (transizioni manuali). Puoi combinare entrambi gli approcci.

extends CharacterBody2D

@onready var anim_tree: AnimationTree = $AnimationTree
@onready var state_machine: AnimationNodeStateMachinePlayback = anim_tree.get("parameters/playback")

func _physics_process(delta: float) -> void:
    # ... movement logic here ...
    move_and_slide()
    _update_animation_parameters()

func _update_animation_parameters() -> void:
    # Approach 1: Set condition parameters — transitions fire automatically
    anim_tree.set("parameters/conditions/is_moving", velocity.length() > 10.0)
    anim_tree.set("parameters/conditions/is_idle", velocity.length() <= 10.0)
    anim_tree.set("parameters/conditions/is_on_floor", is_on_floor())
    anim_tree.set("parameters/conditions/is_jumping", velocity.y < 0 and not is_on_floor())
    anim_tree.set("parameters/conditions/is_falling", velocity.y > 0 and not is_on_floor())

    # Approach 2: Use travel() for direct control
    # if velocity.length() > 10.0:
    #     state_machine.travel("Walk")
    # else:
    #     state_machine.travel("Idle")

6. travel() vs condizioni

Basato su condizioni (consigliato per la locomozione)

Imposta parametri booleani ogni frame e lascia che le transizioni scattino automaticamente. È più dichiarativo e mantiene il codice pulito. La state machine gestisce per te la logica delle transizioni, i crossfade e i casi limite.

# Declarative: just describe the current state of the world
anim_tree.set("parameters/conditions/is_moving", velocity.length() > 10.0)
anim_tree.set("parameters/conditions/is_on_floor", is_on_floor())

travel() (consigliato per le azioni una tantum)

travel() richiede una transizione di stato. Rispetta le regole di transizione — se non esiste un percorso valido dallo stato corrente alla destinazione, la chiamata viene ignorata. Questo la rende sicura da chiamare ripetutamente. Usala per trigger una tantum come attacchi, emote o animazioni di cutscene.

# travel() — requests a transition (respects transition rules)
state_machine.travel("Jump")

# Get current state name
var current: StringName = state_machine.get_current_node()
print(current)  # "Idle", "Walk", etc.

# Check if travel is possible
var is_playing: bool = state_machine.is_playing()
print(is_playing)

7. Blend tree

I blend tree ti permettono di interpolare in modo morbido tra più animazioni in base a un valore continuo, invece di commutare bruscamente tra stati discreti. È l'ideale per il blending della velocità di camminata/corsa e per il movimento direzionale.

BlendSpace1D

Un blend 1D tra due o più animazioni lungo un unico asse. Uso comune: il blending di Walk e Run in base alla velocità di movimento.

Nell'editor, crea un nodo BlendSpace1D dentro la tua state machine (oppure come tree root a sé stante). Aggiungi i punti di animazione:

# BlendSpace1D setup (in editor):
# Point 0.0 = Walk animation
# Point 1.0 = Run animation

# Control from code:
var speed_factor: float = clamp(velocity.length() / max_speed, 0.0, 1.0)
anim_tree.set("parameters/WalkRun/blend_position", speed_factor)

BlendSpace2D

Un blend 2D con due assi. Perfetto per il movimento a 8 direzioni o per i giochi top-down in cui il personaggio può muoversi in qualsiasi direzione.

# BlendSpace2D setup (in editor):
# Place animations at positions:
#   Idle at (0, 0)
#   WalkRight at (1, 0), WalkLeft at (-1, 0)
#   WalkUp at (0, -1), WalkDown at (0, 1)
#   Diagonals at corners

# Control from code:
var input_dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
anim_tree.set("parameters/Movement/blend_position", input_dir)

8. Tipi di nodo comuni

AnimationTree supporta diversi tipi di nodo che possono essere combinati per creare comportamenti di animazione complessi:

9. Pattern OneShot (attacchi, emote)

Il nodo OneShot è uno dei pattern più utili in AnimationTree. Riproduce un'animazione una tantum sopra la tua animazione di base (come riprodurre un fendente d'attacco durante la camminata) e poi torna automaticamente all'animazione di base.

Configurazione in un BlendTree

Per usare OneShot, la radice del tuo AnimationTree (o uno stato al suo interno) deve essere un BlendTree:

# BlendTree graph setup:
#
#   [StateMachine] ---> [OneShot "AttackOneShot"] ---> [Output]
#   (base locomotion)      ^
#                          |
#                   [Animation "Attack"]
#                   (shot input)
#
# The StateMachine provides the base (idle/walk/run).
# The Attack animation is connected to the OneShot's "shot" input.

Attivare da codice

extends CharacterBody2D

@onready var anim_tree: AnimationTree = $AnimationTree

func _input(event: InputEvent) -> void:
    if event.is_action_pressed("attack"):
        _play_attack()

func _play_attack() -> void:
    # Fire the one-shot animation
    anim_tree.set(
        "parameters/AttackOneShot/request",
        AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
    )

func _process(delta: float) -> void:
    # Check if the one-shot is currently active
    var is_attacking: bool = anim_tree.get("parameters/AttackOneShot/active")
    if is_attacking:
        # Optionally disable movement during attack
        pass

Costanti di richiesta OneShot

10. Esempio pratico: character controller completo

Ecco uno script completo per un personaggio da platform 2D che combina la locomozione con state machine e un attacco OneShot. È un pattern pronto per la produzione che puoi adattare al tuo progetto.

extends CharacterBody2D

const SPEED := 200.0
const JUMP_VELOCITY := -350.0
const SPRINT_MULTIPLIER := 1.6

@onready var anim_tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = anim_tree.get("parameters/playback")
@onready var sprite: Sprite2D = $Sprite2D

var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")

func _ready() -> void:
    anim_tree.active = true

func _physics_process(delta: float) -> void:
    _apply_gravity(delta)
    _handle_jump()
    _handle_movement()
    move_and_slide()
    _update_animation()

func _apply_gravity(delta: float) -> void:
    if not is_on_floor():
        velocity.y += gravity * delta

func _handle_jump() -> void:
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = JUMP_VELOCITY

func _handle_movement() -> void:
    var direction := Input.get_axis("move_left", "move_right")
    var is_sprinting := Input.is_action_pressed("sprint")
    var current_speed := SPEED * (SPRINT_MULTIPLIER if is_sprinting else 1.0)

    if direction != 0.0:
        velocity.x = direction * current_speed
        sprite.flip_h = direction < 0.0
    else:
        velocity.x = move_toward(velocity.x, 0.0, SPEED)

func _update_animation() -> void:
    # Skip animation updates during attack
    var is_attacking: bool = anim_tree.get("parameters/AttackOneShot/active")
    if is_attacking:
        return

    if not is_on_floor():
        if velocity.y < 0:
            playback.travel("Jump")
        else:
            playback.travel("Fall")
    elif abs(velocity.x) > 10.0:
        if Input.is_action_pressed("sprint"):
            playback.travel("Run")
        else:
            playback.travel("Walk")
    else:
        playback.travel("Idle")

func _input(event: InputEvent) -> void:
    if event.is_action_pressed("attack") and is_on_floor():
        anim_tree.set(
            "parameters/AttackOneShot/request",
            AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
        )

11. Risoluzione dei problemi