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

Defold Learn logo

Defold Learn logo

Bullet collision object API

Functions shared by rigid bodies and trigger ghost objects. Defold keeps ownership of each object's user pointer, motion state, collision shape, and world membership. Logical child shapes are inspected and mutated through bullet3d.shape; ownership is not transferred to Lua.

Positions, distances, and CCD thresholds use Defold units. Rotations, coefficients, flags, activation state, and time values use Bullet values. Floating-point and vector inputs must be finite. CCD radii and motion thresholds must also be non-negative.

Version: alpha

FUNCTIONS
bullet3d.collision_object.activate() Activate a collision object
bullet3d.collision_object.force_activation_state() Force the activation state
bullet3d.collision_object.get_activation_state() Get the activation state
bullet3d.collision_object.get_ccd_motion_threshold() Get the CCD motion threshold
bullet3d.collision_object.get_ccd_swept_sphere_radius() Get the CCD swept sphere radius
bullet3d.collision_object.get_collision_filter_group() Get the collision filter group
bullet3d.collision_object.get_collision_filter_mask() Get the collision filter mask
bullet3d.collision_object.get_collision_flags() Get collision flags
bullet3d.collision_object.get_contact_processing_threshold() Get the contact processing threshold
bullet3d.collision_object.get_deactivation_time() Get deactivation time
bullet3d.collision_object.get_friction() Get friction
bullet3d.collision_object.get_internal_type() Get the Bullet collision object type
bullet3d.collision_object.get_position() Get the world position
bullet3d.collision_object.get_restitution() Get restitution
bullet3d.collision_object.get_rotation() Get the world rotation
bullet3d.collision_object.get_world_transform() Get the world transform
bullet3d.collision_object.has_collision_flag() Test a collision flag
bullet3d.collision_object.has_contact_response() Test whether the object responds to contacts
bullet3d.collision_object.is_active() Test whether a collision object is active
bullet3d.collision_object.is_awake() Test whether a collision object is awake
bullet3d.collision_object.is_ghost_object() Test whether the object is a ghost trigger
bullet3d.collision_object.is_kinematic() Test whether the object is kinematic
bullet3d.collision_object.is_rigid_body() Test whether the object is a rigid body
bullet3d.collision_object.is_static() Test whether the object is static
bullet3d.collision_object.is_static_or_kinematic() Test whether the object is static or kinematic
bullet3d.collision_object.is_valid() Test whether a collision object handle is valid
bullet3d.collision_object.set_activation_state() Set the activation state
bullet3d.collision_object.set_awake() Set whether a collision object is awake
bullet3d.collision_object.set_ccd_motion_threshold() Set the CCD motion threshold
bullet3d.collision_object.set_ccd_swept_sphere_radius() Set the CCD swept sphere radius
bullet3d.collision_object.set_contact_processing_threshold() Set the contact processing threshold
bullet3d.collision_object.set_deactivation_time() Set deactivation time
bullet3d.collision_object.set_friction() Set friction
bullet3d.collision_object.set_position() Set the world position
bullet3d.collision_object.set_restitution() Set restitution
bullet3d.collision_object.set_rotation() Set the world rotation
bullet3d.collision_object.set_world_transform() Set the world transform
CONSTANTS
bullet3d.collision_object.ACTIVE_TAG Active simulation state
bullet3d.collision_object.CF_CHARACTER_OBJECT Character collision object flag
bullet3d.collision_object.CF_CUSTOM_MATERIAL_CALLBACK Custom material callback flag
bullet3d.collision_object.CF_DISABLE_SPU_COLLISION_PROCESSING Disable SPU collision processing flag
bullet3d.collision_object.CF_DISABLE_VISUALIZE_OBJECT Disable debug visualization flag
bullet3d.collision_object.CF_KINEMATIC_OBJECT Kinematic collision object flag
bullet3d.collision_object.CF_NO_CONTACT_RESPONSE Disable contact response flag
bullet3d.collision_object.CF_STATIC_OBJECT Static collision object flag
bullet3d.collision_object.CO_COLLISION_OBJECT Generic collision object type
bullet3d.collision_object.CO_GHOST_OBJECT Ghost collision object type
bullet3d.collision_object.CO_HF_FLUID Height-field fluid collision object type
bullet3d.collision_object.CO_RIGID_BODY Rigid body collision object type
bullet3d.collision_object.CO_SOFT_BODY Soft body collision object type
bullet3d.collision_object.DISABLE_DEACTIVATION Disable automatic deactivation
bullet3d.collision_object.DISABLE_SIMULATION Disable simulation
bullet3d.collision_object.ISLAND_SLEEPING Sleeping simulation state
bullet3d.collision_object.WANTS_DEACTIVATION Wants-deactivation simulation state

