AnimationTree Máquinas de estados
no Godot 4

1. Introdução

O AnimationTree é o sistema do Godot 4 para blending complexo de animações e transições de estado. Se você já tentou gerenciar múltiplas animações com chamadas de AnimationPlayer.play() espalhadas pelo código, sabe como isso rapidamente se torna ingerenciável. O AnimationTree resolve esse problema com um grafo visual de estados e transições.

Apesar de ser incrivelmente poderoso, a documentação oficial do AnimationTree é escassa e muitas vezes deixa os desenvolvedores no escuro. Este guia percorre tudo – da configuração básica aos blend trees avançados – com código GDScript real que você pode copiar direto para o seu projeto.

2. Pré-requisitos

Antes de configurar o seu AnimationTree, você precisa de:

• Um node AnimationPlayer com, pelo menos, as animações Idle, Walk, Run e Jump já criadas
• O AnimationPlayer deve ser um irmão ou filho do node onde você adiciona o AnimationTree (normalmente ambos são filhos do node raiz do seu personagem)
• Godot 4.x (este guia usa a API do Godot 4 — a API do AnimationTree mudou significativamente em relação ao Godot 3)

3. Configuração básica

Configurar um AnimationTree leva quatro passos:

1. Adicione um node AnimationTree — Adicione-o como filho do seu personagem (ex.: CharacterBody2D ou CharacterBody3D), ao lado do seu AnimationPlayer.
2. Defina anim_player — No Inspector, aponte a propriedade "Anim Player" para o seu node AnimationPlayer.
3. Defina tree_root — Clique na propriedade "Tree Root" no Inspector e crie uma nova AnimationNodeStateMachine.
4. Defina active = true — Marque a caixa "Active" no Inspector ou defina no código.

Sua árvore de cena deve ficar assim:

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. Fundamentos da máquina de estados

Uma máquina de estados no AnimationTree funciona com um conceito simples: os estados representam animações e as transições definem as condições para alternar entre elas.

Adicionando estados

Assim que o tree_root do seu AnimationTree for uma AnimationNodeStateMachine, dê duplo clique nele no Inspector para abrir o editor da máquina de estados:

1. Clique com o botão direito na área do grafo e selecione Add Animation
2. Escolha uma animação do seu AnimationPlayer (Idle, Walk, Run, Jump, etc.)
3. Repita para cada estado de animação que você precisar

Adicionando transições

Para criar uma transição entre dois estados:

1. Clique no node do estado de origem
2. Arraste até o estado de destino para criar uma seta de transição
3. Clique na seta de transição para configurá-la no Inspector

Propriedades da transição

Uma configuração típica para um personagem de plataforma:

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. Controlando a máquina de estados via código

Há duas maneiras principais de conduzir a máquina de estados: definindo parâmetros de condição (transições automáticas) e chamando travel() (transições manuais). Você pode combinar as duas abordagens.

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. condições

Baseado em condições (recomendado para locomoção)

Defina parâmetros booleanos a cada frame e deixe as transições dispararem automaticamente. Isso é mais declarativo e mantém o seu código limpo. A máquina de estados cuida da lógica de transição, dos crossfades e dos casos extremos por você.

# 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() (recomendado para ações pontuais)

travel() solicita uma transição de estado. Ele respeita as regras de transição — se não existir um caminho válido do estado atual até o alvo, a chamada é ignorada. Isso o torna seguro para ser chamado repetidamente. Use-o para gatilhos pontuais como ataques, emotes ou animações de 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 Trees

Os blend trees permitem interpolar suavemente entre várias animações com base em um valor contínuo, em vez de alternar bruscamente entre estados discretos. Isso é ideal para o blending de velocidade de caminhada/corrida e para movimento direcional.

BlendSpace1D

Um blend 1D entre duas ou mais animações ao longo de um único eixo. Uso comum: mesclar Walk e Run com base na velocidade de movimento.

No editor, crie um node BlendSpace1D dentro da sua máquina de estados (ou como tree root autônomo). Adicione pontos de animação:

# 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

Um blend 2D usando dois eixos. Perfeito para movimento em 8 direções ou jogos top-down em que o personagem pode se mover em qualquer direção.

# 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. Tipos de node comuns

O AnimationTree suporta vários tipos de node que podem ser combinados para criar comportamentos de animação complexos:

9. Padrão OneShot (ataques, emotes)

O node OneShot é um dos padrões mais úteis do AnimationTree. Ele reproduz uma animação única por cima da sua animação base (como reproduzir um golpe de ataque enquanto caminha) e, em seguida, retorna automaticamente para a animação base.

Configuração no BlendTree

Para usar o OneShot, o root do seu AnimationTree (ou um estado dentro dele) precisa ser um 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.

Acionando via código

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

Constantes de request do OneShot

10. Exemplo prático: character controller completo

Aqui está um script completo de personagem de plataforma 2D que combina locomoção por máquina de estados com um ataque OneShot. Este é um padrão pronto para produção que você pode adaptar ao seu próprio projeto.

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. Solução de problemas