Getting ready

You will also need the sample projects in your Eclipse workspace as well as data/caveman.atlas and data/trex.atlas along with their corresponding PNG textures.

How to do it…

First things first, the code for this recipe is located inside the AnimatedSpriteSample.java file, which uses the known ApplicationListener pattern. We are going to use two texture atlases created with texturepacker-gui that contain a walk cycle animation for our caveman and the merciless Tyrannosaurus Rex respectively. Feel free to catch up with atlases in the More effective rendering with regions and atlases recipe.

The caveman walk cycle can be found in the caveman-sheet.png and caveman.atlas files while the dinosaur is stored in the trex-sheet.png and trex.atlas files. As usual, everything is located under the [cookbook]/samples/samples-android/assets/data folder. Here is a simplified version of the dinosaur sprite sheet:

The FRAME_DURATION determines for how long (in seconds) we should show each frame of our sprite sheet before advancing to the next one. Since our animations were tailored to be displayed at 30 frames per second, we set it to 1.0f / 30.0f:

private static final float FRAME_DURATION = 1.0f / 30.0f;

To achieve this demo's goal, we will need a camera, a sprite batch, and two atlases, one for the caveman and another one for the dinosaur walk cycles. We will also need a background texture if we do not want to show a dull black background:

private TextureAtlas cavemanAtlas;
private TextureAtlas dinosaurAtlas;
private Texture background;

Texture atlases simply provide a collection of texture regions we can retrieve by name. We need a way of specifying how our animations are going to be played. To that end, Libgdx provides us with the Animation class. Every distinct character animation should have its own Animation object to represent it. Therefore, we will use a dinosaurWalk instance and a cavemanWalk instance. Finally, we will control how our animations advance through the animationTime variable:

private Animation dinosaurWalk;
private Animation cavemanWalk;
private float animationTime;

Inside the create() method, we build the orthographic camera, rendering area, and batch. We also initialize our animationTime variable to 0.0f to start counting from then onwards:

camera = new OrthographicCamera();
viewport = new FitViewport(SCENE_WIDTH, SCENE_HEIGHT, camera);
batch = new SpriteBatch();
animationTime = 0.0f;

The next step is to load the atlases for the caveman and the dinosaur as well as the background texture:

cavemanAtlas = new TextureAtlas(Gdx.files.internal("data/caveman.atlas"));
dinosaurAtlas = new TextureAtlas(Gdx.files.internal("data/trex.atlas"));
background = new Texture(Gdx.files.internal("data/jungle-level.png"));

Later, we retrieve the collection of regions of both our atlases using the getRegions() method and sort them alphabetically because that is how we have arranged the frames in our animation atlases:

Array<AtlasRegion> cavemanRegions = new Array<AtlasRegion>(cavemanAtlas.getRegions());
cavemanRegions.sort(new RegionComparator());

Array<AtlasRegion> dinosaurRegions = new Array<AtlasRegion>(dinosaurAtlas.getRegions());
dinosaurRegions.sort(new RegionComparator());

The RegionComparator class is nothing more than a convenience inner class to sort our AtlasRegion arrays. AtlasRegion inherits from TextureRegion featuring additional data related to its packaging. In this case, we are interested in its name member so as to be able to sort the images alphabetically:

private static class RegionComparator implements Comparator<AtlasRegion> {
   @Override
   public int compare(AtlasRegion region1, AtlasRegion region2) {
      return region1.name.compareTo(region2.name);
   }
}

It is now time to create the Animation instances. The constructor takes the frame duration, Array<TextureRegion>, representing all the frames that form the animation and the playback mode. Just like the name hints, PlayMode.LOOP makes an animation play over and over again. We will learn more about other play modes later on in this recipe. The code is as follows:

cavemanWalk = new Animation(FRAME_DURATION, cavemanRegions, PlayMode.LOOP);
dinosaurWalk = new Animation(FRAME_DURATION, dinosaurRegions, PlayMode.LOOP);

Finally, we position the camera to be at half its width and height so we can see the background properly, which will be rendered with its bottom-left corner at the origin:

