How to use physics with cocos2d-x

2017-04-20 Andreas Löw Get Sourcecode from GitHub

What you are going to learn from this tutorial

In this tutorial you are going to learn:

  • How physics enabled games work in cocos2d-x
  • How to create physics collision shapes for cocos2d-x
  • How to load the shapes in your game
  • How to set up a simple scene with dropping objects

I assume that you already have basic knowledge about cocos2d-x. If not please check out our tutorial Using sprite sheet animations in cocos2d-x — it explains the basics setting up a simple game scene.

The complete source code for this tutorial is available on github.

This screenshot shows you what the demo project from the tutorial looks like:

There's a bunch of differnt objects that you can drop on the scene by tapping / clicking in the game scene.

The objects fall down and nicely collide with other objects.

How do I enable the physics in cococs2d-x?

The nice thing about cocos2d-x is that it already comes with a everything you need to create cool games. This includes a physics engine called Chipmunk.

So everything you need to get the engine running is to initialize it during scene creation:

auto scene = Scene::createWithPhysics();

The next step is to set the gravity vector (if you want to enable gravity):

scene->getPhysicsWorld()->setGravity(Vec2(0, -900));

You can also enable debug drawing during — which is quite helpful to see if your collision shapes are created as you expect them to be or if you expect some strange behaviour:

// optional: enable debug draw

With this setup your are ready to add sprites to your scene:

auto sprite = Sprite::create("banana.png");

The important line of code is the sprite->setPhysicsBody(body) — it converts your normal sprite into a shape controlled by the simulation.

But where to get the PhysicsBody body from?

cocos2d-x contains several constructors for PhysicsBody objects:

Creating a circle or box is simple — but creating the collision shapes for a complex object is not. Especially since the polygon has to meet 2 conditions:

This means that every convex polygon is ok. But concave polygons have to be split into multiple convex polygons:

Convex decomposition of a concave polygon

Yes — you are right — this is a tedious job. I personally got fed up with it directly after creating my first object...

How to create collision shapes — the easy way

We've developed an application for you to simplify the whole work: It's called PhysicsEditor. The editor looks like this:

Creating shapes with PhysicsEditor

And you can download it from here — It's available for Windows, MacOS and Linux:

PhysicsEditor costs some bucks but believe me: You'll love it. Instead of creating the shapes manually it'll really help you speed up your development. It comes with a 7 days trial — long enough to get through this tutorial.

After installing PhysicsEditor you'll first have to choose the framework you want to develop with — which is of course cocos2d-x. Choose it from the Exporter settings in the top right panel.

Now drag & drop your sprites on the left panel.

Creating shapes manually

Let's create some shapes manually — before doing it all automatically. E.g. let's start with the crate.png from the demo project.

Click on the Polygon shape in the toolbar to create a triangle.

Editing collision polygons for cocos2d-x

Basic editing:

You can also add multiple fixtures to a single body to build more complex objects. Use the Circle tool to add circles.

The small blue circle with the cross is the pivot / anchor point of your sprite. It's applied to the sprite and can be used for aligning and positioning the sprite in your game scene.

This is already a big improvement over creating the shapes by looking up coordinates in a graphics tool. But it gets even better....

Creating shapes automatically

The Shape tracer reduces your work even more:

Automatically generating physics shapes

The most important setting here is the Tolerance. It allows you to control the shape creation.

It's now an act of balance: Find the best tolerance value that gives you a good shape coverage while keeping the vertex count low.

Not enough vertices, bad shape coverage.
Good shape coverage, but way too many vertices.
Good balance between coverage and vertices.

Setting physics parameters

There are 2 levels of physics parameters: Body and fixture level. The body level parameters effect the whole body and all fixtures inside. The fixture level parameters only effect the fixture itself.

Body parameters

Dynamic body

This flag is required if you want the shape to move. If this is ticked off the shape participates in collision detection but never moves. You can use this for e.g. floor, walls, obstacles.

Affected by gravity

The body is accelerated by the gravity in the game scene.

Allows rotation

The body can rotate. You usually want this enabled to get a realistic behaviour of objects. You might not want to enable it on your game character to keep his head up all the time.

Linear damping

Reduce the speed of a shape over time.

Velocity limit

Use this to set a maximum speed for the object.

Angular damping

Reduce rotation of an object over time.

Angular velocity limit

Sets the maximum rotation speed of a body

