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

Defold Learn logo

Defold Learn logo

Bullet rigid body API

Rigid body functions accept the collision object userdata returned by bullet3d.get_rigid_body(). Passing a trigger ghost object raises an error. Defold retains ownership of the collision shape, motion state, world membership, and native user pointer. The shape's logical children can be mutated through bullet3d.shape; shared resource shapes become per-instance copies on first mutation. Mass and local inertia can be changed for dynamic bodies without changing their Defold collision-object type.

Linear quantities use Defold units. Angular velocity, damping, and factors are unscaled. Torque and angular impulse use squared physics scale because inertia scales with length squared. Floating-point and vector inputs must be finite. Damping must be in [0, 1], and sleeping thresholds must be non-negative.

Version: alpha

FUNCTIONS
bullet3d.rigid_body.apply_central_force() Apply a force at the center of mass
bullet3d.rigid_body.apply_central_impulse() Apply an impulse at the center of mass
bullet3d.rigid_body.apply_force() Apply a force at a world-space position
bullet3d.rigid_body.apply_force_at_relative_position() Apply a force at a center-of-mass-relative position
bullet3d.rigid_body.apply_impulse() Apply an impulse at a relative position
bullet3d.rigid_body.apply_linear_impulse() Apply a linear impulse at a world-space position
bullet3d.rigid_body.apply_torque() Apply torque
bullet3d.rigid_body.apply_torque_impulse() Apply a torque impulse
bullet3d.rigid_body.clear_forces() Clear accumulated force and torque
bullet3d.rigid_body.compute_aabb() Compute the world-space AABB
bullet3d.rigid_body.get_angular_damping() Get angular damping
bullet3d.rigid_body.get_angular_factor() Get the angular factor
bullet3d.rigid_body.get_angular_sleeping_threshold() Get the angular sleeping threshold
bullet3d.rigid_body.get_angular_velocity() Get angular velocity
bullet3d.rigid_body.get_center_of_mass_position() Get the center-of-mass world position
bullet3d.rigid_body.get_damping() Get linear and angular damping
bullet3d.rigid_body.get_flags() Get rigid body flags
bullet3d.rigid_body.get_gravity() Get body gravity
bullet3d.rigid_body.get_inverse_mass() Get inverse mass
bullet3d.rigid_body.get_linear_damping() Get linear damping
bullet3d.rigid_body.get_linear_factor() Get the linear factor
bullet3d.rigid_body.get_linear_sleeping_threshold() Get the linear sleeping threshold
bullet3d.rigid_body.get_linear_velocity() Get linear velocity
bullet3d.rigid_body.get_linear_velocity_from_local_point() Get velocity at a body-local point
bullet3d.rigid_body.get_linear_velocity_from_world_point() Get velocity at a world-space point
bullet3d.rigid_body.get_local_inertia() Get local inertia
bullet3d.rigid_body.get_mass() Get mass
bullet3d.rigid_body.get_total_force() Get total accumulated force
bullet3d.rigid_body.get_total_torque() Get total accumulated torque
bullet3d.rigid_body.get_velocity_in_local_point() Get velocity at a center-of-mass-relative point
bullet3d.rigid_body.get_world() Get the body's world
bullet3d.rigid_body.has_flag() Test a rigid body flag
bullet3d.rigid_body.is_valid() Test whether a handle refers to a valid rigid body
bullet3d.rigid_body.set_angular_damping() Set angular damping
bullet3d.rigid_body.set_angular_factor() Set the angular factor
bullet3d.rigid_body.set_angular_velocity() Set angular velocity
bullet3d.rigid_body.set_damping() Set linear and angular damping
bullet3d.rigid_body.set_flags() Set rigid body flags
bullet3d.rigid_body.set_gravity() Set body gravity
bullet3d.rigid_body.set_linear_damping() Set linear damping
bullet3d.rigid_body.set_linear_factor() Set the linear factor
bullet3d.rigid_body.set_linear_velocity() Set linear velocity
bullet3d.rigid_body.set_mass() Set mass and calculate local inertia
bullet3d.rigid_body.set_mass_properties() Set explicit mass properties
bullet3d.rigid_body.set_sleeping_thresholds() Set the sleeping thresholds
CONSTANTS
bullet3d.rigid_body.BT_DISABLE_WORLD_GRAVITY Disable automatic world gravity for a rigid body

Functions

bullet3d.rigid_body.apply_central_force()

bullet3d.rigid_body.apply_central_force(body,force)

Apply a force at the center of mass

PARAMETERS

body btRigidBody
 rigid body
force vector3
 force in Defold units

bullet3d.rigid_body.apply_central_impulse()

bullet3d.rigid_body.apply_central_impulse(body,impulse)

Apply an impulse at the center of mass

PARAMETERS

