Box2D. Box2dObject

Box2D Object - extend with your own custom physics objects

  • A LittleJS object with Box2D physics, dynamic by default
  • Provides interface for Box2D body and fixture functions
  • Each object can have multiple fixtures and joints
  • Angular values are clockwise like angle: angular velocity, torque, joint angles, limits and motor speeds

Constructor

new Box2dObject(posopt, sizeopt, tileInfoopt, angleopt, coloropt, bodyTypeopt, renderOrderopt)

Create a LittleJS object with Box2d physics

Parameters:
NameTypeAttributesDefaultDescription
posVector2<optional>
sizeVector2<optional>
tileInfoTileInfo<optional>
anglenumber<optional>
0
colorColor<optional>
bodyTypenumber<optional>
renderOrdernumber<optional>
0

Extends

  • EngineObject

Members

body

Properties
TypeDescription
Object

The Box2d body, undefined once it is destroyed

edgeLists :Array.<Array.<Vector2>>

Type:
  • Array.<Array.<Vector2>>
Properties
TypeDescription
Array.<Array.<Vector2>>

List of all edges for default box2d drawing

edgeLoops :Array.<Array.<Vector2>>

Type:
  • Array.<Array.<Vector2>>
Properties
TypeDescription
Array.<Array.<Vector2>>

List of all edge loops for default box2d drawing

lineColor

Properties
TypeDescription
Color

Line color used for default box2d drawing

lineWidth

Properties
TypeDescription
number

Line width used for default box2d drawing

Methods

addBox(sizeopt, offsetopt, angleopt, densityopt, frictionopt, restitutionopt, isSensoropt)

Add a box shape to the body

Parameters:
NameTypeAttributesDefaultDescription
sizeVector2<optional>
offsetVector2<optional>
anglenumber<optional>
0

LittleJS convention (clockwise positive). Negated internally to match Box2D's CCW-positive convention so the fixture aligns with the same angle passed to drawRect/drawTile.

densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addCircle(diameteropt, offsetopt, densityopt, frictionopt, restitutionopt, isSensoropt)

Add a circle shape to the body

Parameters:
NameTypeAttributesDefaultDescription
diameternumber<optional>
1
offsetVector2<optional>
densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addEdge(point1, point2, densityopt, frictionopt, restitutionopt, isSensoropt)

Add an edge shape to the body

Parameters:
NameTypeAttributesDescription
point1Vector2
point2Vector2
densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addEdgeList(points, densityopt, frictionopt, restitutionopt, isSensoropt)

Add an edge list to the body

Parameters:
NameTypeAttributesDescription
pointsArray.<Vector2>
densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addEdgeLoop(points, densityopt, frictionopt, restitutionopt, isSensoropt)

Add an edge loop to the body, an edge loop connects the end points

Parameters:
NameTypeAttributesDescription
pointsArray.<Vector2>
densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addPoly(points, densityopt, frictionopt, restitutionopt, isSensoropt)

Add a polygon shape to the body, the convex hull of its points; Box2D takes 3 to 8 points, not all in a line, and no fixture is made from any other; points closer than .001 count as one

Parameters:
NameTypeAttributesDescription
pointsArray.<Vector2>
densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addRandomPoly(diameteropt, densityopt, frictionopt, restitutionopt, isSensoropt)

Add a random polygon shape to the body

Parameters:
NameTypeAttributesDefaultDescription
diameternumber<optional>
1
densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addRegularPoly(diameteropt, sidesopt, densityopt, frictionopt, restitutionopt, isSensoropt)

Add a regular polygon shape to the body

Parameters:
NameTypeAttributesDefaultDescription
diameternumber<optional>
1
sidesnumber<optional>
8

3 to 8, the most Box2D polygons have

densitynumber<optional>
frictionnumber<optional>
restitutionnumber<optional>
isSensorboolean<optional>

addShape(shape, densityopt, frictionopt, restitutionopt, isSensoropt)

Add a shape fixture to the body

Parameters:
NameTypeAttributesDefaultDescription
shapeObject
densitynumber<optional>
1
frictionnumber<optional>
0.2
restitutionnumber<optional>
0
isSensorboolean<optional>
false

