AnimationTree State Machine
trong Godot 4

1. Giới thiệu

AnimationTree là hệ thống của Godot 4 dùng cho việc trộn animation phức tạp và chuyển đổi trạng thái. Nếu bạn từng thử quản lý nhiều animation bằng các lệnh gọi AnimationPlayer.play() rải rác khắp mã của mình, hẳn bạn biết nó nhanh chóng trở nên khó kiểm soát đến mức nào. AnimationTree giải quyết vấn đề này bằng một đồ thị trực quan gồm các trạng thái và transition.

Dù cực kỳ mạnh mẽ, tài liệu chính thức của AnimationTree lại sơ sài và thường khiến các nhà phát triển phải mò mẫm. Hướng dẫn này đi qua mọi thứ, từ thiết lập cơ bản đến blend tree nâng cao, kèm mã GDScript thực tế mà bạn có thể sao chép vào dự án của mình.

2. Điều kiện tiên quyết

Trước khi thiết lập AnimationTree, bạn cần:

• Một node AnimationPlayer đã có sẵn tối thiểu các animation Idle, Walk, Run và Jump
• AnimationPlayer phải là node anh em hoặc node con của node nơi bạn thêm AnimationTree (thông thường cả hai đều là node con của node gốc nhân vật)
• Godot 4.x (hướng dẫn này dùng API của Godot 4 — API của AnimationTree đã thay đổi đáng kể so với Godot 3)

3. Thiết lập cơ bản

Thiết lập một AnimationTree gồm bốn bước:

1. Thêm một node AnimationTree — Thêm nó làm node con của nhân vật (ví dụ CharacterBody2D hoặc CharacterBody3D), đặt cạnh AnimationPlayer của bạn.
2. Thiết lập anim_player — Trong Inspector, trỏ thuộc tính "Anim Player" tới node AnimationPlayer của bạn.
3. Thiết lập tree_root — Nhấp vào thuộc tính "Tree Root" trong Inspector và tạo một AnimationNodeStateMachine mới.
4. Đặt active = true — Tích ô "Active" trong Inspector, hoặc thiết lập bằng mã.

Cây scene của bạn sẽ trông như thế này:

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. Kiến thức cơ bản về State Machine

State machine trong AnimationTree hoạt động dựa trên một khái niệm đơn giản: các trạng thái (state) đại diện cho các animation, còn các transition định nghĩa điều kiện để chuyển đổi giữa chúng.

Thêm trạng thái

Một khi tree_root của AnimationTree là một AnimationNodeStateMachine, hãy nhấp đúp vào nó trong Inspector để mở trình chỉnh sửa state machine:

1. Nhấp chuột phải vào vùng đồ thị và chọn Add Animation
2. Chọn một animation từ AnimationPlayer của bạn (Idle, Walk, Run, Jump, v.v.)
3. Lặp lại cho mỗi trạng thái animation bạn cần

Thêm transition

Để tạo một transition giữa hai trạng thái:

1. Nhấp vào node trạng thái nguồn
2. Kéo tới trạng thái đích để tạo mũi tên transition
3. Nhấp vào mũi tên transition để cấu hình nó trong Inspector

Thuộc tính của transition

Một thiết lập điển hình cho nhân vật platformer:

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. Điều khiển State Machine từ mã

Có hai cách chính để điều khiển state machine: thiết lập các tham số điều kiện (transition tự động) và gọi travel() (transition thủ công). Bạn có thể kết hợp cả hai cách tiếp cận.

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() so với điều kiện

Dựa trên điều kiện (khuyến nghị cho di chuyển)

Thiết lập các tham số boolean mỗi khung hình và để các transition tự động kích hoạt. Cách này mang tính khai báo hơn và giữ cho mã của bạn gọn gàng. State machine sẽ xử lý logic transition, crossfade và các trường hợp biên giúp bạn.

# 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() (khuyến nghị cho các hành động đơn lẻ)

travel() yêu cầu một chuyển đổi trạng thái. Nó tôn trọng các quy tắc transition — nếu không tồn tại đường đi hợp lệ từ trạng thái hiện tại tới trạng thái đích, lệnh gọi sẽ bị bỏ qua. Điều này khiến việc gọi lặp lại là an toàn. Hãy dùng nó cho các trigger đơn lẻ như tấn công, emote, hoặc animation 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 Tree

Blend tree cho phép bạn nội suy mượt mà giữa nhiều animation dựa trên một giá trị liên tục, thay vì chuyển đổi cứng giữa các trạng thái rời rạc. Điều này hoàn hảo cho việc trộn tốc độ đi/chạy và di chuyển theo hướng.

BlendSpace1D

Một phép trộn 1D giữa hai hoặc nhiều animation dọc theo một trục duy nhất. Cách dùng phổ biến: trộn Walk và Run dựa trên tốc độ di chuyển.

Trong editor, tạo một node BlendSpace1D bên trong state machine của bạn (hoặc làm tree root độc lập). Thêm các điểm animation:

# 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

Một phép trộn 2D dùng hai trục. Hoàn hảo cho di chuyển 8 hướng hoặc game top-down nơi nhân vật có thể di chuyển theo bất kỳ hướng nà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. Các loại Node thông dụng

AnimationTree hỗ trợ một số loại node có thể kết hợp để tạo hành vi animation phức tạp:

9. Mẫu OneShot (Tấn công, Emote)

Node OneShot là một trong những mẫu hữu ích nhất trong AnimationTree. Nó phát một animation một lần lên trên animation nền của bạn (như phát đòn vung tấn công trong khi đang đi bộ), rồi tự động trở về animation nền.

Thiết lập trong BlendTree

Để dùng OneShot, gốc AnimationTree của bạn (hoặc một trạng thái bên trong nó) cần phải là một 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.

Kích hoạt từ mã

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

Các hằng số Request của OneShot

10. Ví dụ thực tế: Character Controller đầy đủ

Dưới đây là một script nhân vật platformer 2D hoàn chỉnh, kết hợp di chuyển bằng state machine với đòn tấn công OneShot. Đây là một mẫu sẵn sàng cho sản phẩm mà bạn có thể điều chỉnh cho dự án của mình.

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. Khắc phục sự cố