Animated Sprites and Methods

Tuesday Tutorials are back! Today’s tutorial is from Brent Sorrentino, a Corona Ambassador based in northern Colorado. Brent has been an active part of the Corona community for almost two years. He is a freelance travel photographer, Corona developer, and graphic designer. In addition to using Corona to develop his own apps, he regularly lends a hand in the forums, helping other developers solve coding issues. His website can be accessed here.

Today’s tutorial covers how to implement animated sprites and use the related APIs. While this might seem like a rehash of previous tutorials, several key improvements have been implemented since the current sprite system was introduced earlier this year. In addition, many developers are still confused about how to implement sprites in Corona because, in fact, there are two approaches leading to a similar result:

1. The old (and now depreciated) sprite.* library.
2. The current sprite APIs that work cohesively with image sheets and the display.* library.

While Corona is technically “backwards compatible” with the depreciated sprite.* library, we strongly encourage that you use (or migrate to) the current sprite methods. If you haven’t implemented the current methods or haven’t ever used sprites in Corona, this tutorial will walk you through the process.

For those already familiar with basic animation in Corona, this tutorial introduces the full array of sprite event listeners and how to implement them.

Tutorial Contents

1. Configuring a Basic Image Sheet or “Sprite Sheet”
2. Defining Animation Sequences
3. Declaring a Sprite Object
4. Sprite Control Methods — managing playback and sequences
5. Sprite Properties — accessing and setting various sprite properties
6. Sprite Event Listeners — detecting sequence events such as “ended”, “loop”, and “next”

Configuring a Basic Image Sheet or “Sprite Sheet”

What exactly is a image sheet? Imagine it as a sheet of paper on which you draw the individual frames for your animated object(s). Other technical terms include texture atlas, image map, or sprite sheet. In Corona, we’ll simply refer to it as an image sheet, because its usage is not limited to either static or animated objects — you can, and often should, use image sheets for both purposes: static images picked from a portion of an image sheet, and animated sprites utilizing multiple frames from a sheet.

Detailed technical notes and usage examples for the graphics.newImageSheet() API are located here, but in this tutorial we’ll discuss how to use image sheets for animated sprites.

Pictured below is a sample image sheet for a running cat. If you want to use this image sheet to follow through the entire tutorial, you can copy the hi-resolution version from here. This sheet consists of eight “frames” in a specifically ordered  sequence. By default, the animation will begin at the top-left frame, proceed to the next frame (to its right), wrap to the next row when it reaches the end of the current row, and finally stop (or repeat) when the entire sequence is complete.

Let’s proceed with how to configure this image sheet in Corona. First, set up an indexed table for a basic image sheet of uniform-sized frames. You can (and often will) set up an image sheet using frames of different sizes packed in a tight, optimized arrangement (see documentation), but in this tutorial we’ll use a basic image sheet.

IMPORTANT:  sheetContentWidth and sheetContentHeight represent the overall 1:1 dimensions of the image sheet, meaning the 1:1 content scale that you’ve set up in your app’s config.lua file. This allows you to use different image sheets for different devices, for example a @1 sheet for the original iPad and a high-resolution @2 sheet for the Retina iPad. Thus, if your 1:1 sheet is 1024×1024 pixels in overall dimensions (not per-frame), build your 2:1 sheet at 2048×2048 — but always specify the 1:1 dimensions in your image sheet setup. If you’ve defined your config.lua file properly, Corona will take care of the rest!

Now, define the actual image sheet, referencing both the image file and the data table you created. This assumes that your image sheet file resides at the root of your project directory, not in a subfolder.

Defining Animation Sequences

You can define animated frame sequences in two ways:

• consecutively using a starting frame index and frame count
• non-consecutively using a specific order of frames

This makes the Corona sprite system very flexible — you can use the same image sheet for multiple animation sequences.  In both cases, you’ll need to define your sequences in a comma-separated array of sub-tables.

Consecutive frames

Non-consecutive frames

Mixed sequences (both consecutive and non-consecutive sequences)

Declaring the Sprite Object

Using the current sprite method, you’ll declare sprites with the display.newSprite() API. The syntax is simple:

display.newSprite( [parent,] imageSheet, sequenceData )

• parent = The parent display group in which to insert the sprite (optional).
• imageSheet = The image sheet which the sprite should utilize.
• sequenceData = The array of animation sequences which you set up. The sprite will default to the first sequence in the array unless you specify otherwise (see Sprite Control Methods below).

In context of this tutorial, your sprite declaration should look like this:

The sprite is now a display object, just like static images, vector objects, etc.  It can be moved, manipulated, linked to a physics body, and more.  To remove a sprite object, simply use object:removeSelf() or display.remove( object ). Don’t forget to set the reference to nil after removal!

Sprite Control Methods

The sprite system provides four key control methods which you’ll use to control the playback and sequence of your sprites.

• animation:play()
  Start the animation playing. Animations do not begin playing when you create them — you must start each animation manually using this command.
• animation:pause()
  Pauses the animation. There is no “stop” control method; instead, pause the animation using this method.
• animation:setFrame( frame )


  Immediately set or skip to the indicated frame index. If you want to “stop and reset” an animation sometime after you have started playing it, use the :pause() and :setFrame( frame ) commands consecutively, setting the frame back to the beginning of the sequence.
• animation:setSequence( sequence )


  Set the sprite to a specific sequence that you declared in your sequence array. For example, if you want to change your cat animation from “normalRun” to “fastRun”, you would use animation:setSequence( “fastRun” ) and use animation:play() to begin playing it, since the animation will not play automatically after you change the sequence.

Putting It Together

Let’s put the entire animation together. To set up your cat animation with two animation sequences “normalRun” and “fastRun”, your code should look like this:

Go ahead and test your project in the Corona Simulator and see the result!  The cat should appear in the center of the screen, animating on the “normalRun” sequence (since you didn’t specify a sequence, the cat defaults to the first sequence in the sequence array).  Experiment with changing the sequence by typing animation:setSequence( “fastRun” ) on the line before animation:play().

Sprite Properties

Corona provides several properties which can yield information about existing sprites. You can even modify the timeScale (relative speed) of a particular sprite. These properties are as follows:

• object.frame
  A read-only property that represents the currently shown frame index of the loaded sequence. This does not set the frame — use the :setFrame() command to explicitly set an animation frame.
• object.isPlaying
  Returns true if the animation is currently playing; false if it is not.
• object.numFrames
  A read-only property that represents the number of frames in currently loaded sequence.
• object.sequence
  A read-only property that returns the name of the currently playing sequence.
• object.timeScale
  Gets or sets the scale to be applied to the animation time. This is used to control a sprite’s animation speed dynamically. For example, a time scale of 1.0 (default) runs the animation at normal speed. A time scale of 2.0 runs the animation twice as fast. A time scale of 0.5 runs the animation at half speed. The maximum allowed value is 20.0 and the minimum allowed value is 0.05. The value supports up to 2 decimal places.

Sprite Event Listeners

Now that you have a basic sprite declared and two sequences (“normalRun” and “fastRun”), let’s examine sprite event listeners and how to implement them. A sprite event listener, by definition, “listens” to the activity of a sprite and sends information to the listener function.

For example, assume that you want your running cat to loop through 4 cycles of the “normalRun” sequence then change to the “fastRun” sequence. This would be effectively impossible (and awkward) using standard timers, so instead we’ll implement a sprite event listener.

Before we proceed to the example, examine the five event phases available to sprites. These phases are implemented in the most recent Public Release of Corona (2012.894) and beyond.

• began = The sprite has started playing.
• ended = The sprite has finished playing.
• bounce = The sprite has bounced from forward to backward while playing.
• loop = The sprite has looped to the beginning of the sequence.
• next = The sprite has played a subsequent frame that’s not one of the above phases.

We’ll discuss how to “listen” for these phases below, but first let’s modify the running cat’s “normalRun” sequence by adding a loopCount of 4. This allows you to detect an ended phase when all 4 loops are complete.

Now, let’s write the listener function and add the actual event listener to the running cat. You can place this at the end of your sample code, after the sequences are declared and the sprite object placed on the screen.

A sprite listener transmits all phases to the listener function. It’s your responsibility to filter the phase(s) using conditional if-then clauses and perform actions when they occur in the sprite animation sequence. In this particular case we listen for the ended phase, which occurs after 4 complete loops as dictated by the sequence’s loopCount parameter. When the sequence ends, we switch the cat animation to the “fastRun” sequence and play it.

Note that you can use one sprite listener for all of your sprites — simply get the sprite reference using event.target in the listener function (this was formerly event.sprite in the depreciated sprite library; if migrating from the depreciated sprite library, use event.target instead).

In Summary

This tutorial has examined most of the current sprite methods, including setting up basic image sheets, defining animation sequences, controlling sprite playback, accessing various sprite properties, and using sprite event listeners for fine-tuned control. Hopefully this tutorial has provided some valuable insight and tips for developers using sprites in their apps, and for those migrating from the depreciated sprite library to the current sprite methods.