Box2D documentation

Functions for interacting with Box2D.

Version: beta (1.14.0)

TYPES
b2Body	Box2D body
b2d.joint.filter_definition	Box2D filter-joint definition
b2d.shape_create_definition	Box2D 3.x shape creation definition
b2World	Box2D world

RECORDS
b2d.aabb	Box2D axis-aligned bounding box
b2d.chain_definition	Box2D 3.x chain definition
b2d.chain_geometry	Box2D chain geometry
b2d.contact_data	Box2D contact data
b2d.contact_point	Box2D contact manifold point
b2d.explosion_definition	Box2D explosion definition
b2d.filter	Box2D collision filter
b2d.filter_options	Partial Box2D collision filter
b2d.fixture_cast_hit	Box2D 2.x cast hit
b2d.fixture_definition	Box2D 2.x fixture definition
b2d.fixture_info	Box2D 2.x fixture information
b2d.joint.distance_definition	Box2D distance-joint definition
b2d.joint.friction_definition	Box2D friction-joint definition
b2d.joint.gear_definition	Box2D gear-joint definition
b2d.joint.motor_definition	Box2D motor-joint definition
b2d.joint.mouse_definition	Box2D mouse-joint definition
b2d.joint.prismatic_definition	Box2D prismatic-joint definition
b2d.joint.pulley_definition	Box2D pulley-joint definition
b2d.joint.revolute_definition	Box2D revolute-joint definition
b2d.joint.rope_definition	Box2D rope-joint definition
b2d.joint.weld_definition	Box2D weld-joint definition
b2d.joint.wheel_definition	Box2D wheel-joint definition
b2d.mass_data	Box2D mass data
b2d.mover_capsule	Box2D mover capsule
b2d.mover_plane	Box2D mover collision plane
b2d.query_filter	Box2D world-query filter
b2d.shape_cast_hit	Box2D 3.x cast hit
b2d.shape_cast_output	Direct Box2D shape cast result
b2d.shape_info	Box2D 3.x shape information
b2d.transform	Box2D transform
b2d.tree_stats	Box2D broad-phase query statistics
b2d.version_info	Box2D version information
b2d.world_counters	Box2D world counters
b2d.world_profile	Box2D world profiling data

FUNCTIONS
b2d.get_body()	Get the Box2D body from a collision object
b2d.get_gameobject_id()	Get the game object id associated with a Box2D body
b2d.get_version()	Get the Box2D version information for the active backend.
b2d.get_world()	Get the Box2D world from the current collection

Types

b2Body

b2Body = userdata

An opaque handle to the native Box2D body of a collision-object component. Obtain it with b2d.get_body and pass it to functions in b2d.body. The collision object owns the body, so the handle becomes invalid when its component or game object is deleted.

EXAMPLES

local body = b2d.get_body("#collisionobject")
if body then
    print(b2d.body.get_position(body))
end

b2d.joint.filter_definition

b2d.joint.filter_definition = {}

The optional definition passed to b2d.joint.create_filter. Filter joints currently have no configurable fields, so omit the argument or pass an empty table. The type is reserved for future options.

EXAMPLES

local body_a = b2d.get_body("#collisionobject_a")
local body_b = b2d.get_body("#collisionobject_b")
local joint = b2d.joint.create_filter(body_a, body_b, {})

b2d.shape_create_definition

b2d.shape_create_definition = { shape:b2d.shape.definition, density?:number, friction?:number, restitution?:number, material?:integer, sensor?:boolean, is_sensor?:boolean, filter?:b2d.filter } | { type:b2d.shape.SHAPE_TYPE, radius?:number, center?:vector3, center1?:vector3, center2?:vector3, v0?:vector3, v1?:vector3, v2?:vector3, v3?:vector3, hx?:number, hy?:number, angle?:number, vertices?:vector3[], density?:number, friction?:number, restitution?:number, material?:integer, sensor?:boolean, is_sensor?:boolean, filter?:b2d.filter }

Geometry and material properties accepted by b2d.body.create_shape. The geometry can be supplied in the shape field as a b2d.shape.definition, or its fields can be placed directly in this table. Material properties such as density, friction, restitution, and filter are optional.

EXAMPLES

