When you create simple Box2d objects, they will collide with each other. But what if you do not want an object colliding with all other objects? What if you want certain objects colliding with only certain other objects? How do we achieve this finer grained control?

Say that our game has three game objects: 1. Player, 2. Enemies and 3. Power Ups. Normally, all three objects would collide with each other. But what if what we really want to do is this:

1. Player and enemies can collide
2. Player and power ups can collide
3. Enemies and power ups SHOULD NOT collide

There is something called a groupIndex. Two fixtures with the same positive groupIndex will always collide. And two fixtures with negative groupIndex will never collide. But what if we want an even finer grained control than this?

Category Bits and Mask Bits

There are two properties called categoryBits and maskBits which you can set for a fixture. An integer is 16 bits, so you can have up to 16 different categories. What do I mean by this? See below for 16 possible categories (in binary and also in hex).

Category_01 = 0000 0000 0000 0001 (0×0001)
Category_02 = 0000 0000 0000 0010 (0×0002)
Category_03 = 0000 0000 0000 0100 (0×0004)
…
Category_15 = 0100 0000 0000 0000 (0×4000)
Category_16 = 1000 0000 0000 0000 (0×8000)

The categoryBits and maskBits can be used together with bitwise operators to control collision between objects.

Example

So let us put the above information to practical use. We have three game objects, so we can define three categories for our game objects.

#define CATEGORY_PLAYER    0x0001     // 0000 0000 0000 0001
#define CATEGORY_ENEMY     0x0002     // 0000 0000 0000 0010
#define CATEGORY_POWERUP   0x0004     // 0000 0000 0000 0100

When we define the fixture for our game objects, we can now set the categoryBits and the maskBits like so. The code below says that the player will collide with enemies and power ups.

b2FixtureDef playerFixture;
... 
playerFixture.filter.categoryBits = CATEGORY_PLAYER;
playerFixture.filter.maskBits = CATEGORY_ENEMY | CATEGORY_POWERUP;

The code below says that the power up only collides with the player (and not enemies)

b2FixtureDef powerupFixture;
... 
powerupFixture.filter.categoryBits = CATEGORY_POWERUP;
powerupFixture.filter.maskBits = CATEGORY_PLAYER;

And finally, the code below says that enemies only collides with the player (and not the power up)

b2FixtureDef enemyFixture;
... 
enemyFixture.filter.categoryBits = CATEGORY_ENEMY;
enemyFixture.filter.maskBits = CATEGORY_PLAYER;

Once you set the categoryBits and maskBits, Box2d uses these and the rule below to determine whether the objects collide.

uint16 catA = fixtureA.filter.categoryBits;
uint16 maskA = fixtureA.filter.maskBits;
uint16 catB = fixtureB.filter.categoryBits;
uint16 maskB = fixtureB.filter.maskBits;
 
if ((catA & maskB) != 0 && (catB & maskA) != 0) {
    // fixtures can collide
}

It is important to remember that if you want two fixtures to collide, the maskBits must include the categoryBits of the other fixture with which you want it to collide. Meaning, in the code below, the the player’s maskBits must include CATEGORY_ENEMY AND the enemy’s maskBits must also include CATEGORY_PLAYER. It is not enough to set it for just one of the fixtures. In other words, just because you set the player’s maskBits to collide with the enemy does not mean that they will collide. If A is set to collide with B, B must also be set to collide with A in order for the two to actually collide.

playerDef.categoryBits = CATEGORY_PLAYER;
playerDef.maskBits = CATEGORY_ENEMY;  // <-- point to the enemy
 
enemyDef.categoryBits = CATEGORY_ENEMY;
enemyDef.maskBits = CATEGORY_PLAYER;  // <-- point to the player

Conclusion

This should be fairly flexible enough for a great deal of your needs. If you need even more control than this, then I would suggest taking a look at Box2d’s contact listener’s PreSolve event (b2ContactListener::PreSolve).

Happy coding!

Also, I would like to share the good news that the game we have been working on has been picked up by a major publisher. We hope to release it around September, so please stay tuned! The game has been built using the very same articles and tutorials found on this blog.

What Is It?

PVRTC-I and -II are a family of lossy, fixed-rate texture compression formats used in PowerVR’s MBX and SGX technologies. PVRTC is the compressed texture format used in all generations of the iPhone, iPod Touch and iPad (source). You will see PVR and PVRTC being used interchangeably. They are not the same. They key thing to keep in mind is that a PVR is uncompressed, and PVRTC is compressed. Also, a PVR is a container which may contain various formats (a PVRTC is contained within a PVR file, for example). Some uncompressed PVR types are:

• RGBA8888: 32-bit texture with alpha channel, best image quality
• RGBA4444: 16-bit texture with alpha channel, good image quality
• RGB565: 16-bit texture without alpha channel, good image quality but no alpha (transparency)

Here are the PVRTC types, which are compressed and lossy (meaning, quality is degraded):

• PVRTC4BPP: Compressed format, 4 bits per pixel, ok image quality
• PVRTC2BPP: Compressed format, 2 bits per pixel, poor image quality

Pros and Cons

Why would you want to use a PVRTC texture? Because, it is the native texture format and is hardware accelerated. This translates to faster loading time than PNGs. Have you ever been plagued by long load times? Then PVRTC may be the answer. But even better, it will use less memory on the device and give you a performance boost.

It all sounds great! But wait, there is a downside. The downside is that because it is a lossy compression, the quality of your textures will suffer. Given a PNG of the same dimension, a PVRTC4BPP texture will take up more disk space and it will look worse (you will see artifacts, especially if you rely heavily on transparency or have a lot of gradients).

Why Size Does Matter

As you may have already guessed, the amount of space used increases as the quality increases. This means RGBA8888 uses the most amount of space (in memory AND on disk). Here is a handy formula to calculate how much space will be used.

numBytes = width * height * bitsPerPixel / 8

What this means is that given a 1024×1024 image, a RGBA8888 texture will require 4 MB of space. And a PVRTC4BPP will take 512 KB space. Why does size on disk matter at all? There is a very good reason for keeping the amount of space taken by your textures as low as possible.

This is due to the 20 MB size limit imposed by AT&T (I do not know about Verizon or other international providers). If your application is over 20 MB, users will not be able to download your application over the air from their devices. They will have to go to a computer that has iTunes installed and download it from their Mac or PC. If you are working on a game, then you have to start rationing out disk space as textures aren’t the only assets that will require disk space (the other big one being audio).

So which one should you pick? A PNG will take less space on disk, but the loading time will be longer. The amount of space a PNG will take once loaded to memory is dependent on the pixel format that you set in Cocos2d, like so:

[CCTexture2D setDefaultAlphaPixelFormat:kTexture2DPixelFormat_RGBA4444];
// Available textures 
// kCCTexture2DPixelFormat_RGBA8888 - 32-bit texture with Alpha channel
// kCCTexture2DPixelFormat_RGB565 - 16-bit texture without Alpha channel
// kCCTexture2DPixelFormat_A8 - 8-bit textures used as masks
// kCCTexture2DPixelFormat_I8 - 8-bit intensity texture
// kCCTexture2DPixelFormat_AI88 - 16-bit textures used as masks
// kCCTexture2DPixelFormat_RGBA4444 - 16-bit textures: RGBA4444
// kCCTexture2DPixelFormat_RGB5A1 - 16-bit textures: RGB5A1
// kCCTexture2DPixelFormat_PVRTC4 - 4-bit PVRTC-compressed texture: PVRTC4
// kCCTexture2DPixelFormat_PVRTC2 - 2-bit PVRTC-compressed texture: PVRTC2

Using a PVRTC will give you better performance and faster loading times, but worse quality and more disk space. Well, I guess you’ll have to pick the lesser of the two evils You can always mix PNGs and PVRTCs, so that is another option. It is definitely a balancing act.

Tools of the Trade

So, how exactly do you create a PVRTC texture from a PNG? There are a few tools available.

• TexturePacker allows you create sprite sheets with an option for saving the textures as a PVRTC.
• TextureTool is a tool in the iOS SDK that allows you to compress your textures into a PVR texture format.
• PVRTexTool is the one I use. It is a free tool which comes with both a GUI and a command line utility.

I can’t speak for TexturePacker because I haven’t used it before, but with the other two, you will have to tinker with it to have it generate the correct textures. Let me save you the frustration and give you a simple PVRTexTool command-line command that I use to convert my Zwoptex created texture atlas from a PNG to a PVR.

PVRTexTool -fOGLPVRTC4 -iMyAtlas.png -yflip0 -premultalpha -pvrtiterations8

The command above will create a PVRTC4BPP texture which will be saved as MyAtlas.pvr. If you are curious about what all the options mean, then take a look at the manual that comes with PVRTexTool, which has detailed information about them.

How to Load it Using Cocos2d

This part is pretty trivial. Here is the code to load the PVRTC texture in Cocos2d. I’m assuming that you are loading a sprite atlas.