Functions

bullet3d.collision_object.activate()

bullet3d.collision_object.activate(object,force)

Activate a collision object

PARAMETERS

object btCollisionObject
 collision object
[force] boolean
 force activation of a static or kinematic object; defaults to false

bullet3d.collision_object.force_activation_state()

bullet3d.collision_object.force_activation_state(object,state)

Force the activation state

PARAMETERS

object btCollisionObject
 collision object
state number
 activation state

bullet3d.collision_object.get_activation_state()

bullet3d.collision_object.get_activation_state(object)

Get the activation state

PARAMETERS

object btCollisionObject
 collision object

RETURNS

state number
 one of the activation constants

bullet3d.collision_object.get_ccd_motion_threshold()

bullet3d.collision_object.get_ccd_motion_threshold(object)

Get the CCD motion threshold

PARAMETERS

object btCollisionObject
 collision object

RETURNS

threshold number
 threshold in Defold units

bullet3d.collision_object.get_ccd_swept_sphere_radius()

bullet3d.collision_object.get_ccd_swept_sphere_radius(object)

Get the CCD swept sphere radius

PARAMETERS

object btCollisionObject
 collision object

RETURNS

radius number
 radius in Defold units

bullet3d.collision_object.get_collision_filter_group()

bullet3d.collision_object.get_collision_filter_group(object)

Returns the raw unsigned 16-bit filter group that Defold assigned to the object's Bullet broadphase proxy. Use this value as category_bits in a bullet3d.world query filter. Bullet applies reciprocal filtering: the query's mask_bits must include this group, and the query's category_bits must be included in the object's filter mask.

PARAMETERS

object btCollisionObject
 collision object in a Bullet world

RETURNS

group number
 raw unsigned 16-bit collision filter group

bullet3d.collision_object.get_collision_filter_mask()

bullet3d.collision_object.get_collision_filter_mask(object)

Returns the raw unsigned 16-bit filter mask that Defold assigned to the object's Bullet broadphase proxy. Use this value as mask_bits in a bullet3d.world query filter. Bullet applies reciprocal filtering: the query's category_bits must be included in this mask, and the query's mask_bits must include the object's filter group.

PARAMETERS

object btCollisionObject
 collision object in a Bullet world

RETURNS

mask number
 raw unsigned 16-bit collision filter mask

bullet3d.collision_object.get_collision_flags()

bullet3d.collision_object.get_collision_flags(object)

Get collision flags

PARAMETERS

object btCollisionObject
 collision object

RETURNS

flags number
 bit field of CF_* constants

bullet3d.collision_object.get_contact_processing_threshold()

bullet3d.collision_object.get_contact_processing_threshold(object)

Get the contact processing threshold

PARAMETERS

object btCollisionObject
 collision object

RETURNS

threshold number
 threshold in Defold units

bullet3d.collision_object.get_deactivation_time()

bullet3d.collision_object.get_deactivation_time(object)

Get deactivation time

PARAMETERS

object btCollisionObject
 collision object

RETURNS

seconds number
 deactivation time

bullet3d.collision_object.get_friction()

bullet3d.collision_object.get_friction(object)

Get friction

PARAMETERS

object btCollisionObject
 collision object

RETURNS

friction number
 friction coefficient

bullet3d.collision_object.get_internal_type()

bullet3d.collision_object.get_internal_type(object)

Get the Bullet collision object type

PARAMETERS

object btCollisionObject
 collision object

RETURNS

type number
 one of the CO_* constants

bullet3d.collision_object.get_position()

bullet3d.collision_object.get_position(object)

Get the world position

PARAMETERS

object btCollisionObject
 collision object

RETURNS

position vector3
 world position in Defold units

bullet3d.collision_object.get_restitution()

