AnimationTree स्टेट मशीन
Godot 4 में

1. परिचय

AnimationTree, Godot 4 का जटिल एनिमेशन ब्लेंडिंग और स्टेट ट्रांज़िशन के लिए सिस्टम है। यदि आपने कभी अपने कोड में जगह-जगह बिखरे AnimationPlayer.play() कॉल्स के साथ कई एनिमेशन प्रबंधित करने की कोशिश की है, तो आप जानते हैं कि यह कितनी जल्दी बेकाबू हो जाता है। AnimationTree इसे स्टेट्स और ट्रांज़िशन के एक विज़ुअल ग्राफ़ के साथ हल करता है।

अत्यंत शक्तिशाली होने के बावजूद, AnimationTree का आधिकारिक डॉक्युमेंटेशन कम है और अक्सर डेवलपर्स को अनुमान लगाने पर छोड़ देता है। यह गाइड बुनियादी सेटअप से लेकर उन्नत ब्लेंड ट्री तक सब कुछ समझाती है – वास्तविक GDScript कोड के साथ जिसे आप सीधे अपने प्रोजेक्ट में कॉपी कर सकते हैं।

2. पूर्वापेक्षाएं

अपना AnimationTree सेट करने से पहले, आपको चाहिए:

• एक AnimationPlayer नोड जिसमें कम से कम Idle, Walk, Run और Jump एनिमेशन पहले से बने हों
• AnimationPlayer उस नोड का सिबलिंग या चाइल्ड होना चाहिए जहां आप AnimationTree जोड़ते हैं (आमतौर पर दोनों आपके कैरेक्टर रूट नोड के चाइल्ड होते हैं)
• Godot 4.x (यह गाइड Godot 4 API का उपयोग करती है — AnimationTree API Godot 3 की तुलना में काफी बदल गया है)

3. बुनियादी सेटअप

AnimationTree का सेटअप चार चरणों में होता है:

1. एक AnimationTree नोड जोड़ें — इसे अपने AnimationPlayer के साथ, अपने कैरेक्टर (जैसे CharacterBody2D या CharacterBody3D) के चाइल्ड के रूप में जोड़ें।
2. anim_player सेट करें — Inspector में "Anim Player" प्रॉपर्टी को अपने AnimationPlayer नोड की ओर इंगित करें।
3. tree_root सेट करें — Inspector में "Tree Root" प्रॉपर्टी पर क्लिक करें और एक नई AnimationNodeStateMachine बनाएं।
4. active = true सेट करें — Inspector में "Active" चेकबॉक्स को सक्षम करें या इसे कोड में सेट करें।

आपका सीन ट्री इस तरह दिखना चाहिए:

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. स्टेट मशीन की मूल बातें

AnimationTree में एक स्टेट मशीन एक सरल अवधारणा पर काम करती है: स्टेट्स एनिमेशन का प्रतिनिधित्व करते हैं और ट्रांज़िशन उनके बीच स्विच करने की शर्तें परिभाषित करते हैं।

स्टेट्स जोड़ना

एक बार जब आपके AnimationTree का tree_root एक AnimationNodeStateMachine हो जाए, तो स्टेट मशीन एडिटर खोलने के लिए Inspector में उस पर डबल-क्लिक करें:

1. ग्राफ़ क्षेत्र में दायाँ-क्लिक करें और Add Animation चुनें
2. अपने AnimationPlayer से एक एनिमेशन चुनें (Idle, Walk, Run, Jump आदि)
3. आपको जितने भी एनिमेशन स्टेट चाहिए, उनके लिए इसे दोहराएं

ट्रांज़िशन जोड़ना

दो स्टेट्स के बीच ट्रांज़िशन बनाने के लिए:

1. स्रोत स्टेट नोड पर क्लिक करें
2. ट्रांज़िशन तीर बनाने के लिए लक्ष्य स्टेट तक खींचें
3. ट्रांज़िशन तीर पर क्लिक करके उसे Inspector में कॉन्फ़िगर करें

ट्रांज़िशन प्रॉपर्टीज़

एक प्लेटफॉर्मर कैरेक्टर के लिए एक सामान्य सेटअप:

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. कोड से स्टेट मशीन को नियंत्रित करना

स्टेट मशीन को चलाने के दो मुख्य तरीके हैं: कंडीशन पैरामीटर सेट करना (स्वचालित ट्रांज़िशन) और travel() को कॉल करना (मैनुअल ट्रांज़िशन)। आप दोनों दृष्टिकोणों को मिला सकते हैं।

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() बनाम शर्तें

शर्त-आधारित (चलने-फिरने के लिए अनुशंसित)

हर फ़्रेम में बूलियन पैरामीटर सेट करें और ट्रांज़िशन को स्वचालित रूप से फ़ायर होने दें। यह अधिक घोषणात्मक है और आपके कोड को साफ़ रखता है। स्टेट मशीन आपके लिए ट्रांज़िशन लॉजिक, क्रॉसफेड और एज केस को संभालती है।

# 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() एक स्टेट ट्रांज़िशन का अनुरोध करता है। यह ट्रांज़िशन नियमों का सम्मान करता है — यदि वर्तमान स्टेट से लक्ष्य तक कोई मान्य पथ मौजूद नहीं है, तो कॉल को अनदेखा कर दिया जाता है। इससे इसे बार-बार कॉल करना सुरक्षित हो जाता है। इसका उपयोग हमले, इमोट्स या कटसीन एनिमेशन जैसे एकल-बार के ट्रिगर्स के लिए करें।

# 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. ब्लेंड ट्री

ब्लेंड ट्री आपको असतत स्टेट्स के बीच हार्ड-स्विचिंग के बजाय एक निरंतर मान के आधार पर कई एनिमेशन के बीच सहज रूप से इंटरपोलेट करने देते हैं। यह चलने/दौड़ने की गति की ब्लेंडिंग और दिशात्मक गति के लिए आदर्श है।

BlendSpace1D

एक ही अक्ष के साथ दो या अधिक एनिमेशन के बीच एक 1D ब्लेंड। सामान्य उपयोग: गति के आधार पर Walk और Run की ब्लेंडिंग।

एडिटर में, अपनी स्टेट मशीन के अंदर (या एक स्टैंडअलोन ट्री रूट के रूप में) एक BlendSpace1D नोड बनाएं। एनिमेशन पॉइंट जोड़ें:

# 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

दो अक्षों का उपयोग करके एक 2D ब्लेंड। 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 की रूट (या उसके भीतर का एक स्टेट) एक 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. व्यावहारिक उदाहरण: संपूर्ण कैरेक्टर कंट्रोलर

यहां एक संपूर्ण 2D प्लेटफॉर्मर कैरेक्टर स्क्रिप्ट है जो स्टेट मशीन आधारित चलने-फिरने को एक 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. समस्या-निवारण