CCTexture2D *tex = [[CCTextureCache sharedTextureCache] addImage:@"MyAtlas.pvr"];
[[CCSpriteFrameCache sharedSpriteFrameCache] addSpriteFramesWithFile:@"MyAtlas.plist" texture:tex];

I hope this has been helpful. And for those in the United States, happy 4th of July! I live near Washington D.C., but I am not courageous enough to brave the traffic to go see the fireworks I-66 will do that to you (if you live around here, you’ll know what I mean!).

What’s Covered?

I will be covering the following topics in this tutorial.

• Simple object oriented game design
• User input / touch detection
• Applying forces to game objects to make it move and jump
• Collision detection

Simple Object Oriented Game Design

The example app will be a very rudimentary platformer, with some platforms and the player represented by a circle. Again, I am creating the physics world by reading in the tile map designed in the program Tiled as described in my previous tutorial. The newest version of Tiled at the time of this writing is 0.6.0, and you must go into preferences and set gzip as the default compression or Cocos2d will fail to load the tile map file. The player will be able to move to the right (moving to the left is left to the reader as an exercise) and jump. The app has only two objects. The first is the player object and the other is the platform object. Both the player and the platform object will inherit from the general GameObject class. The general GameObject class inherits from Cocos2d’s CCSprite object and has a property called “type” which is used to distinguish between a player and a platform. Having our objects inherit from the same parent object (GameObject) will make it easier to identify objects when we handle collision detection.

Here is the code for the GameObject class. Notice that it inherits from CCSprite and that we initialize the default type to kGameObjectNone (there is an enum defined in Constants.h, which is not shown here but will be included in the sample source).

// GameObject.h
#import "cocos2d.h"
#import "Constants.h"
 
@interface GameObject : CCSprite {
    GameObjectType  type;
}
 
@property (nonatomic, readwrite) GameObjectType type;
@end
 
////////////////////////////////////////////////////////
 
// GameObject.m
@implementation GameObject
@synthesize type;
 
- (id)init
{
    self = [super init];
    if (self) {
        type = kGameObjectNone;
    }
 
    return self;
}
 
- (void)dealloc
{
    [super dealloc];
}
@end

The next one shown is the Player class. Note that the extension for the Player class is Player.mm (two m’s). Do you see the Box2d’s b2Body object that is declared? Box2d is written in C++ not Objective-C, so this is the reason we must make the Player class support both Objective-C and C++ by naming the extension with two m’s. With only one, you will see a lot of errors during compilation. You can see that the type is set to kGameObjectPlayer. You will see the “type” come into play when we discuss collision detection later.

The Player class will be in charge of creating the Box2d physics object and adding itself into the physics world when the createBox2dObject method is called. We set the custom user data (playerBodyDef.userData) to “self” so that we can access the Cocos2d object from the Box2d’s contact listener. It also has methods to make the Player move to the right and jump, which will also be discussed later in the tutorial.

// Player.h
#import "cocos2d.h"
#import "Box2D.h"
#import "GameObject.h"
 
@interface Player : GameObject {
    b2Body          *body;
}
 
-(void) createBox2dObject:(b2World*)world;
-(void) jump;
-(void) moveRight;
 
@property (nonatomic, readwrite) b2Body *body;
@end
 
///////////////////////////////////////////////////////
 
// Player.mm
#import "Player.h"
#import "Constants.h"
 
@implementation Player
@synthesize body;
 
- (id) init {
	if ((self = [super init])) {
		type = kGameObjectPlayer;
	}
	return self;
}
 
-(void) createBox2dObject:(b2World*)world {
    b2BodyDef playerBodyDef;
	playerBodyDef.type = b2_dynamicBody;
	playerBodyDef.position.Set(self.position.x/PTM_RATIO, self.position.y/PTM_RATIO);
	playerBodyDef.userData = self;
	playerBodyDef.fixedRotation = true;
 
	body = world->CreateBody(&playerBodyDef);
 
	b2CircleShape circleShape;
	circleShape.m_radius = 0.7;
	b2FixtureDef fixtureDef;
	fixtureDef.shape = &circleShape;
	fixtureDef.density = 1.0f;
	fixtureDef.friction = 1.0f;
	fixtureDef.restitution =  0.0f;
	body->CreateFixture(&fixtureDef);
}
 
-(void) moveRight {
    b2Vec2 impulse = b2Vec2(7.0f, 0.0f);
    body->ApplyLinearImpulse(impulse, body->GetWorldCenter());		
}
 
-(void) jump {
    b2Vec2 impulse = b2Vec2(4.0f, 15.0f);
    body->ApplyLinearImpulse(impulse, body->GetWorldCenter());		    
}
@end

As for the platform object, there isn’t a specific Platform object. For convenience, we simply allocate a GameObject object and specifically set the type to kGameObjectPlatform (see makeBox2dObjectAt method in GameScene way below).

User Input / Touch Detection

The following two lines inside GameScene’s init method are responsible for enabling the touch input. The swallowsTouches argument on line 3 says that whatever touches that GameScene receives is “swallowed” or ends in GameScene and is not further propagated.

1
2
3

// Inside GameScene's init method
self.isTouchEnabled = YES;
[[CCTouchDispatcher sharedDispatcher] addTargetedDelegate:self priority:0 swallowsTouches:YES];

The method below is called when the mouse is clicked in the simulator or the screen is touched on the device. We get the location of the touch, and if the touch is on the left half of the screen, we move the player to the right. If the touch is on the right half of the screen, we make the player jump. We are not using it in this tutorial, but if you need it, then there is also a complimentary method to detect when the touch has ended. Note that this code is for a single touch, not multi-touches.

// GameScene.mm
-(BOOL) ccTouchBegan:(UITouch *)touch withEvent:(UIEvent *)event {    
    CGPoint location = [touch locationInView:[touch view]];
    location = [[CCDirector sharedDirector] convertToGL:location];
    if (location.x <= screenSize.width / 2) {
        [player moveRight];        
    } else {
        [player jump];
    }
    return TRUE;
}
 
-(void) ccTouchEnded:(UITouch *)touch withEvent:(UIEvent *)event {
    CCLOG(@"Touch ended");
}

Applying Forces to Game Objects to Make it Move and Jump

To make the player move and jump, we apply a force to the player object. Recall that the Player class has the createBox2dObject method which should be called to add a physics object representing the player into the physics world. To move the player to the right, we simply tell Box2d to apply a positive ‘x’ force to the physics object that represents the player. And to make it jump, we apply a positive ‘x’ force along with a positive ‘y’ force to the physics object. In this case, we are applying an impulse force (it’s a sudden burst of force) but you are not limited to it (please see the Box2d manual for information on other kind of forces). All the rest is handled by the Box2d physics engine. Once the force has been applied, we update the player’s position in the main game loop with the new position provided to us by the physics engine (see the complete GameScene source further down, inside the update method).

-(void) moveRight {
    b2Vec2 impulse = b2Vec2(7.0f, 0.0f);
    body->ApplyLinearImpulse(impulse, body->GetWorldCenter());		
}
 
-(void) jump {
    b2Vec2 impulse = b2Vec2(4.0f, 15.0f);
    body->ApplyLinearImpulse(impulse, body->GetWorldCenter());		    
}

Collision Detection

For our simple example, only two objects exist in the world (player and platform). In order to detect when the player has made contact with the platform and when the player has lost contact with the platform, we must set up a contact listener and tell Box2d to use said contact listener. The contact listener is a C++ class which inherits from Box2d’s b2ContactListener class.

The two functions that we are most interested in are BeginContact and EndContact. As the function name suggests, BeginContact is called whenever two objects in the world make contact with each other. And EndContact is called as soon as the contact is broken. You see that a b2Contact object is passed to the functions, which can be used to get the user data. The b2Contact object has two function calls GetFixtureA() and GetFixtureB() which can be used to return the two Box2d bodies involved in the collision, and subsequently the user data (our GameObject objects) stored in them. Recall that all the objects in our app is inherited from the GameObject class, so we can safely cast the user data for both to GameObjects. Once we have the two GameObjects, we can check the “type” property of each of the objects to check whether it is the player or the platform. It is important to remember that no guarantee is made as to which object of the two objects is the player object or the platform object. It is up to us to determine their types, so both objects must be checked to see if it is one or the other.

To help keep the code cleaner and easier to read, there are two macros called IS_PLAYER(x,y) and IS_PLATFORM(x,y) which test whether either one of the the objects is a player or a platform. For this simple example, a simple message is printed to the console when the contact is made or lost. In a real game, you could, for example, play a sound effect when two objects collide. Also, please remember that although it is tempting to implement game logic that alters the physics world inside a contact callback, this is not allowed. The Box2d manual states that…

