Intro to Box2D with Cocos2D Tutorial: Bouncing Balls ~ PakTechClub

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 Cocos2D 0.99.1-final 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-0.99.1 Box2d Application template, but explains how things work step-by-step.

This tutorial assumes that you’ve already gone through thetutorial 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-0.99.1 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 HelloWorldScene.h with the following:

#import "cocos2d.h"
 
@interface HelloWorld : CCLayer {   
}
 
+ (id) scene;
 
@end

And replace HelloWorldScene.mm with the following:

#import "HelloWorldScene.h"
 
@implementation HelloWorld
 
+ (id)scene {
 
    CCScene *scene = [CCScene node];
    HelloWorld *layer = [HelloWorld node];
    [scene addChild:layer];
    return scene;
 
}
 
- (id)init {
 
    if ((self=[super init])) {
    }
    return self;
}
 
@end

One last step – verify that all of your files in the Classes folder (such as HelloWorldScene) end with .mm instead of .m. If they end with .m, just rename them to .mm. We need to do this because Box2D uses C++ and this lets the compiler know that we’re about to start using C++ in this file.

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 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, add the following to the top of your HelloWorldScene.mm:

#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 HelloWorldScene.h:

#import "Box2D.h"

Also add member variables to your HelloWorld class:

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

Then add the following to your init method in HelloWorldScene.mm:

CGSize winSize = [CCDirector sharedDirector].winSize;
 
// Create sprite and add it to the layer
_ball = [CCSprite spriteWithFile:@"Ball.jpg" rect:CGRectMake(0, 0, 52, 52)];
_ball.position = ccp(100, 100);
[self addChild:_ball];
 
// Create a world
b2Vec2 gravity = b2Vec2(0.0f, -30.0f);
bool doSleep = true;
_world = new b2World(gravity, doSleep);
 
// Create edges around the entire screen
b2BodyDef groundBodyDef;
groundBodyDef.position.Set(0,0);
b2Body *groundBody = _world->CreateBody(&groundBodyDef);
b2PolygonShape groundBox;
b2FixtureDef boxShapeDef;
boxShapeDef.shape = &groundBox;
groundBox.SetAsEdge(b2Vec2(0,0), b2Vec2(winSize.width/PTM_RATIO, 0));
groundBody->CreateFixture(&boxShapeDef);
groundBox.SetAsEdge(b2Vec2(0,0), b2Vec2(0, winSize.height/PTM_RATIO));
groundBody->CreateFixture(&boxShapeDef);
groundBox.SetAsEdge(b2Vec2(0, winSize.height/PTM_RATIO), 
    b2Vec2(winSize.width/PTM_RATIO, winSize.height/PTM_RATIO));
groundBody->CreateFixture(&boxShapeDef);
groundBox.SetAsEdge(b2Vec2(winSize.width/PTM_RATIO, 
    winSize.height/PTM_RATIO), b2Vec2(winSize.width/PTM_RATIO, 0));
groundBody->CreateFixture(&boxShapeDef);
 
// Create ball body and shape
b2BodyDef ballBodyDef;
ballBodyDef.type = b2_dynamicBody;
ballBodyDef.position.Set(100/PTM_RATIO, 100/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:)];

Phew, that was a lot of code. 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.jpg" rect:CGRectMake(0, 0, 52, 52)];
_ball.position = ccp(100, 100);
[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, -30.0f);
bool doSleep = true;
_world = new b2World(gravity, doSleep);

Next, we create the world object. When we create this object, we need to specify an initial gravity vector. We set it here to -30 along the y axis, so bodies will appear to drop to the bottom of the screen. We also need to specify a value indicating whether or not objects should “sleep” once they are at rest. A sleeping object will not take up processing time until certain actions occur such as colliding with another object.

b2BodyDef groundBodyDef;
groundBodyDef.position.Set(0,0);
b2Body *groundBody = _world->CreateBody(&groundBodyDef);
b2PolygonShape groundBox;
b2FixtureDef boxShapeDef;
boxShapeDef.shape = &groundBox;
groundBox.SetAsEdge(b2Vec2(0,0), b2Vec2(winSize.width/PTM_RATIO, 0));
groundBody->CreateFixture(&boxShapeDef);
groundBox.SetAsEdge(b2Vec2(0,0), b2Vec2(0, winSize.height/PTM_RATIO));
groundBody->CreateFixture(&boxShapeDef);
groundBox.SetAsEdge(b2Vec2(0, winSize.height/PTM_RATIO), 
    b2Vec2(winSize.width/PTM_RATIO, winSize.height/PTM_RATIO));
groundBody->CreateFixture(&boxShapeDef);
groundBox.SetAsEdge(b2Vec2(winSize.width/PTM_RATIO, 
    winSize.height/PTM_RATIO), b2Vec2(winSize.width/PTM_RATIO, 0));
groundBody->CreateFixture(&boxShapeDef);

Next, we create invisible edges around the entire screen, that line up with the edges of our iPhone. We do this by performing the following steps:

We first create a body definition and specify that the body should be positioned in the lower left corner.
We then use the world object to create the body object.
We then create a polygon shape for each edge of the screen. These “shapes” are actually just lines. Note that we have to convert the pixels into “meters” by using our conversion ratio as we discussed above.
We create a fixture definition, specifying the polygon shape.
We then use the body object to create a fixture object for each shape.
Also note that one body object can contain multiple fixture objects!

// Create ball body and shape
b2BodyDef ballBodyDef;
ballBodyDef.type = b2_dynamicBody;
ballBodyDef.position.Set(100/PTM_RATIO, 100/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 do this by performing similar steps to how we created the ground body, but note the following differences:

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 use a different shape this time – a circle shape.
This time we want to set some parameters on the fixture, so we can’t use the shortcut method and need to specify the fixture definition. 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 bounce against the bottom of the screen a bit.

A Note On The Simulation

As promised let’s talk about those density, friction, and restitution variables that we set on the ball.

Density is mass per unit volume. So the more dense an object is, the more mass it has, and the harder it is to move.
Friction is a measure of how hard it is for objects to slide against each other. This should be in the range of 0 to 1. 0 means there is no friction, and 1 means there is a lot of friction.
Restitution is a measure of how “bouncy” an object is. This should usually be in the range of 0 to 1. 0 means the object will not bounce, and 1 means the bounce is perfectly elastic, meaning it will bounce away with the same velocity that it impacted an object.

Feel free to play around with these values and see what difference it makes. Try to see if you can make your ball more bouncy!

Finishing Touches

It would be cool if we could get the ball to bounce around the screen as we tilt our device around. For one thing that will help us test that we’ve got all the boundaries working! This is quite easy to do. Add the following to your init method:

self.isAccelerometerEnabled = YES;

Then add the following method somewhere in the file:

- (void)accelerometer:(UIAccelerometer *)accelerometer didAccelerate:(UIAcceleration *)acceleration {
 
    // Landscape left values
    b2Vec2 gravity(-acceleration.y * 15, acceleration.x *15);
    _world->SetGravity(gravity);
 
}

All we’re doing here is setting the gravity vector in the simulation to be a multiple of the acceleration vector. Give it a compile and run (on your device), and you should be able to bounce your ball all around the screen!

Where To Go From Here?

Here’s a project with the all of the above code.

If you want to learn more about Box2D, check out my tutorial series on How To Create A Breakout Game with Box2D and Cocos2D!

PakTechClub

Wednesday 22 February 2012