b2d.world

Namespace: b2d.world Language: Lua Type: Defold Lua File: script_box2d_world_v2.cpp Source: engine/gamesys/src/gamesys/scripts/box2d/v2/script_box2d_world_v2.cpp

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

API

b2d.world.cast_mover

Type: FUNCTION The capsule table has center1, center2, and radius fields. 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 (table) - capsule table with center1, center2, and radius
• translation (vector3) - capsule displacement
• filter (table) (optional) - optional query filter with category_bits and mask_bits

Returns

• fraction (number) - travel fraction before collision

b2d.world.cast_ray

Type: FUNCTION 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 (table) - optional query filter with category_bits, mask_bits, and optional group_index
• max_results (number) - optional maximum result count

Returns

• hits (table) - array of hit tables with fixture, shape, point, normal, and fraction
• stats (table) - table with node_visits and leaf_visits

b2d.world.cast_ray

Type: FUNCTION 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 (table) (optional) - optional query filter with category_bits and mask_bits
• max_results (number) (optional) - optional maximum result count. Omit or pass 0 for unlimited results.

Returns

• hits (table) - array of cast hit tables
• stats (table) - tree stats table

b2d.world.cast_ray_closest

Type: FUNCTION 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 (table) - optional query filter with category_bits, mask_bits, and optional group_index

Returns

• hit (table) - hit table with fixture, shape, point, normal, fraction, node_visits, and leaf_visits, or nil

b2d.world.cast_ray_closest

Type: FUNCTION The translation is the ray displacement from origin.

Parameters

• world (b2World) - world
• origin (vector3) - ray start position
• translation (vector3) - ray displacement
• filter (table) (optional) - optional query filter with category_bits and mask_bits

Returns

• hit (table

  nil) - closest cast hit table with node_visits and leaf_visits, or nil on miss

b2d.world.cast_shape

Type: FUNCTION 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 (table) - shape table using the same format as the shape field in b2d.body.create_fixture
• translation (vector3) - world shape translation
• filter (table) - optional query filter with category_bits, mask_bits, and optional group_index
• max_results (number) - optional maximum result count

Returns

• hits (table) - array of hit tables with fixture, shape, point, normal, and fraction
• stats (table) - table with node_visits and leaf_visits

b2d.world.cast_shape

Type: FUNCTION The shape table uses the same circle, capsule, segment, polygon, and box formats as b2d.body.create_shape. The translation is the shape displacement.

Parameters

• world (b2World) - world
• shape (table) - shape table
• translation (vector3) - shape displacement
• filter (table) (optional) - optional query filter with category_bits and mask_bits
• max_results (number) (optional) - optional maximum result count. Omit or pass 0 for unlimited results.

Returns

• hits (table) - array of cast hit tables
• stats (table) - tree stats table

b2d.world.collide_mover

Type: FUNCTION The capsule table has center1, center2, and radius fields. Plane result tables include shape, normal, offset, and hit.

Parameters

• world (b2World) - world
• capsule (table) - capsule table with center1, center2, and radius
• filter (table) (optional) - optional query filter with category_bits and mask_bits
• max_results (number) (optional) - optional maximum result count. Omit or pass 0 for unlimited results.

Returns

• planes (table) - array of plane result tables

b2d.world.enable_continuous

Type: FUNCTION Enable or disable continuous collision.

Parameters

• world (b2World) - world
• enable (boolean) - true to enable continuous collision

b2d.world.enable_sleeping

Type: FUNCTION Enable or disable world sleeping.

Parameters

• world (b2World) - world
• enable (boolean) - true to allow sleeping

b2d.world.enable_speculative

Type: FUNCTION Enable or disable speculative collision.

Parameters

• world (b2World) - world
• enable (boolean) - true to enable speculative collision

b2d.world.enable_warm_starting

Type: FUNCTION Enable or disable warm starting.

Parameters

• world (b2World) - world
• enable (boolean) - true to enable warm starting

b2d.world.explode

Type: FUNCTION The definition table requires position, radius, falloff, and impulse_per_length. It may also include mask_bits.

Parameters

• world (b2World) - world
• definition (table) - explosion definition

b2d.world.get_awake_body_count

Type: FUNCTION Get the number of awake bodies.

Parameters

• world (b2World) - world

Returns

• count (number) - awake body count

b2d.world.get_counters

Type: FUNCTION The returned table contains body_count, shape_count, contact_count, joint_count, island_count, stack_used, static_tree_height, tree_height, byte_count, task_count, and color_counts.