Fixture parameters

These parameters apply to only 1 part of the body.


Controls how heavy an object is: The higher the density value and the bigger the object the heavier it is.


This is the bounciness of the fixture. Higher values let objects bounce off from others.


Reduce the sprite's speed if it glides over other objects.


The tag can be used to identify a specific fixture — e.g. a character's head or feet.

Collision group

Only bodies in the same group can collide with each other. You can use this to layer your game scene.

The bit masks

Each fixture has 3 bit masks which help filter what happens in case of collisions

defines what this fixture is
defines what this object collides with — and creates a physical reaction
defines which collisions report contact

This allows you to create fixtures for different purposes:

These parameters are all stored as part of the data file PhysicsEditor creates for you. The parameters are automatically applied as soon as you create an object.

Exporting and importing the physics data

If you finished editing the sprites press the Publish button in the top toolbar. This exports an xml file that you can load in your game. Make sure that the data file is written to your Resources folder and that you include it in your project.

Adding the loader

PhysicsEditor requires a loader to read the shapes at runtime. The loader code is open source and available from our loader repository. The example project already contains the loader for cocos2d-x.

The loader class is called PhysicsShapeCache and is implemented as a singleton to make it easy to access the data from everywhere. You can access the loader instance using PhysicsShapeCache::getInstance().

Use addShapesWithFile("filename") to load a shapes definition file. You can also load multiple files at once. Just make sure that the sprites have different names.

To unload the shapes use removeShapesWithFile("filename").

To get the PhysicsBody structure of a shape use createBodyWithName("name of the sprite").

The convenience method setBodyOnSprite("name of the sprite", sprite) directly sets the body on the given sprite.

A quick walk through the example project

Creating the scene, physics setup

The createScene method creates the physics world scene, and the gravity vector.

Scene* HelloWorld::createScene()
    // create the scene with physics enabled
    auto scene = Scene::createWithPhysics();

    // set gravity
    scene->getPhysicsWorld()->setGravity(Vec2(0, -900));

    // optional: set debug draw
    // scene->getPhysicsWorld()->setDebugDrawMask(0xffff);

    auto layer = HelloWorld::create();

    return scene;

Initialising the game scene

This code block loads the physics shapes from the Shapes.plist created with PhysicsEditor.

It also adds a background image which has no physics properties, the ground sprite (static physics object) and drops a banana. The spawnSprite("name") loads a sprite and sets the physics shape.

Finally there's a touch listener setup to add new shapes when the screen is touched or the mouse is clicked in the scene.

bool HelloWorld::init()
    if ( !Layer::init() )
        return false;

    auto pos = Vec2(Director::getInstance()->getVisibleSize()) / 2 +

    // Load shapes
    shapeCache = PhysicsShapeCache::getInstance();

    // Load background image
    Sprite *background = Sprite::create("background.png");

    // Add ground sprite and drop a banana
    spawnSprite("ground.png", pos);
    spawnSprite("banana.png", pos);

    // Add touch listener
    auto listener = EventListenerTouchOneByOne::create();
    listener->onTouchBegan = CC_CALLBACK_2(HelloWorld::onTouchesBegan, this);
    _eventDispatcher->addEventListenerWithSceneGraphPriority(listener, this);

    return true;

Creating sprites with physics enabled

This code block creates a sprite and sets its physics body. It also adds the sprite to the scene.

void HelloWorld::spawnSprite(const std::string &name, Vec2 pos)
    // create a sprite with the given image name
    auto sprite = Sprite::create(name);

    // attach physics body
    shapeCache->setBodyOnSprite(name, sprite);

    // set position and add it to the scene

Adding random sprites

The onTouchesBegan() method spawns random objects at the position where the touch was detected.

bool HelloWorld::onTouchesBegan(Touch *touch, Event *event)
    auto touchLoc = touch->getLocation();

    static int i = 0;
    static std::string sprites[] = { "banana.png", "cherries.png", "crate.png", "orange.png" };

    spawnSprite(sprites[i], touchLoc);
    i = (i + 1) % (sizeof(sprites)/sizeof(sprites[0]));

    return false;


Well — that's it for the start. You've now learned how easy it is to add physics shapes to your game.

Did you like the tutorial? Please share!

Source code available for download

The source code is available on GitHub. Clone it using git:

git clone

or download one of the archives: PhysicsEditor-Cocos2d-x.tar.gz