Defold C

Defold C++

dmGameObject

dmGameSystem

dmGraphics

dmResource

dmScript

Defold Lua

Extension

firebase

Version

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: beta

ENUMS
bullet3d.collision_object.ACTIVATION_STATE	Collision object activation states
bullet3d.collision_object.COLLISION_FLAG	Collision object flags
bullet3d.collision_object.INTERNAL_TYPE	Native collision object types

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

Enums

bullet3d.collision_object.ACTIVATION_STATE

bullet3d.collision_object.ACTIVATION_STATE: integer

Collision object activation states

VALUES

`bullet3d.collision_object.ACTIVE_TAG`	Active simulation state.
`bullet3d.collision_object.ISLAND_SLEEPING`	Sleeping simulation state.
`bullet3d.collision_object.WANTS_DEACTIVATION`	Wants-deactivation simulation state.
`bullet3d.collision_object.DISABLE_DEACTIVATION`	Disable automatic deactivation.
`bullet3d.collision_object.DISABLE_SIMULATION`	Disable simulation.

bullet3d.collision_object.COLLISION_FLAG

bullet3d.collision_object.COLLISION_FLAG: integer

Collision object flags

VALUES

`bullet3d.collision_object.CF_DYNAMIC_OBJECT`	Zero-valued default dynamic-object flag. Compare the complete collision-flags value with this constant; do not pass it to `has_collision_flag`, since zero is not a bit that can be tested.
`bullet3d.collision_object.CF_STATIC_OBJECT`	Static collision object 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_CUSTOM_MATERIAL_CALLBACK`	Custom material callback flag.
`bullet3d.collision_object.CF_CHARACTER_OBJECT`	Character collision object flag.
`bullet3d.collision_object.CF_DISABLE_VISUALIZE_OBJECT`	Disable debug visualization flag.
`bullet3d.collision_object.CF_DISABLE_SPU_COLLISION_PROCESSING`	Disable SPU collision processing flag.

bullet3d.collision_object.INTERNAL_TYPE

bullet3d.collision_object.INTERNAL_TYPE: integer

Native collision object types

VALUES

`bullet3d.collision_object.CO_COLLISION_OBJECT`	Generic collision object type.
`bullet3d.collision_object.CO_RIGID_BODY`	Rigid body collision object type.
`bullet3d.collision_object.CO_GHOST_OBJECT`	Ghost collision object type.
`bullet3d.collision_object.CO_SOFT_BODY`	Soft body collision object type.
`bullet3d.collision_object.CO_HF_FLUID`	Height-field fluid collision object type.

Functions

bullet3d.collision_object.activate()

bullet3d.collision_object.activate(object:btCollisionObject, [force:boolean])

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:btCollisionObject, state:bullet3d.collision_object.ACTIVATION_STATE)

Force the activation state

PARAMETERS

`object`	`btCollisionObject`	collision object
`state`	`bullet3d.collision_object.ACTIVATION_STATE`	activation state

bullet3d.collision_object.get_activation_state()

bullet3d.collision_object.get_activation_state(object:btCollisionObject)→state:bullet3d.collision_object.ACTIVATION_STATE

Get the activation state

PARAMETERS

object btCollisionObject collision object

RETURNS

state bullet3d.collision_object.ACTIVATION_STATE activation state

bullet3d.collision_object.get_ccd_motion_threshold()

bullet3d.collision_object.get_ccd_motion_threshold(object:btCollisionObject)→threshold:number

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:btCollisionObject)→radius:number

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:btCollisionObject)→group:integer

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 integer raw unsigned 16-bit collision filter group

bullet3d.collision_object.get_collision_filter_mask()

bullet3d.collision_object.get_collision_filter_mask(object:btCollisionObject)→mask:integer

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 integer raw unsigned 16-bit collision filter mask

bullet3d.collision_object.get_collision_flags()

bullet3d.collision_object.get_collision_flags(object:btCollisionObject)→flags:integer

Get collision flags

PARAMETERS

object btCollisionObject collision object

RETURNS

flags integer bit field of CF_* constants

bullet3d.collision_object.get_contact_processing_threshold()

bullet3d.collision_object.get_contact_processing_threshold(object:btCollisionObject)→threshold:number

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:btCollisionObject)→seconds:number

Get deactivation time

PARAMETERS

object btCollisionObject collision object

RETURNS

seconds number deactivation time

bullet3d.collision_object.get_friction()

bullet3d.collision_object.get_friction(object:btCollisionObject)→friction:number

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:btCollisionObject)→type:bullet3d.collision_object.INTERNAL_TYPE

Get the Bullet collision object type

PARAMETERS

object btCollisionObject collision object

RETURNS

type bullet3d.collision_object.INTERNAL_TYPE native collision object type

bullet3d.collision_object.get_position()

bullet3d.collision_object.get_position(object:btCollisionObject)→position:vector3

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:btCollisionObject)→restitution:number

Get restitution

PARAMETERS

object btCollisionObject collision object

RETURNS

restitution number restitution coefficient

bullet3d.collision_object.get_rotation()

bullet3d.collision_object.get_rotation(object:btCollisionObject)→rotation:quaternion

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:btCollisionObject)→(position:vector3, rotation:quaternion)

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:btCollisionObject, flag:integer)→set:boolean

Test a collision flag

PARAMETERS

`object`	`btCollisionObject`	collision object
`flag`	`integer`	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:btCollisionObject)→result:boolean

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:btCollisionObject)→active:boolean

This exposes Bullet's native btCollisionObject::isActive result. It is false for ISLAND_SLEEPING and DISABLE_SIMULATION, and true for the other activation states available to Defold collision objects. 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:btCollisionObject)→awake:boolean

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:btCollisionObject)→result:boolean

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:btCollisionObject)→kinematic:boolean

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:btCollisionObject)→result:boolean

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:btCollisionObject)→static:boolean

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:btCollisionObject)→result:boolean

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:btCollisionObject)→valid:boolean

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:btCollisionObject, state:bullet3d.collision_object.ACTIVATION_STATE)

Set the activation state

PARAMETERS

`object`	`btCollisionObject`	collision object
`state`	`bullet3d.collision_object.ACTIVATION_STATE`	activation state

bullet3d.collision_object.set_awake()

bullet3d.collision_object.set_awake(object:btCollisionObject, awake:boolean)

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:btCollisionObject, threshold:number)

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:btCollisionObject, radius:number)

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:btCollisionObject, threshold:number)

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:btCollisionObject, seconds:number)

Set deactivation time

PARAMETERS

`object`	`btCollisionObject`	collision object
`seconds`	`number`	finite deactivation time

bullet3d.collision_object.set_friction()

bullet3d.collision_object.set_friction(object:btCollisionObject, friction:number)

Set friction

PARAMETERS

`object`	`btCollisionObject`	collision object
`friction`	`number`	finite friction coefficient

bullet3d.collision_object.set_position()

bullet3d.collision_object.set_position(object:btCollisionObject, position:vector3)

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:btCollisionObject, restitution:number)

Set restitution

PARAMETERS

`object`	`btCollisionObject`	collision object
`restitution`	`number`	finite restitution coefficient

bullet3d.collision_object.set_rotation()

bullet3d.collision_object.set_rotation(object:btCollisionObject, rotation:quaternion)

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

PARAMETERS

`object`	`btCollisionObject`	collision object
`rotation`	`quaternion`	finite, non-zero world rotation; normalized by the binding

bullet3d.collision_object.set_world_transform()

bullet3d.collision_object.set_world_transform(object:btCollisionObject, position:vector3, rotation:quaternion)

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`	finite, non-zero world rotation; normalized by the binding

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