Intro to Box2D with Cocos2D 2.X Tutorial: Bouncing Balls

Bouncing Ball Example

Update 1/9/2013: Fully updated for Cocos2D 2.1-beta4 (original post by Ray Wenderlich, update by Brian Broom).

This tutorial helps get you started with Box2D with Cocos2D by showing you how to create a simple app that shows a ball that you can bounce around the screen by rotating your iPhone with the accelerometer.

This tutorial is based on an excellent example by Kyle from iPhoneDev.net, but updated to the latest version of Cocos2D and with some more detailed explanations of how things work. It also has some elements of the sample project that is included in the cocos2d Box2d Application template, but explains how things work step-by-step.

This tutorial assumes that you’ve already gone through the tutorial on how to create a simple game with Cocos2D, or have equivalent knowledge.

So anyway, let’s get started learning Box2D with Cocos2D and start bouncing away!

Creating An Empty Project

Begin by creating a new project in XCode by selecting the cocos2d v2.x cocos2d iOS with Box2d Application template, and naming your project Box2D. If you compile and run this template, you’ll see a pretty cool example demonstrating many aspects of Box2D. However, for the purposes of this tutorial, we’re going to create everything from scratch so we can gain a good understanding of how things work.

So let’s clear out the template so we have a known-good starting point. Replace HelloWorldLayer.h with the following:

#import "cocos2d.h"

#define PTM_RATIO 32.0

@interface HelloWorldLayer : CCLayer {   
}

+ (id) scene;

@end

And replace HelloWorldLayer.mm with the following:

#import "HelloWorldLayer.h"

@implementation HelloWorldLayer

+ (id)scene {
    
    CCScene *scene = [CCScene node];
    HelloWorldLayer *layer = [HelloWorldLayer node];
    [scene addChild:layer];
    return scene;
    
}

- (id)init {
    
    if ((self=[super init])) {
    }
    return self;
}

@end

If you compile and run that, you should see a blank screen. Ok great – now let’s start creating our Box2D scene.

The Box2D World In Theory

Before we go any further, let’s talk a bit about how things work in Box2D.

The first thing you need to do when using Cocos2D is to create a world object for Box2D. The world object is the main object in Cocos2D that manages all of the objects and the physics simulation.

Once we’ve created the world object, we need to add some bodies to the world. Bodies can be objects that move around in your game like ninja stars or monsters, but they can also be static bodies that don’t move such as platforms or walls.

There are a bunch of things you need to do to create a body – create a body definition, a body object, a shape, a fixture definition, and a fixture object. Here’s what all of these crazy things mean!

• You first create a body definition to specify initial properties of the body such as position or velocity.
• Once you set that up, you can use the world object to create a body object by specifying the body definition.
• You then create a shape representing the geometry you wish to simulate.
• You then create a fixture definition – you set the shape of the fixture definition to be the shape you created, and set other properties such as density or friction.
• Finally you can use the body object to create a fixture object by specifying the fixture definition.
• Note that you can add as many fixture objects to a single body object. This can come in handy when creating complex objects.

Once you’ve added all of the bodies you like to your world, Box2D can take over and do the simulation – as long as you call its “Step” function periodically so it has processing time.

But note that Box2D only updates its internal model of where objects are – if you’d like the Cocos2D sprites to update their position to be in the same location as the physics simulation, you’ll need to periodically update the position of the sprites as well.

Ok so now that we have a basic understanding of how things should work, let’s see it in code!

The Box2D World In Practice

Ok, before you begin download a picture of a ball I made, along with the retina version, that we’re going to add to the scene. Once you have it downloaded, drag it to the Resources folder in your project and make sure that “Copy items into destination group’s folder (if needed)” is checked.

Next, take a look at this line we added earlier in HelloWorldLayer.h:

#define PTM_RATIO 32.0

This is defining a ratio of pixels to “meters”. When you specify where bodies are in Cocos2D, you give it a set of units. Although you may consider using pixels, that would be a mistake. According to the Box2D manual, Box2D has been optimized to deal with units as small as 0.1 and as big as 10. So as far as length goes people generally tend to treat it as “meters” so 0.1 would be about teacup size and 10 would be about box size.

So we don’t want to pass pixels in, because even small objects would be 60×60 pixels, way bigger than the values Box2D has been optimized for. So we need to have a way to convert pixels to “meters”, hence we can just define a ratio like the above. So if we had a 64 pixel object, we could divide it by PTM_RATIO to get 2 “meters” that Box2D can deal with for physics simulation purposes.

Ok, now for the fun stuff. Add the following to the top of HelloWorldLayer.h:

#import "Box2D.h"

Also add member variables to your HelloWorldLayer class:

b2World *_world;
b2Body *_body;
CCSprite *_ball;

Then add this to your init method in HelloWorldLayer.mm:

CGSize winSize = [CCDirector sharedDirector].winSize;

// Create sprite and add it to the layer
_ball = [CCSprite spriteWithFile:@"ball.png" rect:CGRectMake(0, 0, 52, 52)];
_ball.position = ccp(100, 300);
[self addChild:_ball];

// Create a world
b2Vec2 gravity = b2Vec2(0.0f, -8.0f);
_world = new b2World(gravity);

// Create ball body and shape
b2BodyDef ballBodyDef;
ballBodyDef.type = b2_dynamicBody;
ballBodyDef.position.Set(100/PTM_RATIO, 300/PTM_RATIO);
ballBodyDef.userData = _ball;
_body = _world->CreateBody(&ballBodyDef);

b2CircleShape circle;
circle.m_radius = 26.0/PTM_RATIO;

b2FixtureDef ballShapeDef;
ballShapeDef.shape = &circle;
ballShapeDef.density = 1.0f;
ballShapeDef.friction = 0.2f;
ballShapeDef.restitution = 0.8f;
_body->CreateFixture(&ballShapeDef);

[self schedule:@selector(tick:)];

A few lines should be familiar from the Cocos2d tutorial, but much of it is new. Let’s explain it bit by bit. I’ll repeat the code here section by section to make it easier to explain.

CGSize winSize = [CCDirector sharedDirector].winSize;

// Create sprite and add it to the layer
_ball = [CCSprite spriteWithFile:@"ball.png" rect:CGRectMake(0, 0, 52, 52)];
_ball.position = ccp(100, 300);
[self addChild:_ball];

First, we add the sprite to the scene just like we normally would using Cocos2D. If you’ve followed the previous Cocos2D tutorials there should be no surprises here.

// Create a world
b2Vec2 gravity = b2Vec2(0.0f, -8.0f);
_world = new b2World(gravity);

Next, we create the world object. When we create this object, we need to specify an initial gravity vector. We set it here to -8 along the y axis, so bodies will appear to drop to the bottom of the screen.

// Create ball body and shape
b2BodyDef ballBodyDef;
ballBodyDef.type = b2_dynamicBody;
ballBodyDef.position.Set(100/PTM_RATIO, 300/PTM_RATIO);
ballBodyDef.userData = _ball;
_body = _world->CreateBody(&ballBodyDef);

b2CircleShape circle;
circle.m_radius = 26.0/PTM_RATIO;

b2FixtureDef ballShapeDef;
ballShapeDef.shape = &circle;
ballShapeDef.density = 1.0f;
ballShapeDef.friction = 0.2f;
ballShapeDef.restitution = 0.8f;
_body->CreateFixture(&ballShapeDef);

Next, we create the ball body.

• We specify the type as a dynamic body. The default value for bodies is to be a static body, which means it does not move and will not be simulated. Obviously we want our ball to be simulated!
• We set the user data parameter to be our ball CCSprite. You can set the user data parameter on a body to be anything you like, but usually it is quite convenient to set it to the sprite so you can access it in other places (such as when two bodies collide).
• We have to define a shape – a circle shape. Remember that Box2d doesn’t look at the sprite image, we have to tell it what the shapes are so it can simulate them correctly.
• Finally we set some parameters on the fixture. We’ll cover what the parameters mean later on.

[self schedule:@selector(tick:)];

The last thing in the method is to schedule a method named tick to be called as often as possible. Note that this isn’t the ideal way to do things – it’s better if the tick method is called at a set frequency (such as 60 times a second). However, for this tutorial we’re going to stay as-is.

So let’s write the tick method! Add this after your init method:

- (void)tick:(ccTime) dt {
    
    _world->Step(dt, 10, 10);
    for(b2Body *b = _world->GetBodyList(); b; b=b->GetNext()) {    
        if (b->GetUserData() != NULL) {
            CCSprite *ballData = (CCSprite *)b->GetUserData();
            ballData.position = ccp(b->GetPosition().x * PTM_RATIO,
                                    b->GetPosition().y * PTM_RATIO);
            ballData.rotation = -1 * CC_RADIANS_TO_DEGREES(b->GetAngle());
        }        
    }
    
}

The first thing we do here is to call the “Step” function on the world so it can perform the physics simulation. The two parameters here are velocity iterations and position iterations – you should usually set these somewhere in the range of 8-10.

The next thing we do is make our sprites match the simulation. So we iterate through all of the bodies in the world looking for those with user data set. Once we find them, we know that the user data is a sprite (because we made it that way!), so we update the position and angle of the sprite to match the physics simulation.

One last thing to add – cleanup! Add this to the end of the file:

- (void)dealloc {    
    delete _world;
    _body = NULL;
    _world = NULL;
    [super dealloc];
}

Give it a compile and run, and you should see a ball drop down and off the screen. Whoops, we didn’t define a floor for the ball to bounce on.