Create a circular shape using an inline geometry definition:

local body = b2d.get_body("#collisionobject")
local shape = b2d.body.create_shape(body, {
    type = b2d.shape.SHAPE_TYPE_CIRCLE,
    radius = 16,
    density = 1,
    friction = 0.4,
})

b2World

b2World = userdata

An opaque handle to the Box2D physics world owned by the current collection. Obtain it with b2d.get_world and pass it to functions in b2d.world. The engine creates and destroys the world together with the collection; it cannot be constructed directly from Lua.

EXAMPLES

local world = b2d.get_world()
if world then
    pprint(world)
end

Records

b2d.aabb

Box2D axis-aligned bounding box

FIELDS

`lower`	`vector3`	Lower bound.
`upper`	`vector3`	Upper bound.

b2d.chain_definition

Box2D 3.x chain definition

FIELDS

`vertices`	`vector3[]`	Chain vertices.
`[loop]`	`boolean`	Whether the chain is closed.
`[prev_vertex]`	`vector3`	Ghost vertex preceding an open chain.
`[next_vertex]`	`vector3`	Ghost vertex following an open chain.
`[friction]`	`number`	Segment friction.
`[restitution]`	`number`	Segment restitution.
`[material]`	`integer`	Segment material identifier.
`[filter]`	`b2d.filter_options`	Collision filter fields to override.
`[enable_sensor_events]`	`boolean`	Whether to enable sensor events.

b2d.chain_geometry

Box2D chain geometry

FIELDS

`loop`	`boolean`	Whether the chain is closed.
`segment_count`	`integer`	Number of chain segments.
`vertices`	`vector3[]`	Chain vertices.
`[prev_vertex]`	`vector3`	Ghost vertex preceding an open chain.
`[next_vertex]`	`vector3`	Ghost vertex following an open chain.

b2d.contact_data

Box2D contact data

FIELDS

`shape_a`	`b2d.shape_info`	First contact shape.
`shape_b`	`b2d.shape_info`	Second contact shape.
`normal`	`vector3`	Contact normal.
`rolling_impulse`	`number`	Rolling resistance impulse.
`point_count`	`integer`	Number of manifold points.
`points`	`b2d.contact_point[]`	Contact manifold points.

b2d.contact_point

Box2D contact manifold point

FIELDS

`point`	`vector3`	World contact point.
`anchor_a`	`vector3`	Contact anchor on the first body.
`anchor_b`	`vector3`	Contact anchor on the second body.
`separation`	`number`	Contact separation.
`normal_impulse`	`number`	Normal impulse.
`tangent_impulse`	`number`	Tangent impulse.
`total_normal_impulse`	`number`	Total normal impulse.
`normal_velocity`	`number`	Relative normal velocity.
`id`	`integer`	Contact point identifier.
`persisted`	`boolean`	Whether the point persisted from the previous step.

b2d.explosion_definition

Box2D explosion definition

FIELDS

`position`	`vector3`	Explosion center.
`radius`	`number`	Explosion radius.
`falloff`	`number`	Distance over which the impulse falls off.
`impulse_per_length`	`number`	Impulse applied per unit length.
`[mask_bits]`	`integer`	Optional collision mask.

b2d.filter

Box2D collision filter

FIELDS

`category_bits`	`integer`	Collision category bits.
`mask_bits`	`integer`	Collision mask bits.
`group_index`	`integer`	Collision group index.

Partial Box2D collision filter

FIELDS

`[category_bits]`	`integer`	Collision category bits.
`[mask_bits]`	`integer`	Collision mask bits.
`[group_index]`	`integer`	Collision group index.

b2d.fixture_cast_hit

Box2D 2.x cast hit

FIELDS

`fixture`	`b2d.fixture_info`	Hit fixture.
`shape`	`b2d.fixture_info`	Hit fixture child shape.
`point`	`vector3`	Hit point.
`normal`	`vector3`	Hit normal.
`fraction`	`number`	Hit fraction.
`[node_visits]`	`integer`	Number of tree nodes visited by a closest query.
`[leaf_visits]`	`integer`	Number of tree leaves visited by a closest query.

b2d.fixture_definition

Box2D 2.x fixture definition

FIELDS

