Maszyny stanów AnimationTree
w Godot 4

1. Wprowadzenie

AnimationTree to system Godot 4 do złożonego mieszania animacji i przełączania stanów. Jeśli kiedykolwiek próbowałeś zarządzać wieloma animacjami za pomocą wywołań AnimationPlayer.play() rozsianych po całym kodzie, wiesz, jak szybko staje się to niemożliwe do opanowania. AnimationTree rozwiązuje ten problem za pomocą wizualnego grafu stanów i przejść.

Mimo że AnimationTree jest niezwykle potężny, jego oficjalna dokumentacja jest uboga i często pozostawia programistów bez odpowiedzi. Ten przewodnik prowadzi przez wszystko – od podstawowej konfiguracji po zaawansowane drzewa mieszania – z prawdziwym kodem GDScript, który możesz skopiować bezpośrednio do swojego projektu.

2. Wymagania wstępne

Zanim skonfigurujesz swój AnimationTree, potrzebujesz:

• Węzła AnimationPlayer z już utworzonymi co najmniej animacjami Idle, Walk, Run i Jump
• AnimationPlayer musi być rodzeństwem lub dzieckiem węzła, do którego dodajesz AnimationTree (zwykle oba są dziećmi głównego węzła postaci)
• Godot 4.x (ten przewodnik korzysta z API Godot 4 — API AnimationTree znacząco zmieniło się względem Godot 3)

3. Podstawowa konfiguracja

Konfiguracja AnimationTree wymaga czterech kroków:

1. Dodaj węzeł AnimationTree — Dodaj go jako dziecko swojej postaci (np. CharacterBody2D lub CharacterBody3D), obok AnimationPlayer.
2. Ustaw anim_player — W Inspektorze wskaż właściwością „Anim Player” swój węzeł AnimationPlayer.
3. Ustaw tree_root — Kliknij właściwość „Tree Root” w Inspektorze i utwórz nową AnimationNodeStateMachine.
4. Ustaw active = true — Zaznacz pole „Active” w Inspektorze albo ustaw to w kodzie.

Twoje drzewo sceny powinno wyglądać tak:

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. Podstawy maszyny stanów

Maszyna stanów w AnimationTree działa według prostej koncepcji: stany reprezentują animacje, a przejścia definiują warunki przełączania między nimi.

Dodawanie stanów

Gdy tree_root Twojego AnimationTree jest już typu AnimationNodeStateMachine, kliknij go dwukrotnie w Inspektorze, aby otworzyć edytor maszyny stanów:

1. Kliknij prawym przyciskiem myszy w obszarze grafu i wybierz Add Animation
2. Wybierz animację ze swojego AnimationPlayer (Idle, Walk, Run, Jump itd.)
3. Powtórz dla każdego potrzebnego stanu animacji

Dodawanie przejść

Aby utworzyć przejście między dwoma stanami:

1. Kliknij węzeł stanu źródłowego
2. Przeciągnij do stanu docelowego, aby utworzyć strzałkę przejścia
3. Kliknij strzałkę przejścia, aby skonfigurować ją w Inspektorze

Właściwości przejścia

Typowa konfiguracja dla postaci z platformówki:

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. Sterowanie maszyną stanów z kodu

Istnieją dwa główne sposoby sterowania maszyną stanów: ustawianie parametrów warunków (automatyczne przejścia) oraz wywoływanie travel() (przejścia ręczne). Oba podejścia można łączyć.

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 warunki

Oparte na warunkach (zalecane dla poruszania się)

W każdej klatce ustawiaj parametry logiczne i pozwól, aby przejścia wyzwalały się automatycznie. To bardziej deklaratywne i utrzymuje kod w czystości. Maszyna stanów sama zajmuje się logiką przejść, crossfade'ami i przypadkami brzegowymi.

# 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() (zalecane dla akcji jednorazowych)

travel() żąda przejścia stanu. Respektuje reguły przejść — jeśli z bieżącego stanu nie istnieje prawidłowa ścieżka do celu, wywołanie jest ignorowane. Dzięki temu można je bezpiecznie wywoływać wielokrotnie. Używaj go do jednorazowych wyzwalaczy, takich jak ataki, emotki czy animacje przerywników.

# 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. Drzewa mieszania (Blend Trees)

Drzewa mieszania pozwalają płynnie interpolować między wieloma animacjami na podstawie wartości ciągłej, zamiast twardo przełączać między dyskretnymi stanami. To idealne rozwiązanie do mieszania prędkości chodu/biegu oraz ruchu kierunkowego.

BlendSpace1D

Mieszanie 1D między dwoma lub więcej animacjami wzdłuż jednej osi. Typowe zastosowanie: mieszanie Walk i Run w zależności od prędkości poruszania się.

W edytorze utwórz węzeł BlendSpace1D wewnątrz swojej maszyny stanów (lub jako samodzielny tree root). Dodaj punkty animacji:

# 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

Mieszanie 2D wykorzystujące dwie osie. Idealne do ruchu 8-kierunkowego lub gier z widokiem z góry, w których postać może poruszać się w dowolnym kierunku.

# 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. Popularne typy węzłów

AnimationTree obsługuje kilka typów węzłów, które można łączyć w celu tworzenia złożonego zachowania animacji:

9. Wzorzec OneShot (ataki, emotki)

Węzeł OneShot to jeden z najbardziej przydatnych wzorców w AnimationTree. Odtwarza jednorazową animację na wierzchu Twojej animacji bazowej (np. odtwarzanie zamachu atakiem podczas chodzenia), a następnie automatycznie wraca do animacji bazowej.

Konfiguracja w BlendTree

Aby użyć OneShot, root Twojego AnimationTree (lub stan w jego wnętrzu) musi być typu 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.

Wyzwalanie z kodu

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

Stałe żądań OneShot

10. Przykład praktyczny: pełny kontroler postaci

Oto kompletny skrypt postaci 2D do platformówki, który łączy poruszanie się oparte na maszynie stanów z atakiem OneShot. To gotowy do produkcji wzorzec, który możesz dostosować do własnego projektu.

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. Rozwiązywanie problemów