Getting Started: working with Sprites

So, you have AndEngine set up, and you have your project put together- so the next question is- how do you put things onto the project?  Well, the most common object to be placed in a game world is a Sprite.  A Sprite is, simply put, any pre-rendered two-dimensional object that you place on the screen.  They work something like pictures, with one major difference: sprites can interact with everything.

Types of Sprites

To begin, let’s look at the different kinds of sprites.  In AndEngine, there are 3 major kinds-

(1) A Sprite.  This is the most basic kind of sprite.  It mostly just sits there.  Unless its picture is manually changed, it stays the same.  Thanks to AndEngine, it can do anything a normal sprite can do, but it doesn’t have any of the special qualities the other sprites have.

Sprites are usually defined in onLoadScene like this:

	Sprite mySprite = new Sprite(startingX, startingY, this.myTextureRegion);

This example will create a sprite named mySprite whose top-right corner is located at (startingX, startingY)- both of which need to be defined as integers.  The image presented on mySprite will be myTextureRegion.  For more on Texture Regions, check the Texture Region Guide.

(2) The second kind of sprite is a TiledSprite.  A tiled sprite is somewhere halfway in between a regular sprite an an animated sprite- it doesn’t animate at a regular rate, but it takes a tiled texture region, and with a command (found below) can switch between its different tiles.  TiledSprites are defined in onLoadScene like this:

	TiledSprite myTiledSprite = new TiledSprite(startingX, startingY, this.myTiledTextureRegion);

For the most part, you can see that it looks- and works- just like an ordinary sprite, with the only difference being that it uses a TiledTextureRegion instead of a normal texture region- at first, it will only use the first tile, but when given the commands found below, it will change what it looks like.

(3) The third kind of sprite is the AnimatedSprite.  If you’re making a game, you’ll probably be using at least one AnimatedSprite- it takes in a series of images and plays them at whatever speed you specify, one after another, often looping (though they can be set not to.)

Animated sprites are defined in onLoadScenes like this:

AnimatedSprite myAnimatedSprite = new AnimatedSprite(startingX, startingY, this.myTiledTextureRegion);

So, this still looks pretty much the same- startingX, startingY, and myTiledTextureRegion.  However, this time, instead of being shown as a series of tiles, it is shown as an animation (based on the animation speed you set it to after it’s initialized)- check the code below to see how this works.

Basic Sprite Commands

Now that we know the differences, you may be wondering- what is a sprite?  Honestly, a sprite is little more than a rectangle which has its face set to a particular image and is given a few particular actions useful in games.  As a matter of fact, the base sprite class extends BaseRectangle, so any commands that will work on Google’s BaseRectangle will also work on a sprite.  A sprite differs from BaseRectangle, however, when it comes to movement, size, and interaction- and that’s where some of AndEngine’s special features shine.  Here are a few special commands that work with sprites:

scene.attachChild(mySprite); alternatively, sprite.addToScene(scene);

This line would attach the child to the scene, officially making it a part of your app!  This should also be done in onLoadScene.

mySprite.getX, mySprite.getY, mySprite.setPosition(x,y);

These are commands that will give or set the current coordinates of the sprite.  Therefore, if you wanted to move something left, you could get its x position, subtract a number, and then set that position back with the command sprite.setPosition(sprite.getX-10, sprite.getY).

mySprite.setScale(x);

Makes the sprite larger or smaller, based on a power of X (for example, setScale(2) would make it twice as big, while setScale(0.5f) would make it half as big.

mySprite.setRotation(x);

Rotates the sprite by x degrees.  For example, setRotation(90) would turn it sideways, while setRotation(360) would have no effect, as it would take it full circle.  

mySprite.setVisibility(false); 

This command can prove valuable when you want to remove a sprite, but leave it in memory.  An example of how this is useful is this: say you have a game where you fire bullets.  Every time a bullet leaves the screen, you need to remove it, but within seconds, you’ll be creating another.  Rather than taking the extra processing power to remove the enemy and make a new one, it is better practice to remove the bullet, then reuse it next time you need a bullet.

myTiledSprite.nextTile();

This is a command given for a tiled sprite which changes its image to the next tile.

myTiledSprite.setCurrentTileIndex(x);

This is a command given for a tiled sprite which changes its image to a specific tile.

scene.detachChild(mySprite);  

 

This command will remove your sprite from the scene properly.  Sometimes, you may want to just use mySprite.setVisibile(false); Using this command will help reduce memory leaks (which are a big problem, and can even break your game if they have multiple levels back to back).

myAnimatedSprite.animate(x, int loopingCount);

This is a command given for animated sprite which starts it animating with the frame length X (in milliseconds).  If a second variable is given (as an int or boolean), it will repeat that many times.

myAnimatedSprite.stopAnimation(x);

This is a command given for animated sprite which stops its animation at the frame x.  If x is left blank, it stops it at the current frame.

This is a command given for animated sprite which starts it animating with the frame length X (in milliseconds).

There are hundreds of commands that can be used with sprites- these are simply some of the most common ones to get you started.  As you can see, AndEngine’s sprite class is a powerful tool that is essential for any game.  If you’re interested in using physics or creating an array of sprites (such as multiple enemies or targets), check the AndEngineExamples, use Google to find a guide, or check back here in a few weeks- both of these are planned topics.  If you have any other questions, feel free to comment, e-mail, or head over to the forums- the community will help you with anything you need!  Up next: Getting Started: Input: Touch Events and Motion Events.