AnimationTree State Machine
ใน Godot 4

1. บทนำ

AnimationTree คือระบบของ Godot 4 สำหรับการเบลนด์อนิเมชันที่ซับซ้อนและการเปลี่ยน state หากคุณเคยพยายามจัดการอนิเมชันหลายตัวด้วยการเรียก AnimationPlayer.play() กระจายอยู่ทั่วโค้ด คุณคงรู้ดีว่ามันเริ่มควบคุมไม่ได้เร็วแค่ไหน AnimationTree แก้ปัญหานี้ด้วยกราฟภาพของ state และ transition

แม้จะทรงพลังอย่างเหลือเชื่อ แต่เอกสารทางการของ AnimationTree กลับมีน้อยและมักทำให้นักพัฒนาต้องเดาเอาเอง คู่มือนี้จะพาคุณไปตั้งแต่การตั้งค่าพื้นฐานไปจนถึง blend tree ขั้นสูง พร้อมโค้ด GDScript จริงที่คุณคัดลอกไปใช้ในโปรเจกต์ได้ทันที

2. สิ่งที่ต้องมีก่อน

ก่อนตั้งค่า AnimationTree คุณต้องมี:

• โหนด AnimationPlayer ที่มีอนิเมชันอย่างน้อย Idle, Walk, Run และ Jump สร้างไว้แล้ว
• AnimationPlayer ต้องเป็นโหนดพี่น้องหรือลูกของโหนดที่คุณเพิ่ม AnimationTree เข้าไป (โดยทั่วไปทั้งสองเป็นลูกของโหนดรากตัวละครของคุณ)
• Godot 4.x (คู่มือนี้ใช้ API ของ Godot 4 — API ของ AnimationTree เปลี่ยนไปมากจาก Godot 3)

3. การตั้งค่าพื้นฐาน

การตั้งค่า AnimationTree มีสี่ขั้นตอน:

1. เพิ่มโหนด AnimationTree — เพิ่มเป็นลูกของตัวละครของคุณ (เช่น CharacterBody2D หรือ CharacterBody3D) วางไว้ข้าง ๆ AnimationPlayer
2. ตั้งค่า anim_player — ใน Inspector ให้ชี้พรอเพอร์ตี "Anim Player" ไปยังโหนด AnimationPlayer ของคุณ
3. ตั้งค่า tree_root — คลิกพรอเพอร์ตี "Tree Root" ใน Inspector แล้วสร้าง AnimationNodeStateMachine ใหม่
4. ตั้งค่า active = true — ติ๊กช่อง "Active" ใน Inspector หรือตั้งค่าในโค้ด

โครงสร้างซีน (scene tree) ของคุณควรมีลักษณะแบบนี้:

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. พื้นฐาน State Machine

State machine ใน AnimationTree ทำงานบนแนวคิดง่าย ๆ: state แทนอนิเมชัน และ transition กำหนดเงื่อนไขในการสลับระหว่างกัน

การเพิ่ม State

เมื่อ tree_root ของ AnimationTree เป็น AnimationNodeStateMachine แล้ว ให้ดับเบิลคลิกที่มันใน Inspector เพื่อเปิดเอดิเตอร์ของ state machine:

1. คลิกขวาในพื้นที่กราฟแล้วเลือก Add Animation
2. เลือกอนิเมชันจาก AnimationPlayer ของคุณ (Idle, Walk, Run, Jump ฯลฯ)
3. ทำซ้ำสำหรับแต่ละ state ของอนิเมชันที่คุณต้องการ

การเพิ่ม Transition

ในการสร้าง transition ระหว่างสอง state:

1. คลิกที่โหนด state ต้นทาง
2. ลากไปยัง state ปลายทางเพื่อสร้างลูกศร transition
3. คลิกที่ลูกศร transition เพื่อตั้งค่าใน Inspector

พรอเพอร์ตีของ Transition

การตั้งค่าทั่วไปสำหรับตัวละครในเกมแพลตฟอร์เมอร์:

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. ควบคุม State Machine จากโค้ด