…for example, you may have a collision that applies damage and try to destroy the associated actor and its rigid body. However, Box2D does not allow you to alter the physics world inside a callback because you might destroy objects that Box2D is currently processing, leading to orphaned pointers (http://www.box2d.org/manual.html)

// ContactListener.h
#import "Box2D.h"
 
class ContactListener : public b2ContactListener {
public:
	ContactListener();
	~ContactListener();
 
	virtual void BeginContact(b2Contact *contact);
	virtual void EndContact(b2Contact *contact);
	virtual void PreSolve(b2Contact *contact, const b2Manifold *oldManifold);
	virtual void PostSolve(b2Contact *contact, const b2ContactImpulse *impulse);
};
 
/////////////////////////////
 
// ContactListener.mm
#import "ContactListener.h"
#import "Constants.h"
#import "GameObject.h"
 
#define IS_PLAYER(x, y)         (x.type == kGameObjectPlayer || y.type == kGameObjectPlayer)
#define IS_PLATFORM(x, y)       (x.type == kGameObjectPlatform || y.type == kGameObjectPlatform)
 
 
ContactListener::ContactListener() {
}
 
ContactListener::~ContactListener() {
}
 
void ContactListener::BeginContact(b2Contact *contact) {
	GameObject *o1 = (GameObject*)contact->GetFixtureA()->GetBody()->GetUserData();
	GameObject *o2 = (GameObject*)contact->GetFixtureB()->GetBody()->GetUserData();
 
	if (IS_PLATFORM(o1, o2) && IS_PLAYER(o1, o2)) {
        CCLOG(@"-----> Player made contact with platform!");
    }
}
 
void ContactListener::EndContact(b2Contact *contact) {
	GameObject *o1 = (GameObject*)contact->GetFixtureA()->GetBody()->GetUserData();
	GameObject *o2 = (GameObject*)contact->GetFixtureB()->GetBody()->GetUserData();
 
	if (IS_PLATFORM(o1, o2) && IS_PLAYER(o1, o2)) {
        CCLOG(@"-----> Player lost contact with platform!");
    }
}
 
void ContactListener::PreSolve(b2Contact *contact, const b2Manifold *oldManifold) {
}
 
void ContactListener::PostSolve(b2Contact *contact, const b2ContactImpulse *impulse) {
}

You then register the contact listener when you set up the physics world.

 contactListener = new ContactListener();
 world->SetContactListener(contactListener);

Wrap-up and Loose Ends

Below is the code for the GameScene class. If certain things look unfamiliar to you, please refer to the previous two tutorials that I mentioned in the beginning of the article. If you have read those tutorials, then things should be familiar except for the contact listener registration code and the touch detection code, which I have already explained earlier in the tutorial.

You can find the complete source code for download and the demo video at the end of the tutorial.

// GameScene.h
 
#import "cocos2d.h"
#import "Box2D.h"
#import "GLES-Render.h"
#import "ContactListener.h"
 
@class Player;
 
@interface GameScene : CCLayer
{
    CGSize screenSize;
	b2World* world;
	GLESDebugDraw *m_debugDraw;
	CCTMXTiledMap *tileMapNode;	
    Player *player;
    ContactListener *contactListener;
}
 
+(id) scene;
@end
 
///////////////////////////////////////////////
 
// GameScene.mm
#import "GameScene.h"
#import "Constants.h"
#import "Player.h"
#import "GameObject.h"
 
@interface GameScene(Private) 
-(void) setupPhysicsWorld;
@end
 
@implementation GameScene
 
+(id) scene
{
	// 'scene' is an autorelease object.
	CCScene *scene = [CCScene node];
 
	// 'layer' is an autorelease object.
	GameScene *layer = [GameScene node];
 
	// add layer as a child to scene
	[scene addChild: layer];
 
	// return the scene
	return scene;
}
 
- (void) makeBox2dObjAt:(CGPoint)p 
			   withSize:(CGPoint)size 
				dynamic:(BOOL)d 
			   rotation:(long)r 
			   friction:(long)f 
				density:(long)dens 
			restitution:(long)rest 
				  boxId:(int)boxId {
 
	// Define the dynamic body.
	//Set up a 1m squared box in the physics world
	b2BodyDef bodyDef;
//	bodyDef.angle = r;
 
	if(d)
		bodyDef.type = b2_dynamicBody;
 
	bodyDef.position.Set(p.x/PTM_RATIO, p.y/PTM_RATIO);
 
    GameObject *platform = [[GameObject alloc] init];
    [platform setType:kGameObjectPlatform];
	bodyDef.userData = platform;
 
	b2Body *body = world->CreateBody(&bodyDef);
 
	// Define another box shape for our dynamic body.
	b2PolygonShape dynamicBox;
	dynamicBox.SetAsBox(size.x/2/PTM_RATIO, size.y/2/PTM_RATIO);
 
	// Define the dynamic body fixture.
	b2FixtureDef fixtureDef;
	fixtureDef.shape = &dynamicBox;	
	fixtureDef.density = dens;
	fixtureDef.friction = f;
	fixtureDef.restitution = rest;
	body->CreateFixture(&fixtureDef);
}
 
 
 
- (void) drawCollisionTiles {
	CCTMXObjectGroup *objects = [tileMapNode objectGroupNamed:@"Collision"];
	NSMutableDictionary * objPoint;
 
	int x, y, w, h;	
	for (objPoint in [objects objects]) {
		x = [[objPoint valueForKey:@"x"] intValue];
		y = [[objPoint valueForKey:@"y"] intValue];
		w = [[objPoint valueForKey:@"width"] intValue];
		h = [[objPoint valueForKey:@"height"] intValue];	
 
		CGPoint _point=ccp(x+w/2,y+h/2);
		CGPoint _size=ccp(w,h);
 
		[self makeBox2dObjAt:_point 
					withSize:_size 
					 dynamic:false 
					rotation:0 
					friction:1.5f 
					 density:0.0f 
				 restitution:0 
					   boxId:-1];
	}
}
 
- (void) addScrollingBackgroundWithTileMap {
	tileMapNode = [CCTMXTiledMap tiledMapWithTMXFile:@"scroller.tmx"];
	tileMapNode.anchorPoint = ccp(0, 0);
	[self addChild:tileMapNode];
}
 
 
// initialize your instance here
-(id) init
{
	if( (self=[super init])) {
 
		// enable touches
		self.isTouchEnabled = YES;
 
		screenSize = [CCDirector sharedDirector].winSize;
		[[CCTouchDispatcher sharedDispatcher] addTargetedDelegate:self priority:0 swallowsTouches:YES];   
 
		[self setupPhysicsWorld];
 
		[self addScrollingBackgroundWithTileMap];
		[self drawCollisionTiles];
 
		player = [Player spriteWithFile:@"Icon-Small.png"];        
		player.position = ccp(100.0f, 180.0f);
		[player createBox2dObject:world];
 
		[self addChild:player];
 
        // Start main game loop
		[self scheduleUpdate];
	}
	return self;
}
 
-(void) setupPhysicsWorld {
    b2Vec2 gravity = b2Vec2(0.0f, -9.8f);
    bool doSleep = true;
    world = new b2World(gravity, doSleep);
 
    m_debugDraw = new GLESDebugDraw(PTM_RATIO);
    world->SetDebugDraw(m_debugDraw);
    uint32 flags = 0;
    flags += b2DebugDraw::e_shapeBit;
    m_debugDraw->SetFlags(flags);
 
    contactListener = new ContactListener();
    world->SetContactListener(contactListener);
}
 
-(void) draw {
	glDisable(GL_TEXTURE_2D);
	glDisableClientState(GL_COLOR_ARRAY);
	glDisableClientState(GL_TEXTURE_COORD_ARRAY);
 
	world->DrawDebugData();
 
	// restore default GL states
	glEnable(GL_TEXTURE_2D);
	glEnableClientState(GL_COLOR_ARRAY);
	glEnableClientState(GL_TEXTURE_COORD_ARRAY);
}
 
- (void) update:(ccTime)dt {
	//It is recommended that a fixed time step is used with Box2D for stability
	//of the simulation, however, we are using a variable time step here.
	//You need to make an informed choice, the following URL is useful
	//http://gafferongames.com/game-physics/fix-your-timestep/
 
	int32 velocityIterations = 8;
	int32 positionIterations = 1;
 
	// Instruct the world to perform a single step of simulation. It is
	// generally best to keep the time step and iterations fixed.
	world->Step(dt, velocityIterations, positionIterations);
 
 
	//Iterate over the bodies in the physics world
	for (b2Body* b = world->GetBodyList(); b; b = b->GetNext()) {
		if (b->GetUserData() != NULL) {
			//Synchronize the AtlasSprites position and rotation with the corresponding body
			CCSprite *myActor = (CCSprite*)b->GetUserData();
			myActor.position = CGPointMake( b->GetPosition().x * PTM_RATIO, 
							b->GetPosition().y * PTM_RATIO);
			myActor.rotation = -1 * CC_RADIANS_TO_DEGREES(b->GetAngle());
		}	
	}	
 
	b2Vec2 pos = [player body]->GetPosition();
	CGPoint newPos = ccp(-1 * pos.x * PTM_RATIO + 50, self.position.y * PTM_RATIO);	
	[self setPosition:newPos];
}
 
-(BOOL) ccTouchBegan:(UITouch *)touch withEvent:(UIEvent *)event {    
    CGPoint location = [touch locationInView:[touch view]];
    location = [[CCDirector sharedDirector] convertToGL:location];
    if (location.x <= screenSize.width / 2) {
        [player moveRight];        
    } else {
        [player jump];
    }
	return TRUE;
}
 
// on "dealloc" you need to release all your retained objects
- (void) dealloc {
    // in case you have something to dealloc, do it in this method
 
    delete contactListener;
    delete world;
    world = NULL;
 
    delete m_debugDraw;
 
    // don't forget to call "super dealloc"
    [super dealloc];
}
@end

Demo video of the Simple Platformer in action

Download source: SimplePlatformer.zip

Happy Saint Patrick’s Day! I wrote this tutorial while knocking back some Guinness, so I must blame alcohol if you see any glaring mistakes

In the meanwhile, here is a very simple change you can make to your game that will instantly increase your frame rate from 30 FPS to 60 FPS especially on the first generation (2G) or the second generation (3G) iPhones. Best of all, the change won’t take you more than a few seconds to make! Inside GameConfig.h, you will see GAME_AUTOROTATION defined in one of two ways:

The below uses UIViewController and Core Animation to perform the auto rotation:

#define GAME_AUTOROTATION kGameAutorotationUIViewController

Or you may see below, which will mean Cocos2d’s CCDirector will handle the auto rotation:

#define GAME_AUTOROTATION kGameAutorotationCCDirector

It is much faster if you let Cocos2d handle the auto rotation because rotation is done by a cheap call to glRotatef() function. This instantly increased my frame rate from 30 FPS to 60 FPS on the 1st generation iPhone.

If you would like more details on why this is, please take a look at the Cocos2d wiki at http://www.cocos2d-iphone.org/wiki/doku.php/prog_guide:autorotation

Video Demo

Here is the video of the demo in action. The circle is the object that the camera should be following. I placed a little Cocos2D sprite in the center just for kicks. Please excuse the choppy video.

Box2D Side Scroller from Min K on Vimeo.

Platform Generation

For this simple demo, I used the excellent and free software called Tiled Map Editor to lay out the scene. You do not have to use the program to draw your scene. You can create the Box2D objects manually. Please check the software’s web site to learn more about using the software. There really is not much to learn though, because it is very simple to use and understand. The image on the left shows that I have two layers. One layer is the tile layer and the other is actually an object layer, which I titled Collision. I simply drew two boxes in the Collision layer. For this example, the tile layer is actually empty, but you can decide to lay down some actual tile images if you want. Then in the code, I will read the location and size of these collision boxes and create a Box2D object out of them. Here is the code to achieve this.

- (void) addScrollingBackgroundWithTileMap {
	tileMapNode = [CCTMXTiledMap tiledMapWithTMXFile:@"scroller.tmx"];
	tileMapNode.anchorPoint = ccp(0, 0);
	[self addChild:tileMapNode];
}

The code above reads in the tile map with the filename “scroller.tmx” that I saved using the application. If you delve into the CCTMXTiledMap source, you will see that the tiles are actually CCSprite objects. But again, for this example, my tile layer is empty because I am only using the object layer which I labeled Collision in Tiled.

- (void) drawCollisionTiles {
	CCTMXObjectGroup *objects = [tileMapNode objectGroupNamed:@"Collision"];
	NSMutableDictionary * objPoint;
 
	int x, y, w, h;	
	for (objPoint in [objects objects]) {
		x = [[objPoint valueForKey:@"x"] intValue];
		y = [[objPoint valueForKey:@"y"] intValue];
		w = [[objPoint valueForKey:@"width"] intValue];
		h = [[objPoint valueForKey:@"height"] intValue];	
 
		CGPoint _point=ccp(x+w/2,y+h/2);
		CGPoint _size=ccp(w,h);
 
		[self makeBox2dObjAt:_point 
					withSize:_size 
					 dynamic:false 
					rotation:0 
					friction:0.0f 
					 density:0.0f 
				 restitution:0 
					   boxId:-1];
	}
}

The drawCollisionTiles method above will read the Collision boxes from the tile map and create Box2D objects out of them. It loops through the node to find all the objects and then uses the location (x, y) and the size (w, h) to create the Box2D object to be placed into the physics world and then simulated. The thing to notice here is that the friction value is set to 0.0. This will cause the circle, which I am using as the player object, to slide across the platform. Had I actually set the friction to a non-zero value (like 4.0) you would have seen the circle actually rotate and roll across the screen instead of gliding across the screen. Actually, you need to set the friction to a non-zero value for both the platforms and the player object.

- (void) makeBox2dObjAt:(CGPoint)p 
			   withSize:(CGPoint)size 
				dynamic:(BOOL)d 
			   rotation:(long)r 
			   friction:(long)f 
				density:(long)dens 
			restitution:(long)rest 
				  boxId:(int)boxId {
 
	// Define the dynamic body.
	//Set up a 1m squared box in the physics world
	b2BodyDef bodyDef;
//	bodyDef.angle = r;
 
	bodyDef.position.Set(p.x/PTM_RATIO, p.y/PTM_RATIO);
	bodyDef.userData = NULL;
	//bodyDef.userData = sprite;
 
	b2Body *body = world->CreateBody(&bodyDef);
 
	// Define another box shape for our dynamic body.
	b2PolygonShape dynamicBox;
	dynamicBox.SetAsBox(size.x/2/PTM_RATIO, size.y/2/PTM_RATIO);
 
	// Define the dynamic body fixture.
	b2FixtureDef fixtureDef;
	fixtureDef.shape = &dynamicBox;	
	fixtureDef.density = dens;
	fixtureDef.friction = f;
	fixtureDef.restitution = rest;
	body->CreateFixture(&fixtureDef);
}

The method above handles the Box2D object creation. It is standard code for creating a Box2D object. Please refer to Beginning Box2D Physics Engine if you do not understand the code above.

Let’s Continue…

Now, let’s put everything together.

-(id) init {
	if( (self=[super init])) {
		b2Vec2 gravity = b2Vec2(0.0f, -9.8f);
		bool doSleep = true;
		world = new b2World(gravity, doSleep);
 
		m_debugDraw = new GLESDebugDraw(PTM_RATIO);
		world->SetDebugDraw(m_debugDraw);
		uint32 flags = 0;
		flags += b2DebugDraw::e_shapeBit;
		m_debugDraw->SetFlags(flags);
 
 
		[self addScrollingBackgroundWithTileMap];
		[self drawCollisionTiles];
 
		CCSprite *sprite = [CCSprite spriteWithFile:@"Icon-Small.png"];
		sprite.position = ccp(100.0f, 180.0f);
 
		[self addChild:sprite];
 
		b2BodyDef playerBodyDef;
		playerBodyDef.type = b2_dynamicBody;
		playerBodyDef.position.Set(sprite.position.x/PTM_RATIO, sprite.position.y/PTM_RATIO);
		playerBodyDef.userData = sprite;
 
		playerBody = world->CreateBody(&playerBodyDef);
 
		b2CircleShape circleShape;
		circleShape.m_radius = 1.0f;
 
		b2FixtureDef fixtureDef;
		fixtureDef.shape = &circleShape;
		fixtureDef.density = 1.0f;
		fixtureDef.friction = 0.0f;
		fixtureDef.restitution =  0.0f;
		playerBody->CreateFixture(&fixtureDef);
 
		b2Vec2 impulse = b2Vec2(10, 0);
		playerBody->ApplyLinearImpulse(impulse, playerBody->GetWorldCenter());		
 
		[self scheduleUpdate];
	}
	return self;
}

First, in the code above, it creates the Box2D world and sets up the debug drawing. It then calls addScrollingBackgroundWithTileMap and drawCollisionTiles to load the tile map and then creates the Box2D objects from the Collision layer. I used the small Cocos2D logo as the sprite for the player object. Standard Box2D object creation code follows, and then an impulse force is applied to the circle to make it move to the right of the screen. Set the impulse force to a bigger value to speed up the scroll speed.

- (void) update:(ccTime)dt {
	//It is recommended that a fixed time step is used with Box2D for stability
	//of the simulation, however, we are using a variable time step here.
	//You need to make an informed choice, the following URL is useful
	//http://gafferongames.com/game-physics/fix-your-timestep/
 
	int32 velocityIterations = 8;
	int32 positionIterations = 1;
 
	// Instruct the world to perform a single step of simulation. It is
	// generally best to keep the time step and iterations fixed.
	world->Step(dt, velocityIterations, positionIterations);
 
 
	//Iterate over the bodies in the physics world
	for (b2Body* b = world->GetBodyList(); b; b = b->GetNext()) {
		if (b->GetUserData() != NULL) {
			//Synchronize the AtlasSprites position and rotation with the corresponding body
			CCSprite *myActor = (CCSprite*)b->GetUserData();
			myActor.position = CGPointMake( b->GetPosition().x * PTM_RATIO, 
					   b->GetPosition().y * PTM_RATIO);
			myActor.rotation = -1 * CC_RADIANS_TO_DEGREES(b->GetAngle());
		}	
	}	
 
	b2Vec2 pos = playerBody->GetPosition();
	CGPoint newPos = ccp(-1 * pos.x * PTM_RATIO + 50, self.position.y * PTM_RATIO);	
	[self setPosition:newPos];
}

Again, the block of code above is standard Box2D code to simulate the physics world for a slice of time, updating the sprite position and rotation to the value calculated by the Box2D physics engine. Again, remember to set the friction value to something other than 0.0 to see the circle rotate and roll across the screen instead of gliding. The code to actually scroll the background is the last three lines of the method. First, we get the location of the circle in the Box2D world. Please note that I said Box2D world. The value needs to be converted into pixels because we are setting the new position for a Cocos2D node, so they are multiplied by the constant PTM_RATIO. The “y” position is used as is, but the “x” position is updated to scroll the screen. The screen is scrolling from right to left, so it is multiplied by negative one. Then a buffer value of 50 is added to move the circle slightly to the right of the screen. If you do not add the buffer value, then the circle will be flushed all the way to the left of the screen with the left half of the circle clipped and only the right half the circle showing.

Sample Code

I hope this has been helpful to someone. And here is the sample code.

Happy coding!

Cocos2d comes with two physics engines. One is called Chipmunk and the other is called Box2d. Chipmunk sounds cuter and is written in C, whereas Box2D is written in C++. I chose to learn Box2d because it seems to be the more popular and mature of the two. Instead of trying to explain what a physics engine is, it is probably better for you to read the full definition on Wikipedia. Pretty cool! So how does Box2d physics engine work with Cocos2D? It is fairly simple. The way Box2d interacts with Cocos2d is that you update the positions of your Cocos2d objects with the positions calculated by Box2d.

Getting Started

When you create a new Cocos2d project, there is an application template called “cocos2d box2d Application”. If you select that, you will have a sample Box2D Cocos2d application that you can compile and test right away. I am going to try to deconstruct the sample Box2d application, attempting to explain the individual pieces of the code. In the sample application, you touch the screen and a box is created at the location that you touch the screen. The box falls to the ground following the law of gravity and also interacts with the ground and other boxes. Take a look at the image to your left or the video of the application in action below.

Cocos2D Box2D Sample App from Min K on Vimeo.

Definitions and Idiosyncrasies

Here are some terms that you will see being used when people talk about Box2D and physics engines. Along with the definitions are a few things you should know about Box2d before you get started. It is probably a good idea to at least skim over them. You can find most of the definitions on the Box2d web site, but I will include it here for convenience.

Shape is a 2 dimensional geometrical object, such as a circle, square or a polygon.

Rigid bodies are physics objects that are, well, rigid or stiff. They do not change shape (like being squish-able).

Dynamic bodies are objects that interact with objects in the world. They have attributes such as density, friction and restitution.

Static bodies are objects that are the opposite of dynamic bodies. Objects that are static bodies do not move. Static bodies only collide with dynamic bodies and do not collide with other static bodies.

Constraint is a physical connection that removes degrees of freedom from bodies. In 2 dimensions, a body has 3 degrees of freedom (two translation coordinates and one rotating coordinate). If we take a body and pin it to the wall (like a pendulum) we have constrained the body to the wall. At this point the body can only rotate about the pin, so the constraint has removed 2 degrees of freedom.

Fixture binds a shape to a body and adds material properties such as density, friction, and restitution (body is a parent of a fixture).

Friction determines how slippery the object is when moving over a surface.

Density or mass determines the weight of the object. The heavier it is, the harder it is to move, for example.

Restitution determines the bounciness of the object.

Joints can be used to connect together bodies.

Joint limit restricts the range of motion of a joint. For example, the human elbow allows a certain range of angles.

Joint motor drives the motion of the connected bodies according to the joint’s degrees of freedom. For example, you can use a motor to drive the rotation of an elbow.

Sleeping bodies are bodies that have come to rest and do not need to be processed by the physics engine.

World means a physics world with a collection of bodies, fixtures and constraints that interact together. Box2D supports the creation of multiple worlds, but this is usually not necessary or desirable.

Here are some things to keep in mind about Box2D.

1. Box2d does all its maths using the metric system (meters, kilograms, seconds aka MKS units).
2. Box2d uses radians for angles.
3. Box2d works best with objects that are between 0.1 and 10 meters. But it is the most optical if you keep your game objects close to 1 meter as possible.
4. You’ll notice a constant called PTM_RATIO (value is 32) in the sample. You can use it to convert pixels to meters (divide by PTM_RATIO) and meters to pixels (multiply by PTM_RATIO). You can set PTM_RATIO to any value you want, but you should pick a good value so that when divided by it, the resulting value will be no less than 0.1 meters and no more than 10 meters (and optimally close to 1 meter as possible).
5. Box2d is C++, so make sure to use C++ memory allocation and deallocations. If you are mixing Objective-C with C++ code, the file extension must be .mm (not .m).

Breakdown of the Code

You can find the complete code further down the screen. Here, I’m going to explain the code in pieces so that it is more readable and manageable.

@interface HelloWorld : CCLayer {
	b2World* world;
	GLESDebugDraw *m_debugDraw;
}

The block of code above should be in the header. We declare a b2World pointer and a GLESDebugDraw pointer. The b2World pointer is the physics world that will hold all the physics objects. GLESDebugDraw allows any Box2D bodies to be shown (i.e. outlined), instead of using a sprite. It is a useful verification and debugging tool. When you are ready for production, you want to get rid of DebugDraw and use your real art work.

// Define the gravity vector.
b2Vec2 gravity;
gravity.Set(0.0f, -10.0f);
 
// Do we want to let bodies sleep?
// This will speed up the physics simulation
bool doSleep = true;
 
// Construct a world object, which will hold and simulate the rigid bodies.
world = new b2World(gravity, doSleep);
 
world->SetContinuousPhysics(true);

You will see the block of code above inside the init method. First, you define the gravity vector to point downward at -10.0. Recall that gravity is 9.8 meters per second squared, so we just use -10.0 to approximate gravity (negative because it is going down in the Y direction). Then, the Box2d world is created with the doSleep boolean variable is set to true, which means that bodies in the world are allowed to sleep when they come to rest. A sleeping body does not require simulation and thus does not require processing. This translates into better performance.

The Box2D manual states that SetContinuousPhysics(true) is more for testing purposes and is used for fast moving objects and continuous collision detection (CCD). The Box2D’s manual states the following regarding CCD.

By default, Box2D uses continuous collision detection (CCD) to prevent dynamic bodies from tunneling through static bodies. This is done by sweeping shapes from their old position to their new positions. The engine looks for new collisions during the sweep and computes the time of impact (TOI) for these collisions. Bodies are moved to their first TOI and then halted for the remainder of the time step.

Normally CCD is not used between dynamic bodies. This is done to keep performance reasonable. In some game scenarios you need dynamic bodies to use CCD. For example, you may want to shoot a high speed bullet at a stack of dynamic bricks. Without CCD, the bullet might tunnel through the bricks.

uint32 flags = 0;
flags += b2DebugDraw::e_shapeBit;
m_debugDraw->SetFlags(flags);				
 
// Define the ground body.
b2BodyDef groundBodyDef;
// Explicitly added here for clarity by me.
groundBodyDef.type = b2_staticBody;
groundBodyDef.position.Set(0, 0); // bottom-left corner
 
// Call the body factory which allocates memory for the ground body
// from a pool and creates the ground box shape (also from a pool).
// The body is also added to the world.
b2Body* groundBody = world->CreateBody(&groundBodyDef);

Next, you set up the the GLESDebugDraw. You are interested in drawing shapes, so you set the bit to the e_shapeBit (some of the other available bits are e_jointBit, e_aabbBit, e_pairBit and e_centerOfMassBit — please check the reference for detailed information on them). You then define the body object for the ground and set the position. Remember that (0, 0) is the lower-left corner in Cocos2d and Box2D. You then call the factory method to create the body by calling the CreateBody function, passing in the reference to the b2BodyDef so that it can fill in the values. The ground is a static body (as opposed to a dynamic body). Remember, a static body do not collide with each other and are immovable. A body is static when it has zero mass. Bodies have zero mass by default, so it is static by default. The line “groundBodyDef.type = b2_staticBody;” is not in the code when you create the sample Box2D application from the template, but I explicitly added it here for clarity. After creating the body, you must create the fixture, which is done with the code below.

// Define the ground box shape.
b2PolygonShape groundBox;		
 
// bottom
groundBox.SetAsEdge(b2Vec2(0,0), b2Vec2(screenSize.width/PTM_RATIO,0));
groundBody->CreateFixture(&groundBox,0);
 
// top
groundBox.SetAsEdge(b2Vec2(0,screenSize.height/PTM_RATIO), 
                 b2Vec2(screenSize.width/PTM_RATIO,screenSize.height/PTM_RATIO));
groundBody->CreateFixture(&groundBox,0);
 
// left
groundBox.SetAsEdge(b2Vec2(0,screenSize.height/PTM_RATIO), b2Vec2(0,0));
groundBody->CreateFixture(&groundBox,0);
 
// right
groundBox.SetAsEdge(b2Vec2(screenSize.width/PTM_RATIO,screenSize.height/PTM_RATIO), 
                   b2Vec2(screenSize.width/PTM_RATIO,0));
groundBody->CreateFixture(&groundBox,0);

The code above creates the fixtures to attach to the body. Recall that a fixture must be a child to a body and that the width and height are divided by PTM_RATIO to convert pixels to meters. We create a fixture for each side of the box (top, bottom, left and right) and attach it to the body. The second parameter to CreateFixture denotes the density (which is 0). Here, you passed the shape to the CreateFixture function, but there is another way to create a fixture. There is an overloaded CreateFixture function that takes a b2FixtureDef instead.

// Note: Not part of the sample code -- just here for illustration
b2FixtureDef groundFixtureDef;
groundFixtureDef.type = b2_staticBody;
groundFixtureDef.position.Set(0, 0);
 
// Then you pass the reference to groundFixtureDef to CreateFixture instead.
// bottom
groundBox.SetAsEdge(b2Vec2(0,0), b2Vec2(screenSize.width/PTM_RATIO,0));
groundBox.CreateFixture(&groundFixtureDef);
...
// do similar for top, left and right

The rest of the code in init is normal Cocos2D code — it adds a sprite image, adds a label and then schedules a timer to call the method called tick. Now, for the rest of the code.

-(void) draw {
   glDisable(GL_TEXTURE_2D);
   glDisableClientState(GL_COLOR_ARRAY);
   glDisableClientState(GL_TEXTURE_COORD_ARRAY);
 
   world->DrawDebugData();
 
   // restore default GL states
   glEnable(GL_TEXTURE_2D);
   glEnableClientState(GL_COLOR_ARRAY);
   glEnableClientState(GL_TEXTURE_COORD_ARRAY);
}

The draw method is where OpenGL calls take place. This is where you call the DrawDebugData() function (for GLESDebugDraw). OpenGL is a state based, so you need to disable certain states before DrawDebugData() is called and re-enable them after. You don’t have to know the details. This is the code provided by the template, so it is enough to copy/paste the code above and simply remember to disable and enable them as done above.

- (void)ccTouchesEnded:(NSSet *)touches withEvent:(UIEvent *)event {
   //Add a new body/atlas sprite at the touched location
   for( UITouch *touch in touches ) {
      CGPoint location = [touch locationInView: [touch view]];
      location = [[CCDirector sharedDirector] convertToGL: location];
      [self addNewSpriteWithCoords: location];
   }
}

The method above is triggered when the screen is touched. When the screen is touched, it calls the addNewSpriteWithCoords method, passing in the location of the screen that was touched. The addNewSpriteWithCoords method creates a box at that location. The box that is created with be simulated by the Box2D physics engine (meaning, it will fall at 10.0 (or 9.8) meters or second squared.

-(void) addNewSpriteWithCoords:(CGPoint)p {
   CCLOG(@"Add sprite %0.2f x %02.f",p.x,p.y);
   CCSpriteBatchNode *batch = (CCSpriteBatchNode*) [self getChildByTag:kTagBatchNode];
 
   //We have a 64x64 sprite sheet with 4 different 32x32 images.  The following code is
   //just randomly picking one of the images
   int idx = (CCRANDOM_0_1() > .5 ? 0:1);
   int idy = (CCRANDOM_0_1() > .5 ? 0:1);
   CCSprite *sprite = [CCSprite spriteWithBatchNode:batch 
                                rect:CGRectMake(32 * idx,32 * idy,32,32)];
   [batch addChild:sprite];
 
   sprite.position = ccp( p.x, p.y);
 
   // Define the dynamic body.
   //Set up a 1m squared box in the physics world
   b2BodyDef bodyDef;
   bodyDef.type = b2_dynamicBody;
 
   bodyDef.position.Set(p.x/PTM_RATIO, p.y/PTM_RATIO);
   bodyDef.userData = sprite;
   b2Body *body = world->CreateBody(&bodyDef);
 
   // Define another box shape for our dynamic body.
   b2PolygonShape dynamicBox;
   dynamicBox.SetAsBox(.5f, .5f);//These are mid points for our 1m box
 
   // Define the dynamic body fixture.
   b2FixtureDef fixtureDef;
   fixtureDef.shape = &dynamicBox;	
   fixtureDef.density = 1.0f;
   fixtureDef.friction = 0.3f;
   body->CreateFixture(&fixtureDef);
}

As mentioned, the method above is called when the screen is touched. First, the Cocos2D sprite is created at the location of the touch. Then, a Box2D body is created in order to simulate the physics for that object. It is defined as a dynamic body (b2_dynamicBody). We let Box2D know the position (in meters) and then create the body. A fixture is created with a shape, density and friction and attached to the body. The userData object is a void pointer that can point to any user defined object. Here we set it to the Cocos2d Sprite object for use later. Note that, here, we use the alternative way to create the fixture from b2FixtureDef as explained earlier.

-(void) tick: (ccTime) dt {
   //It is recommended that a fixed time step is used with Box2D for stability
   //of the simulation, however, we are using a variable time step here.
   //You need to make an informed choice, the following URL is useful
   //http://gafferongames.com/game-physics/fix-your-timestep/
 
   int32 velocityIterations = 8;
   int32 positionIterations = 1;
 
   // Instruct the world to perform a single step of simulation. It is
   // generally best to keep the time step and iterations fixed.
   world->Step(dt, velocityIterations, positionIterations);
 
 
   //Iterate over the bodies in the physics world
   for (b2Body* b = world->GetBodyList(); b; b = b->GetNext()) {
      if (b->GetUserData() != NULL) {
         //Synchronize the AtlasSprites position and rotation with the corresponding body
	 CCSprite *myActor = (CCSprite*)b->GetUserData();
	 myActor.position = CGPointMake( b->GetPosition().x * PTM_RATIO, 
                                    b->GetPosition().y * PTM_RATIO);
	 myActor.rotation = -1 * CC_RADIANS_TO_DEGREES(b->GetAngle());
      }	
   }
}

The tick method above is the method that was scheduled in the init method. You will notice the world->Step() call. As noted in the comment, the Step() function is used to perform a single step of the simulation. You pass in the values for velocity iterations and position iterations as the parameters. These values are used by the physics engine to simulate the physics equations. The higher these numbers are, the better (more accurate) the simulations are, but the tradeoff is performance. So play around with these values to find the right value for your needs. We loop through the list of bodies in the physics world and then update the position and rotation of the sprites (which was stored in userData pointer) with the value that is calculated by Box2D.

- (void)accelerometer:(UIAccelerometer*)accelerometer 
         didAccelerate:(UIAcceleration*)acceleration {	
 
   static float prevX=0, prevY=0;
 
   //#define kFilterFactor 0.05f
   #define kFilterFactor 1.0f	// don't use filter. the code is here just as an example
 
   float accelX = (float) acceleration.x * kFilterFactor + (1- kFilterFactor)*prevX;
   float accelY = (float) acceleration.y * kFilterFactor + (1- kFilterFactor)*prevY;
 
   prevX = accelX;
   prevY = accelY;
 
   // accelerometer values are in "Portrait" mode. Change them to Landscape left
   // multiply the gravity by 10
   b2Vec2 gravity( -accelY * 10, accelX * 10);
 
   world->SetGravity( gravity );
}

Finally, the last block of code merely transforms the accelerometer readings into a Box2D gravity vector. Notice that X and Y values are switched due to the device being in landscape mode. As you tilt your phone, you will see the boxes shifting in the tilt direction.

The End

This was a simple exercise, but hopefully it was helpful in getting your head wrapped around the fundamentals. The key ideas to take away from this lesson are that 1. Box2D (physics engine) calculates the positions of the objects and you update the game objects with the values provided by Box2D, 2. physics objects are rigid bodies that can be either static or dynamic and 3. a body can be bound to one or more fixture(s) that define material properties such as the shape, density, friction and restitution.

In a future post, I am going to try doing something a bit more exciting than the sample application. So please stay tuned!

The Complete Code

#import "cocos2d.h"
#import "Box2D.h"
#import "GLES-Render.h"
 
// HelloWorld Layer
@interface HelloWorld : CCLayer
{
	b2World* world;
	GLESDebugDraw *m_debugDraw;
}
// returns a Scene that contains the HelloWorld as the only child
+(id) scene;
 
// adds a new sprite at a given coordinate
-(void) addNewSpriteWithCoords:(CGPoint)p;
@end

#import "HelloWorldScene.h"
 
//Pixel to metres ratio. Box2D uses metres as the unit for measurement.
//This ratio defines how many pixels correspond to 1 Box2D "metre"
//Box2D is optimized for objects of 1x1 metre therefore it makes sense
//to define the ratio so that your most common object type is 1x1 metre.
#define PTM_RATIO 32
 
// enums that will be used as tags
enum {
	kTagTileMap = 1,
	kTagBatchNode = 1,
	kTagAnimation1 = 1,
};
 
@implementation HelloWorld
 
+(id) scene {
	// 'scene' is an autorelease object.
	CCScene *scene = [CCScene node];
	HelloWorld *layer = [HelloWorld node];
	[scene addChild: layer];
	return scene;
}
 
-(id) init {
    if( (self=[super init])) {
        // enable touches
	self.isTouchEnabled = YES;
 
	// enable accelerometer
	self.isAccelerometerEnabled = YES;
 
	CGSize screenSize = [CCDirector sharedDirector].winSize;
	CCLOG(@"Screen width %0.2f screen height %0.2f",screenSize.width,screenSize.height);
 
	// Define the gravity vector.
	b2Vec2 gravity;
	gravity.Set(0.0f, -10.0f);
 
	// Do we want to let bodies sleep?
	// This will speed up the physics simulation
	bool doSleep = true;
 
	// Construct a world object, which will hold and simulate the rigid bodies.
	world = new b2World(gravity, doSleep);
 
	world->SetContinuousPhysics(true);
 
	// Debug Draw functions
	m_debugDraw = new GLESDebugDraw( PTM_RATIO );
	world->SetDebugDraw(m_debugDraw);
 
	uint32 flags = 0;
	flags += b2DebugDraw::e_shapeBit;
	m_debugDraw->SetFlags(flags);		
 
 
	// Define the ground body.
	b2BodyDef groundBodyDef;
	groundBodyDef.position.Set(0, 0); // bottom-left corner
 
	// Call the body factory which allocates memory for the ground body
	// from a pool and creates the ground box shape (also from a pool).
	// The body is also added to the world.
	b2Body* groundBody = world->CreateBody(&groundBodyDef);
 
	// Define the ground box shape.
	b2PolygonShape groundBox;		
 
	// bottom
	groundBox.SetAsEdge(b2Vec2(0,0), b2Vec2(screenSize.width/PTM_RATIO,0));
	groundBody->CreateFixture(&groundBox,0);
 
	// top
	groundBox.SetAsEdge(b2Vec2(0,screenSize.height/PTM_RATIO), 
                       b2Vec2(screenSize.width/PTM_RATIO,screenSize.height/PTM_RATIO));
	groundBody->CreateFixture(&groundBox,0);
 
	// left
	groundBox.SetAsEdge(b2Vec2(0,screenSize.height/PTM_RATIO), b2Vec2(0,0));
	groundBody->CreateFixture(&groundBox,0);
 
	// right
	groundBox.SetAsEdge(b2Vec2(screenSize.width/PTM_RATIO,screenSize.height/PTM_RATIO), 
                          b2Vec2(screenSize.width/PTM_RATIO,0));
	groundBody->CreateFixture(&groundBox,0);
 
 
	//Set up sprite
	CCSpriteBatchNode *batch = [CCSpriteBatchNode batchNodeWithFile:@"blocks.png" 
                                          capacity:150];
	[self addChild:batch z:0 tag:kTagBatchNode];
 
	[self addNewSpriteWithCoords:ccp(screenSize.width/2, screenSize.height/2)];
 
	CCLabelTTF *label = [CCLabelTTF labelWithString:@"Tap screen" 
                                          fontName:@"Marker Felt" fontSize:32];
	[self addChild:label z:0];
	[label setColor:ccc3(0,0,255)];
	label.position = ccp( screenSize.width/2, screenSize.height-50);
 
	[self schedule: @selector(tick:)];
    }
    return self;
}
 
-(void) draw {
   glDisable(GL_TEXTURE_2D);
   glDisableClientState(GL_COLOR_ARRAY);
   glDisableClientState(GL_TEXTURE_COORD_ARRAY);
 
   world->DrawDebugData();
 
   // restore default GL states
   glEnable(GL_TEXTURE_2D);
   glEnableClientState(GL_COLOR_ARRAY);
   glEnableClientState(GL_TEXTURE_COORD_ARRAY);
}
 
-(void) addNewSpriteWithCoords:(CGPoint)p {
   CCLOG(@"Add sprite %0.2f x %02.f",p.x,p.y);
   CCSpriteBatchNode *batch = (CCSpriteBatchNode*) [self getChildByTag:kTagBatchNode];
 
   //We have a 64x64 sprite sheet with 4 different 32x32 images.  The following code is
   //just randomly picking one of the images
   int idx = (CCRANDOM_0_1() > .5 ? 0:1);
   int idy = (CCRANDOM_0_1() > .5 ? 0:1);
   CCSprite *sprite = [CCSprite spriteWithBatchNode:batch 
                                rect:CGRectMake(32 * idx,32 * idy,32,32)];
   [batch addChild:sprite];
 
   sprite.position = ccp( p.x, p.y);
 
   // Define the dynamic body.
   //Set up a 1m squared box in the physics world
   b2BodyDef bodyDef;
   bodyDef.type = b2_dynamicBody;
 
   bodyDef.position.Set(p.x/PTM_RATIO, p.y/PTM_RATIO);
   bodyDef.userData = sprite;
   b2Body *body = world->CreateBody(&bodyDef);
 
   // Define another box shape for our dynamic body.
   b2PolygonShape dynamicBox;
   dynamicBox.SetAsBox(.5f, .5f);//These are mid points for our 1m box
 
   // Define the dynamic body fixture.
   b2FixtureDef fixtureDef;
   fixtureDef.shape = &dynamicBox;	
   fixtureDef.density = 1.0f;
   fixtureDef.friction = 0.3f;
   body->CreateFixture(&fixtureDef);
}
 
 
 
-(void) tick: (ccTime) dt {
   //It is recommended that a fixed time step is used with Box2D for stability
   //of the simulation, however, we are using a variable time step here.
   //You need to make an informed choice, the following URL is useful
   //http://gafferongames.com/game-physics/fix-your-timestep/
 
   int32 velocityIterations = 8;
   int32 positionIterations = 1;
 
   // Instruct the world to perform a single step of simulation. It is
   // generally best to keep the time step and iterations fixed.
   world->Step(dt, velocityIterations, positionIterations);
 
 
   //Iterate over the bodies in the physics world
   for (b2Body* b = world->GetBodyList(); b; b = b->GetNext()) {
      if (b->GetUserData() != NULL) {
         //Synchronize the AtlasSprites position and rotation with the corresponding body
	 CCSprite *myActor = (CCSprite*)b->GetUserData();
	 myActor.position = CGPointMake( b->GetPosition().x * PTM_RATIO, 
                                    b->GetPosition().y * PTM_RATIO);
	 myActor.rotation = -1 * CC_RADIANS_TO_DEGREES(b->GetAngle());
      }	
   }
}
 
- (void)ccTouchesEnded:(NSSet *)touches withEvent:(UIEvent *)event {
   //Add a new body/atlas sprite at the touched location
   for( UITouch *touch in touches ) {
      CGPoint location = [touch locationInView: [touch view]];
      location = [[CCDirector sharedDirector] convertToGL: location];
      [self addNewSpriteWithCoords: location];
   }
}
 
- (void)accelerometer:(UIAccelerometer*)accelerometer 
         didAccelerate:(UIAcceleration*)acceleration {	
 
   static float prevX=0, prevY=0;
 
   //#define kFilterFactor 0.05f
   #define kFilterFactor 1.0f	// don't use filter. the code is here just as an example
 
   float accelX = (float) acceleration.x * kFilterFactor + (1- kFilterFactor)*prevX;
   float accelY = (float) acceleration.y * kFilterFactor + (1- kFilterFactor)*prevY;
 
   prevX = accelX;
   prevY = accelY;
 
   // accelerometer values are in "Portrait" mode. Change them to Landscape left
   // multiply the gravity by 10
   b2Vec2 gravity( -accelY * 10, accelX * 10);
 
   world->SetGravity( gravity );
}
 
- (void) dealloc {
   // in case you have something to dealloc, do it in this method
   delete world;
   world = NULL;
 
   delete m_debugDraw;
 
   // don't forget to call "super dealloc"
   [super dealloc];
}
@end

I recently discovered a program that enables non-programmers to author iPhone games using a drag and drop interface, without nary a worry about programming. It will make about 60-70% of the easy stuff very easy to do, but the remaining 30-40% is probably painful to achieve without a lot of workarounds — workarounds that would have been unnecessary if you had programmed it instead. I will say that it is probably great for the simple stuff and for rapid prototyping.

On the other end spectrum are those who are a glutton for pain and insist on doing everything from scratch. If you are making a game on the iPhone, this usually means delving into the mysteries of OpenGL ES. My salute to those brave souls who travel the path less traveled by, but for mere mortals such as myself, I would opt for the middle-way and use a robust and mature library like Cocos2d.

Cocos2d is a wonderful 2d game library. The blood of OpenGL ES is flowing rigorously underneath the hood so you get the performance benefits of OpenGL ES while being shielded from having to touch it directly. To date, there are thousands of games made with Cocos2d, including many of the top free and paid games on the Apple App store.

It can be a daunting task to learn anything related to game programming if you have never attempted it before. It is as much a science as it is an art. And with an open source library such as Cocos2d, it is that much more important for a mentor to hold your hand and show you the way to the path of enlightenment. Notice I said to the “path” of enlightenment and not to enlightenment itself. That task belongs to only you! There are not too many books on the subject in the market, and the book Cocos2d for iPhone 0.99 Beginner’s Guide is a welcome addition to any aspiring iPhone game programmer’s library.

As the title of the book suggests, the author assumes that the reader is a beginning game developer (not necessarily a beginning iPhone developer). The book will take you through building 3 complete iPhone games, each of which is of a different genre. The first game is a puzzle, the second a vertical shooter, and the third is a physics based game using the Chipmunk physics engine. Readers will be able to take away useful information from each of these games, as different genre of games will require a different mentality and programming skill set. The author also lists some links to games that come with complete source code, which I found very useful as well.

It will give you a fairly complete overview of the Cocos2d engine. The chapters are organized in a logical manner, and each chapter builds on the previous chapters. I particularly liked the chapter about the particle system in Cocos2d. Readers will also appreciate the fact that the author introduces the tools that are commonly used by Cocos2d programmers. These tools will prove to be an invaluable time saver, and you will immediately recognize the benefits of using them.

The book is written in a fairly clear manner and does a good job of explaining the code. For example, just when you start to feel lost, you will be happy to run across sections titled “What Just Happened?” that will explain the code for you in plain English.

It did, however, seem slightly rushed. I also did not particularly care for the formatting of the source code in the book and wished more care was taken with them. It must be noted that I reviewed the PDF version of the book, so I cannot speak for the printed version. These imperfections only slightly mar the usefulness of the book. And those just starting out with Cocos2d will certainly learn a great deal from the book, which is the target demographic of the book (as it is obvious and evident from the title of the book).

Make captivating games for the iPhone using Packt’s new book on Cocos2d

Packt is pleased to announce Cocos2d for iPhone 0.99 Beginner’s Guide, a new book which helps in building fun and exciting iPhone games using the cocos2d for iPhone framework. Written by Pablo Ruiz, this book will help programmers make their first iPhone game in no time.

Cocos2d for iPhone is a robust but simple-to-use game framework for building 2D games, demos, and other graphical/interactive applications for the iPhone. Its API comes integrated with Box2D and Chipmunk physics engines. Being an open source platform, it is compatible both with closed and open source games. Over 1500 AppStore games have been built with cocos2d for iPhone.

Cocos2d for iPhone 0.99 Beginner’s Guide explains in detail, all the key concepts of the iPhone framework and game programming required for readers to build their very first iPhone game. Readers will learn to add animations, sounds, and particle effects to their games which will help enhance their games with a lot of cool features and eye candy while making the game behave realistically using a physics engine.

This book is filled with illustrations, diagrams, and tips for building iPhone games, with clear step-by-step instructions and practical examples. It covers basic features such as sprites, actions, menu design creation and also helps readers utilize Cocos2d for pasting labels, integrating it with Social Networks and surfing through scenes, layers and transitions.

Seasoned and beginner programmers with a desire to enter the iPhone industry, who possess some basic programming experience with Objective-C and a good understanding of OOP, will find this book to be an interesting and beneficial read. The book is out now and available from Packt. For more information please visit: -
www.packtpub.com/cocos2d-games-for-iphone-0-99-beginners-guide/book

Tip 1: Do not use UIImage imageNamed: method

UIImage’s imageNamed method caches the image. This is a handy feature that can beneficial, but depending on your needs, it may be better for you to manage the cache yourself. For example, if you are loading huge images that do not get used often, then it would be better for you to release the image after each use. I would suggest extending UIImage with a new method that does not cache the image like this:

The header file:

#import <Foundation/Foundation.h>
@interface UIImage (DoNotCache)
+ (UIImage *)newImageNotCached:(NSString *)filename;
@end

The implementation file:

@implementation UIImage (DoNotCache)
+ (UIImage *)newImageNotCached:(NSString *)filename {
    NSString *imageFile = [[NSString alloc] initWithFormat:@"%@/%@", [[NSBundle mainBundle] resourcePath], filename];
    UIImage *image = [[UIImage alloc] initWithContentsOfFile:imageFile];
    [imageFile release];
    return image;
}
@end

This way, you have complete control over the memory used by your images. You can then cache these images into a NSMutableArray and then release them when you no longer need them.

Tip 2: Break out your views into separate XIB / NIB files

If your view can be separated into multiple views, then create a separate UIViewController for each of them. This way, you can unload the views when not needed, instead of it consuming valuable memory even when they’re not visible. So always think about how your view can be separated into multiple views that can be loaded lazily.

Tip 3: Manually trigger didReceiveMemoryWarning

You can manually trigger didReceiveMemoryWarning from the simulator so make sure to test it in the simulator! The option is under Hardware / Simulate Memory Warning.

Tip 4: Use a local NSAutoRelease Pool

If you are autoreleasing lot of objects, you may run into situations where your objects may not be released until your program terminates. If so, think about using a local autorelease pool. Autorelease pools are staked, so if you create a new autorelease pool, it gets inserted into the top of the stack.

NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
NSString *string = [[[NSString alloc] init] autorelease];
[pool drain];

Tip 5: Be mindful of container classes retaining and releasing objects

Pay attention to whether the library class you are using is retaining or releasing your objects. For example, when you add an object into a NSMutableArray, it is automatically retained. So you want to send the object that you are adding a release message to avoid memory leaks.

NSMutableArray *array = [[NSMutableArray alloc] init];
 
// obj has retain count of +1
MyObject *obj = [[MyObject alloc] init];
 
// obj has retain count of +2, so make sure to release it
[array addObject:array];     
 
// obj has retain count of +1
[obj release];

This also means when you remove an object from the array, it will automatically be released. If you are not sure whether the method you are calling is retaining or releasing, then make sure to look up the documentation for that peace of mind.

Also check out my original entry titled Handling didReceiveMemoryWarning.

So let’s use CCAnimationCache!

So let’s say that you have a class derived from CCSprite for each game object, and that you load the animations for the game object during initialization by calling CCSprite addAnimation. Now you’ll have to change it to use CCAnimationCache instead. It’s pretty simple. Note that I only load the animation into the cache once by checking a boolean variable to see if it has already been loaded. I do this because there can be many instances of the game object on the screen at once (imagine bullets), and the application would crash if you tried to load the same animation twice. You could initialize the animation outside of your game object, but if you wanted to initialize it when your game object is instantiated, just remember to load it once as it is done here.

@implementation SomeGameObject 
static BOOL animationLoaded = NO;
 
// Some other code...
 
- (void) initializeAnimations {
    if (NO == animationLoaded) {
        animationLoaded = YES;
        CCAnimation *anim1 = [CCAnimation animationWithFrames:some_array1];
        [[CCAnimationCache sharedAnimationCache] addAnimation:anim1 name:@"anim1"];
 
        CCAnimation *anim2 = [CCAnimation animationWithFrames:some_array2];
        [[CCAnimationCache sharedAnimationCache] addAnimation:anim2 name:@"anim2"];
 
        CCAnimation *anim3 = [CCAnimation animationWithFrames:some_array3];
        [[CCAnimationCache sharedAnimationCache] addAnimation:anim3 name:@"anim1"];   
    }
}
@end

Then when you are ready to use the animation, it’s simple to retrieve them by name like so:

CCAnimation *anim1 = [[CCAnimationCache sharedAnimationCache] animationByName:@"anim1"];
CCAnimation *anim2 = [[CCAnimationCache sharedAnimationCache] animationByName:@"anim2"];
CCAnimation *anim3 = [[CCAnimationCache sharedAnimationCache] animationByName:@"anim3"];

Hope this simple tip was helpful to someone. Happy coding!