DEFOLD
Home Features Showcase Learn Asset Portal Community Support API Free Download Donate  

Defold Learn logo

Defold Learn logo

Box2D b2World documentation

Query and cast functions for the Defold-owned Box2D v2 world.

Version: alpha

FUNCTIONS
b2d.world.cast_mover() Cast a mover capsule.
b2d.world.cast_ray() Cast a ray.
b2d.world.cast_ray() Cast a ray and collect hits.
b2d.world.cast_ray_closest() Cast a ray and return the closest hit.
b2d.world.cast_ray_closest() Cast a ray and return the closest hit.
b2d.world.cast_shape() Cast a shape.
b2d.world.cast_shape() Cast a shape and collect hits.
b2d.world.collide_mover() Collide a mover capsule against the world.
b2d.world.enable_continuous() Enable or disable continuous collision.
b2d.world.enable_sleeping() Enable or disable world sleeping.
b2d.world.enable_speculative() Enable or disable speculative collision.
b2d.world.enable_warm_starting() Enable or disable warm starting.
b2d.world.explode() Apply an explosion impulse.
b2d.world.get_awake_body_count() Get the number of awake bodies.
b2d.world.get_counters() Get world counters.
b2d.world.get_gravity() Get world gravity.
b2d.world.get_hit_event_threshold() Get the hit event threshold.
b2d.world.get_maximum_linear_speed() Get the maximum linear speed.
b2d.world.get_profile() Get world profiling data.
b2d.world.get_restitution_threshold() Get the restitution threshold.
b2d.world.is_continuous_enabled() Get whether continuous collision is enabled.
b2d.world.is_locked() Check whether the world is locked.
b2d.world.is_sleeping_enabled() Get whether world sleeping is enabled.
b2d.world.is_valid() Check whether a world handle is valid.
b2d.world.is_warm_starting_enabled() Get whether warm starting is enabled.
b2d.world.overlap_aabb() Overlap an AABB.
b2d.world.overlap_aabb() Find shapes overlapping an AABB.
b2d.world.overlap_shape() Overlap a shape.
b2d.world.overlap_shape() Find shapes overlapping a shape proxy.
b2d.world.rebuild_static_tree() Rebuild the static broad-phase tree.
b2d.world.set_contact_tuning() Set contact solver tuning.
b2d.world.set_gravity() Set world gravity.
b2d.world.set_hit_event_threshold() Set the hit event threshold.
b2d.world.set_joint_tuning() Set joint solver tuning.
b2d.world.set_maximum_linear_speed() Set the maximum linear speed.
b2d.world.set_restitution_threshold() Set the restitution threshold.

Functions

b2d.world.cast_mover()

b2d.world.cast_mover(world:b2World, capsule:b2d.mover_capsule, translation:vector3, [filter:b2d.query_filter])→fraction:number

The return value is the fraction of translation that can be traveled before collision, or 1 if there is no hit.

PARAMETERS

world b2World
 world
capsule b2d.mover_capsule
 mover capsule
translation vector3
 capsule displacement
[filter] b2d.query_filter
 optional query filter

RETURNS

fraction number
 travel fraction before collision

b2d.world.cast_ray()

b2d.world.cast_ray(world:b2World, origin:vector3, translation:vector3, [filter:b2d.query_filter], [max_results:integer])→(hits:b2d.fixture_cast_hit[], stats:b2d.tree_stats)

Cast a ray.

PARAMETERS

world b2World
 world from b2d.get_world or b2d.body.get_world
origin vector3
 world ray origin
translation vector3
 world ray translation
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count

RETURNS

hits b2d.fixture_cast_hit[]
 ray-cast hits
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.cast_ray()

b2d.world.cast_ray(world:b2World, origin:vector3, translation:vector3, [filter:b2d.query_filter], [max_results:integer])→(hits:b2d.shape_cast_hit[], stats:b2d.tree_stats)

The translation is the ray displacement from origin. Result order is not guaranteed by Box2D.

PARAMETERS

world b2World
 world
origin vector3
 ray start position
translation vector3
 ray displacement
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count. Omit or pass 0 for unlimited results.

RETURNS

hits b2d.shape_cast_hit[]
 ray-cast hits
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.cast_ray_closest()

b2d.world.cast_ray_closest(world:b2World, origin:vector3, translation:vector3, [filter:b2d.query_filter])→hit:b2d.fixture_cast_hit|nil

Cast a ray and return the closest hit.

PARAMETERS

world b2World
 world from b2d.get_world or b2d.body.get_world
origin vector3
 world ray origin
translation vector3
 world ray translation
[filter] b2d.query_filter
 optional query filter

RETURNS

hit b2d.fixture_cast_hit
nil
 closest hit, or nil

b2d.world.cast_ray_closest()

b2d.world.cast_ray_closest(world:b2World, origin:vector3, translation:vector3, [filter:b2d.query_filter])→hit:b2d.shape_cast_hit|nil

