Machines à états AnimationTree
dans Godot 4

1. Introduction

AnimationTree est le système de Godot 4 pour le mélange d'animations complexes et les transitions d'états. Si vous avez déjà essayé de gérer plusieurs animations avec des appels AnimationPlayer.play() disséminés dans votre code, vous savez à quel point cela devient vite ingérable. AnimationTree résout ce problème avec un graphe visuel d'états et de transitions.

Bien qu'il soit incroyablement puissant, la documentation officielle d'AnimationTree est succincte et laisse souvent les développeurs dans le flou. Ce guide couvre tout, de la configuration de base aux blend trees avancés, avec du vrai code GDScript que vous pouvez copier directement dans votre projet.

2. Prérequis

Avant de configurer votre AnimationTree, vous avez besoin :

• D'un nœud AnimationPlayer contenant au minimum les animations Idle, Walk, Run et Jump déjà créées
• L'AnimationPlayer doit être un frère ou un enfant du nœud auquel vous ajoutez l'AnimationTree (généralement, les deux sont des enfants du nœud racine de votre personnage)
• De Godot 4.x (ce guide utilise l'API de Godot 4 — l'API AnimationTree a considérablement changé depuis Godot 3)

3. Configuration de base

La configuration d'un AnimationTree se fait en quatre étapes :

1. Ajoutez un nœud AnimationTree — Ajoutez-le comme enfant de votre personnage (par exemple, CharacterBody2D ou CharacterBody3D), aux côtés de votre AnimationPlayer.
2. Définissez anim_player — Dans l'inspecteur, faites pointer la propriété « Anim Player » vers votre nœud AnimationPlayer.
3. Définissez tree_root — Cliquez sur la propriété « Tree Root » dans l'inspecteur et créez un nouveau AnimationNodeStateMachine.
4. Définissez active = true — Cochez la case « Active » dans l'inspecteur, ou définissez-la dans le code.

Votre arbre de scène devrait ressembler à ceci :

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. Les bases des machines à états

Une machine à états dans AnimationTree fonctionne selon un concept simple : les états représentent des animations, et les transitions définissent les conditions de passage de l'un à l'autre.

Ajouter des états

Une fois que le tree_root de votre AnimationTree est un AnimationNodeStateMachine, double-cliquez dessus dans l'inspecteur pour ouvrir l'éditeur de machine à états :

1. Faites un clic droit dans la zone du graphe et sélectionnez Add Animation
2. Choisissez une animation depuis votre AnimationPlayer (Idle, Walk, Run, Jump, etc.)
3. Répétez pour chaque état d'animation dont vous avez besoin

Ajouter des transitions

Pour créer une transition entre deux états :

1. Cliquez sur le nœud d'état source
2. Faites glisser vers l'état de destination pour créer une flèche de transition
3. Cliquez sur la flèche de transition pour la configurer dans l'inspecteur

Propriétés de transition

Une configuration typique pour un personnage de jeu de plateforme :

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. Contrôler la machine à états depuis le code

Il existe deux principales façons de piloter la machine à états : définir des paramètres de condition (transitions automatiques) et appeler travel() (transitions manuelles). Vous pouvez combiner les deux approches.

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 conditions

Basé sur les conditions (recommandé pour la locomotion)

Définissez des paramètres booléens à chaque frame et laissez les transitions se déclencher automatiquement. C'est plus déclaratif et cela garde votre code propre. La machine à états gère pour vous la logique de transition, les fondus enchaînés et les cas limites.

# 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() (recommandé pour les actions ponctuelles)

travel() demande une transition d'état. Il respecte les règles de transition — s'il n'existe aucun chemin valide entre l'état actuel et la cible, l'appel est ignoré. On peut donc l'appeler à répétition sans risque. Utilisez-le pour des déclencheurs ponctuels comme les attaques, les emotes ou les animations de cinématique.

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

Les blend trees vous permettent d'interpoler en douceur entre plusieurs animations en fonction d'une valeur continue, plutôt que de basculer brutalement entre des états discrets. C'est parfait pour le mélange des vitesses de marche/course et le mouvement directionnel.

BlendSpace1D

Un mélange 1D entre deux animations ou plus le long d'un seul axe. Usage courant : mélanger Walk et Run en fonction de la vitesse de déplacement.

Dans l'éditeur, créez un nœud BlendSpace1D à l'intérieur de votre machine à états (ou comme tree root autonome). Ajoutez des points d'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

Un mélange 2D utilisant deux axes. Parfait pour le mouvement à 8 directions ou les jeux en vue de dessus où le personnage peut se déplacer dans n'importe quelle direction.

# 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. Types de nœuds courants

AnimationTree prend en charge plusieurs types de nœuds qui peuvent être combinés pour créer des comportements d'animation complexes :

9. Motif OneShot (attaques, emotes)

Le nœud OneShot est l'un des motifs les plus utiles d'AnimationTree. Il joue une animation ponctuelle par-dessus votre animation de base (comme jouer un coup d'attaque tout en marchant), puis revient automatiquement à l'animation de base.

Configuration dans un BlendTree

Pour utiliser OneShot, la racine de votre AnimationTree (ou un état à l'intérieur) doit être un 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.

Déclenchement depuis le code

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

Constantes de requête OneShot

10. Exemple pratique : contrôleur de personnage complet

Voici un script complet de personnage de jeu de plateforme 2D qui combine la locomotion par machine à états avec une attaque OneShot. C'est un motif prêt pour la production que vous pouvez adapter à votre propre projet.

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. Dépannage