Chipmunk Physics Plugin - 0.8.0

##Description:

This plugin brings the advanced rigid body physics of Chipmunk into Kiwi.

The plugin uses the JavaScript port of Chipmunk Physics Library. Many thanks to all the contributors who made the port possible!

##Files / Folders

• assets/ - Assets used by the examples.
• build/ - Final built version of the plugins.
• debug/ - Contains the src and docs for the debug portion of the plugin.
• docs/ - Documentation of the main chipmunk plugin. Generated by yuidocs.
• examples/ - Examples of using Chipmunk physics.
• lib/ - External libraries that this plugin requires.
• src/ - Source files for the plugin.

##Terminology notes: Let's make sure we're on the same page with these terms:

###Shape A Shape is a term for a collidable area. Circles, Polygons, and Lines are supported.

###Body Body defines the physical parameters of objects: position, rotation, mass, velocity and so forth.

###Space Space is a section of the Chipmunk which simulates physics behaviours. Any Body or Shape that you want to update due to gravity or collisions needs to be attached to the same space.

##How to Include:

Copy the lib/chipmunk-js/cp.js file (or the minified version) into your project directory. We recommend that you place plugin scripts inside a js/lib folder to easily manage all external libraries used, although this is not required.

Copy either the chipmunk-physics-x.x.x.js or the chipmunk-physics-x.x.x.min.js file (they are located in the build folder of this repo) into your project directory. We recommend that you save the files under a js/plugins directory that lives inside of your project directory so that you can easily manage all of the plugins.

Then link in both of the javascript files that we copied above into your HTML file. Make sure to place the link to the plugin itself underneath the link to the kiwi.js file AND the cp.js file.

Now we need to tell the game to use the plugin. To do so you need to add the name of the plugin ("ChipmunkPhysics") to the plugins section of the game options.

var game = new Kiwi.Game("domElementId", "GameName", null, { plugins: ["ChipmunkPhysics"]});

Make sure that you also pass the names of other plugins that you want to use.

Your game should now have access to the plugin.

###Including the Debug Plugin: To include the debug portion of the plugin as well you will need to copy and include a few more files.

Firstly make a copy of and link to the following files:

• lib/chipmunk-js/cp.extra.js
• build/chipmunk-physics-debug-x.x.x.js

Be sure to include the cp.extra.js file first.

Tell the game to use the plugin. Add the ChipmunkPhysicsDebug (the name of the debug plugin) to the plugins section of the game options. Be sure to add it after the ChipmunkPhysics plugin.

var game = new Kiwi.Game("domElementId", "GameName", null, { plugins: ["ChipmunkPhysics", "ChipmunkPhysicsDebug"]});

##Note! Scale doesn't affect Shapes One thing to point out is that changing a Transform's scale will not change any Shape that is attached to a Body which uses that Transform.

The main reason for this is that Chipmunk doesn't contain any scale properties. This plugin is a wrapper for Chipmunk, not a complete rewrite of the physics engine, so we cannot support scale on physics Bodies.

If you do scale a Transform and want a Shape to update with the scale, we recommend updating the information defining that shape. For example, if you want to scale a polygon, you would reset the vertices using the setVerts method.

##How to use: This section covers the following topics:

• Using the Debug Plugin
• Physics Manager
• What can be done in Space
• Physics Component
• Bodies
• Creating Shape's
• Constraints

###Using the Debug Plugin If you include the ChipmunkPhysicsDebug plugin in a game, that game will have access to a chipmunkDebug manager. This manager initialises the debug overlay and handles rendering of shapes, constraints, and bodies.

// Initalises the debug overlay
this.game.chipmunkDebug.init(); 

Executing the init method creates the stage's debug canvas and starts rendering all the bodies/shapes/constraints on the defaultSpace.

The following is a list of rendering options.

this.game.chipmunkDebug.renderConstraints = true;
this.game.chipmunkDebug.renderBodies  = true;
this.game.chipmunkDebug.renderShapes = true;

###Physics Manager The physics manager is created and attached to a game at boot time. The manager is in charge of creating and managing spaces.

Update Speed Time interval between physics updates, in seconds.

this.game.chipmunk.updateSpeed = 1 / 60;

Space The default space which is created at boot time. This is the default space to which the ChipmunkPhysics Components will add the bodies/shapes they create by default.

This is also the object you access to change the direction/level of gravity, damping on all velocities, how accurate the physics is, plus much much more.

