# Animating sprites - part 1

## Description

There are three options when it comes to animating a sprite. These are:

- load a series of images and manually update the sprites image using timers
- add a series of images to a sprite and use the command PlaySprite to handle animation
- use a texture atlas (a series of animation frames on one image), call SetSpriteAnimation to hook up atlas to the system, then call PlaySprite to handle animation

In this example we’re going to examine the second option.

## External media

This example program relies on several images:

## Overview

The process involved is as follows:

- create a sprite
- load our animation frames and add them into the sprite
- play our sprite animation
- main loop where we update the contents of the screen

## Creating a sprite

When creating a sprite that is going to have multiple animation frames added, no image gets passed into the CreateSprite call. This is handled by passing in a parameter of 0 for the image ID as shown here:

    CreateSprite ( 1, 0 )

    agk::CreateSprite ( 1, 0 );

After making this call a sprite with ID number 1 has been created, but does not have an image attached to it.

## Loading and adding animation frames

The next stage of the process is to attach animation frames to our sprite. There are two ways of approaching this:

- load our images, then pass their IDs into the command AddSpriteAnimationFrame
- call AddSpriteAnimationFrame and load the images within it

This code demonstrates the first method:

    LoadImage ( 1, "item0.png" )
    AddSpriteAnimationFrame ( 1, 1 )

    agk::LoadImage ( 1, "item0.png" )
    agk::AddSpriteAnimationFrame ( 1, 1 );

The first call is to LoadImage where the image “item0.png” is loaded into ID slot 1. The next call relates to animation. The command AddSpriteAnimationFrame’s first parameter is the ID number of the sprite. The second parameter is the ID number of the image. By calling this command we’re telling AGK to add “item0.png” into sprite 1s animation sequence.

The alternative method moves the LoadImage call directly into the second parameter of AddSpriteAnimationFrame. By doing this we bypass the need to store the image ID. It’s a slightly quicker method as it’s combining the calls, but not necessarily suitable for all cases:

    AddSpriteAnimationFrame ( 1, LoadImage ( "item0.png" ) )

    agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item0.png" ) );

The call above merges everything into one convenient line, at the expense of not storing or knowing the ID number of the image. This method is used to add all of the frames to the sprite, turning our final block of code into this:

    AddSpriteAnimationFrame ( 1, LoadImage ( "item0.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item1.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item2.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item3.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item4.png" ) )

    agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item0.png" ) );
    agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item1.png" ) );
    agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item2.png" ) );
    agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item3.png" ) );
    agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item4.png" ) );

When dealing with more animation frames it’s more optimal to use some kind of loop and build the image string up programmatically rather than hard coding it as shown in this example.

## Playing a sprite

Our sprite now has five animation frames (images) attached to it and we’re now in a position to animate it. All it takes is a call to the command PlaySprite. This command has several parameters:

- ID number for the sprite
- how many frames per second should be displayed
- whether the sprite is to loop or not
- start frame for the animation
- end frame for the animation

For our example the ID number is 1, the frame rate is set to 10 (a higher value will make it play faster while a lower value will result in a slower animation), 1 is used to indicate the animation will loop, the start point gets set to frame 1 / “item0.png” and finally the end frame is set to frame 5 / “item4.png”:

    PlaySprite ( 1, 10, 1, 1, 5 )

    agk::PlaySprite ( 1, 10, 1, 1, 5 );

After calling PlaySprite the sprite will continually animate until such time that we choose to stop it.

## Main loop

At this point everything is set up and ready to launch. All that remains is for our main loop to update the screen by making a simple call to Sync, as shown here:

    do
       Sync ( )
    loop

    void app::Loop ( void )
    {
       agk::Sync ( );
    }

## Full code listing

Everything is now in place. Here's the final code for our program:

    SetVirtualResolution ( 320, 480 )

    CreateSprite ( LoadImage ( "background.jpg" ) )

    CreateSprite ( 1, 0 )

    AddSpriteAnimationFrame ( 1, LoadImage ( "item0.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item1.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item2.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item3.png" ) )
    AddSpriteAnimationFrame ( 1, LoadImage ( "item4.png" ) )

    PlaySprite ( 1, 10, 1, 1, 5 )

    do
        Sync ( )
    loop

    void app::Begin ( void )
    {
        agk::SetVirtualResolution ( 320, 480 );

        agk::CreateSprite ( agk::LoadImage ( "background.jpg" ) );

        agk::CreateSprite ( 1, 0 );

        agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item0.png" ) );
        agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item1.png" ) );
        agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item2.png" ) );
        agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item3.png" ) );
        agk::AddSpriteAnimationFrame ( 1, agk::LoadImage ( "item4.png" ) );

        agk::PlaySprite ( 1, 10, 1, 1, 5 );
    }

    void app::Loop ( void )
    {
        agk::Sync ( );
    }

## Conclusion

This is just one example of animating sprites within your application. Part 2 demonstrates how to use a texture atlas.