Webdevils

Sprites are similar to movieclips but more efficient. Where movieclips use a separate image for each frame of an animation. A sprite uses one single image that contains all of the frames. Mobile devices have limited memory and images take up most of the memory your projects might use. Using a single image where you once had several can dramatically cut down the amount of memory your app may be using.

Sprite Sheets

A sprite sheet is a single image that contains all of the individual images that make up an animated sequence of images. Here’s an example. This image contains three animated images of the saucer (the four spots in the center move). Each individual image is 48pixels wide by 21 pixels tall. I used a transparent png, where the red was transparent, in my original test. I had to fill in the transparent area or you would not be able to see the white image against the page here.

A sprite sheet can have more than one series of images. As a matter of fact you could have all of the images used in your project inside of a single sprite sheet. Note the iPhone has a maximum image size that is can work with. On earlier iPhones the max size is 1024 by 1024 while newer models support up to 2048 by 2048 pixels.

Try it for yourself

The artwork for this example is more difficult to create than the other examples you’ll need to pay close attention to how it is created and sized. You can use the example image above if you like.

1. Create a new folder where you will store this project
2. Create a new text file and save it to your folder with the name main.lua
3. You’ll need an image containing each image of an animated sequence. That’s one image containing all frames of the animated sequence. See the example image above. Keep your images simple at first to avoid trouble.
4. Note the height and width of each frame. Each frame should be exactly the same size. (this isn’t a requirement for using sprites in Corona, but it is required for the code sample below)

Add the following code to your main.lus file. You’ll need to change the file name of saucer_sprites.png to the name of your image file.

You’ll also need to change 48 to the width of your sprites and 21 to the height. These are the width and height of each individual frames.

 

-- Include the sprite
require "sprite"
-- name the image file containing your sprites, followed by the width and height of each sprite
local saucer_sheet = sprite.newSpriteSheet("saucer_sprites.png", 48, 21)
-- Create a set by naming the sheet and starting frame and number of frames
local saucer_sprite = sprite.newSpriteSet(saucer_sheet, 1, 3)

-- Now create new sprite, give it a name, set the starting frame, end frame,
-- and time between frames in ms, 0 means loop
sprite.add( saucer_sprite, "saucer1", 1, 3, 100, 0 )

-- Create a new Sprite in the display object so we can see it on the screen
local saucer = sprite.newSprite( saucer_sprite )
-- Position your sprite
saucer.x = display.contentWidth / 2
saucer.y = display.contentHeight / 2

-- Prep your sprite
saucer:prepare("saucer1")
-- Start the sprite playing
saucer:play()

Some resources:

• Zwoptex – A sprite packing tool
• Texture Packer – Another sprite packing tool
• Sprite Something – is a pixel drawing tool for the iPhone/iPad

Often you will want to create a short animated clip. This is good for a lots of things especially games. A movieClip is an object that contains a series of images. Movieclips can play display their images in succession to create animated effect.

MovieClips are really a series of images loaded into to Corona and played in sequence. You could accomplish this with a Group containing all of the images and an array. Then writing an enterFrame function to cycle through the images in the array making each one visible in turn.

You could do all of that but, you don’t need to since someone over at Corona has all ready done it for you! This example uses the movieclip.lua file. You can find this in CoronaSDK/SampleCode/Graphics/MovieClip.

Create a new Corona project.

1. Create a folder to work in
2. Copy the movieclip.lua file from CoronaSDK/SampleCode/Graphics/MovieClip into the folder where you will be working
3. Create a new text file and save it into the folder an name it main.lua
4. Create a series of small images to use for the animated sequence. Imagine these images as frames in a movie. Save the images into the project folder

Add the following code to main.lua

-- Import an external library
local movieclip = require("movieclip")

-- Since we're importing a library we need to make a main function
-- to run after the library has loaded