Parameters

• world (b2World) - world

Returns

• counters (table) - world counters

b2d.world.get_gravity

Type: FUNCTION Get world gravity.

Parameters

• world (b2World) - world

Returns

• gravity (vector3) - gravity vector

b2d.world.get_hit_event_threshold

Type: FUNCTION 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

Type: FUNCTION Get the maximum linear speed.

Parameters

• world (b2World) - world

Returns

• speed (number) - maximum linear speed in project units per second

b2d.world.get_profile

Type: FUNCTION The returned table contains Box2D timing fields including step, pairs, collide, solve, merge_islands, prepare_stages, solve_constraints, prepare_constraints, integrate_velocities, warm_start, solve_impulses, integrate_positions, relax_impulses, apply_restitution, store_impulses, split_islands, transforms, hit_events, refit, bullets, sleep_islands, and sensors.

Parameters

• world (b2World) - world

Returns

• profile (table) - world profiling data

b2d.world.get_restitution_threshold

Type: FUNCTION Get the restitution threshold.

Parameters

• world (b2World) - world

Returns

• threshold (number) - restitution threshold in project units per second

b2d.world.is_continuous_enabled

Type: FUNCTION Get whether continuous collision is enabled.

Parameters

• world (b2World) - world

Returns

• enabled (boolean) - true if continuous collision is enabled

b2d.world.is_locked

Type: FUNCTION 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

Type: FUNCTION Get whether world sleeping is enabled.

Parameters

• world (b2World) - world

Returns

• enabled (boolean) - true if sleeping is enabled

b2d.world.is_valid

Type: FUNCTION 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

Type: FUNCTION Get whether warm starting is enabled.

Parameters

• world (b2World) - world

Returns

• enabled (boolean) - true if warm starting is enabled

b2d.world.overlap_aabb

Type: FUNCTION Overlap an AABB.

Parameters

• world (b2World) - world from b2d.get_world or b2d.body.get_world
• aabb (table) - table with lower and upper vector3 fields
• filter (table) - optional query filter with category_bits, mask_bits, and optional group_index
• max_results (number) - optional maximum result count

Returns

• fixtures (table) - array of fixture info tables
• stats (table) - table with node_visits and leaf_visits

b2d.world.overlap_aabb

Type: FUNCTION The AABB table has lower and upper vector3 fields.

Parameters

• world (b2World) - world
• aabb (table) - AABB table with lower and upper
• filter (table) (optional) - optional query filter with category_bits and mask_bits
• max_results (number) (optional) - optional maximum result count. Omit or pass 0 for unlimited results.

Returns

• hits (table) - array of shape info tables
• stats (table) - tree stats table

b2d.world.overlap_shape

Type: FUNCTION Overlap a shape.

Parameters

• world (b2World) - world from b2d.get_world or b2d.body.get_world
• shape (table) - shape table using the same format as the shape field in b2d.body.create_fixture
• filter (table) - optional query filter with category_bits, mask_bits, and optional group_index
• max_results (number) - optional maximum result count

Returns

• fixtures (table) - array of fixture info tables
• stats (table) - table with node_visits and leaf_visits

b2d.world.overlap_shape

Type: FUNCTION The shape table uses the same circle, capsule, segment, polygon, and box formats as b2d.body.create_shape.

Parameters

• world (b2World) - world
• shape (table) - shape table
• filter (table) (optional) - optional query filter with category_bits and mask_bits
• max_results (number) (optional) - optional maximum result count. Omit or pass 0 for unlimited results.

Returns

• hits (table) - array of shape info tables
• stats (table) - tree stats table

b2d.world.rebuild_static_tree

Type: FUNCTION Rebuild the static broad-phase tree.

Parameters

• world (b2World) - world

b2d.world.set_contact_tuning

Type: FUNCTION 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

Type: FUNCTION Set world gravity.

Parameters

• world (b2World) - world
• gravity (vector3) - gravity vector

b2d.world.set_hit_event_threshold

Type: FUNCTION Set the hit event threshold.

Parameters

• world (b2World) - world
• threshold (number) - hit event threshold in project units per second

b2d.world.set_joint_tuning

Type: FUNCTION 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

Type: FUNCTION Set the maximum linear speed.

Parameters

• world (b2World) - world
• speed (number) - maximum linear speed in project units per second

b2d.world.set_restitution_threshold

Type: FUNCTION Collisions below this relative speed use inelastic collision response.

Parameters

• world (b2World) - world
• threshold (number) - restitution threshold in project units per second