DEFOLD
Home Features Showcase Learn Asset Portal Community Support API Free Download Donate  

Defold Learn logo

Defold Learn logo

Bullet collision shape API

Borrowed shape handles identify a one-based child slot on a Defold-owned collision object. They remain attached to that logical slot when its native shape is replaced and become invalid with their owning collision object. Shape mutation is copy-on-write, so instances sharing a collision resource are not modified together. Lengths use Defold world units.

Version: beta

TYPES
btCollisionShape Bullet collision shape
bullet3d.shape.definition Bullet collision shape definition
ENUMS
bullet3d.shape.SHAPE_TYPE Collision shape types
FUNCTIONS
bullet3d.collision_object.get_shape() Get one attached shape by one-based index.
bullet3d.collision_object.get_shape_count() Get the number of shapes attached to a collision object.
bullet3d.collision_object.get_shapes() Get all attached shapes.
bullet3d.shape.get_collision_object() Get the owning collision object.
bullet3d.shape.get_index() Get the one-based child index.
bullet3d.shape.get_local_transform() Get a compound child's local transform.
bullet3d.shape.get_shape() Get shape geometry data.
bullet3d.shape.get_type() Get the normalized Defold shape type.
bullet3d.shape.is_valid() Test whether a shape handle and its owner still exist.
bullet3d.shape.set_local_transform() Set a compound child's local transform.
bullet3d.shape.set_shape() Set shape geometry data.

Types

btCollisionShape

btCollisionShape = userdata

Shape handles identify logical child slots and resolve the current native shape on every call.

bullet3d.shape.definition

bullet3d.shape.definition = { type:bullet3d.shape.SHAPE_TYPE, diameter:number, position?:vector3, rotation?:quaternion, target_rotation?:quaternion } | { type:bullet3d.shape.SHAPE_TYPE, dimensions:vector3, position?:vector3, rotation?:quaternion, target_rotation?:quaternion } | { type:bullet3d.shape.SHAPE_TYPE, diameter:number, height:number, position?:vector3, rotation?:quaternion, target_rotation?:quaternion } | { type:bullet3d.shape.SHAPE_TYPE, vertices:vector3[], position?:vector3, rotation?:quaternion, target_rotation?:quaternion }

A sphere has diameter; a box has dimensions; a capsule has diameter and cylindrical-section height; and a convex hull has vertices. Query functions also accept optional position, rotation, and target_rotation fields. Lengths use Defold units.

Enums

bullet3d.shape.SHAPE_TYPE

bullet3d.shape.SHAPE_TYPE: integer

Collision shape types

VALUES

bullet3d.shape.SHAPE_TYPE_BOX Box shape type Value 1. Shape data contains positive vector3 dimensions in Defold units.
bullet3d.shape.SHAPE_TYPE_CAPSULE Capsule shape type Value 2. Shape data contains a positive numeric diameter and positive numeric cylindrical-section height in Defold units.
bullet3d.shape.SHAPE_TYPE_HULL Convex hull shape type Value 3. Shape data contains a vertices array with at least four finite vector3 values in Defold units.
bullet3d.shape.SHAPE_TYPE_MESH Triangle mesh shape type Value 4. Shape data contains only the type; triangle geometry is read-only.
bullet3d.shape.SHAPE_TYPE_SPHERE Sphere shape type Value 0. Shape data contains a positive numeric diameter in Defold units.

Functions

bullet3d.collision_object.get_shape()

bullet3d.collision_object.get_shape(object:btCollisionObject, shape_index:integer)→shape:btCollisionShape

Get one attached shape by one-based index.

PARAMETERS

object btCollisionObject
 collision object
shape_index integer
 one-based shape index

RETURNS

shape btCollisionShape
 borrowed logical shape handle

bullet3d.collision_object.get_shape_count()

bullet3d.collision_object.get_shape_count(object:btCollisionObject)→count:integer

Get the number of shapes attached to a collision object.

PARAMETERS

object btCollisionObject
 collision object

RETURNS

count integer
 shape count

bullet3d.collision_object.get_shapes()

bullet3d.collision_object.get_shapes(object:btCollisionObject)→shapes:btCollisionShape[]

