boxbox

.createWorld( canvas, [options] )

canvas element to render on
options
- gravity (default {x:0, y:10}) can be horizontal, negative, etc
- allowSleep (default true) bodies may sleep when they come to rest. a sleeping body is no longer being simulated, which can improve performance.
- scale (default 30) scale for rendering in pixels / meter
- tickFrequency (default 50) onTick events happen every tickFrequency milliseconds
- collisionOutlines (default false) render outlines over everything for debugging collisions
return a new World

without options

var canvasElem = document.getElementById("myCanvas");
var world = boxbox.createWorld(canvasElem);

with options

var canvasElem = document.getElementById("myCanvas");
var world = boxbox.createWorld(canvasElem, {
  gravity: {x: 0, y: 20},
  scale: 60
});

.applyImpulse( power, degrees )

power of impulse
degrees direction of force. 0 is up, 90 is right, etc.

Apply an instantanious force on this Entity.
With this and all functions that take degrees, you can also provide a vector.

entity.applyImpulse(10, 45); // 45 degree angle
entity.applyImpulse(10, 1, -1); // the vector x=1 y=-1}

.borderColor( [value] )

value css color string
return css color string

get or set entity's border color

.borderWidth( [value] )

value number
return number

get or set entity's border width. Set to 0 to not show a border.

.canvasPosition( )

return {x,y}

Get the Entity position in pixels. Useful for custom rendering. Unlike position the result is relative to the World's scale and camera position.

.clearForce( name )

Stop the force with the given name.

.clearVelocity( name )

Stop the constant velocity with the given name.

.color( [value] )

value css color string
return css color string

get or set entity's color

.destroy( )

destroy this entity and remove it from the world

.draw( [value] )

value function
return function

get or set the draw function for this entity

.friction( [value] )

value number
return number

get or set entity friction

.image( [value] )

value string
return string

get or set entity image

.imageOffsetX( [value] )

value number
return number

get or set entity image offset in the x direction

.imageOffsetY( [value] )

value number
return number

get or set entity image offset in the y direction

.imageStretchToFit( [value] )

value boolean
return boolean

set to true to stretch image to entity size

.maxVelocityX( [value] )

value number
return number

get or set entity max velocity left or right

.maxVelocityY( [value] )

value number
return number

get or set entity max velocity up or down

.name( [value] )

return entity name

get or set entity name

.onFinishContact( callback )

callback
function( entity )
- entity that contact ended with
- this this Entity

Handle end of contact with another entity.

.onImpact( callback )

callback
function( entity, normalForce, tangentialForce )
- entity collided with
- normalForce force of two entities colliding
- tangentialForce force of two entities "rubbing" up against each other
- this this Entity

Handle impact with another entity.

.onKeydown( callback )

callback
function( e )
- e keydown event
- this this Entity

Handle keydown event for this entity.

.onKeyup( callback )

callback
function( e )
- e keyup event
- this this Entity

Handle keyup event for this entity.

.onRender( callback )

callback
function( context )
- context canvas context for rendering
- this Entity

Add an onRender callback to this Entity
Multiple onRender callbacks can be added, and they can be removed with world.unbindOnRender.

.onStartContact( callback )

callback
function( entity )
- entity that contact started with
- this this Entity

Handle start of contact with another entity.

.onTick( callback )

callback
function()
- this Entity

Add an onTick callback to this Entity
Ticks are periodic events that happen independant of rendering. You can use ticks as your "game loop". The default tick frequency is 50 milliseconds, and it can be set as an option when creating the world.
Multiple onTick callbacks can be added, and they can be removed with world.unbindOnTick.

.position( [value] )

value {x,y}
return {x,y}

get or set entity position

.restitution( [value] )

value number
return number

get or set entity restitution (bounciness)

.rotation( [value] )

value degrees
return degrees

get or set entity rotation

.setForce( name, power, degrees )

name of force
power of force
degrees direction of force

Apply a constant force on this Entity. Can be removed later using clearForce.

.setVelocity( name, power, degrees )

name of velocity
power of velocity
degrees direction of velocity

Continuously override velocity of this Entity. Can be removed later using clearVelocity. Usually you probably want setForce or applyImpulse.

.sprite( x, y )

Set the entity's image to the sprite at x, y on the sprite sheet. Used only on entities with spriteSheet:true

.spriteHeight( [value] )

value number
return number

get or set height of a sprite on the sprite sheet

.spriteSheet( [value] )

value boolean
return boolean

