physics2d

class physics2d.world
static world()

Create a new physics world

body(type, x, y)

Create a new rigidbody in this world

Parameters
  • type (enum) – The type of body, STATIC, DYNAMIC or KINEMATIC

  • x (number) – The initial x position of the new body

  • y (number) – The initial y position of the new body

step([deltaTime])

Steps the simulation by deltaTime

draw()

Draws a debug representation of the physics world using primitive shapes

raycast(origin, direction, distance[, mask])

Performs a raycast on the physics world from origin in the direction of direction for the distance of distance

The raycast itself is filtered by the optional mask parameter, a bitfield which is compared to collider categories

Parameters
  • origin (vec2) – The origin of the ray

  • direction (vec2) – The direction of the ray

  • distance (number) – The maximum distance for the ray to travel

Returns

The raycast hit info or nil is no collider was hit

Return type

physics2d.rayHit

overlapBox(origin, size[, mask])
queryBox(origin, size[, mask])
queryBoxAll(origin, size[, mask])
gravity: vec2

The current gravity vector for this world

class physics2d.body

A two dimensional rigidbody that simulated within a physics2d.world. Used to simulate both dynamic and static objects, responding to physical forces, collisions and physics queries (i.e. raycast, queryBox, etc…)

destroy()

Destroys this body, removing it from the world in the next simluation step

circle(radius[, offsetX, offsetY])

Creates and attaches a circle collider to this body

Parameters
  • radius (number) – The radius of the circle

  • radius – The local x offset of the circle

  • radius – The local y offset of the circle

Returns

The new circle collider

Return type

physics2d.circle

box(halfWidth, halfHeight[, offsetX, offsetY, rotation])

Creates and attaches a box collider to this body

Returns

The new box collider

Return type

physics2d.box

polygon(points)

Creates and attaches a polygon collider to this body

Returns

The new polygon collider

Return type

physics2d.polygon

hinge(anchor)
hinge(other, anchor)
hinge(other, anchorA, anchorB)

Creates and attaches a hinge joint to this body. When no other body is provided the hinge joint attaches to the world itself

For two-body joints when one anchor is provided, it will be interpreted as a world space location, which will attach to the relative locations of both bodies. When two anchors (anchorA and anchorB) are provided, they will be interpreted in local space and attach to those locations directly

Parameters
  • other (physics2d.body) – The other body to connect to the joint

  • anchor (vec2) – The world-space anchor for one or two-body hinges

  • anchorA (vec2) – The local-space anchor for the main body

  • anchorB (vec2) – The local-space anchor for the attached body

Returns

The new hinge joint

Return type

physics2d.hinge

slider(anchor, axis)
slider(other, anchor, axis)
slider(other, anchorA, anchorB, axis)

Creates and attaches a slider joint to this body. When no other body is provided the slider joint attaches to the world itself

Returns

The new slider joint

Return type

physics2d.slider

distance(anchorA, anchorB)
distance(other, anchorA, anchorB)
distance(other, anchorA, anchorB)

Creates and attaches a distance joint to this body. When no other body is provided the distance joint attaches to the world itself.

For two-body joints when one anchor is provided, it will be interpreted as a world space location, which will attach to the relative locations of both bodies. When two anchors are provided, they will be interpreted in local space and attach to those locations directly

Returns

The new distance joint

Return type

physics2d.distance

applyForce(force)

Applies a force to this body over time (non-instantanious). Ideal for physical effects such as wind, bouyancy and springs

Parameters

force (vec2) – The force vector to apply

applyTorque(torque)
Parameters

torque (number) – The torque vector to apply

applyLinearImpulse(impulse)
Parameters

impulse (vec2) – The linear impulse to apply

applyAngularImpulse(impulse)
Parameters

impulse (number) – The angular impulse to apply

worldPoint(localPoint)

Transforms localPoint from local space to world space in respect to this body

Parameters

localPoint (vec2) – The local space point to transform

Return type

vec2

worldVector(localVector)

Transforms localVector from world space to local space in respect to this body

Parameters

localVector (vec2) – The world space vector to transform

Return type

vec2

localPoint(worldPoint)

Transforms worldPoint from world space to local space in respect to this body

Parameters

worldPoint (vec2) – The world space point to transform

Return type

vec2

localVector(worldVector)

Transforms worldVector from world space to local space in respect to this body

Parameters

worldVector (vec2) – The world space vector to transform

Return type

vec2

velocityAtLocalPoint(localPoint)

Samples the velocity of the body at localPoint in local space

Useful for determining velocity on a body at a specific location for calculating effects, sounds and damage during collisions

Parameters

localPoint (vec2) – The local point to sample velocity from

Return type

vec2

velocityAtWorldPoint(worldPoint)

Samples the velocity of the body at worldPoint in world space

