bullet3d
Native-style access to the Bullet 3D world and collision objects owned by Defold. World creation, destruction and stepping remain controlled by Defold. The backend name refers to three-dimensional physics.
World, collision-object and rigid-body userdata are borrowed handles to Defold-owned objects. Shape userdata are borrowed logical child-slot handles attached to a collision object. Constraint userdata identify auxiliary native objects owned by this Lua API; destroy them explicitly when no longer needed. They are also destroyed automatically when a required body or world is destroyed.
A collision-object, rigid-body or shape handle becomes invalid when its
collision object is deleted or reloaded. A world handle remains valid across
collision-object reloads, but becomes invalid when its collection and physics
world are destroyed. The corresponding is_valid() function is safe for
checking a retained handle; every other operation rejects an invalid handle.
Functions
bullet3d.get_collision_object(url: string | Hash | Url):Opaque<"btCollisionObject" | "btRigidBody"> | undefinedNbullet3d.get_gameobject_id(object:Opaque<"btCollisionObject" | "btRigidBody">): Hash | undefinedNbullet3d.get_rigid_body(url: string | Hash | Url):Opaque<"btRigidBody"> | undefinedNbullet3d.get_version():bullet3d.VersionInfoNbullet3d.get_world():bullet3d.BtDiscreteDynamicsWorld| undefinedN
bullet3d.get_collision_object(url: string | Hash | Url): Opaque<"btCollisionObject" | "btRigidBody"> | undefinedN
- Since Defold 1.13.2
This returns both rigid bodies and ghost trigger objects. This function raises an error unless the collection uses 3D physics.
Parameters
url:string | Hash | Url— collision object component URL
Returns
object:Opaque<"btCollisionObject" | "btRigidBody"> | undefined— the collision object, ornil
bullet3d.get_gameobject_id(object: Opaque<"btCollisionObject" | "btRigidBody">): Hash | undefinedN
- Since Defold 1.14.0
Returns the id of the game object that owns the collision-object component. Accepts both rigid bodies and ghost trigger objects. Raises a Lua error if the handle is invalid or its game object has been deleted.
const object = bullet3d.get_collision_object("#collisionobject");
if (object !== undefined) {
const id = bullet3d.get_gameobject_id(object);
}local object = bullet3d.get_collision_object("#collisionobject")
local id = bullet3d.get_gameobject_id(object)Parameters
object:Opaque<"btCollisionObject" | "btRigidBody">— the Bullet collision object
Returns
id:Hash | undefined— the game object id, ornilif the collision object has no associated game object
bullet3d.get_rigid_body(url: string | Hash | Url): Opaque<"btRigidBody"> | undefinedN
- Since Defold 1.13.2
Trigger components are ghost objects, so this function returns nil for them.
This function raises an error unless the collection uses 3D physics.
const world = bullet3d.get_world();
const body = bullet3d.get_rigid_body("#collisionobject");
if (world !== undefined && body !== undefined && bullet3d.rigid_body.is_valid(body)) {
bullet3d.rigid_body.apply_central_impulse(body, vmath.vector3(0, 10, 0));
}
// A trigger is a collision object, not a rigid body.
const trigger = bullet3d.get_collision_object("#trigger");
assert(trigger !== undefined && bullet3d.get_rigid_body("#trigger") === undefined);local world = bullet3d.get_world()
local body = bullet3d.get_rigid_body("#collisionobject")
if world and body and bullet3d.rigid_body.is_valid(body) then
bullet3d.rigid_body.apply_central_impulse(body, vmath.vector3(0, 10, 0))
end
-- A trigger is a collision object, not a rigid body.
local trigger = bullet3d.get_collision_object("#trigger")
assert(trigger and bullet3d.get_rigid_body("#trigger") == nil)Parameters
url:string | Hash | Url— collision object component URL
Returns
body:Opaque<"btRigidBody"> | undefined— the rigid body handle, ornil
bullet3d.get_version(): bullet3d.VersionInfoN
bullet3d.get_world(): bullet3d.BtDiscreteDynamicsWorld | undefinedN
- Since Defold 1.13.2
This function raises an error unless the collection uses 3D physics.
Returns
world:bullet3d.BtDiscreteDynamicsWorld | undefined— the world, ornilif the collection has no physics world