`shape`	`b2d.shape.definition`	Shape definition.
`[friction]`	`number`	Fixture friction.
`[restitution]`	`number`	Fixture restitution.
`[density]`	`number`	Fixture density.
`[sensor]`	`boolean`	Whether the fixture is a sensor.
`[is_sensor]`	`boolean`	Alias for `sensor`.
`[filter]`	`b2d.filter`	Collision filter.

b2d.fixture_info

Box2D 2.x fixture information

FIELDS

`[body]`	`b2Body`	Owning body, when returned from a world query.
`index`	`integer`	Fixture index on the body.
`[child_index]`	`integer`	Child-shape index, when returned from a world query.
`type`	`b2d.shape.SHAPE_TYPE`	Shape type.
`sensor`	`boolean`	Whether the fixture is a sensor.
`density`	`number`	Fixture density.
`friction`	`number`	Fixture friction.
`restitution`	`number`	Fixture restitution.
`child_count`	`integer`	Number of child shapes.

b2d.joint.distance_definition

Box2D distance-joint definition

FIELDS

`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[length]`	`number`	Rest length.
`[min_length]`	`number`	Minimum length.
`[max_length]`	`number`	Maximum length.
`[enable_spring]`	`boolean`	Whether the spring is enabled.
`[hertz]`	`number`	Spring frequency in hertz.
`[frequency]`	`number`	Legacy spring frequency alias.
`[damping_ratio]`	`number`	Spring damping ratio.
`[damping]`	`number`	Legacy spring damping-ratio alias.
`[enable_limit]`	`boolean`	Whether length limits are enabled.
`[enable_motor]`	`boolean`	Whether the motor is enabled.
`[max_motor_force]`	`number`	Maximum motor force.
`[motor_speed]`	`number`	Motor speed.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.friction_definition

Box2D friction-joint definition

FIELDS

`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[max_force]`	`number`	Maximum friction force.
`[max_torque]`	`number`	Maximum friction torque.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.gear_definition

Box2D gear-joint definition

FIELDS

`[ratio]`	`number`	Gear ratio.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.motor_definition

Box2D motor-joint definition

FIELDS

`[linear_offset]`	`vector3`	Linear target offset.
`[angular_offset]`	`number`	Angular target offset.
`[max_force]`	`number`	Maximum motor force.
`[max_torque]`	`number`	Maximum motor torque.
`[correction_factor]`	`number`	Position correction factor.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.mouse_definition

Box2D mouse-joint definition

FIELDS

`[target]`	`vector3`	Target position.
`[max_force]`	`number`	Maximum force.
`[hertz]`	`number`	Spring frequency in hertz.
`[frequency]`	`number`	Legacy spring frequency alias.
`[damping_ratio]`	`number`	Spring damping ratio.
`[damping]`	`number`	Legacy spring damping-ratio alias.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.prismatic_definition

Box2D prismatic-joint definition

FIELDS

`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[local_axis_a]`	`vector3`	Local translation axis on the first body.
`[reference_angle]`	`number`	Reference angle.
`[enable_spring]`	`boolean`	Whether the spring is enabled.
`[hertz]`	`number`	Spring frequency in hertz.
`[frequency]`	`number`	Legacy spring frequency alias.
`[damping_ratio]`	`number`	Spring damping ratio.
`[damping]`	`number`	Legacy spring damping-ratio alias.
`[enable_limit]`	`boolean`	Whether translation limits are enabled.
`[lower_translation]`	`number`	Lower translation limit.
`[upper_translation]`	`number`	Upper translation limit.
`[enable_motor]`	`boolean`	Whether the motor is enabled.
`[max_motor_force]`	`number`	Maximum motor force.
`[motor_speed]`	`number`	Motor speed.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.pulley_definition

Box2D pulley-joint definition

FIELDS

`[ground_anchor_a]`	`vector3`	First ground anchor.
`[ground_anchor_b]`	`vector3`	Second ground anchor.
`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[length_a]`	`number`	First segment length.
`[length_b]`	`number`	Second segment length.
`[ratio]`	`number`	Pulley ratio.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.revolute_definition

Box2D revolute-joint definition

FIELDS