body btRigidBody
 rigid body
impulse vector3
 impulse in Defold units

bullet3d.rigid_body.apply_force()

bullet3d.rigid_body.apply_force(body,force,world_position)

This has the same point semantics as b2d.body.apply_force: world_position is the point where the force is applied. The binding converts it to the center-of-mass-relative offset expected by Bullet's applyForce method.

PARAMETERS

body btRigidBody
 rigid body
force vector3
 force in Defold units
world_position vector3
 application point in world space and Defold units

EXAMPLES

Apply an upward force at the game object's current world position: 
function init(self)
    local body = bullet3d.get_rigid_body("#collisionobject")
    local force = vmath.vector3(0, 100, 0)
    bullet3d.rigid_body.apply_force(body, force, go.get_world_position())
end

bullet3d.rigid_body.apply_force_at_relative_position()

bullet3d.rigid_body.apply_force_at_relative_position(body,force,relative_position)

This exposes Bullet's btRigidBody::applyForce point convention directly. relative_position is an offset from the body's center of mass expressed in world axes, not a world position or body-local coordinate.

PARAMETERS

body btRigidBody
 rigid body
force vector3
 force in Defold units
relative_position vector3
 center-of-mass-relative offset in world axes and Defold units

bullet3d.rigid_body.apply_impulse()

bullet3d.rigid_body.apply_impulse(body,impulse,relative_position)

This exposes Bullet's btRigidBody::applyImpulse point convention directly. relative_position is an offset from the body's center of mass expressed in world axes, not a world position or body-local coordinate.

PARAMETERS

body btRigidBody
 rigid body
impulse vector3
 impulse in Defold units
relative_position vector3
 center-of-mass-relative offset in world axes and Defold units

bullet3d.rigid_body.apply_linear_impulse()

bullet3d.rigid_body.apply_linear_impulse(body,impulse,world_position)

This has the same point semantics as b2d.body.apply_linear_impulse. world_position is converted to the center-of-mass-relative offset expected by Bullet's applyImpulse method.

PARAMETERS

body btRigidBody
 rigid body
impulse vector3
 impulse in Defold units
world_position vector3
 application point in world space and Defold units

bullet3d.rigid_body.apply_torque()

bullet3d.rigid_body.apply_torque(body,torque)

Apply torque

PARAMETERS

body btRigidBody
 rigid body
torque vector3
 torque in Defold squared units

bullet3d.rigid_body.apply_torque_impulse()

bullet3d.rigid_body.apply_torque_impulse(body,impulse)

Apply a torque impulse

PARAMETERS

body btRigidBody
 rigid body
impulse vector3
 angular impulse in Defold squared units

bullet3d.rigid_body.clear_forces()

bullet3d.rigid_body.clear_forces(body)

Clear accumulated force and torque

PARAMETERS

body btRigidBody
 rigid body

bullet3d.rigid_body.compute_aabb()

bullet3d.rigid_body.compute_aabb(body)

Calls Bullet's native btRigidBody::getAabb, which immediately calculates the bounds from the body's current collision shape and world transform. This does not read the broadphase proxy's cached AABB.

PARAMETERS

body btRigidBody
 rigid body

RETURNS

aabb table
 table whose lower and upper fields are world-space vector3 bounds in Defold units

bullet3d.rigid_body.get_angular_damping()

bullet3d.rigid_body.get_angular_damping(body)

Get angular damping

PARAMETERS

body btRigidBody
 rigid body

RETURNS

damping number
 angular damping

bullet3d.rigid_body.get_angular_factor()

bullet3d.rigid_body.get_angular_factor(body)

Get the angular factor

PARAMETERS

body btRigidBody
 rigid body

RETURNS

factor vector3
 per-axis angular factor

bullet3d.rigid_body.get_angular_sleeping_threshold()

bullet3d.rigid_body.get_angular_sleeping_threshold(body)

Get the angular sleeping threshold

PARAMETERS

body btRigidBody
 rigid body

RETURNS

threshold number
 threshold in radians per second

bullet3d.rigid_body.get_angular_velocity()

bullet3d.rigid_body.get_angular_velocity(body)

Get angular velocity

PARAMETERS

body btRigidBody
 rigid body

RETURNS

velocity vector3
 angular velocity in radians per second

bullet3d.rigid_body.get_center_of_mass_position()

bullet3d.rigid_body.get_center_of_mass_position(body)

Get the center-of-mass world position

PARAMETERS

body btRigidBody
 rigid body

RETURNS

position vector3
 center-of-mass position in Defold units

bullet3d.rigid_body.get_damping()

bullet3d.rigid_body.get_damping(body)

Get linear and angular damping

PARAMETERS

body btRigidBody
 rigid body

RETURNS

linear number
 linear damping
angular number
 angular damping

