Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Introduction aux fonctions d'animation

Le nœud AnimationPlayer vous permet de créer des animations simples ou complexes.

Dans ce guide, vous apprendrez à :

Travailler avec le panneau d'animation
Animer n'importe quelle propriété de n'importe quel nœud
Créer une animation simple

In Godot, you can animate anything available in the Inspector, such as Node transforms, sprites, UI elements, particles, visibility and color of materials, and so on. You can also modify values of script variables and even call functions.

Créer un nœud AnimationPlayer

Pour utiliser les outils d'animation, nous devons d'abord créer un nœud AnimationPlayer.

The AnimationPlayer node type is the data container for your animations. One AnimationPlayer node can hold multiple animations, which can automatically transition to one another.

After you create an AnimationPlayer node, click on it to open the Animation Panel at the bottom of the viewport.

The animation panel consists of four parts:

Contrôles d'animation (c.-à-d. ajouter, charger, enregistrer et supprimer des animations)
La liste des pistes
La timeline avec les clés d'animation
The timeline and track controls, where you can zoom the timeline and edit tracks, for example.

L'animation par ordinateur repose sur des clés d'animation

A keyframe defines the value of a property at a point in time.

Diamond shapes represent keyframes in the timeline. A line between two keyframes indicates that the value doesn't change between them.

You set values of a node's properties and create animation keyframes for them. When the animation runs, the engine will interpolate the values between the keyframes, resulting in them gradually changing over time.

Deux clés d'animation sont tout ce qu'il faut pour obtenir un mouvement fluide

The timeline defines how long the animation will take. You can insert keyframes at various points, and change their timing.

La timeline dans le panneau d'animation

Each line in the Animation Panel is an animation track that references a Normal or Transform property of a node. Each track stores a path to a node and its affected property. For example, the position track in the illustration refers to the position property of the Sprite2D node.

Exemple de piste d'animation de type Normal

Astuce

Si vous animez la mauvaise propriété, vous pouvez éditer le chemin d'une piste à tout moment en double-cliquant dessus et en tapant le nouveau chemin. Lisez l'animation à l'aide du bouton "Lire du début" Jouer depuis le début (ou en appuyant sur Shift + D sur le clavier) pour voir les changements instantanément.

Tutoriel : Création d'une animation simple

Configuration de la scène

Pour ce didacticiel, nous allons créer un nœud Sprite avec un AnimationPlayer comme enfant. Nous allons animer le sprite pour qu'il se déplacer entre deux points sur l'écran.

Avertissement

AnimationPlayer inherits from Node instead of Node2D or Node3D, which means that the child nodes will not inherit the transform from the parent nodes due to a bare Node being present in the hierarchy.

Par conséquent, il n'est pas recommandé d'ajouter des nœuds qui ont une transformation 2D/3D comme enfant d'un nœud AnimationPlayer.

The sprite holds an image texture. For this tutorial, select the Sprite2D node, click Texture in the Inspector, and then click Load. Select the default Godot icon for the sprite's texture.

Adding an animation

Sélectionnez le nœud AnimationPlayer, puis cliquez sur le bouton "Animation" dans l'éditeur d'animation. Dans la liste, sélectionnez "Nouveau" ( Ajouter une Animation ) pour ajouter une nouvelle animation. Saisissez un nom pour l'animation dans la boîte de dialogue.

Managing animation libraries

For reusability, the animation is registered in a list in the animation library resource. If you add an animation to AnimationPlayer without specifying any particular settings, the animation will be registered in the [Global] animation library that AnimationPlayer has by default.

If there are multiple animation libraries and you try to add an animation, a dialog box will appear with options.

Add a new animation with library option

Ajout d'une piste

To add a new track for our sprite, select it and take a look at the toolbar:

These switches and buttons allow you to add keyframes for the selected node's location, rotation, and scale. Since we are only animating the sprite's position, make sure that only the location switch is selected. The selected switches are blue.

Click on the key button to create the first keyframe. Since we don't have a track set up for the Position property yet, Godot will offer to create it for us. Click Create.

Godot will create a new track and insert our first keyframe at the beginning of the timeline:

La deuxième clé d'animation

We need to set our sprite's end location and how long it will take for it to get there.

Let's say we want it to take two seconds to move between the points. By default, the animation is set to last only one second, so change the animation length to 2 in the controls on the right side of the animation panel's timeline header.

Now, move the sprite right, to its final position. You can use the Move tool in the toolbar or set the Position's X value in the Inspector.

Click on the timeline header near the two-second mark in the animation panel and then click the key button in the toolbar to create the second keyframe.

Lancer l'animation

Cliquez sur le bouton "Jouer depuis le début" ().

Yeah ! Notre animation fonctionne :

Autoplay on load

You can make it so an animation plays automatically when the AnimationPlayer nodes scene starts, or joins another scene. To do this click the "Autoplay on load" button in the animation editor, it's right next to the edit button.

The icon for it will also appear in front of the name of the animation, so you can easily identify which one is the autoplay animation.

Allers et retours

Godot has an interesting feature that we can use in animations. When Animation Looping is set but there's no keyframe specified at the end of the animation, the first keyframe is also the last.

This means we can extend the animation length to four seconds now, and Godot will also calculate the frames from the last keyframe to the first, moving our sprite back and forth.

You can change this behavior by changing the track's loop mode. This is covered in the next chapter.

Paramètres de la piste

