2D Animation tutorial

tutorials/2d/2d_sprite_animation.rst

@@ -8,19 +8,148 @@ Introduction
 
 In this tutorial, you'll learn two different ways to create 2D animated
 characters. Typically, when you create or download an animated character, it
-will come in one of two ways: as individual images or as a single spritesheet
+will come in one of two ways: as individual images or as a single sprite sheet
 containing all the animation's frames. Depending on which type of assets you
 have, you can choose one of the following solutions.
 
 First, we'll use :ref:`AnimatedSprite <class_AnimatedSprite>` to
-animate a collection of individual images. Then, to use a spritesheet, we'll
-use :ref:`AnimationPlayer <class_AnimationPlayer>` along with the _Animation_
+animate a collection of individual images. Then, to use a sprite sheet, we'll
+use :ref:`AnimationPlayer <class_AnimationPlayer>` along with the *Animation*
 property of :ref:`Sprite <class_Sprite>`.
 
+.. note:: Art for the following examples by https://opengameart.org/users/ansimuz
+
 Individual images with AnimatedSprite
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
+
+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:
+:download:`run_animation.zip <files/run_animation.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.png
+
+.. 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 ``AnimatedSprite`` and in its *SpriteFrames* property, select
+"New SpriteFrames".
+
+.. image:: img/2d_animation_new_spriteframes.png
+
+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.png
+
+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.png
+
+Back in the Inspector, check the box for the *Playing* property. 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.
+
+You can add additional animations by clicking the "New 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 KinematicBody2D
+
+    func _process(delta):
+        if Input.is_action_pressed("ui_right"):
+            $AnimatedSprite.play("run")
+        else:
+            $AnimatedSprite.stop()
 
 
-Sprite sheets with AnimationPlayer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sprite sheet with AnimationPlayer
+----------------------------------
 
+In the event you have a sprite sheet containing all of your animation frames,
+you can't easily use ``AnimatedSprite``. Instead, you can use a standard
+:ref:`Sprite <class_Sprite>` node to display the texture, and then animate 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.png
+
+.. 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.png
+
+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 Sprite 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.png
+
+Now select the ``Sprite`` node and click the key icon to add a new track.
+
+.. image:: img/2d_animation_new_track.png
+
+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.png
+
+Press "Play" on the animation to see how it looks.
+
+.. image:: img/2d_animation_running.gif
+
+Summary
+-------
+
+These examples illustrate the two most common situations you'll encounter in
+2D animation. Each has its benefits. Working with ``AnimationPlayer`` is
+a bit more complex, but provides additional functionality, since you can also
+animate other properties like position or scale. Experiment and see which
+works best for your needs.