AnimationTree Durum Makineleri
Godot 4'te

1. Giriş

AnimationTree, Godot 4'ün karmaşık animasyon blend'i ve durum geçişleri için sunduğu sistemdir. Kodunuzun her yerine dağılmış AnimationPlayer.play() çağrılarıyla birden fazla animasyonu yönetmeye çalıştıysanız, bunun ne kadar çabuk kontrolden çıktığını bilirsiniz. AnimationTree, bunu görsel bir durum ve geçiş grafiğiyle çözer.

Son derece güçlü olmasına rağmen AnimationTree'nin resmi dokümantasyonu yetersizdir ve geliştiricileri sıklıkla tahmin yürütmek zorunda bırakır. Bu rehber, temel kurulumdan ileri düzey blend tree'lere kadar her şeyi, projenize doğrudan kopyalayabileceğiniz gerçek GDScript koduyla adım adım anlatır.

2. Ön Koşullar

AnimationTree'nizi kurmadan önce şunlara ihtiyacınız var:

• En azından Idle, Walk, Run ve Jump animasyonları önceden oluşturulmuş bir AnimationPlayer node'u
• AnimationPlayer, AnimationTree'yi eklediğiniz node'un kardeşi veya alt öğesi olmalıdır (genellikle her ikisi de karakter kök node'unuzun alt öğeleridir)
• Godot 4.x (bu rehber Godot 4 API'sini kullanır — AnimationTree API'si Godot 3'e kıyasla önemli ölçüde değişti)

3. Temel Kurulum

Bir AnimationTree'nin kurulumu dört adımda gerçekleşir:

1. Bir AnimationTree node'u ekleyin — Onu, AnimationPlayer'ınızın yanında karakterinizin (ör. CharacterBody2D veya CharacterBody3D) alt öğesi olarak ekleyin.
2. anim_player ayarlayın — Inspector'da "Anim Player" özelliğini AnimationPlayer node'unuza yönlendirin.
3. tree_root ayarlayın — Inspector'da "Tree Root" özelliğine tıklayın ve yeni bir AnimationNodeStateMachine oluşturun.
4. active = true yapın — Inspector'da "Active" onay kutusunu işaretleyin veya koddan ayarlayın.

Sahne ağacınız şöyle görünmelidir:

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. Durum Makinesi Temelleri

AnimationTree'deki bir durum makinesi basit bir kavrama dayanır: durumlar animasyonları temsil eder ve geçişler bunlar arasında geçiş yapma koşullarını tanımlar.

Durum Ekleme

AnimationTree'nizin tree_root'u bir AnimationNodeStateMachine olduğunda, durum makinesi editörünü açmak için Inspector'da üzerine çift tıklayın:

1. Grafik alanına sağ tıklayın ve Add Animation seçeneğini seçin
2. AnimationPlayer'ınızdan bir animasyon seçin (Idle, Walk, Run, Jump vb.)
3. İhtiyacınız olan her animasyon durumu için tekrarlayın

Geçiş Ekleme

İki durum arasında bir geçiş oluşturmak için:

1. Kaynak durum node'una tıklayın
2. Bir geçiş oku oluşturmak için hedef duruma sürükleyin
3. Inspector'da yapılandırmak için geçiş okuna tıklayın

Geçiş Özellikleri

Bir platform oyunu karakteri için tipik bir kurulum:

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. Durum Makinesini Koddan Kontrol Etme

Durum makinesini yönlendirmenin iki temel yolu vardır: koşul parametreleri ayarlamak (otomatik geçişler) ve travel() çağırmak (manuel geçişler). Her iki yaklaşımı birleştirebilirsiniz.

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() ve Koşullar

Koşul Tabanlı (Hareket için Önerilir)

Her karede boolean parametreleri ayarlayın ve geçişlerin otomatik tetiklenmesine izin verin. Bu daha bildirimseldir ve kodunuzu temiz tutar. Durum makinesi, geçiş mantığını, crossfade'leri ve uç durumları sizin yerinize halleder.

# 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() (Tek Seferlik Aksiyonlar için Önerilir)

travel() bir durum geçişi talep eder. Geçiş kurallarına uyar — mevcut durumdan hedefe geçerli bir yol yoksa çağrı yok sayılır. Bu, onu tekrar tekrar çağırmayı güvenli kılar. Saldırılar, emote'lar veya ara sahne animasyonları gibi tek seferlik tetikleyiciler için kullanın.

# 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'ler

Blend tree'ler, ayrık durumlar arasında sert geçiş yapmak yerine sürekli bir değere göre birden fazla animasyon arasında yumuşakça enterpolasyon yapmanızı sağlar. Yürüme/koşma hızı blend'i ve yönlü hareket için mükemmeldir.

BlendSpace1D

Tek bir eksen boyunca iki veya daha fazla animasyon arasında bir 1D blend. Yaygın kullanım: hareket hızına göre Walk ile Run'ın blend'lenmesi.

Editörde, durum makinenizin içinde (veya bağımsız bir tree root olarak) bir BlendSpace1D node'u oluşturun. Animasyon noktaları ekleyin:

# 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

İki eksen kullanan bir 2D blend. 8 yönlü hareket veya karakterin herhangi bir yöne hareket edebildiği yukarıdan bakışlı oyunlar için mükemmeldir.

# 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. Yaygın Node Tipleri

AnimationTree, karmaşık animasyon davranışları oluşturmak için birleştirilebilen çeşitli node tiplerini destekler:

9. OneShot Deseni (Saldırılar, Emote'lar)

OneShot node'u AnimationTree'deki en kullanışlı desenlerden biridir. Temel animasyonunuzun üzerinde tek seferlik bir animasyon oynatır (yürürken bir saldırı savurmasını oynatmak gibi) ve ardından otomatik olarak temel animasyona döner.

BlendTree İçinde Kurulum

OneShot kullanmak için AnimationTree kökünüzün (veya içindeki bir durumun) bir BlendTree olması gerekir:

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

Koddan Tetikleme

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 İstek Sabitleri

10. Pratik Örnek: Eksiksiz Karakter Kontrolcüsü

İşte durum makinesi hareketini bir OneShot saldırısıyla birleştiren eksiksiz bir 2D platform oyunu karakter betiği. Bu, kendi projenize uyarlayabileceğiniz üretime hazır bir desendir.

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. Sorun Giderme