bunnyhero dev

i’m learning cocos2d-x¹. i’m taking notes. the book cocos2d-x by example: a beginner’s guide is a big help.

cocos2d-x’s systems for handling spritesheets and animations is complex. the aforementioned book has practical tutorials, but i wanted a high-level conceptual guide to all of the pieces. here is my attempt at one, based on my exploration of the cocos2d-x source code.

the classes

i’ve conceptually separated the relevant classes into three groups: frames, rendering, and animation (these are not official groupings: they’re my own).

let’s start with frames.

frames

SpriteFrameCache is a singleton that knows how to parse spritesheet files generated by tools like zwoptex and texturepacker (among others). when SpriteFrameCache reads a spritesheet file, it creates a SpriteFrame object for every frame in the file.

each SpriteFrame object contains:

• a reference to the texture
• a source rectangle (which cocos2d-x calls a texture rectangle: it specifies what subset of the texture this SpriteFrame represents)
• and a name.²

when loading a spritesheet file, the SpriteFrameCache also loads the associated texture into memory.³

once you’ve loaded your spritesheet file, your game can query the SpriteFrameCache for any SpriteFrame, by name.

SpriteFrameCache* spriteFrameCache = SpriteFrameCache::getInstance();

//  load the spritesheet file.
spriteFrameCache->addSpriteFramesWithFile("spritesheet.plist");

//  get a SpriteFrame using a name from the spritesheet.plist file.
SpriteFrame* spriteFrame = spriteFrameCache->getSpriteFrameByName("ship.png");

rendering

a SpriteFrame is essentially a data object: it does not display or render anything on its own.

meanwhile, a Sprite is an onscreen object that renders itself using a texture and texture rectangle. sound familiar? this is the same information that a SpriteFrame provides.

you can assign a SpriteFrame to a Sprite with the method Sprite::setDisplayFrame(SpriteFrame *). this will update the Sprite’s texture and texture rectangle to that of the SpriteFrame. thus, when the Sprite draws itself, it will essentially render the SpriteFrame to the screen.⁴

//  continuing from the example above:

Sprite* sprite = Sprite::create();
sprite->setDisplayFrame(spriteFrame);
//  this sprite will now draw itself using the "ship.png" frame.

//  or you can get a SpriteFrame and create a Sprite with it in one step, like this:
Sprite* anotherSprite = Sprite::createWithSpriteFrameName("ship.png");

batch drawing with spritebatchnode

if a bunch of sprites are rendering from the same texture (probably with different texture rects), then they can be rendered much more efficiently in a batch drawing operation. to take advantage of this, you have to manually add them⁵ as children of a SpriteBatchNode, which needs to be initialized with the same texture that all of its child sprites use.

if you do not use a SpriteBatchNode, each Sprite will be drawn with a separate OpenGL drawing operation, which is much slower.

//  SpriteBatchNode must be created with the same texture that its child sprites use.
SpriteBatchNode* spriteBatchNode = SpriteBatchNode::create(sprite->getTexture());
spriteBatchNode->addChild(sprite);

animations

you can animate a Sprite’s appearance by assigning different SpriteFrames to a Sprite, over time.

if you want to string together a sequence of frames to play back in order, automatically, you’ll need the Animation and Animate classes.

an instance of the Animation class contains an array of pointers to SpriteFrames, in the order the are to be played, along with some timing information. it’s basically just a data object.

just as a SpriteFrame doesn’t do any drawing, an Animation doesn’t do any animating. to actually change a Sprite’s appearance over time, you’ll need an instance of the Animate class.

Animate is a subclass of Action. actions are objects that can manipulate the state of a Sprite over time. in this case, the Animate action reads an Animation object’s SpriteFrames, and applies each one to a Sprite, one after the other, with a delay in between.

think of an Animation object like a roll of film, which the projector (the Animate object) “projects” onto the Sprite.

here’s a simple snippet that manually builds an Animation and attaches it to a Sprite:

//  in this example, a spritesheet has already been loaded, with SpriteFrames
//  named "frame0.png", "frame1.png", "frame2.png", etc.

//  create the Animation, and populate it with frames fetched from the SpriteFrameCache

Animation *anim = Animation::create();
for (int i = 0; i < 6; i ++)
{
    std::ostringstream filenameStream;
    filenameStream << "frame" << i << ".png";
    SpriteFrame *frame = spriteFrameCache->getSpriteFrameByName(filenameStream.str().c_str());
    anim->addSpriteFrame(frame);
}
//  we can also set timing information
anim->setDelayPerUnit(0.2f);

//  we now have an Animation object that describes what frames to display,
//  and in what order.

//  next, create the Action that actually alters the Sprite.

Animate *animateAction = Animate::create(anim);

//  finally, we can execute the action.

sprite->runAction(animateAction);

what’s next

manually specifying the frames in code for every animation can get tedious. this is where cocos2d::AnimationCache comes in… but i will save that for a future instalment.