มีสองวิธีหลักในการสั่งงาน state machine: การตั้งค่าพารามิเตอร์ condition (transition อัตโนมัติ) และการเรียก travel() (transition แบบสั่งเอง) คุณสามารถผสมทั้งสองแนวทางเข้าด้วยกันได้

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() กับ Condition

แบบอิง Condition (แนะนำสำหรับการเคลื่อนที่)

ตั้งค่าพารามิเตอร์ boolean ทุกเฟรมและปล่อยให้ transition ทำงานโดยอัตโนมัติ วิธีนี้เป็นเชิงประกาศ (declarative) มากกว่าและทำให้โค้ดของคุณสะอาด State machine จะจัดการตรรกะ transition, crossfade และกรณีขอบเขตต่าง ๆ ให้คุณ

# 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() (แนะนำสำหรับแอ็กชันครั้งเดียว)

travel() ร้องขอการเปลี่ยน state โดยเคารพกฎของ transition — หากไม่มีเส้นทางที่ถูกต้องจาก state ปัจจุบันไปยังเป้าหมาย การเรียกจะถูกละเว้น ทำให้เรียกซ้ำได้อย่างปลอดภัย ใช้กับทริกเกอร์ครั้งเดียว เช่น การโจมตี, อีโมต หรืออนิเมชันคัตซีน

# 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

Blend tree ช่วยให้คุณแทรกค่าระหว่างอนิเมชันหลายตัวได้อย่างราบรื่นตามค่าต่อเนื่อง แทนที่จะสลับ state แบบตายตัว เหมาะอย่างยิ่งสำหรับการเบลนด์ความเร็ว walk/run และการเคลื่อนที่ตามทิศทาง

BlendSpace1D

การเบลนด์แบบ 1 มิติระหว่างอนิเมชันสองตัวขึ้นไปตามแกนเดียว การใช้งานที่พบบ่อย: เบลนด์ Walk และ Run ตามความเร็วการเคลื่อนที่

ในเอดิเตอร์ ให้สร้างโหนด BlendSpace1D ภายใน state machine ของคุณ (หรือเป็น tree root แบบสแตนด์อโลน) แล้วเพิ่มจุดอนิเมชัน:

# 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

การเบลนด์แบบ 2 มิติโดยใช้สองแกน เหมาะอย่างยิ่งสำหรับการเคลื่อนที่ 8 ทิศทางหรือเกมมุมมองบนสุดที่ตัวละครเคลื่อนที่ได้ทุกทิศทาง

# 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. ประเภทโหนดที่พบบ่อย

AnimationTree รองรับโหนดหลายประเภทที่สามารถนำมาผสมกันเพื่อสร้างพฤติกรรมอนิเมชันที่ซับซ้อน:

9. รูปแบบ OneShot (การโจมตี, อีโมต)

โหนด OneShot เป็นหนึ่งในรูปแบบที่มีประโยชน์ที่สุดใน AnimationTree มันเล่นอนิเมชันครั้งเดียวทับบนอนิเมชันฐานของคุณ (เช่นเล่นการเหวี่ยงโจมตีขณะเดิน) แล้วกลับสู่อนิเมชันฐานโดยอัตโนมัติ

การตั้งค่าใน BlendTree

ในการใช้ OneShot ราก AnimationTree ของคุณ (หรือ state ภายในนั้น) ต้องเป็น 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.

การทริกเกอร์จากโค้ด

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

10. ตัวอย่างใช้งานจริง: Character Controller แบบสมบูรณ์

นี่คือสคริปต์ตัวละครแพลตฟอร์เมอร์ 2D ที่สมบูรณ์ซึ่งผสานการเคลื่อนที่ด้วย state machine เข้ากับการโจมตีแบบ OneShot เป็นรูปแบบที่พร้อมใช้งานจริงและปรับใช้กับโปรเจกต์ของคุณเองได้

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. การแก้ปัญหา