The translation is the ray displacement from origin.

PARAMETERS

world b2World
 world
origin vector3
 ray start position
translation vector3
 ray displacement
[filter] b2d.query_filter
 optional query filter

RETURNS

hit b2d.shape_cast_hit
nil
 closest hit, or nil

b2d.world.cast_shape()

b2d.world.cast_shape(world:b2World, shape:b2d.shape.definition, translation:vector3, [filter:b2d.query_filter], [max_results:integer])→(hits:b2d.fixture_cast_hit[], stats:b2d.tree_stats)

Uses Box2D v2 time-of-impact for fixture child shapes that support distance proxies. Grid fixture children are skipped.

PARAMETERS

world b2World
 world from b2d.get_world or b2d.body.get_world
shape b2d.shape.definition
 query shape
translation vector3
 world shape translation
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count

RETURNS

hits b2d.fixture_cast_hit[]
 shape-cast hits
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.cast_shape()

b2d.world.cast_shape(world:b2World, shape:b2d.shape.definition, translation:vector3, [filter:b2d.query_filter], [max_results:integer])→(hits:b2d.shape_cast_hit[], stats:b2d.tree_stats)

The translation is the shape displacement.

PARAMETERS

world b2World
 world
shape b2d.shape.definition
 cast shape
translation vector3
 shape displacement
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count. Omit or pass 0 for unlimited results.

RETURNS

hits b2d.shape_cast_hit[]
 shape-cast hits
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.collide_mover()

b2d.world.collide_mover(world:b2World, capsule:b2d.mover_capsule, [filter:b2d.query_filter], [max_results:integer])→planes:b2d.mover_plane[]

Collide a mover capsule against the world.

PARAMETERS

world b2World
 world
capsule b2d.mover_capsule
 mover capsule
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count. Omit or pass 0 for unlimited results.

RETURNS

planes b2d.mover_plane[]
 collision planes

b2d.world.enable_continuous()

b2d.world.enable_continuous(world:b2World, enable:boolean)

Enable or disable continuous collision.

PARAMETERS

world b2World
 world
enable boolean
 true to enable continuous collision

b2d.world.enable_sleeping()

b2d.world.enable_sleeping(world:b2World, enable:boolean)

Enable or disable world sleeping.

PARAMETERS

world b2World
 world
enable boolean
 true to allow sleeping

b2d.world.enable_speculative()

b2d.world.enable_speculative(world:b2World, enable:boolean)

Enable or disable speculative collision.

PARAMETERS

world b2World
 world
enable boolean
 true to enable speculative collision

b2d.world.enable_warm_starting()

b2d.world.enable_warm_starting(world:b2World, enable:boolean)

Enable or disable warm starting.

PARAMETERS

world b2World
 world
enable boolean
 true to enable warm starting

b2d.world.explode()

b2d.world.explode(world:b2World, definition:b2d.explosion_definition)

Apply an explosion impulse.

PARAMETERS

world b2World
 world
definition b2d.explosion_definition
 explosion definition

b2d.world.get_awake_body_count()

b2d.world.get_awake_body_count(world:b2World)→count:integer

Get the number of awake bodies.

PARAMETERS

world b2World
 world

RETURNS

count integer
 awake body count

b2d.world.get_counters()

b2d.world.get_counters(world:b2World)→counters:b2d.world_counters

Get world counters.

PARAMETERS

world b2World
 world

RETURNS

counters b2d.world_counters
 world counters

b2d.world.get_gravity()

b2d.world.get_gravity(world:b2World)→gravity:vector3

Get world gravity.

PARAMETERS

world b2World
 world

RETURNS

gravity vector3
 gravity vector

b2d.world.get_hit_event_threshold()

b2d.world.get_hit_event_threshold(world:b2World)→threshold:number

Get the hit event threshold.

PARAMETERS

world b2World
 world

RETURNS

threshold number
 hit event threshold in project units per second

b2d.world.get_maximum_linear_speed()

b2d.world.get_maximum_linear_speed(world:b2World)→speed:number

Get the maximum linear speed.

PARAMETERS

world b2World
 world

RETURNS

speed number
 maximum linear speed in project units per second

b2d.world.get_profile()

b2d.world.get_profile(world:b2World)→profile:b2d.world_profile

Get world profiling data.

PARAMETERS

world b2World
 world

RETURNS

profile b2d.world_profile
 world profiling data

b2d.world.get_restitution_threshold()

b2d.world.get_restitution_threshold(world:b2World)→threshold:number

Get the restitution threshold.

PARAMETERS

world b2World
 world

RETURNS

threshold number
 restitution threshold in project units per second

b2d.world.is_continuous_enabled()

b2d.world.is_continuous_enabled(world:b2World)→enabled:boolean

Get whether continuous collision is enabled.

PARAMETERS

world b2World
 world

RETURNS

enabled boolean
 true if continuous collision is enabled