-- Define the main function to initialize this program
function main()
 -- This line makes a new animated "movieClip" from the saucer images in the table
 saucer = movieclip.newAnim{"saucer_01.png", "saucer_02.png", "saucer_03.png"}

 saucer.x = display.contentWidth / 2
 saucer.y = display.contentHeight / 2

 -- Start the animation playing
 saucer:play()
end

-- Call main to start the program
main()

Transitions work well for situations when you want a motion to run from start to finish with a set length of time. For example you’d like to have en element move onto the page and stop in the center over 3 seconds. At other times you’ll want to create a motion that plays continuously. For example, you have object that moves back and forth across the screen for as long as it is on the screen. In these cases transition.to() doesn’t work so well. For these situations we can use the “enterFrame” event.

The enterFrame event

The enterFrame event is an event that us dispatched once every frame. Which of course brings up the idea of frames. Think of frames as the number of times Corona updates the screen. This is typically 30 times per second. So the enterFrame event is an event that is sent 30 times per second.

You can use the enterFrame event to do lots of things. A common purpose is animation. Imagine you had a object on the screen you added 12 degrees to it’s rotation 30 times each second. It would make a complete rotation every second.

Test the enterFrame event

Create a new Corona project

1. Make a folder to work in
2. Create a new text file and save into the folder with the name main.lua
3. Copy a small image into your folder

In your main.lua file add the following code.

-- Make a new image
local invader = display.newImage("invader_04.png")

-- Position the image at a starting location off the left edge of the screen
invader.x = -80
invader.y = 160

-- Use this function move the image, this function will be run once each frame
-- each frame add 5 to the x. If x is greater than 400 move the image to the left
local function move(event)
 invader.x = invader.x + 5
 if invader.x > 400 then
 invader.x = -80
 end
end

-- Add an enterFrame event to the Runtime object
Runtime:addEventListener( "enterFrame", move )

Think of notifications from the program about things that have happened in the program. Use events to determine when an object is tapped or when period of time has passed. Use events to animate things and react to user interaction.

Listeners and Handlers

Listeners are objects that have been assigned to respond to an event. Handlers are the functions that are run when an event occurs. Think of listeners as waiting for and notifying their handlers when the event occurs.

Most objects in Corona can be assigned a listener. Use the addEventListener() method to assign the listener. For example imagine you want a create an event is fired when you tap an image. You might write the following. Try it for yourself.

1. Create a new folder to work in
2. Open a new text file and save it to your folder with the name main.lua
3. Copy an image to use in the example to your folder

Add the following code to main.lua:

-- Create an image and position it in the center of the screen
local invader = display.newImage("invader_04.png")

invader.x = display.contentWidth / 2
invader.y = display.contentHeight / 2

-- Define a handler
local function tapInvader( event )
 transition.to(invader, {time=1000, rotation=invader.rotation+360})
end

-- Add an event listener to the invader
invader:addEventListener("tap", tapInvader)

I added a few comments to the code to explain what is going on. Any line that begins with “–” is ignored and the rest of the line can be used to write a message or description of your code.

Test your project and tap the invader. With each tap it rotates 360!

 

At some point you will want to work with groups of display objects. Corona provides a special type of Group display object.

Try out groups for yourself. Start by making a new Corona project.

1. Create a folder to work in
2. Create a new text file, save it to your folder named main.lua
3. Add a few small images to your folder

First create three images.

local square = display.newImage("square.png")
local circle = display.newImage("circle.png")
local hexagon = display.newImage("hexagon.png")

 

Next create a group.

local group = display.newGroup()

Now add the objects to group

group:insert( square )
group:insert( circle )
group:insert( hexagon )

 

Now we’ll off set the images a little. Here placed circle near the upper right corner of square and hexagon near the lower left corner of square.

square.x = 0
square.y = 0

circle.x = 50
circle.y = -50

hexagon.x = -50
hexagon.y = 50

Now try transforming the group. Notice all of the images transform as a group. Placing the group in the center of the screen moves all of the images there. Rotating the group rotates all of the images. All of the transformations are based on the group’s reference point.