this.game.chipmunk.defaultSpace;

Active If the spaces managed by this plugin should update or not.

this.game.chipmunk.active = false; 

###What can be done in Space Space is used in Chipmunk to contain a singular physics simulation. A space is created by default at boot time. Bodies, shapes, and constraints that you want simulated need to be added to a space in order to function.

Gravity

this.game.chipmunk.defaultSpace.gravityX = 100;
this.game.chipmunk.defaultSpace.gravityY = 100;

Damping Amount of velocity that bodies retain each second. A value of 0.9 means that each bodies velocity will drop by 10% over the course of one second.

this.game.chipmunk.defaultSpace.damping = 1;

View the docs for more information on what you can do.

###Physics Component The easiest way to use Chipmunk Physics with a GameObject is through the ChipmunkPhysics Component provided by this plugin.

Simply attach this Component to a GameObject without defining any options. This will create a Body and a Box Shape based on the GameObject's texture atlas, and attach them to the default space.

var gameobject = new Kiwi.GameObjects.StaticImage( this, x, y );
gameobject.physics = this.components.add( new Kiwi.Plugins.ChipmunkPhysics.Component( this, {} ) );

View examples/2-basic to see this in action.

Config Parameters When initially creating the Physics Component you can pass in an Object Literal which can contain information regarding the body/shapes it should generate.

Below is a list of the options you are most likely to want to edit/pass when using the Component.

var config = {
	// Change the space to which the body/shapes will be added.
	// This can be modified if you use multiple spaces in your game.
	space: newSpace,

	// The default type of body/shapes that will be generated
	// if a type is not passed.
	// Valid types are "box", "poly", "circle" and "line".
	defaultType: "box",

	// Velocities
	velocityX: 0,
	velocityY: 0,
	angularVelo: 0,
	maxVelo: 0,
	maxAngularVelo: 0, 

	// Options regarding the body 
	body: {

		// The type of body to generate. 
		// Will fallback to the "defaultType" if not passed.
		type: "box",

		// The mass of the body. 
		// Default is:  width * height / 1000 
		mass: 100,

		// The owner of the body.
		// Useful to maintain a reference back when using
		// callbacks which return a body/shape.
		// Defaults to the gameobject to which the component is attached.
		owner: sprite,

		// Center of the body from the top/left of the sprite.
		// Defaults to the anchorPoint location which is the center.
		center: {
			x: 100,
			y: 100
		},

		// If the body should be added to the space passed or not.
		// If false, you will need to manually add it to the space if wanted.
		addToSpace: true,

		// Parameters for only "box" types.
		width: 100,
		height: 100,

		// Parameters for only "circle" types.

		// Radius of the body.
		radius: 100,
		offset: {
			x: 0,
			y: 0
		},

		// Parameters for only "segment" types.

		// Starting location.
		start: {
			x: 0,
			y: 0
		},

		// End location.
		end: {
			x: 100,
			y: 0
		},


		// Parameters for only "poly" types.

		// Vertices of the polygon.
		// Must be convex and have a clockwise winding
		verts: [ x1, y1, x2, y2, x3, y3, ... ],
		offset: {
			x: 0,
			y: 0
		},


		// Parameters for only "custom" types.
		// Moment of inertia for the body.
		i: 125

	},

	shape: {
		// All shape parameters will attempt to default to the
		// same as the bodies passed.

		// The type of shape to generate.
		type: "box",

		// If the shape should be added to the space passed or not.
		addToSpace: true,

		// "box" type options
		width: 100,
		height: 100,

		// "circle" type options
		radius: 10,
		offset: {
			x: 0,
			y: 0
		},

		// "segment" type options
		start: {
			x: 0,
			y: 0
			},
		end: {
			x: 100,
			y: 0
		},
		radius: 1,

		// "poly" type options
		verts: [ x1, y1, x2, y2, x3, y3, ... ],
		offset: {
			x: 0,
			y: 0
		}

	}

	// You can always define multiple shapes
	// by passing an array of shape configs
	// with the same accepted parameters as above.

	/*
	shapes: [
		{
			// Shape 1 Config
			// Same available options as above
		},
		{
			// Shape 2 Config.
			// Same available options as above
		}
	]
	*/

}

Bodies and Shapes that have been created will be added to the component under their respective names.

var body = penguin.physics.body;
var shapes = penguin.physics.shapes;

