This tutorial covers the process of creating and using a spritesheet. A spritesheet is a collection of individual sprites grouped together into a single image. I created the spritesheet for this tutorial using TexturePacker. I already documented the process in this tutorial, the only difference is you set the Data Format to Cocos2D instead of Generic XML. The spritesheet and all of the sprites that went in to making it are included in the archive at the end of this tutorial.
The cocos2d.js and main.js files are relatively unchanged:
cocos2d.js:
(function () { var d = document; var c = { COCOS2D_DEBUG:2, box2d:false, showFPS:false, frameRate:60, tag:'gameCanvas', engineDir:'../cocos2d/', appFiles:['MyFifthApp.js'], mainFile:'main.js' }; window.addEventListener('DOMContentLoaded', function () { var s = d.createElement('script'); s.src = c.engineDir + 'platform/jsloader.js'; d.body.appendChild(s); s.c = c; s.id = 'cocos2d-html5'; }); })();
The only real different here is the file name passed in the appFiles array.
main.js:
var cocos2dApp = cc.Application.extend({ config:document.querySelector('#cocos2d-html5')['c'], ctor:function (scene) { this._super(); this.startScene = scene; cc.COCOS2D_DEBUG = this.config['COCOS2D_DEBUG']; cc.setup(this.config['tag']); cc.Loader.shareLoader().onloading = function () { cc.LoaderScene.shareLoaderScene().draw(); }; cc.Loader.shareLoader().onload = function () { cc.AppController.shareAppController().didFinishLaunchingWithOptions(); }; cc.Loader.shareLoader().preload([ {type:"plist",src:"spritesheet.plist"} ]); }, applicationDidFinishLaunching:function () { var director = cc.Director.getInstance(); director.setDisplayStats(this.config['showFPS']); director.setAnimationInterval(1.0 / this.config['frameRate']); director.runWithScene(new this.startScene()); return true; } }); var myApp = new cocos2dApp(MyFifthAppScene);
There are only two changes here. First we added spritesheet.plist to the preloader list. plist files are short for Property List is a configuration format used in Mac/iOS development, but at the end of the day, it’s just data in an XML format. This file was generated for us by TexturePacker and it describes the details and locations of each sprite within the spritesheet, indexed by the original file name. The other difference is we pass MyFifthAppScene to our new cocos2dApp call.
Let’s take a look at ( a portion of ) the file spritesheet.plist:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>frames</key> <dict> <key>Walk_left00.png</key> <dict> <key>frame</key> <string>{{0,0},{128,96}}</string> <key>offset</key> <string>{0,0}</string> <key>rotated</key> <false/> <key>sourceColorRect</key> <string>{{0,0},{128,96}}</string> <key>sourceSize</key> <string>{128,96}</string> </dict> <key>Walk_left01.png</key> <dict> <key>frame</key> <string>{{128,0},{128,96}}</string> <key>offset</key> <string>{0,0}</string> <key>rotated</key> <false/> <key>sourceColorRect</key> <string>{{0,0},{128,96}}</string> <key>sourceSize</key> <string>{128,96}</string> </dict> <key>spritesheet.png</key> <dict> <key>frame</key> <string>{{0,960},{512,1024}}</string> <key>offset</key> <string>{0,0}</string> <key>rotated</key> <false/> <key>sourceColorRect</key> <string>{{0,0},{512,1024}}</string> <key>sourceSize</key> <string>{512,1024}</string> </dict> </dict> <key>metadata</key> <dict> <key>format</key> <integer>2</integer> <key>realTextureFileName</key> <string>spritesheet.png</string> <key>size</key> <string>{512,2048}</string> <key>smartupdate</key> <string>$TexturePacker:SmartUpdate:873706d2c1ad9f5b33d90eefda3a7084$</string> <key>textureFileName</key> <string>spritesheet.png</string> </dict> </dict> </plist>
The details of the file aren’t important, Cocos2D does all of the heavy lifting for us. Just be aware that it describes the general layout and name of each sprite within your spritesheet. Now let’s take a look at MyFifthApp.js where the majority of our changes occurred:
var MyFifthApp = cc.LayerColor.extend({ sprite:null, spriteFrameNamePrefix:"Walk_left", spriteFrameIndex:0, init:function() { this._super(); this.initWithColor(new cc.Color4B(0,0,0,255)); var size = cc.Director.getInstance().getWinSize(); var cache = cc.SpriteFrameCache.getInstance(); cache.addSpriteFrames("spritesheet.plist", "srcSprites/spritesheet.png"); this.sprite = cc.Sprite.createWithSpriteFrameName(this.spriteFrameNamePrefix + "00.png"); this.sprite.setPosition(new cc.Point(300,300)); this.sprite.setScale(3); this.addChild(this.sprite); this.setKeyboardEnabled(true); return this; }, onKeyUp:function(e){}, onKeyDown:function(e){ if(e == cc.KEY.left || e == cc.KEY.right){ var prevPrefix = this.spriteFrameNamePrefix; if(e == cc.KEY.left) this.spriteFrameNamePrefix = "Walk_left"; else this.spriteFrameNamePrefix = "Walk_right"; if(prevPrefix !== this.spriteFrameNamePrefix) this.spriteFrameIndex = 0; if(this.spriteFrameIndex > 18) this.spriteFrameIndex = 0; var indexAsString; if(this.spriteFrameIndex < 10) indexAsString = "0" + this.spriteFrameIndex.toString(); else indexAsString = this.spriteFrameIndex.toString(); this.removeChild(this.sprite); this.sprite = cc.Sprite.createWithSpriteFrameName( this.spriteFrameNamePrefix + indexAsString + ".png" ); this.sprite.setPosition(new cc.Point(300,300)); this.sprite.setScale(3); this.addChild(this.sprite); this.spriteFrameIndex++; } } }); MyFifthAppScene = cc.Scene.extend({ onEnter:function(){ this._super(); var layer = new MyFifthApp(); layer.init(); this.addChild(layer); } });
I wont bother going in to detail on MyFifthAppScene, we’ve done that enough times already. In MyFifthApp we declare a sprite variable to point at the currently active sprite, then declare spriteFrameNamePrefix and spriteFrameIndex. We access the sprites within the sprite sheet using the keys defined in the plist ( the file name ), of which there are 18 frames for walking left and right:
Walk_left00.png –> Walk_left18.png
Walk_right00.png –> Walk_right18.png
We will be building this key dynamically as we switch between sprites.
I am only going to cover the new stuff here, the rest should be pretty familiar at this point. Cocos2D has a built in cache for Sprite frames ( in cocos2D a SpriteFrame is an individual sprite within the spritesheet, while a spritesheet is a SpriteFrames (<- note, plural ) ), the singleton SpriteFrameCache. We add a new spritesheet to it with the call addSpriteFrames, passing in the name of the plist we preloaded earlier in main.js, as well as the path to the spritesheet graphic.
Speaking of which, this is spritesheet.png that TexturePacker generated:
We then get our sprite reference from the spritesheet with a call to createWithSpriteFrameName, passing in the key of the sprite specified in the plist. In this case we are starting with Walk_left00.png. We then position the sprite at 300,300, scale it to 3x it’s size and add it to our layer. Finally we tell Cocos we want to handle keyboard events with a call to setKeyboardEnabled().
Next in the onKeyDown handler we check to see if the user has pressed ( and released ) the left or right arrow. Depending on which direction we are walking, that determines which prefix to use for accessing the sprite sheet, left or right. Next we check if the direction has changed since the last frame, if so, we start the frame index back to 0 to start the animation over.
Next we check to see if we’ve exceed our 18 frames, if we have we roll over to 0. Next we check to see if our index is a single digit ( 0..9 ), in which case we pad it with a 0, so 1 becomes 01. This is simply because that is how the source frames were named when I imported them to TexturePacker. We remove our current ( about to be replaced ) animation frame from the layer. We then put our prefix, index and “.png” together to get the key to the next frame of animation, we access with using createWithSpriteFrameName again. We position and scale the new sprite frame and add it to the scene to replace the previous frame. Finally we advance to the next frame index.
Here is our game in action. Be sure to click in the window to focus keyboard events, then use Left and Right arrows to walk:
This code wouldn’t run when I first deployed it live to my IIS server but worked fine in Apache! The XML loader in CCSAXParser.js was failing, and it turned out to be a permissions issue. When you deploy a new file extensions ( like plist ) to IIS, you need to be sure to add it as an allowed mime type!
For the record, there are actually better ways to handle animation that we will cover in a later tutorial. This tutorial does however illustrate how to load a sprite sheet and access individual sprites. You can download the entire archive here.