bullet3d.rigid_body.get_flags()

bullet3d.rigid_body.get_flags(body)

Get rigid body flags

PARAMETERS

body btRigidBody
 rigid body

RETURNS

flags number
 rigid body flags

bullet3d.rigid_body.get_gravity()

bullet3d.rigid_body.get_gravity(body)

Get body gravity

PARAMETERS

body btRigidBody
 rigid body

RETURNS

gravity vector3
 gravity in Defold units per second squared

bullet3d.rigid_body.get_inverse_mass()

bullet3d.rigid_body.get_inverse_mass(body)

Get inverse mass

PARAMETERS

body btRigidBody
 rigid body

RETURNS

inverse_mass number
 inverse mass

bullet3d.rigid_body.get_linear_damping()

bullet3d.rigid_body.get_linear_damping(body)

Get linear damping

PARAMETERS

body btRigidBody
 rigid body

RETURNS

damping number
 linear damping

bullet3d.rigid_body.get_linear_factor()

bullet3d.rigid_body.get_linear_factor(body)

Get the linear factor

PARAMETERS

body btRigidBody
 rigid body

RETURNS

factor vector3
 per-axis linear factor

bullet3d.rigid_body.get_linear_sleeping_threshold()

bullet3d.rigid_body.get_linear_sleeping_threshold(body)

Get the linear sleeping threshold

PARAMETERS

body btRigidBody
 rigid body

RETURNS

threshold number
 threshold in Defold units per second

bullet3d.rigid_body.get_linear_velocity()

bullet3d.rigid_body.get_linear_velocity(body)

Get linear velocity

PARAMETERS

body btRigidBody
 rigid body

RETURNS

velocity vector3
 velocity in Defold units per second

bullet3d.rigid_body.get_linear_velocity_from_local_point()

bullet3d.rigid_body.get_linear_velocity_from_local_point(body,local_point)

This has the same point semantics as b2d.body.get_linear_velocity_from_local_point. The local origin is the body's center of mass.

PARAMETERS

body btRigidBody
 rigid body
local_point vector3
 point in body-local space and Defold units

RETURNS

velocity vector3
 point velocity in Defold units per second

bullet3d.rigid_body.get_linear_velocity_from_world_point()

bullet3d.rigid_body.get_linear_velocity_from_world_point(body,world_point)

This has the same point semantics as b2d.body.get_linear_velocity_from_world_point.

PARAMETERS

body btRigidBody
 rigid body
world_point vector3
 point in world space and Defold units

RETURNS

velocity vector3
 point velocity in Defold units per second

bullet3d.rigid_body.get_local_inertia()

bullet3d.rigid_body.get_local_inertia(body)

Returns the diagonal local inertia in Defold mass-times-distance-squared units. A zero component denotes an axis with zero inverse inertia.

PARAMETERS

body btRigidBody
 rigid body

RETURNS

inertia vector3
 diagonal local inertia

bullet3d.rigid_body.get_mass()

bullet3d.rigid_body.get_mass(body)

Get mass

PARAMETERS

body btRigidBody
 rigid body

RETURNS

mass number
 mass, or zero for an infinite-mass body

bullet3d.rigid_body.get_total_force()

bullet3d.rigid_body.get_total_force(body)

Get total accumulated force

PARAMETERS

body btRigidBody
 rigid body

RETURNS

force vector3
 accumulated force in Defold units

bullet3d.rigid_body.get_total_torque()

bullet3d.rigid_body.get_total_torque(body)

Get total accumulated torque

PARAMETERS

body btRigidBody
 rigid body

RETURNS

torque vector3
 accumulated torque in Defold squared units

bullet3d.rigid_body.get_velocity_in_local_point()

bullet3d.rigid_body.get_velocity_in_local_point(body,relative_position)

The relative position is expressed in world axes. Despite Bullet's legacy function name, it is not a body-local coordinate.

PARAMETERS

body btRigidBody
 rigid body
relative_position vector3
 center-of-mass-relative offset in world axes and Defold units

RETURNS

velocity vector3
 point velocity in Defold units per second

bullet3d.rigid_body.get_world()

bullet3d.rigid_body.get_world(body)

Get the body's world

PARAMETERS

body btRigidBody
 rigid body

RETURNS

world btDiscreteDynamicsWorld
 owning world

bullet3d.rigid_body.has_flag()

bullet3d.rigid_body.has_flag(body,flag)

Test a rigid body flag

PARAMETERS

body btRigidBody
 rigid body
flag number
 flag or mask

RETURNS

set boolean
 true when all requested flag bits are set

bullet3d.rigid_body.is_valid()

bullet3d.rigid_body.is_valid(body)

Test whether a handle refers to a valid rigid body

PARAMETERS

body btRigidBody
 rigid body

RETURNS