Each property track has a settings panel at the end, where you can set its update mode, track interpolation, and loop mode.

Le mode de mise à jour d'une piste indique à Godot quand mettre à jour les valeurs des propriétés. Cela peut l'être :

Continu: Met à jour la propriété à chaque image
Discret : Met à jour la propriété uniquement sur les clés d'animation
Capture: if the first keyframe's time is greater than 0.0, the current value of the property will be remembered and will be blended with the first animation key. For example, you could use the Capture mode to move a node that's located anywhere to a specific location.

You will usually use "Continuous" mode. The other types are used to script complex animations.

Track interpolation tells Godot how to calculate the frame values between keyframes. These interpolation modes are supported:

Le plus proche : définit la plus valeur de la clé d'animation la plus proche
Linéaire : Change la valeur en se basant sur un calcul linéaire entre deux clés d'animation
Cubique : change la valeur en se basant sur un calcul par fonction cubique entre deux clés d'animation
Linear Angle (Only appears in rotation property): Linear mode with shortest path rotation
Cubic Angle (Only appears in rotation property): Cubic mode with shortest path rotation

With Cubic interpolation, animation is slower at keyframes and faster between them, which leads to more natural movement. Cubic interpolation is commonly used for character animation. Linear interpolation animates changes at a fixed pace, resulting in a more robotic effect.

Godot prend en charge deux modes de boucle, qui affectent l'animation si elle est réglée pour boucler :

Clamp loop interpolation : Lorsque cette option est sélectionnée, l'animation s'arrête après la dernière clé d'animation pour cette piste. Lorsque la première clé d'animation est atteinte à nouveau, l'animation se réinitialise à ses valeurs.
Wrap loop interpolation : Lorsque cette option est sélectionnée, Godot calcule l'animation après la dernière clé d'animation pour atteindre à nouveau les valeurs de la première clé d'animation.

Clés d'animation pour d'autres propriétés

Godot's animation system isn't restricted to position, rotation, and scale. You can animate any property.

Si vous sélectionnez votre sprite pendant que le panneau d'animation est visible, Godot affichera un petit bouton de clé d'animation dans l'Inspecteur pour chacune des propriétés du sprite. Cliquez sur un des boutons pour ajouter une piste et une clé d'animation à votre animation actuelle.

Clés d'animation pour d'autres propriétés

Modifier les clés d'animation

You can click on a keyframe in the animation timeline to display and edit its value in the Inspector.

Éditeur clé d'animation éditant une clé d'animation

You can also edit the easing value for a keyframe here by clicking and dragging its easing curve. This tells Godot how to interpolate the animated property when it reaches this keyframe.

Vous pouvez ajuster vos animations de cette façon jusqu'à ce que le mouvement " vous semble correct."

Utiliser les pistes RESET

Vous pouvez configurer une animation spéciale RESET pour contenir la "pose par défaut". Ceci est utilisé pour s'assurer que la pose par défaut est restaurée lorsque vous sauvegardez la scène et que vous l'ouvrez à nouveau dans l'éditeur.

Pour les pistes existantes, vous pouvez ajouter une animation appelée "RESET" (sensible à la casse), puis ajouter des pistes pour chaque propriété que vous souhaitez réinitialiser. La seule image clé doit être au temps 0, et donnez-lui la valeur par défaut souhaitée pour chaque piste.

Si la propriété Reset On Save de l'AnimationPlayer est mise à true, la scène sera sauvegardée avec les effets de l'animation reset appliqués (comme si elle avait été recherchée au temps 0.0). Cela n'affecte que le fichier sauvegardé - les pistes de propriétés dans l'éditeur restent là où elles étaient.

If you want to reset the tracks in the editor, select the AnimationPlayer node, open the Animation bottom panel then choose Apply Reset in the animation editor's Edit dropdown menu.

When using the keyframe icon next to a property in the inspector the editor will ask you to automatically create a RESET track.

Note

RESET tracks are also used as reference values for blending. See also For better blending.

Onion Skinning

Godot's animation editor allows you use onion skinning while creating an animation. To turn this feature on click on the onion icon in the top right of the animation editor. Now there will be transparent red copies of what is being animated in its previous positions in the animation.

The three dots button next to the onion skinning button opens a dropdown menu that lets you adjust how it works, including the ability to use onion skinning for future frames.

Animation Markers

Animation markers can be used to play a specific part of an animation rather than the whole thing. Here is a use case example, there's an animation file that has a character doing two distinct actions, and the project requires the whole animation, as well as both actions individually. Instead of making two additional animations, markers can be placed on the timeline, and both actions can now be played individually.

To add a marker to an animation right click the space above the timeline and select Insert Marker....

../../_images/animation_marker_click_area.webp

All markers require a unique name within the animation. You can also set the color of the markers for improved organization.

To play the part of the animation between two markers use the play_section_with_markers() and play_section_with_markers_backwards() methods. If no start marker is specified then the beginning of the animation is used, and if no end marker is specified, then the end of the animation is used.

If the end marker is after the end of the animation then the AnimationPlayer will clamp the end of the section so it does not go past the end of the animation.

To preview the animation between two markers use Shift + Click to select the markers. When two are selected the space between them should be highlighted in red.

../../_images/animation_marker_selected.webp

Now all of the play animation buttons will act as if the selected area is the whole animation. Play Animation from Start will treat the first marker as the start of the animation, Play Animation Backwards from End will treat the second marker as the end, and so on.