`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[reference_angle]`	`number`	Reference angle.
`[enable_spring]`	`boolean`	Whether the spring is enabled.
`[hertz]`	`number`	Spring frequency in hertz.
`[frequency]`	`number`	Legacy spring frequency alias.
`[damping_ratio]`	`number`	Spring damping ratio.
`[damping]`	`number`	Legacy spring damping-ratio alias.
`[enable_limit]`	`boolean`	Whether angular limits are enabled.
`[lower_angle]`	`number`	Lower angular limit.
`[upper_angle]`	`number`	Upper angular limit.
`[enable_motor]`	`boolean`	Whether the motor is enabled.
`[max_motor_torque]`	`number`	Maximum motor torque.
`[motor_speed]`	`number`	Motor speed.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.rope_definition

Box2D rope-joint definition

FIELDS

`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[max_length]`	`number`	Maximum rope length.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.weld_definition

Box2D weld-joint definition

FIELDS

`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[reference_angle]`	`number`	Reference angle.
`[hertz]`	`number`	Legacy spring frequency in hertz.
`[frequency]`	`number`	Legacy spring frequency.
`[damping_ratio]`	`number`	Legacy spring damping ratio.
`[damping]`	`number`	Legacy spring damping-ratio alias.
`[linear_hertz]`	`number`	Linear spring frequency in hertz.
`[angular_hertz]`	`number`	Angular spring frequency in hertz.
`[linear_damping_ratio]`	`number`	Linear damping ratio.
`[angular_damping_ratio]`	`number`	Angular damping ratio.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.joint.wheel_definition

Box2D wheel-joint definition

FIELDS

`[local_anchor_a]`	`vector3`	Local anchor on the first body.
`[local_anchor_b]`	`vector3`	Local anchor on the second body.
`[local_axis_a]`	`vector3`	Local suspension axis on the first body.
`[enable_spring]`	`boolean`	Whether the spring is enabled.
`[hertz]`	`number`	Spring frequency in hertz.
`[frequency]`	`number`	Legacy spring frequency alias.
`[damping_ratio]`	`number`	Spring damping ratio.
`[damping]`	`number`	Legacy spring damping-ratio alias.
`[enable_limit]`	`boolean`	Whether translation limits are enabled.
`[lower_translation]`	`number`	Lower translation limit.
`[upper_translation]`	`number`	Upper translation limit.
`[enable_motor]`	`boolean`	Whether the motor is enabled.
`[max_motor_torque]`	`number`	Maximum motor torque.
`[motor_speed]`	`number`	Motor speed.
`[collide_connected]`	`boolean`	Whether connected bodies collide.

b2d.mass_data

Mass properties for a Box2D body or shape.

FIELDS

`mass`	`number`	Body mass, usually in kilograms.
`center`	`vector3`	Local center of mass.
`inertia`	`number`	Rotational inertia about the local origin.

b2d.mover_capsule

Box2D mover capsule

FIELDS

`center1`	`vector3`	First capsule center.
`center2`	`vector3`	Second capsule center.
`radius`	`number`	Capsule radius.

b2d.mover_plane

Box2D mover collision plane

FIELDS

`shape`	`b2d.shape_info`	Colliding shape.
`normal`	`vector3`	Plane normal.
`offset`	`number`	Plane offset.
`hit`	`boolean`	Whether the mover hit the plane.

b2d.query_filter

Box2D world-query filter

FIELDS

`[category_bits]`	`integer`	Optional collision category bits.
`[mask_bits]`	`integer`	Optional collision mask bits.
`[group_index]`	`integer`	Optional collision group index. Supported by the Box2D 2.x backend.

b2d.shape_cast_hit

Box2D 3.x cast hit

FIELDS

`shape`	`b2d.shape_info`	Hit shape.
`point`	`vector3`	Hit point.
`normal`	`vector3`	Hit normal.
`fraction`	`number`	Hit fraction.
`[node_visits]`	`integer`	Number of tree nodes visited by a closest query.
`[leaf_visits]`	`integer`	Number of tree leaves visited by a closest query.

b2d.shape_cast_output

Direct Box2D shape cast result

FIELDS

`point`	`vector3`	Hit point.
`normal`	`vector3`	Hit normal.
`fraction`	`number`	Hit fraction.
`iterations`	`integer`	Number of cast iterations.