Useful for determining velocity on a body at a specific location for calculating effects, sounds and damage during collisions

Parameters

worldPoint (vec2) – The world point to sample velocity from

Return type

vec2

destroyed: boolean

Flag indicating that this body has already been destroyed

position: vec2

The position of this body in the simulated world

mass: number (readonly)

The mass of this body in kilograms

inertia: number

The interial tensor in kg m^2

linearDamping: number

The amount of linear damping to apply, slowing velocity proportionally over time

angularDamping: number

The amount of linear damping to apply, slowing rotation propotionally over time

gravityScale: number

The scale factor to apply to global gravity, settings 0 will disable gravity

bullet: boolean

Continuous physics switch for this body, used to prevent tunneling for fast moving objects

sleepingAllowed: boolean

Flag for allowing sleeping for this body

awake: boolean

Flag for the current awake state of this body, set to true to wake immediately

enabled: boolean

Flag for whether simulation is enabled

fixedRotation: boolean

Flag for fixed rotation state, set to false to disable rotation

onCollisionBegan: function<physics2d.contact>

A callback for when a collision with this body begins, with more information provided by the supplied physics2d.contact object

onCollisionEnded: function<physics2d.contact>

A callback for when a collision with this body ends, with more information provided by the supplied physics2d.contact object

onPreSolve: function<physics2d.contact>

A callback for when a collision with this body is about to be solved, allowing for some physics2d.contact parameters to be modified

See: https://box2d.org/documentation/classb2_contact_listener.html

onPostSolve: function<physics2d.contact>

A callback for when a collision with this body has been solved, allowing for some physics2d.contact information to be used for other purposes

See: https://box2d.org/documentation/classb2_contact_listener.html

class physics2d.collider
destroy()
destroyed: boolean
friction: number
density: number
restitution: number
sensor: boolean
catgeory: integer (bitfield)
mask: integer (bitfield)
group: integer
body: physics2d.body
class physics2d.circle: collider
radius: number
center: vec2
class physics2d.box: collider
center: vec2
size: vec2
angle: number
class physics2d.polygon: collider
points: table<vec2>
class physics2d.joint
destroy()
getReactionForce(invDt)
getReactionTorque(invDt)
enabled: boolean
destroyed: boolean
collideConnected: boolean
anchorA: vec2
anchorB: vec2
localAnchorA: vec2
localAnchorB: vec2
other: physics2d.body
class physics2d.hinge: joint
referenceAngle: number
angle: number
speed: number
useMotor: boolean
maxTorque: number
motorSpeed: number
useLimit: number
lowerLimit: number
upperLimit: number
class physics2d.slider: joint
referenceAngle: number
translation: number
speed: number
useMotor: boolean
maxForce: number
motorSpeed: number
useLimit: number
lowerLimit: number
upperLimit: number
class physics2d.distance: joint
length: number
currentLength: number
stiffness: number
damping: number
minLength: number
maxLength: number
class physics2d.pulley: joint

Not implemented yet

class physics2d.target: joint

Not implemented yet

class physics2d.gear: joint

Not implemented yet

class physics2d.weld: joint

Not implemented yet

class physics2d.friction: joint

Not implemented yet

class physics2d.rope: joint

Not implemented yet

class physics2d.motor: joint

Not implemented yet

class physics2d.rayHit
point: vec2

The world position of the raycast hit location

normal: vec2

The world normal of the raycast hit location

fraction: number

The fraction of the total ray distance travelled before a hit was detected

collider: physics2d.collider

The collider that was hit by the ray

class physics2d.contact
enabled: boolean

Whether the contact is currently enabled, which can be set to false within the physics2d.body.onPreSolve callback

Useful for one way platforms (checking collision normals and conditionally disabling them)

touching: boolean

Where the contact is currently touching (in some cases this may be false during collision resolution substeps)

friction: number

The friction of this contact, which can be modified within the physics2d.body.onPreSolve callback

restitution: number

The restitution of this contact, which can be modified within the physics2d.body.onPreSolve callback

tangentSpeed: number

The tangent of this contact, which can be modified within the physics2d.body.onPreSolve callback

Useful for creating things like conveyor belts which have a moving surface while remaining stationary

localPoint: vec2

The local position of the contact point (averaged from the manifold)

worldPoint: vec2

The world position of the contact point (averaged from the manifold)

localNormal: vec2

The local normal of the contact point (averaged from the manifold)

worldNormal: vec2

The world normal of the contact point (averaged from the manifold)

body: physics2d.body

The first body in this contact (the body receiving the callback)

otherBody: physics2d.body

The second body involved in this collision contact

collider: physics2d.collider

The first collider in this contact (attached to the body recieving the callback)

otherCollider: physics2d.collider

The second collider involved in this collision contact