get or set if this entity's image is a sprite sheet

.spriteWidth( [value] )

value number
return number

get or set width of a sprite on the sprite sheet

.camera( [value] )

value {x,y}
return {x,y}

get or set position of camera

.canvasPositionAt( x, y )

return {x,y}

Get a canvas position for a corresponding world position. Useful for custom rendering in onRender. Respects world scale and camera position.

.createEntity( options )

options
- name of this entity
- x starting x coordinate for the center of the new entity
- y starting y coordinate for the center of the new entity
- type 'dynamic' or 'static'. static objects can't move
- shape 'square' or 'circle' or 'polygon'
- height for box (default 1)
- width for box (default 1)
- radius for circle (default 1)
- points for polygon [{x,y}, {x,y}, {x,y}] must go clockwise must be convex
- density (default 2)
- friction (default 1)
- restitution or bounciness (default .2)
- active (default true) participates in collisions and dynamics
- rotation (default 0) initial rotation in degrees
- fixedRotation (default false) prevent entity from rotating
- bullet (default false) perform expensive continuous collision detection
- maxVelocityX Prevent entity from moving too fast either left or right
- maxVelocityY Prevent entity from moving too fast either up or down
- image file for rendering
- imageOffsetX (default 0) for image
- imageOffsetY (default 0) for image
- imageStretchToFit (default false) for image
- spriteSheet Image is a sprite sheet (default false)
- spriteWidth Used with spriteSheet (default 16)
- spriteHeight Used with spriteSheet (default 16)
- spriteX Used with spriteSheet (default 0)
- spriteY Used with spriteSheet (default 0)
- color CSS color for rendering if no image is given (default 'gray')
- borderColor CSS color for rendering the shape's border (default 'black')
- borderWidth Width of the border. The border does not impact physics. (default 1)
- draw custom draw function, params are context, x, and y
- init a function that is run when the entity is created
- onKeyDown keydown event handler
- onKeyUp keyup event handler
- onStartContact start contact event handler
- onFinishContact finish contact event handler
- onImpact impact event handler
- onRender event handler on render
- onTick event handler on tick
return a new Entity

Example

var player = world.createEntity({
  name: "player",
  shape: "circle",
  radius: 2
});

Templates

You can pass multiple options objects. This allows for "templates" with reusable defaults:

var redCircleTemplate = {color: "red", shape: "circle", radius: 3};
world.createEntity(redCircleTemplate, {x: 5, y: 5});
world.createEntity(redCircleTemplate, {x: 10, y: 5});

The options objects on the right take precedence.

Dollar Properties

You can provide options that start with a $ like this: var ball = world.createEntity({color: "red", $customValue: 15}); These are passed onto the resulting entity as they are: ball.$customValue === 15 This allows you to provide your own custom methods and properties.

.createJoint( entity1, entity2, [options] )

entity1 Entity on one side of the joint
entity2 Entity on the other side of the joint
options
- enableMotor (default false)
- type
  one of
  - distance these entities will always remain the same distance apart
  - revolute
  - gear
  - friction
  - prismatic
  - weld
  - pulley
  - mouse
  - line

Experimental joint support. See box2d documentation for more info.

.find( x1, y1, x2, y2 )

x1 upper left of query box
y1 upper left of query box
x2 lower right of query box
y2 lower right of query box
return array of Entities. may be empty

find Entities in a given query box

.gravity( [value] )

value: {x,y}
return: {x,y}

get or set the world's gravity

.onRender( callback )

callback
function( context )
- context canvas context for rendering
- this World

Add an onRender callback to the World This is useful for custom rendering. For example, to draw text on every frame:

world.onRender(function(ctx) {
  ctx.fillText("Score: " + score, 10, 10);
});

This callback occurs after all entities have been rendered on the frame.
Multiple onRender callbacks can be added, and they can be removed with unbindOnRender.

.onTick( callback )

callback
function()
- this World

Add an onTick callback to the World
Ticks are periodic events that happen independant of rendering. You can use ticks as your "game loop". The default tick frequency is 50 milliseconds, and it can be set as an option when creating the world.
Multiple onTick callbacks can be added, and they can be removed with unbindOnTick.

.scale( [value] )

value number
return number

get or set the scale for rendering in pixels / meter

.unbindOnRender( callback )

callback callback

If the provided function is currently an onRender callback for this World, it is removed.

.unbindOnTick( callback )

callback callback

If the provided function is currently an onTick callback for this World, it is removed.