b2d.shape_info

Box2D 3.x shape information

FIELDS

`index`	`integer`	Shape index on the body.
`shape_id`	`b2Shape`	Shape handle.
`type`	`b2d.shape.SHAPE_TYPE`	Shape type.
`sensor`	`boolean`	Whether the shape is a sensor.
`density`	`number`	Shape density.
`friction`	`number`	Shape friction.
`restitution`	`number`	Shape restitution.
`material`	`integer`	Shape material identifier.
`child_count`	`integer`	Number of child shapes.
`is_chain_segment`	`boolean`	Whether the shape belongs to a chain.

b2d.transform

World transform for a Box2D body.

FIELDS

`position`	`vector3`	World position of the body origin.
`angle`	`number`	World rotation angle in radians.

b2d.tree_stats

Box2D broad-phase query statistics

FIELDS

`node_visits`	`integer`	Number of tree nodes visited.
`leaf_visits`	`integer`	Number of tree leaves visited.

b2d.version_info

Box2D version information

FIELDS

`version`	`string`	Full Box2D version string.
`major`	`integer`	Major version number.
`middle`	`integer`	Middle version number.
`minor`	`integer`	Minor version number.

b2d.world_counters

Box2D world counters

FIELDS

`body_count`	`integer`	Number of bodies.
`shape_count`	`integer`	Number of shapes.
`contact_count`	`integer`	Number of contacts.
`joint_count`	`integer`	Number of joints.
`island_count`	`integer`	Number of islands.
`stack_used`	`integer`	Stack bytes in use.
`static_tree_height`	`integer`	Static broad-phase tree height.
`tree_height`	`integer`	Dynamic broad-phase tree height.
`byte_count`	`integer`	Allocated byte count.
`task_count`	`integer`	Number of tasks.
`color_counts`	`integer[]`	Constraint graph color counts.

b2d.world_profile

Box2D world profiling data

FIELDS

`step`	`number`	Total step time.
`pairs`	`number`	Pair update time.
`collide`	`number`	Collision time.
`solve`	`number`	Solver time.
`merge_islands`	`number`	Island merge time.
`prepare_stages`	`number`	Stage preparation time.
`solve_constraints`	`number`	Constraint solver time.
`prepare_constraints`	`number`	Constraint preparation time.
`integrate_velocities`	`number`	Velocity integration time.
`warm_start`	`number`	Warm-start time.
`solve_impulses`	`number`	Impulse solver time.
`integrate_positions`	`number`	Position integration time.
`relax_impulses`	`number`	Impulse relaxation time.
`apply_restitution`	`number`	Restitution time.
`store_impulses`	`number`	Impulse storage time.
`split_islands`	`number`	Island splitting time.
`transforms`	`number`	Transform update time.
`hit_events`	`number`	Hit-event generation time.
`refit`	`number`	Tree refit time.
`bullets`	`number`	Bullet processing time.
`sleep_islands`	`number`	Island sleeping time.
`sensors`	`number`	Sensor processing time.

Functions

b2d.get_body()

b2d.get_body(url:string|hash|url)→body:b2Body|nil

Get the Box2D body from a collision object

PARAMETERS

url string
hash
url the url to the game object collision component

RETURNS

body b2Body
nil the body if successful. Otherwise nil.

b2d.get_gameobject_id()

b2d.get_gameobject_id(body:b2Body)→id:hash|nil

Returns the id of the game object that owns the body's collision-object component. Raises a Lua error if the body handle is invalid or its game object has been deleted.

PARAMETERS

body b2Body the Box2D body

RETURNS

id hash
nil the game object id, or nil if the body has no associated game object

EXAMPLES

local body = b2d.get_body("#collisionobject")
local id = b2d.get_gameobject_id(body)

b2d.get_version()

b2d.get_version()→info:b2d.version_info

Get the Box2D version information for the active backend.

PARAMETERS

None

RETURNS

info b2d.version_info version information

b2d.get_world()

b2d.get_world()→world:b2World|nil

Get the Box2D world from the current collection

PARAMETERS

None

RETURNS

world b2World
nil the world if successful. Otherwise nil.