bullet3d.collision_object.get_restitution(object)

Get restitution

PARAMETERS

object btCollisionObject
 collision object

RETURNS

restitution number
 restitution coefficient

bullet3d.collision_object.get_rotation()

bullet3d.collision_object.get_rotation(object)

Get the world rotation

PARAMETERS

object btCollisionObject
 collision object

RETURNS

rotation quaternion
 world rotation

bullet3d.collision_object.get_world_transform()

bullet3d.collision_object.get_world_transform(object)

Get the world transform

PARAMETERS

object btCollisionObject
 collision object

RETURNS

position vector3
 world position in Defold units
rotation quaternion
 world rotation

bullet3d.collision_object.has_collision_flag()

bullet3d.collision_object.has_collision_flag(object,flag)

Test a collision flag

PARAMETERS

object btCollisionObject
 collision object
flag number
 collision flag or mask

RETURNS

set boolean
 true when all requested flag bits are set

bullet3d.collision_object.has_contact_response()

bullet3d.collision_object.has_contact_response(object)

Test whether the object responds to contacts

PARAMETERS

object btCollisionObject
 collision object

RETURNS

result boolean
 contact response state

bullet3d.collision_object.is_active()

bullet3d.collision_object.is_active(object)

This exposes Bullet's native btCollisionObject::isActive result. It is false for ISLAND_SLEEPING and DISABLE_SIMULATION, and true for the other activation states. It is unrelated to whether the Defold component is enabled.

PARAMETERS

object btCollisionObject
 collision object

RETURNS

active boolean
 active state

bullet3d.collision_object.is_awake()

bullet3d.collision_object.is_awake(object)

Box2D-style name for the same simulation state returned by bullet3d.collision_object.is_active.

PARAMETERS

object btCollisionObject
 collision object

RETURNS

awake boolean
 false when sleeping or simulation is disabled

bullet3d.collision_object.is_ghost_object()

bullet3d.collision_object.is_ghost_object(object)

Test whether the object is a ghost trigger

PARAMETERS

object btCollisionObject
 collision object

RETURNS

result boolean
 ghost object state

bullet3d.collision_object.is_kinematic()

bullet3d.collision_object.is_kinematic(object)

Test whether the object is kinematic

PARAMETERS

object btCollisionObject
 collision object

RETURNS

kinematic boolean
 kinematic state

bullet3d.collision_object.is_rigid_body()

bullet3d.collision_object.is_rigid_body(object)

Test whether the object is a rigid body

PARAMETERS

object btCollisionObject
 collision object

RETURNS

result boolean
 rigid body state

bullet3d.collision_object.is_static()

bullet3d.collision_object.is_static(object)

Test whether the object is static

PARAMETERS

object btCollisionObject
 collision object

RETURNS

static boolean
 static state

bullet3d.collision_object.is_static_or_kinematic()

bullet3d.collision_object.is_static_or_kinematic(object)

Test whether the object is static or kinematic

PARAMETERS

object btCollisionObject
 collision object

RETURNS

result boolean
 static or kinematic state

bullet3d.collision_object.is_valid()

bullet3d.collision_object.is_valid(object)

Test whether a collision object handle is valid

PARAMETERS

object btCollisionObject
 collision object

RETURNS

valid boolean
 true if the native object still exists

bullet3d.collision_object.set_activation_state()

bullet3d.collision_object.set_activation_state(object,state)

Set the activation state

PARAMETERS

object btCollisionObject
 collision object
state number
 activation state

bullet3d.collision_object.set_awake()

bullet3d.collision_object.set_awake(object,awake)

Passing true calls Bullet's activate(). Passing false requests the native ISLAND_SLEEPING state. As in Bullet, static or kinematic objects are not activated without force, and protected DISABLE_DEACTIVATION or DISABLE_SIMULATION states are not replaced by a sleeping request.

PARAMETERS

object btCollisionObject
 collision object
awake boolean
 requested awake state

bullet3d.collision_object.set_ccd_motion_threshold()

bullet3d.collision_object.set_ccd_motion_threshold(object,threshold)

Set the CCD motion threshold

PARAMETERS

object btCollisionObject
 collision object
threshold number
 finite non-negative threshold in Defold units

EXAMPLES

