Defold C

Defold C++

dmGameObject

dmGameSystem

dmGraphics

dmResource

dmScript

Defold Lua

Extension

firebase

Version

Box2D documentation

Functions for interacting with Box2D.

Version: alpha

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