camera.position.set(VIRTUAL_WIDTH * 0.5f, VIRTUAL_HEIGHT * 0.5f, 0.0f);

We do not want to be leaking memory all over the place. That would be disgusting and unacceptable! That is why we make sure to dispose of all the resources in the conveniently named dispose() method of our ApplicationListener:

@Override
public void dispose() {
   batch.dispose();
   cavemanAtlas.dispose();
   dinosaurAtlas.dispose();
   background.dispose();
}

Finally, we get to the key bit, the render() method. As usual, we first clear the screen with a black background color and set the viewport, that is, our rendering area in screen space. The next step is to increment our animationTime variable with the time that has passed since our last game loop iteration. We can get such information from Gdx.graphics.getDeltaTime(). To prepare the terrain for rendering, we update the camera matrices and frustum planes, set the sprite batch projection matrix, and then call begin().

Which frame shall we draw? That is a good question. Luckily enough, as long as we provide animationTime, the Animation class has all the information it needs to figure it out: the list of frames, the frame time, and the playback mode. We can call getKeyFrame() passing in the time in seconds to obtain the frame to draw each frame and give it to the batch draw() method. That way, we can draw our two animated characters along the background texture. Easy as pie. The code is as follows:

public void render() {      
   ...   

   animationTime += Gdx.graphics.getDeltaTime();
      
   batch.begin();
   
...
   
   TextureRegion cavemanFrame = cavemanWalk.getKeyFrame(animationTime);
   width = cavemanFrame.getRegionWidth();
   height = cavemanFrame.getRegionHeight();
   float originX = width * 0.5f;
   float originY = height * 0.5f;
   
   batch.draw(cavemanFrame,
            1.0f - originX, 3.70f - originY,
            originX, originY,
            width, height,
            WORLD_TO_SCREEN, WORLD_TO_SCREEN,
            0.0f);      
   
   ...

   batch.end();
}

Now you can see our caveman and the dinosaur in motion!

How it works…

The implementation of the Animation class is extremely simple, but it does a great job in helping us introduce animated characters in our games using sprite sheets. See for yourself by reading its implementation in the Libgdx GitHub repository. You will find that reading the Libgdx source at https://github.com/libgdx/libgdx/blob/master/gdx/src/com/badlogic/gdx/graphics/g2d/Animation.java is actually a great way of learning how it works internally; do not let it scare you away.

It holds a low-level Java array of TextureRegion references, the frame duration parameter, and caches the whole animation duration. The main part of the action takes place in the getKeyFrameIndex() method. It simply grabs the current frame index by dividing stateTime over frameDuration. Then, it accesses the region's array depending on the animation PlayMode. It makes sure not to pick an invalid frame and returns the appropriate index. Obviously, if you call the getKeyFrame() method directly, you will obtain the region straightaway.

There's more…

So far, we have seen the most basic operation you can do using the Animation class, simply retrieving the current frame on each iteration of the game loop for rendering purposes. However, if you want to use this system in slightly more complex situations, you will need further control. In this section, we will cover what different playback modes are at our disposal, how to check when a one-shot animation is done, and how to manage complex characters with tons of animations.

<?xml version="1.0" encoding="UTF-8"?>
<animatedCharacter atlas="data/caveman.atlas"
            frameDuration="0.03333" >
   
   <animation name="idle" mode="loop" >
      <frame region="caveman0001" />
      <frame region="caveman0002" />
      <frame region="caveman0003" />
      ...
   </animation>

   <animation name="walk" mode="loop"> ... </animation>
   <animation name="jump" mode="normal">  ... </animation>
</animatedCharacter>

public class AnimatedCharacter
{
   private ArrayMap<String, Animation> animations;
   private float time;
   private Animation currentAnimation;
   
   public AnimatedCharacter(FileHandle file);
   public void update(float deltaTime);
   public AtlasRegion getCurrentFrame();
   public String getAnimation();
   public void setAnimation(String name);
   public void setPlaybackScale(float scale);
   public void stop();
   public void pause();
   public void play();
}

See also