group.x = 160
group.y = 240
group.rotation = 5
group.alpha = .5

You can also animate the group. Try the following.

transition.to( group, {time=3000, rotation=360, transition=easing.inOutExpo})

A group acts as a display object in every way, with the difference that Groups can contain other display objects including other groups.

 

 

 

Once you’ve created more than one object the order in which they stack will be come important. What I mean by “stacking order” is which object is in front and which is behind, imagine layers in Photoshop.

Corona stacks or layers objects in the order that they are created. In other words the first object created would be on the bottom. While each newer object created would stack on top of the previous.

Try this out for yourself. Create a new Corona project.

1. Make a new Folder to work in.
2. Make a new text file, save it to the folder as main.lua.
3. Add three small images to your folder.

Create three images in your Corona project. Use the following to load your images. In my example the images were named square.png, circle.png and hexagon.png.

local square = display.newImage("square.png")
local circle = display.newImage("circle.png")
local hexagon = display.newImage("hexagon.png")

Notice the square is behind the other images. The circle “stacks” or looks like it’s on a layer between the other two. And, the hexagon is on top of the others.

Note: If any of the upper are larger than the images below, the images may not be visible.

The stacking order is determined by the order the images were created. With newer images being placed on top of images that were created earlier.

Corona provides a few methods that allow you to manipulate the stacking order. To move an object to the front use object:toFron(). For example, the following would move the circle to the front.

circle:toFront()

Use the object:toBack() method to move an object to the back. For example, the following moves the hexagon to the back.

hexagon:toBack()

 

 

 

 

 

 

 

Corona provides a simple solution to making things move. The best way to learn is try it for yourself.

Start by creating a folder for your new project. Create a new text file and save it your folder as main.lua. Add an image to your folder. make this image something small, about 100 px by 100 px.

In main.lua add the following code to get the image to show up on the screen.

local square = display.newImage("square.png")

Test your project at this point to make sure your image shows. The image should appear in the upper left of the screen.

Transition

Now add a transition. Add the following code below the code from above.

transition.to( square, {time=3000, x=160, y=240} )

Test your project. The image should move to the center of the screen over 3 seconds. Note, the motion has a constant speed. The object neither speeds up or slows down from the beginning to the end of the motion.

The transition “to” method takes two parameters. The first is the reference to the object that will be animated. In my case I used the variable square. Second is a “table” containing properties that describe the motion.

Note: Lua uses “tables” which are similar to Arrays and Objects in other languages. Though, the syntax is different!

The table I created above {time=3000, x=160, y=240} contains three properties: time, x and y. Notice the table is defined with the {}. Each property and value pair is separated by a comma. Each property and value has an = between the two.

The time property sets the length of the motion. This is set in milliseconds. There 1000 milliseconds in every second. The motion above would last 3 seconds.

The x and y properties animate the x and y properties of the display object, square. You can animate any properties using transition.to. Try animating the rotation property.

transition.to( square, {time=3000, x=160, y=240, rotation=360} )

Test again, this time the image rotates a full 360 degrees while moves to the center of the screen.

Preset properties

Imagine you wanted the box to move on to the stage from outside the edge of the stage. In this case you’d want to set the position of the object to it’s starting location before calling transtion.to().Try adding the following line before transition.to()

square.x = -100
square.y = -100

Test your project again. This time object moves into view from the upper left. Since x of 0 is the left edge of the stage and y of 0 is the top edge of the stage, negative x values place the object off the edge of the stage to the left. While negative y values would place the object off the top edge of the stage.

Other properties

Try experimenting with these properties.

• alpha – Sets the transparency of the object. Use a range of 0 (transparent) to 1 (opaque).
• xScale – Sets the horizontal scale. A value of 2 would make the object twice it’s original size.
• yScale – Sets the vertical scale.

Easing

Obviously the default linear easing is not very exciting. Corona provides a few easing methods.

• easing.inExpo( ) – speed up
  
• easing.inOutExpo( ) – speeds up and slows down
  
