bullet3d

Namespace: bullet3d Language: Lua Type: Defold Lua File: script_bullet3d.cpp Source: engine/gamesys/src/gamesys/scripts/bullet3d/script_bullet3d.cpp

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.

API

btCollisionObject

Type: TYPEDEF Bullet collision object

Parameters

• value (userdata)

btDiscreteDynamicsWorld

Type: TYPEDEF Bullet dynamics world

Parameters

• value (userdata)

btRigidBody

Type: TYPEDEF Rigid bodies use the same Lua userdata representation as collision objects, but rigid-body functions validate the native type before upcasting it.

Parameters

• value (userdata)

bullet3d.get_collision_object

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

  nil) - the collision object, or nil

bullet3d.get_rigid_body

Type: FUNCTION Trigger components are ghost objects, so this function returns nil for them. This function raises an error unless the collection uses 3D physics.

Parameters

• url (string

  hash

  url) - collision object component URL

Returns

• body (btRigidBody

  nil) - the rigid body handle, or nil

Examples

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)

bullet3d.get_version

Type: FUNCTION Get the Bullet version

Returns

• info (bullet3d.version_info) - version information

bullet3d.get_world

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

Returns

• world (btDiscreteDynamicsWorld

  nil) - the world, or nil if the collection has no physics world

bullet3d.version_info

Type: STRUCT Bullet version information

Members

• version (string) - full Bullet version string
• number (integer) - compact numeric Bullet version
• major (integer) - major version number
• minor (integer) - minor version number