Tutorial) 5. Animations from Frames

Nav: (Prev) (Home) (Next)

Note: This tutorial is specifically geared towards beginners who have little to no programming experience. Because of this, a lot of simple stuff will be explained. These explanations will become more scarce as the tutorial goes on as every section expects the reader to have read everything prior to it, so repetition is not needed.

5.0. Animation Frames vs Normal Frames

In the last part of the tutorial, we made variables to store our frames' pointers. From now on, we will not be making variables for our frames as they will be stored directly in animations. This also means that we won't be freeing our frames, as they will be automatically freed in our animations. Here is what your code should look like when you start this section (a few lines regarding frames have been removed):

#include <3ds.h>
#include <spritetools.h>
#include <stdio.h>
#include <link_overworld_png.h>

int main(void)
{
  int linkX = 50;
  int linkY = 50;

  ST_Init();
  ST_Splashscreen(2510);
  ST_DebugSetOn();
  ST_DebugAddVar("Link X",(void *)&linkX, INT);
  ST_DebugAddVar("Link Y",(void *)&linkY, INT);
  consoleInit(GFX_BOTTOM, NULL);

  st_spritesheet *link_o_s = ST_SpritesheetCreateSpritesheetPNG(link_overworld_png);

  ST_RenderSetBackground(0x82, 0xE1, 0x11);

  while (aptMainLoop())
  {
    ST_RenderStartFrame(GFX_TOP);

    ST_InputScan();
    if (ST_InputButtonDown(KEY_DUP))
      linkY--;
    if (ST_InputButtonDown(KEY_DDOWN))
      linkY++;
    if (ST_InputButtonDown(KEY_DLEFT))
      linkX--;
    if (ST_InputButtonDown(KEY_DRIGHT))
      linkX++;
    if (ST_InputButtonPressed(KEY_START))
      break;

    ST_DebugDisplay();

    ST_RenderEndRender();
  }

  ST_Fini();
  return 0;
}

5.1. Making an Animation

You can make an animation using the function ST_AnimationCreateAnimation(s16 fpf, u16 loopFrame, u16 length, ...) which returns a pointer to an animation. The ... means you can enter as many pointers to frames as you need, although for it to work correctly, the number of frames must match the length entered. Make sure you also free your animation at the end of your program with ST_AnimationFreeAnimation(st_animation *animation). Here's an example:

st_spritesheet *link_overworld_s = ST_SpritesheetCreateSpritesheetPNG(link_overworld_png);

st_animation *link_o_walk_down = ST_AnimationCreateAnimation(3, 0, 10,
  ST_AnimationCreateFrame(link_overworld_s, 30, 2, 18, 24),
  ST_AnimationCreateFrame(link_overworld_s, 56, 1, 18, 25),
  ST_AnimationCreateFrame(link_overworld_s, 82, 0, 18, 26),
  ST_AnimationCreateFrame(link_overworld_s, 108, 0, 18, 26),
  ST_AnimationCreateFrame(link_overworld_s, 134, 1, 18, 25),
  ST_AnimationCreateFrame(link_overworld_s, 160, 2, 18, 24),
  ST_AnimationCreateFrame(link_overworld_s, 186, 1, 18, 25),
  ST_AnimationCreateFrame(link_overworld_s, 212, 0, 18, 26),
  ST_AnimationCreateFrame(link_overworld_s, 238, 0, 18, 26),
  ST_AnimationCreateFrame(link_overworld_s, 264, 1, 18, 25));

while (aptMainLoop())
{
  /* ...Code... */
}

ST_AnimationFreeAnimation(link_o_walk_down);
ST_SpritesheetFreeSpritesheet(link_overworld_s);

Please note that the fpf of an animation acts as its speed, although it may function differently than one may expect. The farther from 0 this number is, the slower the animation will play. This is because the fpf of an animation is the number of frames to wait in between each frame of the animation. For example, an animation with an fpf of 1 will run at 60 frames per second while an animation with an fpf of 3 will run at 20 frames per second. Meanwhile, an animation with an fpf of 0 will not play unless the frame is manually changed with either ST_AnimationSetFrame(st_animation *animation, u16 frame), ST_AnimationNextFrame(st_animation *animation), or ST_AnimationPreviousFrame(st_animation *animation). The fpf of an animation can also be changed with ST_AnimationSetSpeed(st_animation *animation, s16 speed).

5.2. Rendering an Animation

The following functions can be used to render an animation:

Function	Description
`ST_RenderAnimationCurrent(st_animation *animation, int x, int y)`	Draws the current frame of an animation at a given position
`ST_RenderAnimationNext(st_animation *animation, int x, int y)`	Itterates the current frame of an animation by 1 and then draws it to the screen. Will loop to the specified `loopFrame` if it excedes the `length`
`ST_RenderAnimationPrevious(st_animation *animation, int x, int y)`	Itterates the current frame of an animation by -1 and then draws it to the screen. Will loop to the specified `loopFrame` if it goes below 0
`ST_RenderAnimationPlay(st_animation *animation, int x, int y)`	Plays an animation at its specified speed at a given position. Will loop to the specified `loopFrame` if needed

The function ST_RenderAnimationPlay will play the animation according to its fpf, going forward when the value is positive and backward when the value is negative.

5.3. Advanced Animation Rendering

Each of the functions in the previous section also has an "Advanced" variant which also takes a scalar multiplier, rotation value, and red, green, blue, and alpha of a color to blend the animation with. For example, the Advanced version of ST_RenderAnimationCurrent(st_animation *animation, int x, int y) is ST_RenderAnimationCurrentAdvanced(st_animation *animation, int x, int y, double scale, double rotate, u8 red, u8 green, u8 blue, u8 alpha). If you want to only do a few of the options in an Advanced function, just use the default values for each unused parameter as follows: