Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

bullet3d5 new

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"> | 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, or nil

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, or nil if 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, or nil

bullet3d.get_version(): bullet3d.VersionInfoN

  • Since Defold 1.13.2

Get the Bullet version

Returns

bullet3d.get_world(): bullet3d.BtDiscreteDynamicsWorld | undefinedN

  • Since Defold 1.13.2

This function raises an error unless the collection uses 3D physics.

Returns

Types

type bullet3d.BtCollisionObject = Opaque<"btCollisionObject" | "btRigidBody">

type bullet3d.BtDiscreteDynamicsWorld = Opaque<"btDiscreteDynamicsWorld">

type bullet3d.BtRigidBody = Opaque<"btRigidBody">

interface bullet3d.VersionInfo { version: string; number: number; major: number; minor: number; }

On this page