mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
287 lines
10 KiB
ReStructuredText
287 lines
10 KiB
ReStructuredText
.. _doc_2d_sprite_animation:
|
|
|
|
2D sprite animation
|
|
===================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
In this tutorial, you'll learn how to create 2D animated
|
|
characters with the AnimatedSprite2D class and the AnimationPlayer.
|
|
Typically, when you create or download an animated character,
|
|
it will come in one of two ways: as individual images or as a single sprite sheet
|
|
containing all the animation's frames.
|
|
Both can be animated in Godot with the AnimatedSprite2D class.
|
|
|
|
First, we'll use :ref:`AnimatedSprite2D <class_AnimatedSprite2D>` to
|
|
animate a collection of individual images.
|
|
Then we will animate a sprite sheet using this class.
|
|
Finally, we will learn another way to animate a sprite sheet
|
|
with :ref:`AnimationPlayer <class_AnimationPlayer>` and the *Animation*
|
|
property of :ref:`Sprite2D <class_Sprite2D>`.
|
|
|
|
.. note:: Art for the following examples by https://opengameart.org/users/ansimuz and tgfcoder.
|
|
|
|
Individual images with AnimatedSprite2D
|
|
---------------------------------------
|
|
|
|
In this scenario, you have a collection of images, each containing one of your
|
|
character's animation frames. For this example, we'll use the following
|
|
animation:
|
|
|
|
.. image:: img/2d_animation_run_preview.gif
|
|
|
|
You can download the images here:
|
|
`2d_sprite_animation_assets.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/2d_sprite_animation_assets.zip>`_
|
|
|
|
Unzip the images and place them in your project folder. Set up your scene tree
|
|
with the following nodes:
|
|
|
|
.. image:: img/2d_animation_tree1.webp
|
|
|
|
.. note:: The root node could also be :ref:`Area2D <class_Area2D>` or
|
|
:ref:`RigidBody2D <class_RigidBody2D>`. The animation will still be
|
|
made in the same way. Once the animation is completed, you can
|
|
assign a shape to the CollisionShape2D. See
|
|
:ref:`Physics Introduction <doc_physics_introduction>` for more
|
|
information.
|
|
|
|
Now select the ``AnimatedSprite2D`` and in its *SpriteFrames* property, select
|
|
"New SpriteFrames".
|
|
|
|
.. image:: img/2d_animation_new_spriteframes.webp
|
|
|
|
Click on the new SpriteFrames resource and you'll see a new panel appear at the
|
|
bottom of the editor window:
|
|
|
|
.. image:: img/2d_animation_spriteframes.webp
|
|
|
|
From the FileSystem dock on the left side, drag the 8 individual images into
|
|
the center part of the SpriteFrames panel. On the left side, change the name
|
|
of the animation from "default" to "run".
|
|
|
|
.. image:: img/2d_animation_spriteframes_done.webp
|
|
|
|
Use the "Play" buttons on the top-right of the *Filter Animations* input to preview the animation.
|
|
You should now see the animation playing in the viewport.
|
|
However, it is a bit slow. To fix this,
|
|
change the *Speed (FPS)* setting in the SpriteFrames panel to 10.
|
|
|
|
You can add additional animations by clicking the "Add Animation" button and
|
|
adding additional images.
|
|
|
|
Controlling the animation
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Once the animation is complete, you can control the animation via code using
|
|
the ``play()`` and ``stop()`` methods. Here is a brief example to play the
|
|
animation while the right arrow key is held, and stop it when the key is
|
|
released.
|
|
|
|
.. tabs::
|
|
.. code-tab:: gdscript GDScript
|
|
|
|
extends CharacterBody2D
|
|
|
|
@onready var _animated_sprite = $AnimatedSprite2D
|
|
|
|
func _process(_delta):
|
|
if Input.is_action_pressed("ui_right"):
|
|
_animated_sprite.play("run")
|
|
else:
|
|
_animated_sprite.stop()
|
|
|
|
.. code-tab:: csharp
|
|
|
|
using Godot;
|
|
|
|
public partial class Character : CharacterBody2D
|
|
{
|
|
private AnimatedSprite2D _animatedSprite;
|
|
|
|
public override void _Ready()
|
|
{
|
|
_animatedSprite = GetNode<AnimatedSprite2D>("AnimatedSprite2D");
|
|
}
|
|
|
|
public override void _Process(double delta)
|
|
{
|
|
if (Input.IsActionPressed("ui_right"))
|
|
{
|
|
_animatedSprite.Play("run");
|
|
}
|
|
else
|
|
{
|
|
_animatedSprite.Stop();
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
Sprite sheet with AnimatedSprite2D
|
|
----------------------------------
|
|
|
|
You can also easily animate from a sprite sheet with the class ``AnimatedSprite2D``.
|
|
We will use this public domain sprite sheet:
|
|
|
|
.. image:: img/2d_animation_frog_spritesheet.png
|
|
|
|
Right-click the image and choose "Save Image As" to download it,
|
|
and then copy the image into your project folder.
|
|
|
|
Set up your scene tree the same way you did previously when using individual images.
|
|
Select the ``AnimatedSprite2D`` and in its *SpriteFrames* property, select "New SpriteFrames".
|
|
|
|
Click on the new SpriteFrames resource.
|
|
This time, when the bottom panel appears, select "Add frames from a Sprite Sheet".
|
|
|
|
.. image:: img/2d_animation_add_from_spritesheet.webp
|
|
|
|
You will be prompted to open a file. Select your sprite sheet.
|
|
|
|
A new window will open, showing your sprite sheet.
|
|
The first thing you will need to do is to change the number of vertical and horizontal images in your sprite sheet.
|
|
In this sprite sheet, we have four images horizontally and two images vertically.
|
|
|
|
.. image:: img/2d_animation_spritesheet_select_rows.webp
|
|
|
|
Next, select the frames from the sprite sheet that you want to include in your animation.
|
|
We will select the top four, then click "Add 4 frames" to create the animation.
|
|
|
|
.. image:: img/2d_animation_spritesheet_selectframes.webp
|
|
|
|
You will now see your animation under the list of animations in the bottom panel.
|
|
Double click on default to change the name of the animation to jump.
|
|
|
|
.. image:: img/2d_animation_spritesheet_animation.webp
|
|
|
|
Finally, check the play button on the SpriteFrames editor to see your frog jump!
|
|
|
|
.. image:: img/2d_animation_play_spritesheet_animation.webp
|
|
|
|
|
|
Sprite sheet with AnimationPlayer
|
|
---------------------------------
|
|
|
|
Another way that you can animate when using a sprite sheet is to use a standard
|
|
:ref:`Sprite2D <class_Sprite2D>` node to display the texture, and then animating the
|
|
change from texture to texture with :ref:`AnimationPlayer <class_AnimationPlayer>`.
|
|
|
|
Consider this sprite sheet, which contains 6 frames of animation:
|
|
|
|
.. image:: img/2d_animation_player-run.png
|
|
|
|
Right-click the image and choose "Save Image As" to download, then copy the
|
|
image into your project folder.
|
|
|
|
Our goal is to display these images one after another in a loop. Start by
|
|
setting up your scene tree:
|
|
|
|
.. image:: img/2d_animation_tree2.webp
|
|
|
|
.. note:: The root node could also be :ref:`Area2D <class_Area2D>` or
|
|
:ref:`RigidBody2D <class_RigidBody2D>`. The animation will still be
|
|
made in the same way. Once the animation is completed, you can
|
|
assign a shape to the CollisionShape2D. See
|
|
:ref:`Physics Introduction <doc_physics_introduction>` for more
|
|
information.
|
|
|
|
Drag the spritesheet into the Sprite's *Texture* property, and you'll see the
|
|
whole sheet displayed on the screen. To slice it up into individual frames,
|
|
expand the *Animation* section in the Inspector and set the *Hframes* to ``6``.
|
|
*Hframes* and *Vframes* are the number of horizontal and vertical frames in
|
|
your sprite sheet.
|
|
|
|
.. image:: img/2d_animation_setframes.webp
|
|
|
|
Now try changing the value of the *Frame* property. You'll see that it ranges
|
|
from ``0`` to ``5`` and the image displayed by the Sprite2D changes accordingly.
|
|
This is the property we'll be animating.
|
|
|
|
Select the ``AnimationPlayer`` and click the "Animation" button followed by
|
|
"New". Name the new animation "walk". Set the animation length to ``0.6`` and
|
|
click the "Loop" button so that our animation will repeat.
|
|
|
|
.. image:: img/2d_animation_new_animation.webp
|
|
|
|
Now select the ``Sprite2D`` node and click the key icon to add a new track.
|
|
|
|
.. image:: img/2d_animation_new_track.webp
|
|
|
|
Continue adding frames at each point in the timeline (``0.1`` seconds by
|
|
default), until you have all the frames from 0 to 5. You'll see the frames
|
|
actually appearing in the animation track:
|
|
|
|
.. image:: img/2d_animation_full_animation.webp
|
|
|
|
Press "Play" on the animation to see how it looks.
|
|
|
|
.. image:: img/2d_animation_running.gif
|
|
|
|
Controlling an AnimationPlayer animation
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like with AnimatedSprite2D, you can control the animation via code using
|
|
the ``play()`` and ``stop()`` methods. Again, here is an example to play the
|
|
animation while the right arrow key is held, and stop it when the key is
|
|
released.
|
|
|
|
.. tabs::
|
|
.. code-tab:: gdscript GDScript
|
|
|
|
extends CharacterBody2D
|
|
|
|
@onready var _animation_player = $AnimationPlayer
|
|
|
|
func _process(_delta):
|
|
if Input.is_action_pressed("ui_right"):
|
|
_animation_player.play("walk")
|
|
else:
|
|
_animation_player.stop()
|
|
|
|
.. code-tab:: csharp
|
|
|
|
using Godot;
|
|
|
|
public partial class Character : CharacterBody2D
|
|
{
|
|
private AnimationPlayer _animationPlayer;
|
|
|
|
public override void _Ready()
|
|
{
|
|
_animationPlayer = GetNode<AnimationPlayer>("AnimationPlayer");
|
|
}
|
|
|
|
public override void _Process(double delta)
|
|
{
|
|
if (Input.IsActionPressed("ui_right"))
|
|
{
|
|
_animationPlayer.Play("walk");
|
|
}
|
|
else
|
|
{
|
|
_animationPlayer.Stop();
|
|
}
|
|
}
|
|
}
|
|
|
|
.. note:: If updating both an animation and a separate property at once
|
|
(for example, a platformer may update the sprite's ``h_flip``/``v_flip``
|
|
properties when a character turns while starting a 'turning' animation),
|
|
it's important to keep in mind that ``play()`` isn't applied instantly.
|
|
Instead, it's applied the next time the :ref:`AnimationPlayer <class_AnimationPlayer>` is processed.
|
|
This may end up being on the next frame, causing a 'glitch' frame,
|
|
where the property change was applied, but the animation was not.
|
|
If this turns out to be a problem, after calling ``play()``, you can call ``advance(0)``
|
|
to update the animation immediately.
|
|
|
|
Summary
|
|
-------
|
|
|
|
These examples illustrate the two classes you can use in Godot for 2D animation.
|
|
``AnimationPlayer`` is a bit more complex than ``AnimatedSprite2D``,
|
|
but it provides additional functionality, since you can also
|
|
animate other properties like position or scale.
|
|
The class ``AnimationPlayer`` can also be used with an ``AnimatedSprite2D``.
|
|
Experiment to see what works best for your needs.
|