Cocos2d-X Basics

Now that you’ve had a C++ refresher, it’s time to get a grasp on the basics of Cocos2d-X.

In this chapter, we will be learning how to create a scene, load a sprite and drag it around via touch control (or mouse control in the case of Windows, Mac or Linux platforms). It’s simple stuff and I’m sure you’ll get the hang of it quickly.

SpriteDraggerX on GitHub

To follow along, please get the source code and project files for SpriteDraggerX. It's a clean, minimal Cocos2d-X iOS example project, showing how to drag a sprite around the screen.

Note that SpriteDraggerX is an iOS-only project. The point is to teach you the basics of Cocos2d-X, without overwhelming you with the details of creating multiple projects for multiple platforms. Rest assured though, we will be covering multiple platforms in a later chapter.

The SpriteDraggerX project opened in Xcode

A Basic Cocos2d-X Project

Open up the project's SpriteDragger.xcodeproj file. This project is intended to be the simplest possible Cocos2d-X code, so there are no extraneous files whatsoever.

The project includes:

• main.m: Launches the app and creates the application delegate.
• App.h/.mm: The application delegate. Sets up Cocos2d-X and passes control to SpriteDragger.
• SpriteDragger.h/.cpp: A subclass of Cocos2d-X's CCApplication object. Creates a blank CCScene and a CCLayer object as its child.
• Layer.h/.cpp: A CCLayer subclass containing a sprite and a background layer object. The Layer object handles the touch input and drags the sprite around the screen, animating a little drop effect when the sprite is finished dragging.
• Sprite.png: The sprite to be dragged.

The sprite we will be dragging around

Click Xcode's Run button and test out the project by dragging the sprite around the screen. When you drop the sprite, it animates a little scaling effect to let you know that you dropped it.

The SpriteDragger app in action... suspenseful action

The App Delegate

iOS apps generally start with an app delegate object.

A delegate is simply an object which implements a few known methods. In Objective C, they are written using protocols. In C++, they are pure virtual classes.

In the case of an iOS app delegate, the first and most important method to implement is called applicationDidFinishLaunching. It is called when (obviously) the application has finished launching. This is where your app takes control and goes about its purpose.

SpriteDraggerX's app delegate is contained in App.h and App.mm. Give these files a skim. You'll see that the app delegate sets up the window, the OpenGL view and Cocos2d-X in the setupGraphics method.

After the graphics are set up, it runs the shared CCApplication, which happens to be the SpriteDragger object contained in SpriteDragger.h/.cpp.

Scenes (CCScene)

The SpriteDragger object simply creates a blank CCScene and then adds a Layer (subclass of CCLayer) object as a child.

bool SpriteDragger::applicationDidFinishLaunching()
{
   // create a generic scene
   CCScene* scene = CCScene::create();
   
   // add the layer
   Layer* layer = new Layer;
   scene->addChild(layer, 1);
   layer->release(); // addChild() retained so we release
   
   // run the first scene
   CCDirector::sharedDirector()->runWithScene(scene);
   
   return true;
}

So what are scenes and layers?

Scenes define different modes of your game. The main menu is one scene, the actual game play is another. Cocos2d-X makes it really easy to run, swap, push, pop and transition between scenes.

Every Cocos2d-X app needs at least one scene. As we've already covered, SpriteDraggerX's scene is created in SpriteDragger.cpp.

Scenes are invisible nodes in Cocos2d-X. You can't actually see a scene, but you can see most of its children, like sprites, buttons, backgrounds, etc.

Layers (CCLayer)

Layers are another type of invisible Cocos2d-X node. You can have multiple layers in a scene, though for the most part you'll only need one layer.

Are you familiar with the concept of layers in graphic editing software such as Photoshop? CCLayer objects stack together in a similar way, like sheets of glass. The highest z order is on top.

Layers are unique in that they have the ability to accept input. You just let Cocos2d-X know that you want the layer to receive input by calling this->setTouchEnabled(true). The layer will then receive ccTouchesBegan(), ccTouchesMoved() and ccTouchesEnded() messages.

Nodes (CCNode)

Layers, as well as scenes and sprites and everything else in Cocos2d-X, derive from nodes (CCNode).

Nodes give every element in Cocos2d-X a common functionality. All nodes have a position, for example, which can be set in order to move the node. Nodes also have anchor points, cameras, z order, rotation, scaling, flipping, skewing and basic on/off visibility.

A node has one possible parent and many possible children. This organizes all Cocos2d-X elements into a hierarchy. The scene is at the top of the hierarchy, then comes the layer, then sprites, backgrounds, etc.

Since a node's position is relative to its parent, moving a parent node (such as a layer) moves all of the children nodes as well. This helps to simplify the mathematics for your game. A complex system can be thought of in smaller, more simple chunks.

You can think of nodes like the leaves, branches, and root of a tree. The root is a scene. The branches and leaves are layers and nodes.

Creating the Background & Sprite

Getting back to the Layer object created by SpriteDragger, we have the following code in the constructor:

Layer::Layer()
{
   // enable touches so we can drag
   this->setTouchEnabled(true);

   // create white background
   this->colorLayer = new CCLayerColor;
   this->colorLayer->initWithColor(ccc4(255, 255, 255, 255));
   this->addChild(this->colorLayer, 1);

   // create sprite
   CCSize iSize = CCDirector::sharedDirector()->getWinSize();
   this->sprite = new CCSprite;
   this->sprite->initWithFile("Sprite.png");
   this->sprite->setPosition(ccp(iSize.width/2.0f, iSize.height/2.0f));
   
   // nudge the anchor point upward because of the shadow
   this->sprite->setAnchorPoint(ccp(0.5f, 0.55f));
   
   // add the sprite to this layer
   this->addChild(this->sprite, 2);
}

The white background color layer is created and added with a z order of 1. This puts the background low in the z order.

The sprite (our beloved yellow sphere) is then created and positioned in the middle of the screen. It is given a z order of 2 so that it is higher than the background.

Anchor Points

The sprite is also given an anchor point which nudges the sprite upward.

You can think of an anchor point like the nail which sticks a piece of rectangular wood onto a wall. After nailing the rectangle to the wall, you can spin it around on the nail. Imagine moving the nail to a different position within the wood. You can still rotate the rectangle, but it will rotate around a different center point.

Each one of your nodes is like a piece of rectangular wood and the anchor points are the nails which stick them to the wall. In the below graphic, the green dots are the nails and the guy in the suit is the piece of wood.

Cocos2d’s SpriteTest app rotating sprites clockwise around individual anchor points