b2d.world.is_locked()

b2d.world.is_locked(world:b2World)→locked:boolean

The world is locked during callbacks and some simulation phases. Functions marked as locked during callbacks cannot be called while this returns true.

PARAMETERS

world b2World
 world

RETURNS

locked boolean
 true if the world is locked

b2d.world.is_sleeping_enabled()

b2d.world.is_sleeping_enabled(world:b2World)→enabled:boolean

Get whether world sleeping is enabled.

PARAMETERS

world b2World
 world

RETURNS

enabled boolean
 true if sleeping is enabled

b2d.world.is_valid()

b2d.world.is_valid(world:b2World)→valid:boolean

Check whether a world handle is valid.

PARAMETERS

world b2World
 world

RETURNS

valid boolean
 true if the world handle is valid

b2d.world.is_warm_starting_enabled()

b2d.world.is_warm_starting_enabled(world:b2World)→enabled:boolean

Get whether warm starting is enabled.

PARAMETERS

world b2World
 world

RETURNS

enabled boolean
 true if warm starting is enabled

b2d.world.overlap_aabb()

b2d.world.overlap_aabb(world:b2World, aabb:b2d.aabb, [filter:b2d.query_filter], [max_results:integer])→(fixtures:b2d.fixture_info[], stats:b2d.tree_stats)

Overlap an AABB.

PARAMETERS

world b2World
 world from b2d.get_world or b2d.body.get_world
aabb b2d.aabb
 query bounds
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count

RETURNS

fixtures b2d.fixture_info[]
 overlapping fixtures
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.overlap_aabb()

b2d.world.overlap_aabb(world:b2World, aabb:b2d.aabb, [filter:b2d.query_filter], [max_results:integer])→(hits:b2d.shape_info[], stats:b2d.tree_stats)

Find shapes overlapping an AABB.

PARAMETERS

world b2World
 world
aabb b2d.aabb
 query bounds
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count. Omit or pass 0 for unlimited results.

RETURNS

hits b2d.shape_info[]
 overlapping shapes
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.overlap_shape()

b2d.world.overlap_shape(world:b2World, shape:b2d.shape.definition, [filter:b2d.query_filter], [max_results:integer])→(fixtures:b2d.fixture_info[], stats:b2d.tree_stats)

Overlap a shape.

PARAMETERS

world b2World
 world from b2d.get_world or b2d.body.get_world
shape b2d.shape.definition
 query shape
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count

RETURNS

fixtures b2d.fixture_info[]
 overlapping fixtures
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.overlap_shape()

b2d.world.overlap_shape(world:b2World, shape:b2d.shape.definition, [filter:b2d.query_filter], [max_results:integer])→(hits:b2d.shape_info[], stats:b2d.tree_stats)

Find shapes overlapping a shape proxy.

PARAMETERS

world b2World
 world
shape b2d.shape.definition
 query shape
[filter] b2d.query_filter
 optional query filter
[max_results] integer
 optional maximum result count. Omit or pass 0 for unlimited results.

RETURNS

hits b2d.shape_info[]
 overlapping shapes
stats b2d.tree_stats
 broad-phase query statistics

b2d.world.rebuild_static_tree()

b2d.world.rebuild_static_tree(world:b2World)

Rebuild the static broad-phase tree.

PARAMETERS

world b2World
 world

b2d.world.set_contact_tuning()

b2d.world.set_contact_tuning(world:b2World, hertz:number, damping_ratio:number, pushout:number)

Set contact solver tuning.

PARAMETERS

world b2World
 world
hertz number
 contact stiffness frequency in hertz
damping_ratio number
 contact damping ratio
pushout number
 pushout velocity in project units per second

b2d.world.set_gravity()

b2d.world.set_gravity(world:b2World, gravity:vector3)

Set world gravity.

PARAMETERS

world b2World
 world
gravity vector3
 gravity vector

b2d.world.set_hit_event_threshold()

b2d.world.set_hit_event_threshold(world:b2World, threshold:number)

Set the hit event threshold.

PARAMETERS

world b2World
 world
threshold number
 hit event threshold in project units per second

b2d.world.set_joint_tuning()

b2d.world.set_joint_tuning(world:b2World, hertz:number, damping_ratio:number)

Set joint solver tuning.

PARAMETERS

world b2World
 world
hertz number
 joint stiffness frequency in hertz
damping_ratio number
 joint damping ratio

b2d.world.set_maximum_linear_speed()

b2d.world.set_maximum_linear_speed(world:b2World, speed:number)

Set the maximum linear speed.

PARAMETERS

world b2World
 world
speed number
 maximum linear speed in project units per second

b2d.world.set_restitution_threshold()

b2d.world.set_restitution_threshold(world:b2World, threshold:number)

Collisions below this relative speed use inelastic collision response.

PARAMETERS

world b2World
 world
threshold number
 restitution threshold in project units per second