physics2d

Simulation

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

• offsetX – The local x offset of the circle

• offsetY – 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

Collision

class physics2d.collider

A two dimensional collider that attaches to a physics2d.body, detects and reacts to collisions

destroy()

Destroys this collider, removing it in the next simluation step

destroyed: boolean

Flag indicating that this collider has already been destroyed

friction: number

The coefficient of friction for this collider

density: number

The density of this collider

restitution: number

The coefficient of restitution for this collider

sensor: boolean

Flag turning this collider into a sensor. Sensors do not physically collide with object bodies but will still report collision detection via callbacks

category: integer (bitfield)

The category for this collider. Categories are used to filter collisions based on their mask bits

Example

PLAYER_CAT = 0x1 -- set bit 1
ENEMY_CAT = 0x2 -- set bit 2
ITEM_CAT = 0x4 -- set bit 3

-- Players can collider with enemies and items
playerCollider.category = PLAYER_CAT
playerCollider.mask = ENEMY_CAT | ITEM_CAT

-- Enemies only collider with players
enemyCollider.category = ENEMY_CAT
enemyCollider.mask = PLAYER_CAT

-- Items only collider with players
itemCollider.category = ITEM_CAT
itemCollider.mask = PLAYER_CAT

mask: integer (bitfield)

The mask determines what categories this collider will pass collision filtering. If the mask bits are set for at least one category of a potential collision partner then a collision will be possible

group: integer

The group index is used for another extra layer of collision filtering. If two colliders have the same group and are positive, they will always collide, and if they are both negative then they will never collide

body: physics2d.body

The body this collider belongs to

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

Represents physical contact between two colliders during a collision

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

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

body: physics2d.body

The body of the collider that was hit by the ray

Constraints

class physics2d.joint

The base class of physical constraints between two bodies (i.e. joints)

destroy()

Destroys this joint, removing it in the next simluation step

getReactionForce(invDt)

Gets the reaction force applied to this joint in the previous frame to keep the constraint satisfied

Call with 1/physicsTimestep to get accurate results

Parameters:

invDt – The inverse timestep

getReactionTorque(invDt)

Gets the reaction torque applied to this joint in the previous frame to keep the constraint satisfied

Call with 1/physicsTimestep to get accurate results

Parameters:

invDt – The inverse timestep

enabled: boolean

Enable/disable this joint

destroyed: boolean

Flag set to true if this joint has already been destroyed

collideConnected: boolean

When enabled bodies connected by a joint will collide with each other. Disabled by default

anchorA: vec2

The anchor point for the first body in world space

anchorB: vec2

The anchor point for the second (attached) body in world space

localAnchorA: vec2

The anchor point for the first body in local space

localAnchorB: vec2

The anchor point for the second (attached) body in local space

other: physics2d.body

The other physics body attached to this joint

class physics2d.hinge: joint

A hinge type joint, pinning the bodies together at the respective anchor points, while allowing for free rotation with optional motor and angular limits

referenceAngle: number

The initial relative angle of the two connected bodies

angle: number

The current angle (in degrees) between the two connected bodies relative to the reference angle

speed: number

The current angular speed of the joint (in degrees per second)

useMotor: boolean

Enable/disables the joint motor (off by default)

maxTorque: number

The maximum amount of torque to apply use the motor

motorSpeed: number

The target speed of the motor

useLimit: number

Enables/disables angular joint limits (off by default)

lowerLimit: number

The lower angular rotation limit in degrees (when limits are enabled)

upperLimit: number

The upper angular rotation limit in degrees (when limits are enabled)

class physics2d.slider: joint

A sliding (prismatic) joint allowing for translation along a single axis

referenceAngle: number

The initial relative angle of the two connected bodies

translation: number

The current relative translation between the two bodies along the constained axis

speed: number

The current relative speed between the two bodies along the constrained axis

useMotor: boolean

Enable/disables the joint motor (off by default)

maxForce: number

The maximum amount of force to apply use the motor

motorSpeed: number

The target speed of the motor

useLimit: number

Enables/disables linear joint limits (off by default)

lowerLimit: number

The lower linear translation limit in meters (when limits are enabled)

upperLimit: number

The upper linear translation limit in meters (when limits are enabled)

class physics2d.distance: joint

A distance based joint constraint with spring-like properties and distance based limits

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