applyAcceleration(acceleration, posopt)

Apply acceleration to this object (changes velocity by acceleration, mass-independent like EngineObject.applyAcceleration, but in units per second). Use applyImpulse if you want the mass-dependent velocity change Δv = impulse / mass, or applyForce for a Newton-style sustained force.

Parameters:
NameTypeAttributesDescription
accelerationVector2
posVector2<optional>

applyAngularAcceleration(acceleration)

Apply angular acceleration to this object (changes angular velocity by acceleration, mass-independent, clockwise — matches EngineObject.applyAngularAcceleration).

Parameters:
NameTypeDescription
accelerationnumber

applyAngularImpulse(impulse)

Apply an instantaneous angular impulse. Changes angular velocity by impulse / inertia immediately, clockwise like angle.

Parameters:
NameTypeDescription
impulsenumber

applyForce(force, posopt)

Apply force to this object

Parameters:
NameTypeAttributesDescription
forceVector2
posVector2<optional>

applyImpulse(impulse, posopt)

Apply an instantaneous linear impulse. Changes velocity immediately by impulse / mass (so heavier bodies move less for the same impulse).

Parameters:
NameTypeAttributesDescription
impulseVector2
posVector2<optional>

applyTorque(torque)

Apply torque to this object, clockwise like angle

Parameters:
NameTypeDescription
torquenumber

beginContact(otherObject, fixtureopt, otherFixtureopt)

Called when a contact begins, while the world steps: a destroy or a setter waits until the step is done, and creating objects, fixtures or joints must wait until after the step

  • The fixtures say which shapes touched, the same objects addBox and the others returned, so a small sensor under a player's feet can tell standing on the ground from touching a wall
Parameters:
NameTypeAttributesDescription
otherObjectBox2dObject
fixtureObject<optional>

This object's fixture that touched

otherFixtureObject<optional>

The other object's fixture that touched

destroy(immediateopt)

Destroy this object and its physics body

Parameters:
NameTypeAttributesDefaultDescription
immediateboolean<optional>
false

Remove it now, as EngineObject.destroy does, children included

destroyAllFixtures()

Destroy all fixtures from the body, from a contact callback once the step is done

destroyFixture(fixture)

Destroy a fixture from the body, from a contact callback once the step is done

Parameters:
NameTypeDescription
fixtureObject

drawFixtures(coloropt, lineColoropt, lineWidthopt, useWebGLopt, contextopt)

Draws all this object's fixtures

Parameters:
NameTypeAttributesDefaultDescription
colorColor<optional>
lineColorColor<optional>
lineWidthnumber<optional>
0.1
useWebGLboolean<optional>
glEnable
contextCanvasRenderingContext2D<optional>

endContact(otherObject, fixtureopt, otherFixtureopt)

Called when a contact ends, while the world steps or a body is destroyed: a destroy or a setter waits until the step is done, and creating objects, fixtures or joints must wait until after the step

Parameters:
NameTypeAttributesDescription
otherObjectBox2dObject
fixtureObject<optional>

This object's fixture that touched

otherFixtureObject<optional>

The other object's fixture that touched

getAngularVelocity() → {number}

Gets the angular velocity, clockwise like angle

Returns:
Type: 
number

getBodyType() → {number}

Gets the physics body type

Returns:
Type: 
number

getCenterOfMass() → {Vector2}

Gets the center of mass in world space

Returns:
Type: 
Vector2

getFixtureList() → {Array.<Object>}

Get list of fixtures for this object

Returns:
Type: 
Array.<Object>

getInertia() → {number}

Gets the rotational inertia about the center of mass

Returns:
Type: 
number

getIsAwake() → {boolean}

Check if this object is awake

Returns:
Type: 
boolean

getJointList() → {Array.<(Box2dJoint|Object)>}

Get list of joints for this object, the Box2dJoint for each one made through LittleJS, and the Box2D joint, cast to its type, for any made on the world directly

Returns:
Type: 
Array.<(Box2dJoint|Object)>

getLinearVelocity() → {Vector2}

Gets the linear velocity

Returns:
Type: 
Vector2

