This post is part of my Mobile Game Development series. Start at the beginning to catch up. This series was inspired by the things I learned developing a new game for Android and iOS called Mirror Maze.
In my last post, I talked about CCNode, the root class for all visible elements in CocosSharp. In this post, I’d like to talk about a class that inherits from CCNode, which I expect you will find yourself making use of quite often: CCSprite.
Let’s say that you want to make a graphic in your favorite graphic editor, output a graphic file, then display that graphic in your game. You would want to use CCSprite to pull this off. First things first, though. That graphic file has to get pulled into your project. Earlier in this series, I talked about how graphic files get put into both your Android and iOS projects, under Content > Images > Hd|Ld. I also mentioned that they have to be placed into both your Android and your iOS projects because each platform includes them in the final package differently. In Android, you need to make sure the Build Action for each file within the Content folder is set to AndroidAsset. In iOS, the Build Action needs to be set to BundleResource.
A quick note here: I found Xamarin Studio didn’t like to set the Build Action properly for iOS references automatically. I had to change each one of them myself to BundleResource.
In that same post, I talked about how you initialize the Game View to know where to look for assets. CCSprites are one of the elements that will put that to use. One of the constructors for CCSprites takes, as a parameter, the name of a file to render. That filename can include the file extension if you like, but it’s good practice not to. In fact, you could include the full path to the file too, if you wanted. Again, it’s good practice not to. Just the name is enough. CocosSharp will look in the folders specified in that initialization for file names matching the one you provide. This allows the engine to pick up either the High Density file or the Low Density file, depending on the pixel density of the device the game is running on.
There are two steps that need to occur for your sprite to be created and added to the active layer. First, you instantiate the sprite. Second, you add the sprite as a child to the current layer (or node).
var sprite = new CCSprite("mysprite");
Doing that, and nothing more, will render your sprite in the current layer at the position (0, 0), which is the lower-left corner of the screen. We will cover positioning much more in a later post. For now, (0, 0) is good enough for us. So now you’ve got a static sprite in your game and that may be exactly what you need. If that is the case, awesome. Carry on and make an great game. Mirror Maze v1, for example, only uses static sprites.
Sprites can do more than display static images, though. Sprites can also do frame-by-frame animation, kind of like cartoons. Why would you want to do something like this? Maybe your game involves a character that has a standing graphic when sitting idle, then needs to walk or run when moving around. The standing graphic is a single frame, but the walking or running animation will be a series of frames in order for the user to see a smooth animation.
There’s four steps to animate your sprite.
Step 1: Design each frame in your graphic editor and output those frames into individual graphic files. This involves your graphic editor program. As I mentioned previously, I use Inkscape. Design your animation frames however you choose, then output them each into their own individual graphic files making sure that each file is the same dimension. This is important so that the animation will look smooth. Also important is how you name the files. You’ll want to name them with a consistent naming scheme, such as “WalkingX”, where X is the number of that file in the sequence.
Step 2: Package those individual graphic files into a sprite sheet. There are a number of ways you can do this, but I used a handy tool called Texture Packer. Texture Packer has a lot of features that you can pay for, but the free version has enough functionality to create a nice sprite sheet for you. What you’ll find from the output of this is that a sprite sheet is actually two things: the graphic file containing all the sprites in a single sheet and the .plist file that specifies where each frame resides in that sprite sheet graphic file. Also remember that you will want to create different sized sprite sheets for your Hd and Ld folders.
Step 3: The output files from Step 2 need to be imported into your respective Images folders for each platform. Remember that Android needs to reference the files as AndroidAsset and iOS needs to reference the files as BundleResource.
Step 4: This is where you create the sprite instance and put that sprite sheet to use. The following code creates a CCSprite, loads up the sprite sheet in a CCSpriteSheet instance, then creates a forever repeating animation with all the sprites whose filename contains “walk” and adds it to the sprite as an Action.
var sprite = new CCSprite();
var spriteSheet = new CCSpriteSheet("hero.plist");
// Find all frames whose name contains "walk". walk1, walk2, walk3, etc.
var walkFrames = spriteSheet.Frames.FindAll(_ =>
// Create an animation that cycles through the walk frames.
var walkAnimation = new CCAnimation(walkFrames, 0.1f);
// Create an action that repeats the animation forever.
var walkingRepeat = new CCRepeatForever(new CCAnimate(walkAnimation));
// Add the repeating animation action to the sprite.
You can also change to a single, static image for the sprite by setting the SpriteFrame:
// First stop the previous walking animation.
// Load the single frame called "stand" and assign it to
// the sprite's SpriteFrame.
sprite.SpriteFrame = spriteSheet.Frames.Find(_ =>
Now you are free to start making characters in your game that have a little more “character” by creating frame-based animations.
In my next post, I’ll take a look at another CCNode child object that allows you to draw things.