Get all attached shapes.

PARAMETERS

object btCollisionObject
 collision object

RETURNS

shapes btCollisionShape[]
 array of borrowed shape handles

EXAMPLES

Enumerate the logical shapes attached to a collision object: 
function init(self)
    local object = bullet3d.get_collision_object("#collisionobject")
    for _, shape in ipairs(bullet3d.collision_object.get_shapes(object)) do
        local index = bullet3d.shape.get_index(shape)
        local data = bullet3d.shape.get_shape(shape)
        print("shape", index, "type", data.type)
    end
end

bullet3d.shape.get_collision_object()

bullet3d.shape.get_collision_object(shape:btCollisionShape)→object:btCollisionObject

Get the owning collision object.

PARAMETERS

shape btCollisionShape
 shape handle

RETURNS

object btCollisionObject
 owning collision object

bullet3d.shape.get_index()

bullet3d.shape.get_index(shape:btCollisionShape)→shape_index:integer

Get the one-based child index.

PARAMETERS

shape btCollisionShape
 shape handle

RETURNS

shape_index integer
 one-based shape index

bullet3d.shape.get_local_transform()

bullet3d.shape.get_local_transform(shape:btCollisionShape)→(position:vector3, rotation:quaternion)

A non-compound collision object's only shape has no child transform, so this function returns the identity transform for it.

PARAMETERS

shape btCollisionShape
 shape handle

RETURNS

position vector3
 local position
rotation quaternion
 local rotation

bullet3d.shape.get_shape()

bullet3d.shape.get_shape(shape:btCollisionShape)→data:bullet3d.shape.definition

The returned table always contains type, one of bullet3d.shape.SHAPE_TYPE_*. A sphere also contains numeric diameter; a box contains vector3 dimensions; a capsule contains numeric diameter and cylindrical-section height; a hull contains a vertices array of vector3 values; and a triangle mesh contains only type. Primitive and hull tables use Defold units and can be passed to a bullet3d.world shape query after adding the desired position and optional rotation fields.

PARAMETERS

shape btCollisionShape
 shape handle

RETURNS

data bullet3d.shape.definition
 typed shape geometry in Defold units

bullet3d.shape.get_type()

bullet3d.shape.get_type(shape:btCollisionShape)→type:bullet3d.shape.SHAPE_TYPE

Get the normalized Defold shape type.

PARAMETERS

shape btCollisionShape
 shape handle

RETURNS

type bullet3d.shape.SHAPE_TYPE
 collision shape type

bullet3d.shape.is_valid()

bullet3d.shape.is_valid(shape:btCollisionShape)→valid:boolean

Test whether a shape handle and its owner still exist.

PARAMETERS

shape btCollisionShape
 shape handle

RETURNS

valid boolean
 validity

bullet3d.shape.set_local_transform()

bullet3d.shape.set_local_transform(shape:btCollisionShape, position:vector3, rotation:quaternion)

A non-compound collision object's only shape has no child transform and is rejected. The binding normalizes the supplied rotation.

PARAMETERS

shape btCollisionShape
 shape handle
position vector3
 finite local position
rotation quaternion
 finite non-zero local rotation

bullet3d.shape.set_shape()

bullet3d.shape.set_shape(shape:btCollisionShape, data:bullet3d.shape.definition)

The table uses the same format as get_shape. Its type must match the existing shape because changing native shape type is not supported. Primitive dimensions must be finite and greater than zero. Hulls require at least four finite vertices. Triangle mesh geometry cannot be changed with this function.

PARAMETERS

shape btCollisionShape
 shape handle
data bullet3d.shape.definition
 typed shape geometry in Defold units

EXAMPLES

Increase the dimensions of the first box shape by 50 percent for this instance: 
function init(self)
    local object = bullet3d.get_collision_object("#collisionobject")
    local shape = bullet3d.collision_object.get_shape(object, 1)
    local data = bullet3d.shape.get_shape(shape)

    if data.type == bullet3d.shape.SHAPE_TYPE_BOX then
        data.dimensions = data.dimensions * 1.5
        bullet3d.shape.set_shape(shape, data)
    end
end