boxbox

api documentation

boxbox

global boxbox object

.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 });

Entity

a single physical object in the physics simulation

.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

World

contains a single self-contained physics simulation

.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.