AnimationTree-Statemachines
in Godot 4

1. Einführung

AnimationTree ist das System von Godot 4 für komplexes Animation-Blending und Zustandsübergänge. Wenn du jemals versucht hast, mehrere Animationen mit über den gesamten Code verstreuten AnimationPlayer.play()-Aufrufen zu verwalten, weißt du, wie schnell das unübersichtlich wird. AnimationTree löst das mit einem visuellen Graphen aus Zuständen und Übergängen.

Obwohl AnimationTree unglaublich mächtig ist, ist die offizielle Dokumentation dünn und lässt Entwickler oft im Ungewissen. Dieser Leitfaden führt dich durch alles – von der grundlegenden Einrichtung bis zu fortgeschrittenen Blend Trees – mit echtem GDScript-Code, den du direkt in dein Projekt kopieren kannst.

2. Voraussetzungen

Bevor du deinen AnimationTree einrichtest, brauchst du:

• Einen AnimationPlayer-Node mit mindestens den bereits erstellten Animationen Idle, Walk, Run und Jump
• Der AnimationPlayer muss ein Geschwister- oder Kind-Node des Nodes sein, an dem du den AnimationTree hinzufügst (typischerweise sind beide Kinder deines Charakter-Root-Nodes)
• Godot 4.x (dieser Leitfaden verwendet die Godot-4-API — die AnimationTree-API hat sich gegenüber Godot 3 erheblich verändert)

3. Grundlegende Einrichtung

Die Einrichtung eines AnimationTree erfolgt in vier Schritten:

1. Einen AnimationTree-Node hinzufügen — Füge ihn als Kind deines Charakters (z. B. CharacterBody2D oder CharacterBody3D) neben deinem AnimationPlayer hinzu.
2. anim_player festlegen — Zeige im Inspector mit der Eigenschaft "Anim Player" auf deinen AnimationPlayer-Node.
3. tree_root festlegen — Klicke im Inspector auf die Eigenschaft "Tree Root" und erstelle eine neue AnimationNodeStateMachine.
4. active = true setzen — Aktiviere im Inspector das Kontrollkästchen "Active" oder setze es im Code.

Dein Szenenbaum sollte so aussehen:

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. Statemachine-Grundlagen

Eine Statemachine im AnimationTree beruht auf einem einfachen Konzept: Zustände repräsentieren Animationen und Übergänge definieren die Bedingungen für den Wechsel zwischen ihnen.

Zustände hinzufügen

Sobald der tree_root deines AnimationTree eine AnimationNodeStateMachine ist, doppelklicke im Inspector darauf, um den Statemachine-Editor zu öffnen:

1. Klicke mit der rechten Maustaste in den Graphen-Bereich und wähle Add Animation
2. Wähle eine Animation aus deinem AnimationPlayer (Idle, Walk, Run, Jump usw.)
3. Wiederhole dies für jeden Animationszustand, den du brauchst

Übergänge hinzufügen

So erstellst du einen Übergang zwischen zwei Zuständen:

1. Klicke auf den Quell-Zustands-Node
2. Ziehe zum Ziel-Zustand, um einen Übergangspfeil zu erstellen
3. Klicke auf den Übergangspfeil, um ihn im Inspector zu konfigurieren

Übergangseigenschaften

Eine typische Einrichtung für einen Plattformer-Charakter:

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. Die Statemachine aus Code steuern

Es gibt zwei Hauptwege, die Statemachine anzusteuern: das Setzen von Bedingungsparametern (automatische Übergänge) und der Aufruf von travel() (manuelle Übergänge). Du kannst beide Ansätze kombinieren.

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. Bedingungen

Bedingungsbasiert (empfohlen für Fortbewegung)

Setze jeden Frame Boolean-Parameter und lass die Übergänge automatisch feuern. Das ist deklarativer und hält deinen Code sauber. Die Statemachine kümmert sich um Übergangslogik, Crossfades und Randfälle für dich.

# 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() (empfohlen für einmalige Aktionen)

travel() fordert einen Zustandsübergang an. Es respektiert die Übergangsregeln — wenn vom aktuellen Zustand kein gültiger Pfad zum Ziel existiert, wird der Aufruf ignoriert. Dadurch ist es sicher, es wiederholt aufzurufen. Verwende es für einmalige Auslöser wie Angriffe, Emotes oder Cutscene-Animationen.

# 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

Blend Trees ermöglichen es dir, anhand eines kontinuierlichen Werts sanft zwischen mehreren Animationen zu interpolieren, statt hart zwischen diskreten Zuständen umzuschalten. Das ist ideal für das Blending von Geh-/Laufgeschwindigkeit und für gerichtete Bewegung.

BlendSpace1D

Ein 1D-Blend zwischen zwei oder mehr Animationen entlang einer einzigen Achse. Häufige Verwendung: das Blending von Walk und Run basierend auf der Bewegungsgeschwindigkeit.

Erstelle im Editor einen BlendSpace1D-Node innerhalb deiner Statemachine (oder als eigenständigen Tree Root). Füge Animationspunkte hinzu:

# 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

Ein 2D-Blend mit zwei Achsen. Perfekt für 8-Richtungs-Bewegung oder Top-Down-Spiele, in denen sich der Charakter in jede Richtung bewegen kann.

# 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. Gängige Node-Typen

AnimationTree unterstützt mehrere Node-Typen, die kombiniert werden können, um komplexes Animationsverhalten zu erzeugen:

9. OneShot-Muster (Angriffe, Emotes)

Der OneShot-Node ist eines der nützlichsten Muster im AnimationTree. Er spielt eine einmalige Animation über deiner Basisanimation ab (etwa das Abspielen eines Angriffsschwungs während des Gehens) und kehrt anschließend automatisch zur Basisanimation zurück.

Einrichtung im BlendTree

Um OneShot zu verwenden, muss der Root deines AnimationTree (oder ein Zustand darin) ein BlendTree sein:

# 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.

Auslösen aus Code

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

OneShot-Request-Konstanten

10. Praxisbeispiel: Vollständiger Character Controller

Hier ist ein vollständiges 2D-Plattformer-Charakterskript, das Statemachine-Fortbewegung mit einem OneShot-Angriff kombiniert. Das ist ein produktionsreifes Muster, das du an dein eigenes Projekt anpassen kannst.

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. Fehlerbehebung