Enable continuous collision detection for a small, fast-moving body: 
function init(self)
    local body = bullet3d.get_rigid_body("#collisionobject")
    bullet3d.collision_object.set_ccd_swept_sphere_radius(body, 0.25)
    bullet3d.collision_object.set_ccd_motion_threshold(body, 0.5)
end

bullet3d.collision_object.set_ccd_swept_sphere_radius()

bullet3d.collision_object.set_ccd_swept_sphere_radius(object,radius)

Set the CCD swept sphere radius

PARAMETERS

object btCollisionObject
 collision object
radius number
 finite non-negative radius in Defold units

bullet3d.collision_object.set_contact_processing_threshold()

bullet3d.collision_object.set_contact_processing_threshold(object,threshold)

Set the contact processing threshold

PARAMETERS

object btCollisionObject
 collision object
threshold number
 finite threshold in Defold units

bullet3d.collision_object.set_deactivation_time()

bullet3d.collision_object.set_deactivation_time(object,seconds)

Set deactivation time

PARAMETERS

object btCollisionObject
 collision object
seconds number
 finite deactivation time

bullet3d.collision_object.set_friction()

bullet3d.collision_object.set_friction(object,friction)

Set friction

PARAMETERS

object btCollisionObject
 collision object
friction number
 finite friction coefficient

bullet3d.collision_object.set_position()

bullet3d.collision_object.set_position(object,position)

The owning game object's position is updated as well.

PARAMETERS

object btCollisionObject
 collision object
position vector3
 finite world position in Defold units

bullet3d.collision_object.set_restitution()

bullet3d.collision_object.set_restitution(object,restitution)

Set restitution

PARAMETERS

object btCollisionObject
 collision object
restitution number
 finite restitution coefficient

bullet3d.collision_object.set_rotation()

bullet3d.collision_object.set_rotation(object,rotation)

The owning game object's rotation is updated as well.

PARAMETERS

object btCollisionObject
 collision object
rotation quaternion
 world rotation

bullet3d.collision_object.set_world_transform()

bullet3d.collision_object.set_world_transform(object,position,rotation)

The owning game object's position and rotation are updated as well, so the transform persists when Defold synchronizes game objects into Bullet.

PARAMETERS

object btCollisionObject
 collision object
position vector3
 finite world position in Defold units
rotation quaternion
 world rotation

EXAMPLES

Move a collision object while preserving its rotation: 
function init(self)
    local object = bullet3d.get_collision_object("#collisionobject")
    local position, rotation = bullet3d.collision_object.get_world_transform(object)
    bullet3d.collision_object.set_world_transform(
        object,
        position + vmath.vector3(0, 5, 0),
        rotation)
    bullet3d.collision_object.activate(object, true)
end

Constants

bullet3d.collision_object.ACTIVE_TAG

Active simulation state

bullet3d.collision_object.CF_CHARACTER_OBJECT

Character collision object flag

bullet3d.collision_object.CF_CUSTOM_MATERIAL_CALLBACK

Custom material callback flag

bullet3d.collision_object.CF_DISABLE_SPU_COLLISION_PROCESSING

Disable SPU collision processing flag

bullet3d.collision_object.CF_DISABLE_VISUALIZE_OBJECT

Disable debug visualization flag

bullet3d.collision_object.CF_KINEMATIC_OBJECT

Kinematic collision object flag

bullet3d.collision_object.CF_NO_CONTACT_RESPONSE

Disable contact response flag

bullet3d.collision_object.CF_STATIC_OBJECT

Static collision object flag

bullet3d.collision_object.CO_COLLISION_OBJECT

Generic collision object type

bullet3d.collision_object.CO_GHOST_OBJECT

Ghost collision object type

bullet3d.collision_object.CO_HF_FLUID

Height-field fluid collision object type

bullet3d.collision_object.CO_RIGID_BODY

Rigid body collision object type

bullet3d.collision_object.CO_SOFT_BODY

Soft body collision object type

bullet3d.collision_object.DISABLE_DEACTIVATION

Disable automatic deactivation

bullet3d.collision_object.DISABLE_SIMULATION

Disable simulation

bullet3d.collision_object.ISLAND_SLEEPING

Sleeping simulation state

bullet3d.collision_object.WANTS_DEACTIVATION

Wants-deactivation simulation state