AnimationTree

Problématique

Une situation courante : vous avez un grand nombre d'animations, et il devient difficile de gérer les transitions entre elles. Votre code est devenu plein d'instructions if, et chaque fois que vous changez quelque chose, tout se casse.

Solution

Utilisez un AnimationTree pour créer une machine à états d'animation. Cela nous permettra d'organiser nos animations et, surtout, de contrôler les transitions entre elles.

Préparation

Attention! Ce document a été partiellement mis à jour. La partie Créer l'animation a été développé à l'aide de Godot 3 et n'a pas été mis à jour. Cependant, il y a très peu de changement pour Godot 4.

La partie AnimationTree a été mis à jour pour Godot 4.

Godot 3.5

Dans le cadre de ce document, j'utiliserai mon dépôt de code yt et plus précisément la version vBase_done.

Ce dernier contient le projet de base pour pour mes vidéos YouTube sur la création d'un jeu de plateforme.

Voici à quoi ressemble le projet de base.

Godot 4.x

Pour la partie AnimationTree, j'utiliserai le projet c08_parallax et plus spécifiquement la branche cours_animTree.

cd # dans le répertoire des projets du cours
git pull
git checkout cours_animTree

Voici à quoi ressemblera le projet à la fin du document.

Créer l'animation

Pour utiliser l'AnimationTree, il faut avoir un noeud AnimationPlayer et ce dernier nécessite un noeud Sprite.

Étape 1 : Convertir le noeud Player en scène.

Cliquer avec le bouton de droit sur le noeud Player et sélectionner "Sauvegarder la branche en tant que Scène".

Travailler sur une scène sera plus facile pour le futur.

Étape 2 : Ajouter un noeud Camera2D

Ajouter à la scène Player un noeud Camera2D pour permettre le suivi du personnage.

• Configurer la propriété Current à "On" pour activer le suivi.
• Activer la propriété Smoothing à Enabled pour activer un suivi fluide.
• Tester le projet

Étape 3 : Ajouter un noeud Sprite

Le noeud Sprite permettra d'ajouter facilement les images au noeud AnimationPlayer.

1. Ajouter un noeud Sprite.

2. Glisser l'image viking2.png sur la propriété Texture du noeud Sprite

   • On devrait obtenir une image similaire à cette capture d'écran

   

3. Il faudra configurer le nombre d'images à l'horizontal et à la vertical qui sont respectivement 9 et 6.

   • Il s'agit des propriétés Hframes et Vframes de la section Animation

Étape 4 : Ajouter un noeud AnimationPlayer

Le noeud AnimationPlayer permet, entre autres, de gérer les animations.

1. Ajouter un noeud AnimationPlayer.
2. Dans le volet inférieur nommé « Animation », ajouter une nouvelle animation appelée « Idle »
   • On clique sur le bouton Animation et on sélectionne Nouveau

On verra une bande avec des nombres apparaître, il s'agit de l'échelle de temps de l'animation. On peut zommer sur celle-ci en maintenant la touche CTRL enfoncée et en faisant aller la molette de la souris. - Dans le cadre du projet, je propose d'afficher le temps pour voir l'échelle affichée aux dizième de seconde.

1. Sélectionner le noeud Sprite.
2. Remarquer la propriété Frame, il y a une petite clé avec un "+" à la droite.

1. Cliquer sur ce bouton pour créer une nouvelle trame dans l'animation.
2. Si une petite fenêtre s'affiche, s'assurer que la courbe de Bezier ne soit pas cochée et cliquer sur Créer.

Une nouvelle image apparaîtra et la propriété Frame sera incrémentée de 1. Le curseur du temps (ligne bleue) sera à zéro

Attention!

Il y a un bogue dans Godot 3.x où il faut repositionner manuellement le curseur du temps après la première image. Il faudra répéter à chaque fois que l'on crée une nouvelle trame d'animation.

1. Repositionner le curseur du temps après la première image.
2. S'assurer que la propriété Frame soit à la valeur 1.
3. Cliquer sur la petite clé
4. Répéter l'opération jusqu'à la fin de l'animation.
5. Ajuster la durée de l'animation à l'aide de la zone de texte au bout du chronomètre.

L'action complète.

1. Répéter les étapes 2 à 11 pour l'ensemble des animations.

Attention!

Il faut souvent séparer les animations de saut. En effet, il y a l'animation de l'impulsion ainsi que l'animation de la chute.

---

Ajouter un noeud AnimationTree

Une fois que les configurations des animations est réalisées, on peut passer à l'étape de l'AnimationTree.

Vidéo où j'explique l'AnimationTree

Ce noeud sert à créer et gérer une machine à état fini pour notre personnage.

Avant d'utiliser le noeud, il faut établir les différents états du personnage. Dans notre cas, les états sont définis dans les types d'animation que l'on a réalisé dans l'AnimationPlayer, par exemple, idle, run, attack_1, ...

Les étapes de base seront les suivantes :

1. Ajouter un noeud AnimationTree au personnage
   • Un volet AnimationTree apparaîtra dans le bas de l'IDE.
