bullet3d.rigid_body
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.
Functions
bullet3d.rigid_body.apply_central_force(body:Opaque<"btRigidBody">, force: Vector3): voidNbullet3d.rigid_body.apply_central_impulse(body:Opaque<"btRigidBody">, impulse: Vector3): voidNbullet3d.rigid_body.apply_force(body:Opaque<"btRigidBody">, force: Vector3, world_position: Vector3): voidNbullet3d.rigid_body.apply_force_at_relative_position(body:Opaque<"btRigidBody">, force: Vector3, relative_position: Vector3): voidNbullet3d.rigid_body.apply_impulse(body:Opaque<"btRigidBody">, impulse: Vector3, relative_position: Vector3): voidNbullet3d.rigid_body.apply_linear_impulse(body:Opaque<"btRigidBody">, impulse: Vector3, world_position: Vector3): voidNbullet3d.rigid_body.apply_torque(body:Opaque<"btRigidBody">, torque: Vector3): voidNbullet3d.rigid_body.apply_torque_impulse(body:Opaque<"btRigidBody">, impulse: Vector3): voidNbullet3d.rigid_body.clear_forces(body:Opaque<"btRigidBody">): voidNbullet3d.rigid_body.compute_aabb(body:Opaque<"btRigidBody">):bullet3d.world.AabbNbullet3d.rigid_body.get_angular_damping(body:Opaque<"btRigidBody">): numberNbullet3d.rigid_body.get_angular_factor(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_angular_sleeping_threshold(body:Opaque<"btRigidBody">): numberNbullet3d.rigid_body.get_angular_velocity(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_center_of_mass_position(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_damping(body:Opaque<"btRigidBody">): LuaMultiReturn<[number, number]>Nbullet3d.rigid_body.get_flags(body:Opaque<"btRigidBody">): numberNbullet3d.rigid_body.get_gravity(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_inverse_mass(body:Opaque<"btRigidBody">): numberNbullet3d.rigid_body.get_linear_damping(body:Opaque<"btRigidBody">): numberNbullet3d.rigid_body.get_linear_factor(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_linear_sleeping_threshold(body:Opaque<"btRigidBody">): numberNbullet3d.rigid_body.get_linear_velocity(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_linear_velocity_from_local_point(body:Opaque<"btRigidBody">, local_point: Vector3): Vector3Nbullet3d.rigid_body.get_linear_velocity_from_world_point(body:Opaque<"btRigidBody">, world_point: Vector3): Vector3Nbullet3d.rigid_body.get_local_inertia(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_mass(body:Opaque<"btRigidBody">): numberNbullet3d.rigid_body.get_total_force(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_total_torque(body:Opaque<"btRigidBody">): Vector3Nbullet3d.rigid_body.get_velocity_in_local_point(body:Opaque<"btRigidBody">, relative_position: Vector3): Vector3Nbullet3d.rigid_body.get_world(body:Opaque<"btRigidBody">):bullet3d.BtDiscreteDynamicsWorldNbullet3d.rigid_body.has_flag(body:Opaque<"btRigidBody">, flag: number): booleanNbullet3d.rigid_body.is_valid(body:Opaque<"btRigidBody">): booleanNbullet3d.rigid_body.set_angular_damping(body:Opaque<"btRigidBody">, damping: number): voidNbullet3d.rigid_body.set_angular_factor(body:Opaque<"btRigidBody">, factor: Vector3): voidNbullet3d.rigid_body.set_angular_velocity(body:Opaque<"btRigidBody">, velocity: Vector3): voidNbullet3d.rigid_body.set_damping(body:Opaque<"btRigidBody">, linear: number, angular: number): voidNbullet3d.rigid_body.set_flags(body:Opaque<"btRigidBody">, flags: number): voidNbullet3d.rigid_body.set_gravity(body:Opaque<"btRigidBody">, gravity: Vector3): voidNbullet3d.rigid_body.set_linear_damping(body:Opaque<"btRigidBody">, damping: number): voidNbullet3d.rigid_body.set_linear_factor(body:Opaque<"btRigidBody">, factor: Vector3): voidNbullet3d.rigid_body.set_linear_velocity(body:Opaque<"btRigidBody">, velocity: Vector3): voidNbullet3d.rigid_body.set_mass(body:Opaque<"btRigidBody">, mass: number): voidNbullet3d.rigid_body.set_mass_properties(body:Opaque<"btRigidBody">, mass: number, local_inertia: Vector3): voidNbullet3d.rigid_body.set_sleeping_thresholds(body:Opaque<"btRigidBody">, linear: number, angular: number): voidN
bullet3d.rigid_body.apply_central_force(body: Opaque<"btRigidBody">, force: Vector3): voidN
- Since Defold 1.13.2
Apply a force at the center of mass
Parameters
body:Opaque<"btRigidBody">— rigid bodyforce:Vector3— force in Defold units
bullet3d.rigid_body.apply_central_impulse(body: Opaque<"btRigidBody">, impulse: Vector3): voidN
- Since Defold 1.13.2
Apply an impulse at the center of mass
Parameters
body:Opaque<"btRigidBody">— rigid bodyimpulse:Vector3— impulse in Defold units
bullet3d.rigid_body.apply_force(body: Opaque<"btRigidBody">, force: Vector3, world_position: Vector3): voidN
- Since Defold 1.13.2
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.
// Apply an upward force at the game object's current world position:
export default defineScript({
init() {
const body = bullet3d.get_rigid_body("#collisionobject");
if (body === undefined) return;
const force = vmath.vector3(0, 100, 0);
bullet3d.rigid_body.apply_force(body, force, go.get_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())
endParameters
body:Opaque<"btRigidBody">— rigid bodyforce:Vector3— force in Defold unitsworld_position:Vector3— application point in world space and Defold units
bullet3d.rigid_body.apply_force_at_relative_position(body: Opaque<"btRigidBody">, force: Vector3, relative_position: Vector3): voidN
- Since Defold 1.13.2
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:Opaque<"btRigidBody">— rigid bodyforce:Vector3— force in Defold unitsrelative_position:Vector3— center-of-mass-relative offset in world axes and Defold units
bullet3d.rigid_body.apply_impulse(body: Opaque<"btRigidBody">, impulse: Vector3, relative_position: Vector3): voidN
- Since Defold 1.13.2
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:Opaque<"btRigidBody">— rigid bodyimpulse:Vector3— impulse in Defold unitsrelative_position:Vector3— center-of-mass-relative offset in world axes and Defold units
bullet3d.rigid_body.apply_linear_impulse(body: Opaque<"btRigidBody">, impulse: Vector3, world_position: Vector3): voidN
- Since Defold 1.13.2
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:Opaque<"btRigidBody">— rigid bodyimpulse:Vector3— impulse in Defold unitsworld_position:Vector3— application point in world space and Defold units
bullet3d.rigid_body.apply_torque(body: Opaque<"btRigidBody">, torque: Vector3): voidN
- Since Defold 1.13.2
Apply torque
Parameters
body:Opaque<"btRigidBody">— rigid bodytorque:Vector3— torque in Defold squared units
bullet3d.rigid_body.apply_torque_impulse(body: Opaque<"btRigidBody">, impulse: Vector3): voidN
- Since Defold 1.13.2
Apply a torque impulse
Parameters
body:Opaque<"btRigidBody">— rigid bodyimpulse:Vector3— angular impulse in Defold squared units
bullet3d.rigid_body.clear_forces(body: Opaque<"btRigidBody">): voidN
- Since Defold 1.13.2
Clear accumulated force and torque
Parameters
body:Opaque<"btRigidBody">— rigid body
bullet3d.rigid_body.compute_aabb(body: Opaque<"btRigidBody">): bullet3d.world.AabbN
- Since Defold 1.13.2
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:Opaque<"btRigidBody">— rigid body
Returns
aabb:bullet3d.world.Aabb— world-space bounds in Defold units
bullet3d.rigid_body.get_angular_damping(body: Opaque<"btRigidBody">): numberN
- Since Defold 1.13.2
Get angular damping
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
damping:number— angular damping
bullet3d.rigid_body.get_angular_factor(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get the angular factor
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
factor:Vector3— per-axis angular factor
bullet3d.rigid_body.get_angular_sleeping_threshold(body: Opaque<"btRigidBody">): numberN
- Since Defold 1.13.2
Get the angular sleeping threshold
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
threshold:number— threshold in radians per second
bullet3d.rigid_body.get_angular_velocity(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get angular velocity
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
velocity:Vector3— angular velocity in radians per second
bullet3d.rigid_body.get_center_of_mass_position(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get the center-of-mass world position
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
position:Vector3— center-of-mass position in Defold units
bullet3d.rigid_body.get_damping(body: Opaque<"btRigidBody">): LuaMultiReturn<[number, number]>N
- Since Defold 1.13.2
Get linear and angular damping
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
linear:number— linear dampingangular:number— angular damping
bullet3d.rigid_body.get_flags(body: Opaque<"btRigidBody">): numberN
- Since Defold 1.13.2
Get rigid body flags
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
flags:number— rigid body flags
bullet3d.rigid_body.get_gravity(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get body gravity
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
gravity:Vector3— gravity in Defold units per second squared
bullet3d.rigid_body.get_inverse_mass(body: Opaque<"btRigidBody">): numberN
- Since Defold 1.13.2
Get inverse mass
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
inverse_mass:number— inverse mass
bullet3d.rigid_body.get_linear_damping(body: Opaque<"btRigidBody">): numberN
- Since Defold 1.13.2
Get linear damping
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
damping:number— linear damping
bullet3d.rigid_body.get_linear_factor(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get the linear factor
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
factor:Vector3— per-axis linear factor
bullet3d.rigid_body.get_linear_sleeping_threshold(body: Opaque<"btRigidBody">): numberN
- Since Defold 1.13.2
Get the linear sleeping threshold
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
threshold:number— threshold in Defold units per second
bullet3d.rigid_body.get_linear_velocity(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get linear velocity
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
velocity:Vector3— velocity in Defold units per second
bullet3d.rigid_body.get_linear_velocity_from_local_point(body: Opaque<"btRigidBody">, local_point: Vector3): Vector3N
- Since Defold 1.13.2
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:Opaque<"btRigidBody">— rigid bodylocal_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(body: Opaque<"btRigidBody">, world_point: Vector3): Vector3N
- Since Defold 1.13.2
This has the same point semantics as
b2d.body.get_linear_velocity_from_world_point.
Parameters
body:Opaque<"btRigidBody">— rigid bodyworld_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(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Returns the diagonal local inertia in Defold mass-times-distance-squared units. A zero component denotes an axis with zero inverse inertia.
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
inertia:Vector3— diagonal local inertia
bullet3d.rigid_body.get_mass(body: Opaque<"btRigidBody">): numberN
- Since Defold 1.13.2
Get mass
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
mass:number— mass, or zero for an infinite-mass body
bullet3d.rigid_body.get_total_force(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get total accumulated force
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
force:Vector3— accumulated force in Defold units
bullet3d.rigid_body.get_total_torque(body: Opaque<"btRigidBody">): Vector3N
- Since Defold 1.13.2
Get total accumulated torque
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
torque:Vector3— accumulated torque in Defold squared units
bullet3d.rigid_body.get_velocity_in_local_point(body: Opaque<"btRigidBody">, relative_position: Vector3): Vector3N
- Since Defold 1.13.2
The relative position is expressed in world axes. Despite Bullet's function name, it is not a body-local coordinate.
Parameters
body:Opaque<"btRigidBody">— rigid bodyrelative_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(body: Opaque<"btRigidBody">): bullet3d.BtDiscreteDynamicsWorldN
- Since Defold 1.13.2
Get the body's world
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
world:bullet3d.BtDiscreteDynamicsWorld— owning world
bullet3d.rigid_body.has_flag(body: Opaque<"btRigidBody">, flag: number): booleanN
- Since Defold 1.13.2
Test a rigid body flag
Parameters
body:Opaque<"btRigidBody">— rigid bodyflag:number— flag or mask
Returns
set:boolean—truewhen all requested flag bits are set
bullet3d.rigid_body.is_valid(body: Opaque<"btRigidBody">): booleanN
- Since Defold 1.13.2
Test whether a handle refers to a valid rigid body
Parameters
body:Opaque<"btRigidBody">— rigid body
Returns
valid:boolean— rigid body validity
bullet3d.rigid_body.set_angular_damping(body: Opaque<"btRigidBody">, damping: number): voidN
- Since Defold 1.13.2
Set angular damping
Parameters
body:Opaque<"btRigidBody">— rigid bodydamping:number— finite angular damping in[0, 1]
bullet3d.rigid_body.set_angular_factor(body: Opaque<"btRigidBody">, factor: Vector3): voidN
- Since Defold 1.13.2
Set the angular factor
Parameters
body:Opaque<"btRigidBody">— rigid bodyfactor:Vector3— per-axis angular factor
bullet3d.rigid_body.set_angular_velocity(body: Opaque<"btRigidBody">, velocity: Vector3): voidN
- Since Defold 1.13.2
Set angular velocity
Parameters
body:Opaque<"btRigidBody">— rigid bodyvelocity:Vector3— finite angular velocity in radians per second
bullet3d.rigid_body.set_damping(body: Opaque<"btRigidBody">, linear: number, angular: number): voidN
- Since Defold 1.13.2
Set linear and angular damping
Parameters
body:Opaque<"btRigidBody">— rigid bodylinear:number— finite linear damping in[0, 1]angular:number— finite angular damping in[0, 1]
bullet3d.rigid_body.set_flags(body: Opaque<"btRigidBody">, flags: number): voidN
- Since Defold 1.13.2
This replaces the complete flag mask. Every enabled gyroscopic mode is evaluated independently, so clear existing gyroscopic mode bits before selecting a different mode.
Parameters
body:Opaque<"btRigidBody">— rigid bodyflags:number— rigid body flags
bullet3d.rigid_body.set_gravity(body: Opaque<"btRigidBody">, gravity: Vector3): voidN
- Since Defold 1.13.2
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.
// Give one body persistent custom gravity without discarding its other flags:
export default defineScript({
init() {
const body = bullet3d.get_rigid_body("#collisionobject");
if (body === undefined) return;
let 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));
},
});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))
endParameters
body:Opaque<"btRigidBody">— rigid bodygravity:Vector3— gravity in Defold units per second squared
bullet3d.rigid_body.set_linear_damping(body: Opaque<"btRigidBody">, damping: number): voidN
- Since Defold 1.13.2
Set linear damping
Parameters
body:Opaque<"btRigidBody">— rigid bodydamping:number— finite linear damping in[0, 1]
bullet3d.rigid_body.set_linear_factor(body: Opaque<"btRigidBody">, factor: Vector3): voidN
- Since Defold 1.13.2
Set the linear factor
Parameters
body:Opaque<"btRigidBody">— rigid bodyfactor:Vector3— per-axis linear factor
bullet3d.rigid_body.set_linear_velocity(body: Opaque<"btRigidBody">, velocity: Vector3): voidN
- Since Defold 1.13.2
Set linear velocity
Parameters
body:Opaque<"btRigidBody">— rigid bodyvelocity:Vector3— finite velocity in Defold units per second
bullet3d.rigid_body.set_mass(body: Opaque<"btRigidBody">, mass: number): voidN
- Since Defold 1.13.2
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.
// Change the mass of a dynamic collision object and inspect its recalculated inertia:
export default defineScript({
init() {
const body = bullet3d.get_rigid_body("#collisionobject");
if (body === undefined) return;
bullet3d.rigid_body.set_mass(body, 5);
print("local inertia", bullet3d.rigid_body.get_local_inertia(body));
},
});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))
endParameters
body:Opaque<"btRigidBody">— dynamic rigid bodymass:number— finite mass greater than zero
bullet3d.rigid_body.set_mass_properties(body: Opaque<"btRigidBody">, mass: number, local_inertia: Vector3): voidN
- Since Defold 1.13.2
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:Opaque<"btRigidBody">— dynamic rigid bodymass:number— finite mass greater than zerolocal_inertia:Vector3— finite non-negative diagonal local inertia in Defold mass-times-distance-squared units
bullet3d.rigid_body.set_sleeping_thresholds(body: Opaque<"btRigidBody">, linear: number, angular: number): voidN
- Since Defold 1.13.2
Set the sleeping thresholds
Parameters
body:Opaque<"btRigidBody">— rigid bodylinear:number— finite non-negative linear threshold in Defold units per secondangular:number— finite non-negative angular threshold in radians per second
Constants
bullet3d.rigid_body.BT_DISABLE_WORLD_GRAVITY: number & { readonly __brand: "bullet3d.rigid_body.BT_DISABLE_WORLD_GRAVITY" }N
- Since Defold 1.13.2
Disable automatic world gravity. Set this bit before assigning custom body gravity that must survive later world-gravity changes or re-adding the body to a world.
bullet3d.rigid_body.BT_ENABLE_GYROSCOPIC_FORCE_EXPLICIT: number & { readonly __brand: "bullet3d.rigid_body.BT_ENABLE_GYROSCOPIC_FORCE_EXPLICIT" }N
- Since Defold 1.13.2
Enable explicit gyroscopic force integration.
bullet3d.rigid_body.BT_ENABLE_GYROSCOPIC_FORCE_IMPLICIT_BODY: number & { readonly __brand: "bullet3d.rigid_body.BT_ENABLE_GYROSCOPIC_FORCE_IMPLICIT_BODY" }N
- Since Defold 1.13.2
Enable implicit body-space gyroscopic force integration. This flag is enabled by default for newly constructed rigid bodies.
bullet3d.rigid_body.BT_ENABLE_GYROSCOPIC_FORCE_IMPLICIT_WORLD: number & { readonly __brand: "bullet3d.rigid_body.BT_ENABLE_GYROSCOPIC_FORCE_IMPLICIT_WORLD" }N
- Since Defold 1.13.2
Enable implicit world-space gyroscopic force integration.