Help me replace my broken Mac Mini!

Click here to lend your support to: Help me replace my broken mac mini and make a donation at !

About this tutorial

Learn about Chipmunk Physics Engine and how to start developing games for the iPhone and other platforms.


  1. Introduction
  2. Setup
  3. Basic Concepts
  4. Initializing Chipmunk
  5. Defining the ball's body and shapes
  6. Tracking the ball's movements
  7. Defining the floor's body and shapes
  8. Evaluating the results & Conclusion
  9. Download the complete project

Initializing Chipmunk

You need 3 basic things to start working with Chipmunk:

  1. Initialize it
  2. Use a timer to make Chipmunk compute the steps of the simulation as you go
  3. Create and configure a Space

Initializing Chipmunk is the easiest part of all, you just need to call cpInitChipmunk(); somewhere along your application initialization. The timer can be setup using a simple NSTimer object or in some cases if you're using a game engine you should use the timer from the engine itself (to ensure synchronization). Finally, creating a new space is as easy as calling cpSpaceNew();.

To complete this 3 steps, begin by adding the correct #import to both the header and the implementation files of you controller.

#import "chipmunk.h"

Then, on your header you'll need to add one variable to store our space and 2 methods, the complete header should look like this:

#import <UIKit/UIKith.>

#import "chipmunk.h"

@interface ChipmunkTutorialViewController : UIViewController {

UIImageView *floor; // Holds our floor image

UIImageView *ball; // Holds our ball image

cpSpace *space; // Holds our Space object


- (void)setupChipmunk; // Bootstraps chipmunk and the timer

- (void)tick:(NSTimer *)timer; // Fires at each "frame"


Now, at the implementation file, start by adding the following call to the bottom of you viewDidLoad message:

[self setupChipmunk];

And finally the implementation of the 2 methods we declared:

// Bootsraps chipmunk and the timer

- (void)setupChipmunk {

// Start chipmunk


// Create a space object

space = cpSpaceNew();

// Define a gravity vector

space->gravity = cpv(0, -100);

// Creates a timer firing at a constant interval (desired frame rate)

// Note that if you are using too much CPU the real frame rate will be lower and

// the timer might fire before the last frame was complete.

// There are techniques you can use to avoid this but I won't approach them here.

[NSTimer scheduledTimerWithTimeInterval:1.0f/60.0f target:self selector:@selector(tick:) userInfo:nil repeats:YES];


// Called at each "frame" of the simulation

- (void)tick:(NSTimer *)timer {

// Tell Chipmunk to take another "step" in the simulation

cpSpaceStep(space, 1.0f/60.0f);


You'll notice that I took this opportunity to setup the gravity for our space. Since gravity is something globally shared by all objects it makes sense it should be setup right at the beginning. One thing you might not understand right away is the value I associated with the gravity field. cpv(x, y) is a convenience function to define a vector, in this case we're saying that the gravity is a force that pulls vertically down with strength 100 but you can adjust the values at will.

This steps take care of most of the initialization process. The code should compile and run correctly but although Chipmunk is running you won't see anything new because we didn't define our bodies yet.


If you find this article useful and enjoy it, consider donating, even a small amount goes a long way to keep the articles up-to-date and to fund new ones.