• easing.inOutQuad( )
• easing.inQuad( )
• easing.linear( )
• easing.outExpo( )
• easing.outQuad( )

Use these in conjunction with the transition property in the table when calling transition.to(). For example:

transition.to(square, {time=3000, x=160, y=240, rotation=360, transition=easing.outExpo} )

This time the image starts of fast and slows to a stop at the end of it’s motion.

 

 

 

 

 

 

Creating an image and adding it to the stage with Corona is very easy. To get started create a folder where you will be working. Create an image to use for the example. Something small since we’ll be testing in the iPhone simulator. For the example assume the stage will be 320px by 480px. Save your image into the folder where you will be working. My image was named square.png.

Next we need to create our Corona project. Create a plain text file and save it into your folder. Name this file main.lua.

Create an image on the screen

Add the following to the top of main.lua

local square = display.newImage("square.png")

Open main.lua with Corona. The simulator should appear and your image appears in the upper left corner.

Position an image with x and y

Try positioning your image on the stage. The display object holding the image is saved in the variable “square”. Set the x and  y property of your image.

square.x = 160
square.y = 240

This should place the image in the center of the simulator. Assuming the width to 320 and height to be 480. The center would half of these numbers 160 and 240.

Notice the image appears in the exact center. This would mean that Corona considers registration point, or point of transformation, for the image to be in the center of the image.

Rotate an image with rotation

Test that out by rotating the image. Add the following line

square.rotation = 45

The square is still center and is rotated around it’s center.

Note! That means that the original position was not x = 0 and y = 0. Remember when the image was first placed it’s upper left corner was aligned with the upper left corner of the stage. If the x and y were 0, then the center of the image should have aligned with the upper left corner. Test it for yourself.

square.x = 0
square.y = 0

Test your work. Notice the center of the image is now in the upper left corner.

So, Corona positions objects initially setting their x and y to half the image height and width, to place the upper left corner of the image in the upper left of the stage.

Reference Point

The center of transformations for an object is called the reference point in Corona. You can position the reference point of an object using the xReference and yReference properties. Changing these values does not change the position of an object, instead it changes the center of transformation.

Think of the reference point as a pin holding your object to the stage. When you set the x and y it’s the pin that is placed at the new x and y coordinates. When the object rotates it rotates around the pin. By default the reference point is placed in the center. Imagine a pin stuck through the center of the object.

The reference point can be manipulated by changing the xReference and yReference. This is useful, since in some cases it will be more convenient to position or transform an object from the upper left corner or location other than the center.

Try it for yourself. Move the reference point to the upper left corner. In my example the image I used was 100px by 100px. By default xReference and yReference are 0 and 0. To move the reference point to the upper I’ll need to set the xReference and yReference to negative half the width and negative half the height, -50 and -50.

square.xReference = -50
square.yReference = -50

Change the x, y and rotation properties a few times each and test your project with each change. You’ll notice the image is transforming around a point in the upper left.

Alternately you can use the following method to set the reference point to the upper left corner of an object. Chnage object to the name of your object, square in my example.

object:setReferencePoint( display.TopLeftReferencePoint )

Removing images

It is important to remove objects when they are not in use. Bit map images take up large chunks of memory. Which, on mobile devices is a scarce resource.

To properly remove an object you need to remove it explicitly from it’s parent. This can be done in one of two ways.

image.parent:remove( image )
-- or --
image:removeSelf()

Sometimes this is not enough to free up memory used by the object. You also need to remove any references to the objects. These references are stored in variables. In the example above the variable square is assigned and holds a reference to a display object after this line:

local square = display.newImage("square.png")

After this line, square can be used reference the display object containing the image “square.png”. This variable also ensures that the memory used by the image”square.png” is not released.

To ensure that an object is released from memory when you are done with it you need to set the value of any variables referencing it to nil. The value nil is an empty, value think of it as no value. To remove square from the display and make sure it’s memory is freed you would want to do the following.

square.parent:removeSelf()
square = nil