bullet3d.world16 new
Read and tune the Bullet dynamics world owned by the current collection. Defold remains responsible for world lifetime, stepping, collision objects, callbacks, and debug drawing.
World and collision-object values returned by this API are borrowed, generational handles. They become invalid when their collection or owning game object is deleted and must not be retained as native pointers.
All positions, distances, translations, dimensions and contact distances use
Defold world units. The binding converts them using physics.scale. Rotations
and unit normals are not scaled. Query functions refresh Bullet broadphase
AABBs before execution, so collision-object transform changes are visible.
Query filters are optional tables with these fields:
category_bits
: [type:integer] unsigned 16-bit category bits, default 65535
mask_bits
: [type:integer] unsigned 16-bit mask bits, default 65535
include_triggers
: [type:boolean] include objects without contact response, default true
ignore
: [type:btCollisionObject|btCollisionObject[]] one collision-object handle or an array of handles to exclude
report_initial_overlaps
: [type:boolean] report shapes overlapping the cast origin as synthesized fraction-zero hits, default false
report_initial_overlaps is a bullet3d.world query option only. It does
not change physics.raycast() or either Box2D backend.
Category and mask checks are reciprocal: the query category must match the object's mask and the object's category must match the query mask.
Temporary query shapes use the same geometry fields as
[ref:bullet3d.shape.get_shape]:
a sphere has type and diameter, a box has type and dimensions, a
Y-axis capsule has type, diameter and height, and a convex hull has
type and a vertices array with at least four vector3 values. The type
is one of the bullet3d.shape.SHAPE_TYPE_* constants. Every shape can specify
position and rotation; their defaults are zero and the identity rotation.
Cast shapes can also specify target_rotation, which defaults to rotation.
Capsule height is the length of the cylindrical middle section; total
end-to-end height is height + diameter. Query sizes are always expressed
in Defold world units. Except for triangle meshes, a table returned by
bullet3d.shape.get_shape can be reused directly after adding the desired
query transform fields. Queries accept only sphere, box, capsule, and hull.
Hull vertices describe a convex hull; concave input is convexified by Bullet.
All query vectors and scalar sizes must be finite. Diameters, dimensions and
capsule heights must be greater than zero; hulls require at least four finite
vertices. Cast translations must be finite and non-zero. Query rotations
must be finite, non-zero quaternions and are normalized by the binding. AABB
lower bounds must not exceed their corresponding upper bounds.
Overlap and enumeration results are arrays of btCollisionObject handles.
Cast results are tables containing object, point, normal, fraction,
initial_overlap, and inside. shape_index is present when Bullet reports
a compound child and is one-based. Cast arrays are sorted by ascending
fraction. fraction is in [0, 1] along the supplied translation. For native
hits, normal is the hit object's outward unit surface normal; synthesized
initial-overlap hits use a zero normal. inside is true for a synthesized
ray-origin hit when Bullet reports signed contact distance less than or equal
to zero. It denotes initial contact or penetration rather than strict
geometric containment, and exact-surface cases follow Bullet's contact
tolerance. Shape-cast initial overlaps set only initial_overlap.
Contact results contain object_a, object_b, position_a, position_b,
normal_on_b, and signed distance. Positions are points on their named
objects, and normal_on_b points from object B toward object A. A negative
distance is penetration and a small positive distance is Bullet's contact
margin. Object order is always normalized to the order supplied by the caller.
max_results is optional. Zero or omission means unlimited results. A
negative value is an error. Broadphase overlaps, native world enumeration,
contacts, and equal-fraction cast hits have unspecified order. A capped query
can therefore return a different equal-priority subset after world changes.
Synchronous queries execute immediately and do not advance simulation.
Async casts are deferred until after the next physics step. They execute on
the main thread rather than a worker thread, and all queued casts for one
world share one broadphase AABB refresh. Every cast in the batch completes
before any callback runs, so callback mutations cannot affect other query
computations in that batch. Deferral avoids blocking the Lua call site but
does not remove the cast work from the frame.
Native fraction-zero cast callbacks are suppressed. Starting overlaps are
omitted by default, or reported through the exact, deduplicated synthesis
enabled by report_initial_overlaps; this avoids direction-dependent Bullet
results for casts that start touching or penetrating another object.
Functions
bullet3d.world.cast_ray(world:bullet3d.BtDiscreteDynamicsWorld, origin: Vector3, translation: Vector3, filter?:bullet3d.world.QueryFilter, max_results?: number):bullet3d.world.CastResult[]Nbullet3d.world.cast_ray_async(world:bullet3d.BtDiscreteDynamicsWorld, origin: Vector3, translation: Vector3, callback: (self: unknown, hits: bullet3d.world.CastResult[]) => void, filter?:bullet3d.world.QueryFilter, max_results?: number): voidNbullet3d.world.cast_ray_closest(world:bullet3d.BtDiscreteDynamicsWorld, origin: Vector3, translation: Vector3, filter?:bullet3d.world.QueryFilter):bullet3d.world.CastResult| undefinedNbullet3d.world.cast_shape(world:bullet3d.BtDiscreteDynamicsWorld, shape:bullet3d.shape.Definition, translation: Vector3, filter?:bullet3d.world.QueryFilter, max_results?: number):bullet3d.world.CastResult[]Nbullet3d.world.cast_shape_async(world:bullet3d.BtDiscreteDynamicsWorld, shape:bullet3d.shape.Definition, translation: Vector3, callback: (self: unknown, hits: bullet3d.world.CastResult[]) => void, filter?:bullet3d.world.QueryFilter, max_results?: number): voidNbullet3d.world.cast_shape_closest(world:bullet3d.BtDiscreteDynamicsWorld, shape:bullet3d.shape.Definition, translation: Vector3, filter?:bullet3d.world.QueryFilter):bullet3d.world.CastResult| undefinedNbullet3d.world.contact_pair_test(world:bullet3d.BtDiscreteDynamicsWorld, object_a:Opaque<"btCollisionObject" | "btRigidBody">, object_b:Opaque<"btCollisionObject" | "btRigidBody">, max_results?: number):bullet3d.world.ContactResult[]Nbullet3d.world.contact_test(world:bullet3d.BtDiscreteDynamicsWorld, object:Opaque<"btCollisionObject" | "btRigidBody">, filter?:bullet3d.world.QueryFilter, max_results?: number):bullet3d.world.ContactResult[]Nbullet3d.world.get_collision_object_count(world:bullet3d.BtDiscreteDynamicsWorld): numberNbullet3d.world.get_collision_objects(world:bullet3d.BtDiscreteDynamicsWorld, max_results?: number):Opaque<"btCollisionObject" | "btRigidBody">[]Nbullet3d.world.get_gravity(world:bullet3d.BtDiscreteDynamicsWorld): Vector3Nbullet3d.world.is_valid(world:bullet3d.BtDiscreteDynamicsWorld): booleanNbullet3d.world.overlap_aabb(world:bullet3d.BtDiscreteDynamicsWorld, aabb:bullet3d.world.Aabb, filter?:bullet3d.world.QueryFilter, max_results?: number):Opaque<"btCollisionObject" | "btRigidBody">[]Nbullet3d.world.overlap_point(world:bullet3d.BtDiscreteDynamicsWorld, point: Vector3, filter?:bullet3d.world.QueryFilter, max_results?: number):Opaque<"btCollisionObject" | "btRigidBody">[]Nbullet3d.world.overlap_shape(world:bullet3d.BtDiscreteDynamicsWorld, shape:bullet3d.shape.Definition, filter?:bullet3d.world.QueryFilter, max_results?: number):Opaque<"btCollisionObject" | "btRigidBody">[]Nbullet3d.world.set_gravity(world:bullet3d.BtDiscreteDynamicsWorld, gravity: Vector3): voidN
bullet3d.world.cast_ray(world: bullet3d.BtDiscreteDynamicsWorld, origin: Vector3, translation: Vector3, filter?: bullet3d.world.QueryFilter, max_results?: number): bullet3d.world.CastResult[]N
- Since Defold 1.13.2
Casts immediately from origin to origin + translation and returns all
matching hits sorted by fraction. Translation must be non-zero.
Bullet's convex ray test normally does not report a ray whose start and end are both inside
the same convex hull. Set filter.report_initial_overlaps = true to perform
an exact point-overlap test at the origin and synthesize one deduplicated hit
per initially touching or overlapping object with fraction = 0, zero normal,
point = origin, initial_overlap = true, and inside = true. The point is
the query origin, not a surface contact. This explicitly supports the
inside-hull behavior requested by issue #5348. Fraction-zero native callbacks
and starting overlaps are suppressed when the option is false.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleorigin:Vector3— ray origin in world spacetranslation:Vector3— non-zero ray displacement in world unitsfilter?:bullet3d.world.QueryFilter— query filtermax_results?:number— maximum sorted hits, or zero for all
Returns
hits:bullet3d.world.CastResult[]— cast results sorted by ascending fraction. ⚠️shape_indexis 1-based; passed to Defold unchanged.
bullet3d.world.cast_ray_async(world: bullet3d.BtDiscreteDynamicsWorld, origin: Vector3, translation: Vector3, callback: (self: unknown, hits: bullet3d.world.CastResult[]) => void, filter?: bullet3d.world.QueryFilter, max_results?: number): voidN
- Since Defold 1.13.2
Queues the same ray query as bullet3d.world.cast_ray and returns without
executing it. After the next physics step, callback(self, hits) receives the
cast-result array sorted by fraction. The query observes post-step world state.
It is deferred on the main thread, not executed concurrently; use it to move
work out of the current Lua call and to query the stepped state, not as a
guarantee of lower total CPU time. Queued casts for the same world share one
broadphase AABB refresh and all finish before their callbacks begin.
// Queue a downward cast and inspect only the closest non-trigger hit:
const world = bullet3d.get_world();
if (world !== undefined) {
bullet3d.world.cast_ray_async(
world,
go.get_world_position(),
vmath.vector3(0, -100, 0),
(self, hits) => {
const hit = hits[0];
if (hit !== undefined) {
print("hit", hit.object);
}
},
{ include_triggers: false },
1,
);
}bullet3d.world.cast_ray_async(
bullet3d.get_world(),
go.get_world_position(),
vmath.vector3(0, -100, 0),
function(self, hits)
if hits[1] then
print("hit", hits[1].object)
end
end,
{ include_triggers = false },
1)Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleorigin:Vector3— ray origin in world spacetranslation:Vector3— non-zero ray displacement in world unitscallback:(self: unknown, hits: bullet3d.world.CastResult[]) => void— function called ascallback(self, hits)filter?:bullet3d.world.QueryFilter— query filtermax_results?:number— maximum sorted hits, or zero for all
bullet3d.world.cast_ray_closest(world: bullet3d.BtDiscreteDynamicsWorld, origin: Vector3, translation: Vector3, filter?: bullet3d.world.QueryFilter): bullet3d.world.CastResult | undefinedN
- Since Defold 1.13.2
Equivalent to bullet3d.world.cast_ray with one result, but returns the
hit table directly or nil on a miss.
// Cast downward and report the closest non-trigger hit:
export default defineScript({
init() {
const world = bullet3d.get_world();
if (world === undefined) return;
const origin = go.get_world_position();
const translation = vmath.vector3(0, -100, 0);
const filter = { include_triggers: false };
const hit = bullet3d.world.cast_ray_closest(world, origin, translation, filter);
if (hit !== undefined) {
const distance = vmath.length(translation) * hit.fraction;
print("hit", hit.object, "after", distance, "units");
}
},
});function init(self)
local world = bullet3d.get_world()
local origin = go.get_world_position()
local translation = vmath.vector3(0, -100, 0)
local filter = { include_triggers = false }
local hit = bullet3d.world.cast_ray_closest(
world, origin, translation, filter)
if hit then
local distance = vmath.length(translation) * hit.fraction
print("hit", hit.object, "after", distance, "units")
end
endParameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleorigin:Vector3— ray origin in world spacetranslation:Vector3— non-zero ray displacement in world unitsfilter?:bullet3d.world.QueryFilter— query filter
Returns
hit:bullet3d.world.CastResult | undefined— closest cast result, ornilon a miss. ⚠️shape_indexis 1-based; passed to Defold unchanged.
bullet3d.world.cast_shape(world: bullet3d.BtDiscreteDynamicsWorld, shape: bullet3d.shape.Definition, translation: Vector3, filter?: bullet3d.world.QueryFilter, max_results?: number): bullet3d.world.CastResult[]N
- Since Defold 1.13.2
Sweeps the temporary shape from shape.position by translation, while
interpolating from shape.rotation to shape.target_rotation. Translation
must be non-zero. The query executes immediately and returns all matching hits
sorted by fraction. Bullet's convex sweep supports only convex query shapes.
When filter.report_initial_overlaps is true, an exact contact test at the
starting transform synthesizes one deduplicated hit per overlapping object
with fraction = 0, point = shape.position, zero normal,
initial_overlap = true, and inside = false. The point is the query-shape
origin, not a surface contact, and the result does not report penetration depth.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleshape:bullet3d.shape.Definition— convex query shape with optional target rotationtranslation:Vector3— non-zero sweep displacement in world unitsfilter?:bullet3d.world.QueryFilter— query filtermax_results?:number— maximum sorted hits, or zero for all
Returns
hits:bullet3d.world.CastResult[]— cast results sorted by ascending fraction. ⚠️shape_indexis 1-based; passed to Defold unchanged.
bullet3d.world.cast_shape_async(world: bullet3d.BtDiscreteDynamicsWorld, shape: bullet3d.shape.Definition, translation: Vector3, callback: (self: unknown, hits: bullet3d.world.CastResult[]) => void, filter?: bullet3d.world.QueryFilter, max_results?: number): voidN
- Since Defold 1.13.2
Queues the same convex sweep as bullet3d.world.cast_shape and returns
without executing it. After the next physics step, callback(self, hits)
receives the sorted cast-result array from the post-step world state. The
operation is deferred on the main thread rather than run concurrently. All
queued casts for one world share one broadphase AABB refresh and all finish
before their callbacks begin.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleshape:bullet3d.shape.Definition— convex query shape with optional target rotationtranslation:Vector3— non-zero sweep displacement in world unitscallback:(self: unknown, hits: bullet3d.world.CastResult[]) => void— function called ascallback(self, hits)filter?:bullet3d.world.QueryFilter— query filtermax_results?:number— maximum sorted hits, or zero for all
bullet3d.world.cast_shape_closest(world: bullet3d.BtDiscreteDynamicsWorld, shape: bullet3d.shape.Definition, translation: Vector3, filter?: bullet3d.world.QueryFilter): bullet3d.world.CastResult | undefinedN
- Since Defold 1.13.2
Equivalent to bullet3d.world.cast_shape with one result, but returns
the hit table directly or nil on a miss.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleshape:bullet3d.shape.Definition— convex query shape with optional target rotationtranslation:Vector3— non-zero sweep displacement in world unitsfilter?:bullet3d.world.QueryFilter— query filter
Returns
hit:bullet3d.world.CastResult | undefined— closest cast result, ornilon a miss. ⚠️shape_indexis 1-based; passed to Defold unchanged.
bullet3d.world.contact_pair_test(world: bullet3d.BtDiscreteDynamicsWorld, object_a: Opaque<"btCollisionObject" | "btRigidBody">, object_b: Opaque<"btCollisionObject" | "btRigidBody">, max_results?: number): bullet3d.world.ContactResult[]N
- Since Defold 1.13.2
Runs Bullet's discrete pair contact algorithm without changing the simulation.
Both borrowed handles must belong to world and must identify different
objects. The output preserves the caller's A/B order even when Bullet's
internal manifold order is reversed. Collision filters are not applied to an
explicitly selected pair.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleobject_a:Opaque<"btCollisionObject" | "btRigidBody">— first collision object in the worldobject_b:Opaque<"btCollisionObject" | "btRigidBody">— different second collision object in the worldmax_results?:number— maximum number of contact points, or zero for all
Returns
contacts:bullet3d.world.ContactResult[]— normalized contact results
bullet3d.world.contact_test(world: bullet3d.BtDiscreteDynamicsWorld, object: Opaque<"btCollisionObject" | "btRigidBody">, filter?: bullet3d.world.QueryFilter, max_results?: number): bullet3d.world.ContactResult[]N
- Since Defold 1.13.2
Runs Bullet's discrete contact test between object and matching objects in
the same world. The supplied object is always object_a in returned contacts.
The borrowed collision-object handle must belong to world. Bullet may return
several contact points for one object pair and may include small positive
contact-margin distances.
// Inspect current contacts for this collision object:
export default defineScript({
update(self, dt) {
const world = bullet3d.get_world();
const object = bullet3d.get_collision_object("#collisionobject");
if (world === undefined || object === undefined) return;
const filter = { include_triggers: false };
const contacts = bullet3d.world.contact_test(world, object, filter);
for (const contact of contacts) {
if (contact.distance < 0) {
print("penetration", -contact.distance, "against", contact.object_b);
}
}
},
});function update(self, dt)
local world = bullet3d.get_world()
local object = bullet3d.get_collision_object("#collisionobject")
local filter = { include_triggers = false }
local contacts = bullet3d.world.contact_test(world, object, filter)
for _, contact in ipairs(contacts) do
if contact.distance < 0 then
print("penetration", -contact.distance, "against", contact.object_b)
end
end
endParameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleobject:Opaque<"btCollisionObject" | "btRigidBody">— collision object belonging to the worldfilter?:bullet3d.world.QueryFilter— filter applied to candidateobject_bvaluesmax_results?:number— maximum number of contact points, or zero for all
Returns
contacts:bullet3d.world.ContactResult[]— normalized contact results
bullet3d.world.get_collision_object_count(world: bullet3d.BtDiscreteDynamicsWorld): numberN
- Since Defold 1.13.2
Get the number of collision objects in the world
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handle
Returns
count:number— number of collision objects
bullet3d.world.get_collision_objects(world: bullet3d.BtDiscreteDynamicsWorld, max_results?: number): Opaque<"btCollisionObject" | "btRigidBody">[]N
- Since Defold 1.13.2
Returns the Defold-owned collision objects currently registered in the world. Internal or unmanaged Bullet objects without Defold ownership metadata are not exposed.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handlemax_results?:number— maximum number of results, or zero for all
Returns
objects:Opaque<"btCollisionObject" | "btRigidBody">[]— array of collision-object handles
bullet3d.world.get_gravity(world: bullet3d.BtDiscreteDynamicsWorld): Vector3N
- Since Defold 1.13.2
Get world gravity
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handle
Returns
gravity:Vector3— gravity in Defold units per second squared
bullet3d.world.is_valid(world: bullet3d.BtDiscreteDynamicsWorld): booleanN
- Since Defold 1.13.2
Test whether a world handle is valid
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handle
Returns
valid:boolean—trueif the native world still exists
bullet3d.world.overlap_aabb(world: bullet3d.BtDiscreteDynamicsWorld, aabb: bullet3d.world.Aabb, filter?: bullet3d.world.QueryFilter, max_results?: number): Opaque<"btCollisionObject" | "btRigidBody">[]N
- Since Defold 1.13.2
Finds collision objects whose Bullet broadphase bounds overlap the supplied world-space AABB. This is intentionally a broadphase query and can include objects whose actual collision geometry does not intersect the box. Use bullet3d.world.overlap_point or bullet3d.world.overlap_shape for exact narrow-phase overlap tests.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleaabb:bullet3d.world.Aabb— world-space boundsfilter?:bullet3d.world.QueryFilter— query filtermax_results?:number— maximum number of results, or zero for all
Returns
objects:Opaque<"btCollisionObject" | "btRigidBody">[]— array of overlapping collision-object handles
bullet3d.world.overlap_point(world: bullet3d.BtDiscreteDynamicsWorld, point: Vector3, filter?: bullet3d.world.QueryFilter, max_results?: number): Opaque<"btCollisionObject" | "btRigidBody">[]N
- Since Defold 1.13.2
Performs an exact narrow-phase test using a temporary zero-radius Bullet sphere at the world-space point. A result is returned only for a contact with signed distance less than or equal to zero, so broadphase-only false positives are removed. Results on an exact surface follow Bullet's contact tolerance.
Parameters
world:bullet3d.BtDiscreteDynamicsWorld— world handlepoint:Vector3— point in world spacefilter?:bullet3d.world.QueryFilter— query filtermax_results?:number— maximum number of results, or zero for all
Returns
objects:Opaque<"btCollisionObject" | "btRigidBody">[]— array of overlapping collision-object handles
bullet3d.world.overlap_shape(world: bullet3d.BtDiscreteDynamicsWorld, shape: bullet3d.shape.Definition, filter?: bullet3d.world.QueryFilter, max_results?: number): Opaque<"btCollisionObject" | "btRigidBody">[]N
- Since Defold 1.13.2
Performs an exact Bullet contact test for a temporary sphere, box, Y-axis capsule, or convex hull. Multiple native contact points for the same target object are deduplicated in the returned overlap array.
// Find non-trigger objects overlapping a two-unit sphere around this game object:
export default defineScript({
init() {
const world = bullet3d.get_world();
if (world === undefined) return;
const shape = {
type: bullet3d.shape.SHAPE_TYPE_SPHERE,
diameter: 2,
position: go.get_world_position(),
};
const filter = { include_triggers: false };
const overlaps = bullet3d.world.overlap_shape(world, shape, filter);
for (const object of overlaps) {
print("overlap", object);
}
},
});function init(self)
local world = bullet3d.get_world()
local shape = {
type = bullet3d.shape.SHAPE_TYPE_SPHERE,
diameter = 2,
position = go.get_world_position(),
}
local filter = { include_triggers = false }
local overlaps = bullet3d.world.overlap_shape(world, shape, filter)
for _, object in ipairs(overlaps) do
print("overlap", object)
end
endParameters
world:bullet3d.BtDiscreteDynamicsWorld— world handleshape:bullet3d.shape.Definition— convex query shapefilter?:bullet3d.world.QueryFilter— query filtermax_results?:number— maximum number of results, or zero for all
Returns
objects:Opaque<"btCollisionObject" | "btRigidBody">[]— array of overlapping collision-object handles
bullet3d.world.set_gravity(world: bullet3d.BtDiscreteDynamicsWorld, gravity: Vector3): voidN
- Since Defold 1.13.2
Bullet propagates the new value to active dynamic bodies unless they have
bullet3d.rigid_body.BT_DISABLE_WORLD_GRAVITY set. Such bodies retain their
custom body gravity.
// Set gravity for the current collection's physics world:
export default defineScript({
init() {
const world = bullet3d.get_world();
if (world !== undefined) {
bullet3d.world.set_gravity(world, vmath.vector3(0, -9.81, 0));
}
},
});function init(self)
local world = bullet3d.get_world()
if world then
bullet3d.world.set_gravity(world, vmath.vector3(0, -9.81, 0))
end
endParameters
world:bullet3d.BtDiscreteDynamicsWorld— world handlegravity:Vector3— finite gravity in Defold units per second squared