###Bodies To create a new body for use in Kiwi you can use the Kiwi.Plugins.ChipmunkPhysics.Body class. This class requires that you pass it a mass and a moment of inertia.

You can also optionally pass it a transformation that the body should use to position itself. This is how a body is fixed to a sprite's location.

var body = new Kiwi.Plugins.ChipmunkPhysics.Body({
		mass: 100,
		
		// Chipmunk contains a few useful methods to create
		// inertia depending on use case of the body. 
		i: 25
	});

Alternatively you can use a few of the static methods to create a body based on information provided. View the statics.js file for a full list.

	var boxbody = Kiwi.Plugins.ChipmunkPhysics.createBoxBody({
		mass: 100,
		width: 25,
		height: 25
		});

	var circlebody = Kiwi.Plugins.ChipmunkPhysics.createCircleBody({
		mass: 75,
		radius: 25
		});

	var segmentbody = Kiwi.Plugins.ChipmunkPhysics.createSegmentBody({
		mass: 100,
		start: {
			x: 0,
			y: 0
			},
		end: {
			x: 100,
			y: 0
			}
		});

	var polybody = Kiwi.Plugins.ChipmunkPhysics.createPolyBody({
		mass: 100,
		verts: [x1, y1, x2, y2, ...]
		});

Adding to Space If a body should be affected by gravity and have a velocity of its own, then you need to add it to a space.

this.game.chipmunk.defaultSpace.addBody( body );

Moving Bodies You move a body in a number of ways.

One way is to set the velocity of a body using the setVel method.

var x = 100;
var y = 0;
body.setVel( x, y );

Another way is to apply a force to the object. That force will then be constantly applied to the body. This is equivalent to constant acceleration.

body.applyForce( 
	// The first parameter is the velocity vector
	{
		x: 100,
		y: 20,
	}, 
	// The second parameter is the offset of the vector
	// from the body's centroid.
	{ 
		x: 0,
		y: 0,
	});

View the docs for more information on what you can do with Bodies.

###Creating Shapes Shapes mainly define collision areas in Chipmunk and so there are a few different types avaliable to you.

• Polygons - Must be convex; no concave support
• Circles
• Segments - Also known as lines

Each shape requires that you pass it a body. This will define its location, rotation, and so forth.

If shapes are to collide against other shapes you will need to add them to the same space. This should also be the same space the body is attached to.

An example of creating a circle shape is as follows:

// It is assumed you have created a body above...

var circleshape = new Kiwi.Plugins.ChipmunkPhysics.Shapes.Circle({
	body: body,
	radius: 25
});
this.game.chipmunk.space.addShape( circleshape );

If you want a shape to not move when another shape collides with it (for example, you would not want the ground to move when someone lands) then instead of creating a new body you should use what is called a Static Body instead.

Spaces will have a reference to a staticBody you can use for your shapes. Shapes which use the staticBody can then be position by changing their offsets.

var circleshape = new Kiwi.Plugins.ChipmunkPhysics.Shapes.Circle({
	radius: 25,

	// Access the staticBody for unmoving geometry
	body: this.game.chipmunk.space.staticBody,

	// Use the offset to position the shape...
	offset: {
		x: 100,
		y: 250
	}
}); 

this.game.chipmunk.space.addShape( circleshape );

###Constraints Constraints allow you to define how two bodies interact together. A good example of this can be found on the joints tab of the chipmunk demos.

All available joints can be found under the Kiwi.Plugins.ChipmunkPhysics.Joints namespace.

Joints need to be added to a space to be simulated just like bodies/shapes. They also require a configuration object defining the two bodies they are joining and more information depending on the type of constraint created.

var joint = new Kiwi.Plugins.ChipmunkPhysics.Joints.DampedSpring({
	// First body we are joining
	bodyA: firstBody,

	// Second body we are joining
	bodyB: secondBody,

	// Location of the spring on the first body.
	// 0,0 will be at the bodies centeral point. 
	anchorPointA: {
		x: 0,
		y: 0
	},

	// Location of the spring on the second body.
	// 0,0, will be at the bodies centeral point.
	anchorPointB: {
		x: 0,
		y: 0
	},

	restLength: 100,
	stiffness: 50
});

this.game.chipmunk.space.addConstraint( joint );

##More Documentation Further examples can be found in the examples folder of this repo.

View the API documentation located in the docs folder for a more robust list of features located on each object.

##Thanks If you have further questions, suggestions, or find any issues with the plugin, don't hesitate to contact us at KiwiJS.