2. Sélectionner le type de machine que l'on désire avec la propriété Tree Root.
   • Dans notre cas, ce sera un AnimationNodeStateMachine
   • Note : Personnallement, n'ayant fait que du 2D, je n'ai exploré que l'option AnimationNodeStateMachine. Il se peut que vous ayez exploré d'autres options selon les tutoriels que vous avez suivi.
3. Associer l'AnimationPlayer que l'on désire gérer.
   • Dans notre cas, on n'a qu'un noeud AnimationPlayer.

1. Dans le volet AnimationTree, cliquer avec le bouton de droite dans l'espace de travail et ajouter l'animation idle.
   • Activer la propriété Active de l'AnimationTree.
   • Pour voir l'animation idle, il suffit d'appuyer sur le bouton play dans l'état (rectangle noir).

1. Répéter l'opération précédente en ajoutant l'animation running.
   • On peut tester l'animation.
2. Répèter l'opération précédente en ajoutant l'animation attack1.
   • Tester l'animation.
   • On remarque que l'attaque "gèle" après s'être exécutée. La raison est que l'animation ne boucle pas. Il faudra ajouter une transition pour qu'elle reviennent à l'état idle.

1. Ajouter une transition d'idle vers l'attaque.
   • Dans la petite barre d'outils, il y a une petite flèche avec une ligne (3e bouton). Ce bouton sert à ajouter des transitions entre les états.
   • Pour ajouter une transition, il faut cliquer-glisser de l'état source et vers l'état destination.
2. Tester l'animation d'attaque
   • Il gèle encore, car il n'y a pas de transition de l'attaque vers l'idle.
3. Ajouter une transition entre l'état "attaque" vers idle.
4. Tester l'attaque.
   • L'animation "gig", car elle passe successivement de l'idle à l'attaque et à l'idle.

1. Sélectionner la transition de l'attaque vers l'idle
2. Modifier la propriété Switch Mode pour AtEnd.

1. Das les propriétés Advance, configurer le mode pour Auto

1. Tester l'attaque
   • Tout devrait fonctionner.
2. Ajouter les transitions entre run et idle.
   • Laisser les transitions telles quelles, car la n dn se fera dans le code.
3. Ajouter l'ensemble des animations.
   • Le saut devra être composé de jump et fall.
   • Il devra avoir un état fall seul avec des transitions aller-retour avec idle. La gestion se fera dans le code.
4. L'état idle sera l'état initial. Faire une transition entre Start et idle.
5. Définir dead comme étant l'état de fin. Il suffit de sélectionner l'état et de faire une transition vers End.

La configuration de l'AnimationTree est terminée. Il est maintenant temps de passer à la programmation.

---

Programmer les transitions entre les états

Comme indiquer précédement, il faudra gérer les transitions entre les états dans le code.

Godot possède une mécanisme géniale qui permet de simplifier la gestion des transitions. En effet, il y a une classe nommée AnimationNodeStateMachinePlayback qui permet de "voyager" d'un état à un autre automatiquement.

Étape 1 : Objets pour la gestion de l'animation

Dans la classe Player.cs, créer les deux membres suivants :

AnimationTree animTree;
AnimationNodeStateMachinePlayback stateMachine;

Dans la méthode _Ready(), ajouter le code suivant :

animTree = GetNode<AnimationTree>("AnimationTree");
animTree.Active = true;

// Récupère le paramètre "parameters/playback" de l'animation tree
stateMachine = (AnimationNodeStateMachinePlayback)animTree.Get("parameters/playback");

Dans Godot, la méthode GodotObject.Get permet de récupérer les propriétés d'un noeud. Dans notre cas, on récupère la propriété playback de l'AnimationTree qui est un AnimationNodeStateMachinePlayback.

Pour connaître la chaîne du paramètre, il suffit de sélectionner le noeud dans l'IDE et de cliquez avec le bouton droit sur la propriété qui nous intéresse. Un menu contextuel apparaîtra et il suffit de sélectionner Copier le chemin de la propriété.

Étape 2 : Ajouter les méthodes pour gérer les transitions

Pour passer d'un état à l'autre, on utilise la méthode AnimationNodeStateMachinePlayback.Travel qui prend en paramètre le nom de l'état de destination.

Cette méthode trouve le chemin le plus court pour passer de l'état actuel à l'état de destination.

Dans le if (isOnFloor())..., il y a le else qui vérifie si le vecteur d'entrée est différent de zéro. Modifier cette partie pour avoir ce code.

if (inputVector != Vector2.Zero) {
    stateMachine.Travel("run");
} else {
    stateMachine.Travel("idle");
}

Pour la portion aérienne où l'on retrouve le if (!isOnFloor()...), modifier le code pour le suivant:

if (!IsOnFloor()){
    if (velocity.Y < 0) {
        GD.Print("rising");
        stateMachine.Travel("jump");
    } 
    if (velocity.Y > 0) {
        GD.Print("falling");
        stateMachine.Travel("fall");
    }
}

Si tout fonctionne bien, on devrait avoir un résultat similaire à celui-ci.

---

Référence

• KidsCanCode.org : Controlling animation states
• GDQuest - Finite state machine