valid boolean
 rigid body validity

bullet3d.rigid_body.set_angular_damping()

bullet3d.rigid_body.set_angular_damping(body,damping)

Set angular damping

PARAMETERS

body btRigidBody
 rigid body
damping number
 finite angular damping in [0, 1]

bullet3d.rigid_body.set_angular_factor()

bullet3d.rigid_body.set_angular_factor(body,factor)

Set the angular factor

PARAMETERS

body btRigidBody
 rigid body
factor vector3
 per-axis angular factor

bullet3d.rigid_body.set_angular_velocity()

bullet3d.rigid_body.set_angular_velocity(body,velocity)

Set angular velocity

PARAMETERS

body btRigidBody
 rigid body
velocity vector3
 finite angular velocity in radians per second

bullet3d.rigid_body.set_damping()

bullet3d.rigid_body.set_damping(body,linear,angular)

Set linear and angular damping

PARAMETERS

body btRigidBody
 rigid body
linear number
 finite linear damping in [0, 1]
angular number
 finite angular damping in [0, 1]

bullet3d.rigid_body.set_flags()

bullet3d.rigid_body.set_flags(body,flags)

Set rigid body flags

PARAMETERS

body btRigidBody
 rigid body
flags number
 rigid body flags

bullet3d.rigid_body.set_gravity()

bullet3d.rigid_body.set_gravity(body,gravity)

A later bullet3d.world.set_gravity() call, or removing and re-adding the body to a world, can overwrite custom body gravity unless the body's BT_DISABLE_WORLD_GRAVITY flag is set.

PARAMETERS

body btRigidBody
 rigid body
gravity vector3
 gravity in Defold units per second squared

EXAMPLES

Give one body persistent custom gravity without discarding its other flags: 
function init(self)
    local body = bullet3d.get_rigid_body("#collisionobject")
    local flags = bullet3d.rigid_body.get_flags(body)
    flags = bit.bor(flags, bullet3d.rigid_body.BT_DISABLE_WORLD_GRAVITY)
    bullet3d.rigid_body.set_flags(body, flags)
    bullet3d.rigid_body.set_gravity(body, vmath.vector3(0, 4, 0))
end

bullet3d.rigid_body.set_linear_damping()

bullet3d.rigid_body.set_linear_damping(body,damping)

Set linear damping

PARAMETERS

body btRigidBody
 rigid body
damping number
 finite linear damping in [0, 1]

bullet3d.rigid_body.set_linear_factor()

bullet3d.rigid_body.set_linear_factor(body,factor)

Set the linear factor

PARAMETERS

body btRigidBody
 rigid body
factor vector3
 per-axis linear factor

bullet3d.rigid_body.set_linear_velocity()

bullet3d.rigid_body.set_linear_velocity(body,velocity)

Set linear velocity

PARAMETERS

body btRigidBody
 rigid body
velocity vector3
 finite velocity in Defold units per second

bullet3d.rigid_body.set_mass()

bullet3d.rigid_body.set_mass(body,mass)

Recalculates local inertia from the body's current collision shape. Only a dynamic body can be changed; zero mass cannot be used to convert it into a static body. Values too small to have a finite native inverse are rejected. The body is activated after the update.

PARAMETERS

body btRigidBody
 dynamic rigid body
mass number
 finite mass greater than zero

EXAMPLES

Change the mass of a dynamic collision object and inspect its recalculated inertia: 
function init(self)
    local body = bullet3d.get_rigid_body("#collisionobject")
    bullet3d.rigid_body.set_mass(body, 5)
    print("local inertia", bullet3d.rigid_body.get_local_inertia(body))
end

bullet3d.rigid_body.set_mass_properties()

bullet3d.rigid_body.set_mass_properties(body,mass,local_inertia)

Sets mass and diagonal local inertia together, updates the world-space inertia tensor, and activates the body. Only dynamic bodies are accepted. A zero inertia component is allowed and disables angular response on that local axis; negative, non-finite, or nonzero values too small to have a finite native inverse are rejected.

PARAMETERS

body btRigidBody
 dynamic rigid body
mass number
 finite mass greater than zero
local_inertia vector3
 finite non-negative diagonal local inertia in Defold units

bullet3d.rigid_body.set_sleeping_thresholds()

bullet3d.rigid_body.set_sleeping_thresholds(body,linear,angular)

Set the sleeping thresholds

PARAMETERS

body btRigidBody
 rigid body
linear number
 finite non-negative linear threshold in Defold units per second
angular number
 finite non-negative angular threshold in radians per second

Constants

bullet3d.rigid_body.BT_DISABLE_WORLD_GRAVITY

Set this bit with bullet3d.rigid_body.set_flags() before assigning custom body gravity that must survive later world-gravity changes or re-adding the body to a world.