getMass() → {number}

Gets the mass

Returns:
Type: 
number

getSpeed() → {number}

Get the speed of this object

Returns:
Type: 
number

hasFixtures() → {boolean}

Check if this object has any fixtures

Returns:
Type: 
boolean

hasJoints() → {boolean}

Check if this object has any joints

Returns:
Type: 
boolean

render()

Render the object, uses box2d drawing if no tile info exists

renderDebugInfo()

Render debug info

resetMassData()

Reset the mass, center of mass, and moment, from a contact callback once the step is done

setAngle(angle)

Sets the angle, from a contact callback the body turns once the step is done, keeping the position it has then

Parameters:
NameTypeDescription
anglenumber

setAngularDamping(damping)

Sets the angular damping

Parameters:
NameTypeDescription
dampingnumber

setAngularVelocity(angularVelocity)

Sets the angular velocity, clockwise like angle

Parameters:
NameTypeDescription
angularVelocitynumber

setAwake(isAwakeopt)

Set the sleep state of the body

Parameters:
NameTypeAttributesDefaultDescription
isAwakeboolean<optional>
true

setBodyType(type)

Set the physics body type, from a contact callback it changes once the step is done

Parameters:
NameTypeDescription
typenumber

setBullet(isBulletopt)

Should be like a bullet for continuous collision detection?

Parameters:
NameTypeAttributesDefaultDescription
isBulletboolean<optional>
true

setCenterOfMass(center)

Set the center of mass of the body, local to it

Parameters:
NameTypeDescription
centerVector2

setFilterData(categoryBitsopt, ignoreCategoryBitsopt, groupIndexopt)

Set the collision filter data for the fixtures this body has now, a fixture added later has the default filter, category 1 colliding with everything

Parameters:
NameTypeAttributesDefaultDescription
categoryBitsnumber<optional>
1
ignoreCategoryBitsnumber<optional>
0
groupIndexnumber<optional>
0

setFixedRotation(isFixedopt)

Set whether the body can rotate

Parameters:
NameTypeAttributesDefaultDescription
isFixedboolean<optional>
true

setGravityScale(scaleopt)

Sets the gravity scale

Parameters:
NameTypeAttributesDefaultDescription
scalenumber<optional>
1

setLinearDamping(damping)

Sets the linear damping

Parameters:
NameTypeDescription
dampingnumber

setLinearVelocity(velocity)

Sets the linear velocity

Parameters:
NameTypeDescription
velocityVector2

setMass(mass)

Set the mass of the body

Parameters:
NameTypeDescription
massnumber

setMassData(localCenteropt, massopt, momentOfInertiaopt)

Set the mass data of the body, from a contact callback once the step is done; a mass of 0 or less becomes 1, use setBodyType for a static body; call it after adding fixtures and after setFixedRotation, both of which put the mass back to what the fixtures give

Parameters:
NameTypeAttributesDescription
localCenterVector2<optional>
massnumber<optional>
momentOfInertianumber<optional>

About the center of mass

setMomentOfInertia(momentOfInertia)

Set the moment of inertia of the body, about its center of mass

Parameters:
NameTypeDescription
momentOfInertianumber

setPosition(pos)

Sets the position, from a contact callback the body moves once the step is done, keeping the angle it has then

Parameters:
NameTypeDescription
posVector2

setSensor(isSensoropt)

Set if this body is a sensor

Parameters:
NameTypeAttributesDefaultDescription
isSensorboolean<optional>
true

setSleepingAllowed(isAllowedopt)

Set whether the body is allowed to sleep

Parameters:
NameTypeAttributesDefaultDescription
isAllowedboolean<optional>
true

setTransform(pos, angle)

Sets the position and angle, from a contact callback the body moves once the step is done

Parameters:
NameTypeDescription
posVector2
anglenumber

updatePhysics()

Box2d objects updated with Box2d world step

updateTransforms(updateChildrenopt)

Update the object transform, called automatically by engine even when paused; its body places it, so it can be a parent but not a child, connect it to another with a joint

Parameters:
NameTypeAttributesDefaultDescription
updateChildrenboolean<optional>
true

Also update the children's transforms