bullet3d.constraint
Creates and controls Bullet constraints between Defold rigid bodies. A
constraint belongs to the supplied world and is destroyed automatically
with either body, with the world, or when the module is finalized. It is
temporarily removed from the native world while either linked body is
disabled and is restored when both bodies are enabled again. Dropping its
Lua userdata does not destroy the native constraint; call destroy for
early release.
Creator positions and all other linear values use Defold units and are
converted with physics.scale. Angles are radians. Axes are one-based in
Lua: axes 1-3 are linear and axes 4-6 are angular. Mutating functions cannot
be called while the physics world is stepping. Floating-point and vector
inputs must be finite. Axis vectors must be non-zero and are normalized.
Input rotations must be finite, non-zero quaternions and are normalized by
the binding.
CONSTRAINT_TYPE_* values identify the concrete constraint exposed by this
binding. This deliberately distinguishes universal, hinge2, and spring 6-DOF
constraints independently of Bullet's internal constraint type hierarchy.
Functions
bullet3d.constraint.create_cone_twist(2 overloads):bullet3d.constraint.BtTypedConstraintN(body_a:Opaque<"btRigidBody">, body_b:Opaque<"btRigidBody"> | undefined, params:bullet3d.constraint.ConeTwistParams& Required<Pick<bullet3d.constraint.ConeTwistParams, "frame_b_position" | "frame_b_rotation">>)(body_a:Opaque<"btRigidBody">, body_b: undefined, params:bullet3d.constraint.ConeTwistParams)
bullet3d.constraint.create_generic_6dof(2 overloads):bullet3d.constraint.BtTypedConstraintN(body_a:Opaque<"btRigidBody">, body_b:Opaque<"btRigidBody"> | undefined, params:bullet3d.constraint.Generic6DofParams& Required<Pick<bullet3d.constraint.Generic6DofParams, "frame_b_position" | "frame_b_rotation">>)(body_a:Opaque<"btRigidBody">, body_b: undefined, params:bullet3d.constraint.Generic6DofParams)
bullet3d.constraint.create_generic_6dof_spring(body_a:Opaque<"btRigidBody">, body_b:Opaque<"btRigidBody">, params:bullet3d.constraint.Generic6DofSpringParams):bullet3d.constraint.BtTypedConstraintNbullet3d.constraint.create_hinge(2 overloads):bullet3d.constraint.BtTypedConstraintNbullet3d.constraint.create_hinge2(body_a:Opaque<"btRigidBody">, body_b:Opaque<"btRigidBody">, params:bullet3d.constraint.AnchorAxesParams):bullet3d.constraint.BtTypedConstraintNbullet3d.constraint.create_point_to_point(2 overloads):bullet3d.constraint.BtTypedConstraintNbullet3d.constraint.create_slider(2 overloads):bullet3d.constraint.BtTypedConstraintN(body_a:Opaque<"btRigidBody">, body_b:Opaque<"btRigidBody"> | undefined, params:bullet3d.constraint.SliderParams& Required<Pick<bullet3d.constraint.SliderParams, "frame_b_position" | "frame_b_rotation">>)(body_a:Opaque<"btRigidBody">, body_b: undefined, params:bullet3d.constraint.SliderParams)
bullet3d.constraint.create_universal(body_a:Opaque<"btRigidBody">, body_b:Opaque<"btRigidBody">, params:bullet3d.constraint.AnchorAxesParams):bullet3d.constraint.BtTypedConstraintNbullet3d.constraint.destroy(constraint:bullet3d.constraint.BtTypedConstraint): voidNbullet3d.constraint.enable_cone_twist_motor(constraint:bullet3d.constraint.BtTypedConstraint, enabled: boolean): voidNbullet3d.constraint.enable_spring(constraint:bullet3d.constraint.BtTypedConstraint, axis: number, enabled: boolean): voidNbullet3d.constraint.get_6dof_angle(constraint:bullet3d.constraint.BtTypedConstraint, axis: number): numberNbullet3d.constraint.get_6dof_axis(constraint:bullet3d.constraint.BtTypedConstraint, axis: number): Vector3Nbullet3d.constraint.get_6dof_motor(constraint:bullet3d.constraint.BtTypedConstraint, axis: number): LuaMultiReturn<[boolean, number, number, number]>Nbullet3d.constraint.get_6dof_position(constraint:bullet3d.constraint.BtTypedConstraint, axis: number): numberNbullet3d.constraint.get_anchors(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Vector3]>Nbullet3d.constraint.get_angles(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number]>Nbullet3d.constraint.get_axes(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Vector3]>Nbullet3d.constraint.get_body_a(constraint:bullet3d.constraint.BtTypedConstraint):Opaque<"btRigidBody">Nbullet3d.constraint.get_body_b(constraint:bullet3d.constraint.BtTypedConstraint):Opaque<"btRigidBody"> | undefinedNbullet3d.constraint.get_collide_connected(constraint:bullet3d.constraint.BtTypedConstraint): booleanNbullet3d.constraint.get_cone_twist_limits(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number, number]>Nbullet3d.constraint.get_frame_a(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Quaternion]>Nbullet3d.constraint.get_frame_b(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Quaternion]>Nbullet3d.constraint.get_hinge_angle(constraint:bullet3d.constraint.BtTypedConstraint): numberNbullet3d.constraint.get_hinge_limits(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number]>Nbullet3d.constraint.get_hinge_motor(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[boolean, number, number]>Nbullet3d.constraint.get_limit(constraint:bullet3d.constraint.BtTypedConstraint, axis: number): LuaMultiReturn<[number, number]>Nbullet3d.constraint.get_pivots(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Vector3]>Nbullet3d.constraint.get_slider_limits(constraint:bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number, number, number]>Nbullet3d.constraint.get_slider_motor(constraint:bullet3d.constraint.BtTypedConstraint, motor: "linear" | "angular"): LuaMultiReturn<[boolean, number, number]>Nbullet3d.constraint.get_slider_position(constraint:bullet3d.constraint.BtTypedConstraint): numberNbullet3d.constraint.get_twist_angle(constraint:bullet3d.constraint.BtTypedConstraint): numberNbullet3d.constraint.get_type(constraint:bullet3d.constraint.BtTypedConstraint):bullet3d.constraint.ConstraintTypeNbullet3d.constraint.get_type_name(constraint:bullet3d.constraint.BtTypedConstraint): stringNbullet3d.constraint.get_use_linear_reference_frame_a(constraint:bullet3d.constraint.BtTypedConstraint): booleanNbullet3d.constraint.get_world(constraint:bullet3d.constraint.BtTypedConstraint):bullet3d.BtDiscreteDynamicsWorldNbullet3d.constraint.is_active(constraint:bullet3d.constraint.BtTypedConstraint): booleanNbullet3d.constraint.is_angular_only(constraint:bullet3d.constraint.BtTypedConstraint): booleanNbullet3d.constraint.is_limited(constraint:bullet3d.constraint.BtTypedConstraint, axis: number): booleanNbullet3d.constraint.is_past_swing_limit(constraint:bullet3d.constraint.BtTypedConstraint): booleanNbullet3d.constraint.is_valid(constraint:bullet3d.constraint.BtTypedConstraint): booleanNbullet3d.constraint.set_6dof_motor(constraint:bullet3d.constraint.BtTypedConstraint, axis: number, enabled: boolean, target_velocity: number, max_force: number, bounce?: number): voidNbullet3d.constraint.set_angular_only(constraint:bullet3d.constraint.BtTypedConstraint, angular_only: boolean): voidNbullet3d.constraint.set_cone_twist_limits(constraint:bullet3d.constraint.BtTypedConstraint, swing_span_1: number, swing_span_2: number, twist_span: number, softness?: number, bias?: number, relaxation?: number): voidNbullet3d.constraint.set_cone_twist_motor_target(constraint:bullet3d.constraint.BtTypedConstraint, target: Quaternion, constraint_space?: boolean): voidNbullet3d.constraint.set_frame_a(constraint:bullet3d.constraint.BtTypedConstraint, position: Vector3, rotation: Quaternion): voidNbullet3d.constraint.set_frame_b(constraint:bullet3d.constraint.BtTypedConstraint, position: Vector3, rotation: Quaternion): voidNbullet3d.constraint.set_hinge_axis(constraint:bullet3d.constraint.BtTypedConstraint, axis: Vector3): voidNbullet3d.constraint.set_hinge_limits(constraint:bullet3d.constraint.BtTypedConstraint, lower: number, upper: number, bias?: number, relaxation?: number): voidNbullet3d.constraint.set_hinge_motor(constraint:bullet3d.constraint.BtTypedConstraint, enabled: boolean, target_velocity: number, max_impulse: number): voidNbullet3d.constraint.set_hinge_motor_target(constraint:bullet3d.constraint.BtTypedConstraint, target_angle: number, time_step: number): voidNbullet3d.constraint.set_limit(constraint:bullet3d.constraint.BtTypedConstraint, axis: number, lower: number, upper: number): voidNbullet3d.constraint.set_pivots(constraint:bullet3d.constraint.BtTypedConstraint, pivot_a: Vector3, pivot_b: Vector3): voidNbullet3d.constraint.set_slider_limits(constraint:bullet3d.constraint.BtTypedConstraint, lower_linear: number, upper_linear: number, lower_angular: number, upper_angular: number): voidNbullet3d.constraint.set_slider_motor(constraint:bullet3d.constraint.BtTypedConstraint, motor: "linear" | "angular", enabled: boolean, target_velocity: number, max_force: number): voidNbullet3d.constraint.set_spring_damping(constraint:bullet3d.constraint.BtTypedConstraint, axis: number, damping: number): voidNbullet3d.constraint.set_spring_equilibrium_point(constraint:bullet3d.constraint.BtTypedConstraint, axis?: number, value?: number): voidNbullet3d.constraint.set_spring_stiffness(constraint:bullet3d.constraint.BtTypedConstraint, axis: number, stiffness: number): voidN
bullet3d.constraint.create_cone_twist(2 overloads): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
The world is derived from body_a.
(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody"> | undefined, params: bullet3d.constraint.ConeTwistParams & Required<Pick<bullet3d.constraint.ConeTwistParams, "frame_b_position" | "frame_b_rotation">>)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody"> | undefined— second body or worldparams:bullet3d.constraint.ConeTwistParams & Required<Pick<bullet3d.constraint.ConeTwistParams, "frame_b_position" | "frame_b_rotation">>— local frames and options
(body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.ConeTwistParams)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:undefined— second body or worldparams:bullet3d.constraint.ConeTwistParams— local frames and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— cone-twist constraint
bullet3d.constraint.create_generic_6dof(2 overloads): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
The params table requires local frame A and, for a two-body constraint,
local frame B. It optionally accepts collide_connected. The world is
derived from body_a. The active 6-DOF solver ignores its legacy
linear-reference-frame selector, so that field is rejected rather than
silently accepted.
(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody"> | undefined, params: bullet3d.constraint.Generic6DofParams & Required<Pick<bullet3d.constraint.Generic6DofParams, "frame_b_position" | "frame_b_rotation">>)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody"> | undefined— second body or worldparams:bullet3d.constraint.Generic6DofParams & Required<Pick<bullet3d.constraint.Generic6DofParams, "frame_b_position" | "frame_b_rotation">>— local frames and options
(body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.Generic6DofParams)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:undefined— second body or worldparams:bullet3d.constraint.Generic6DofParams— local frames and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— generic 6-DOF constraint
bullet3d.constraint.create_generic_6dof_spring(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody">, params: bullet3d.constraint.Generic6DofSpringParams): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
Both bodies and both local frames are required. The params table optionally
accepts collide_connected. The world is derived from body_a. The active
spring 6-DOF solver ignores its legacy linear-reference-frame selector, so
that field is rejected rather than silently accepted.
// Create a spring that moves along its first linear axis:
export default defineScript({
init() {
const body_a = bullet3d.get_rigid_body("/body_a#collisionobject");
const body_b = bullet3d.get_rigid_body("/body_b#collisionobject");
let spring: bullet3d.constraint.BtTypedConstraint | undefined;
if (body_a !== undefined && body_b !== undefined) {
spring = bullet3d.constraint.create_generic_6dof_spring(body_a, body_b, {
frame_a_position: vmath.vector3(),
frame_a_rotation: vmath.quat(),
frame_b_position: vmath.vector3(),
frame_b_rotation: vmath.quat(),
});
bullet3d.constraint.set_limit(spring, 1, -1, 1);
bullet3d.constraint.enable_spring(spring, 1, true);
bullet3d.constraint.set_spring_stiffness(spring, 1, 20);
bullet3d.constraint.set_spring_damping(spring, 1, 0.5);
bullet3d.constraint.set_spring_equilibrium_point(spring, 1, 0);
}
return { spring };
},
final(self) {
if (self.spring !== undefined && bullet3d.constraint.is_valid(self.spring)) {
bullet3d.constraint.destroy(self.spring);
}
},
});function init(self)
local body_a = bullet3d.get_rigid_body("/body_a#collisionobject")
local body_b = bullet3d.get_rigid_body("/body_b#collisionobject")
self.spring = bullet3d.constraint.create_generic_6dof_spring(body_a, body_b, {
frame_a_position = vmath.vector3(),
frame_a_rotation = vmath.quat(),
frame_b_position = vmath.vector3(),
frame_b_rotation = vmath.quat(),
})
bullet3d.constraint.set_limit(self.spring, 1, -1, 1)
bullet3d.constraint.enable_spring(self.spring, 1, true)
bullet3d.constraint.set_spring_stiffness(self.spring, 1, 20)
bullet3d.constraint.set_spring_damping(self.spring, 1, 0.5)
bullet3d.constraint.set_spring_equilibrium_point(self.spring, 1, 0)
end
function final(self)
if self.spring and bullet3d.constraint.is_valid(self.spring) then
bullet3d.constraint.destroy(self.spring)
end
endParameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody">— second bodyparams:bullet3d.constraint.Generic6DofSpringParams— local frames and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— spring 6-DOF constraint
bullet3d.constraint.create_hinge(2 overloads): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
The world is derived from body_a.
(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody"> | undefined, params: bullet3d.constraint.HingeParams & Required<Pick<bullet3d.constraint.HingeParams, "frame_b_position" | "frame_b_rotation">>)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody"> | undefined— second body or worldparams:bullet3d.constraint.HingeParams & Required<Pick<bullet3d.constraint.HingeParams, "frame_b_position" | "frame_b_rotation">>— local frames and options
(body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.HingeParams)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:undefined— second body or worldparams:bullet3d.constraint.HingeParams— local frames and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— hinge constraint
// Create a motorized hinge with a 90-degree range:
export default defineScript({
init() {
const body_a = bullet3d.get_rigid_body("/door#collisionobject");
const body_b = bullet3d.get_rigid_body("/frame#collisionobject");
let hinge: bullet3d.constraint.BtTypedConstraint | undefined;
if (body_a !== undefined) {
hinge = bullet3d.constraint.create_hinge(body_a, body_b, {
frame_a_position: vmath.vector3(-0.5, 0, 0),
frame_a_rotation: vmath.quat(),
frame_b_position: vmath.vector3(0.5, 0, 0),
frame_b_rotation: vmath.quat(),
});
bullet3d.constraint.set_hinge_limits(hinge, -math.pi / 4, math.pi / 4);
bullet3d.constraint.set_hinge_motor(hinge, true, 1.5, 2.5);
}
return { hinge };
},
final(self) {
if (self.hinge !== undefined && bullet3d.constraint.is_valid(self.hinge)) {
bullet3d.constraint.destroy(self.hinge);
}
},
});function init(self)
local body_a = bullet3d.get_rigid_body("/door#collisionobject")
local body_b = bullet3d.get_rigid_body("/frame#collisionobject")
self.hinge = bullet3d.constraint.create_hinge(body_a, body_b, {
frame_a_position = vmath.vector3(-0.5, 0, 0),
frame_a_rotation = vmath.quat(),
frame_b_position = vmath.vector3(0.5, 0, 0),
frame_b_rotation = vmath.quat(),
})
bullet3d.constraint.set_hinge_limits(self.hinge, -math.pi / 4, math.pi / 4)
bullet3d.constraint.set_hinge_motor(self.hinge, true, 1.5, 2.5)
end
function final(self)
if self.hinge and bullet3d.constraint.is_valid(self.hinge) then
bullet3d.constraint.destroy(self.hinge)
end
endbullet3d.constraint.create_hinge2(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody">, params: bullet3d.constraint.AnchorAxesParams): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
Both bodies are required. Its initial linear suspension travel is one Defold
unit in either direction. The world is derived from body_a.
Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody">— second bodyparams:bullet3d.constraint.AnchorAxesParams— anchor, axes, and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— hinge2 constraint
bullet3d.constraint.create_point_to_point(2 overloads): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
The world is derived from body_a; both bodies must belong to that same world.
(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody"> | undefined, params: bullet3d.constraint.PointToPointParams & Required<Pick<bullet3d.constraint.PointToPointParams, "pivot_b">>)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody"> | undefined— second body or worldparams:bullet3d.constraint.PointToPointParams & Required<Pick<bullet3d.constraint.PointToPointParams, "pivot_b">>— pivots and options
(body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.PointToPointParams)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:undefined— second body or worldparams:bullet3d.constraint.PointToPointParams— pivots and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— point-to-point constraint
// Join two bodies at matching local pivots and explicitly destroy the
// constraint when the script is finalized:
export default defineScript({
init() {
const body_a = bullet3d.get_rigid_body("/body_a#collisionobject");
const body_b = bullet3d.get_rigid_body("/body_b#collisionobject");
let constraint: bullet3d.constraint.BtTypedConstraint | undefined;
if (body_a !== undefined) {
constraint = bullet3d.constraint.create_point_to_point(body_a, body_b, {
pivot_a: vmath.vector3(0.5, 0, 0),
pivot_b: vmath.vector3(-0.5, 0, 0),
});
}
return { constraint };
},
final(self) {
if (self.constraint !== undefined && bullet3d.constraint.is_valid(self.constraint)) {
bullet3d.constraint.destroy(self.constraint);
}
},
});function init(self)
local body_a = bullet3d.get_rigid_body("/body_a#collisionobject")
local body_b = bullet3d.get_rigid_body("/body_b#collisionobject")
self.constraint = bullet3d.constraint.create_point_to_point(body_a, body_b, {
pivot_a = vmath.vector3(0.5, 0, 0),
pivot_b = vmath.vector3(-0.5, 0, 0),
})
end
function final(self)
if self.constraint and bullet3d.constraint.is_valid(self.constraint) then
bullet3d.constraint.destroy(self.constraint)
end
endbullet3d.constraint.create_slider(2 overloads): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
The world is derived from body_a.
(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody"> | undefined, params: bullet3d.constraint.SliderParams & Required<Pick<bullet3d.constraint.SliderParams, "frame_b_position" | "frame_b_rotation">>)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody"> | undefined— second body or worldparams:bullet3d.constraint.SliderParams & Required<Pick<bullet3d.constraint.SliderParams, "frame_b_position" | "frame_b_rotation">>— local frames and options
(body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.SliderParams)Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:undefined— second body or worldparams:bullet3d.constraint.SliderParams— local frames and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— slider constraint
bullet3d.constraint.create_universal(body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody">, params: bullet3d.constraint.AnchorAxesParams): bullet3d.constraint.BtTypedConstraintN
- Since Defold 1.13.2
Both bodies are required. The world is derived from body_a.
Parameters
body_a:Opaque<"btRigidBody">— first bodybody_b:Opaque<"btRigidBody">— second bodyparams:bullet3d.constraint.AnchorAxesParams— anchor, axes, and options
Returns
constraint:bullet3d.constraint.BtTypedConstraint— universal constraint
bullet3d.constraint.destroy(constraint: bullet3d.constraint.BtTypedConstraint): voidN
- Since Defold 1.13.2
Destroy a constraint
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
bullet3d.constraint.enable_cone_twist_motor(constraint: bullet3d.constraint.BtTypedConstraint, enabled: boolean): voidN
- Since Defold 1.13.2
Enable or disable the cone-twist motor
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— cone-twist constraintenabled:boolean— motor state
bullet3d.constraint.enable_spring(constraint: bullet3d.constraint.BtTypedConstraint, axis: number, enabled: boolean): voidN
- Since Defold 1.13.2
Enable or disable a spring axis
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— spring 6-DOF or hinge2 constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.enabled:boolean— spring state
bullet3d.constraint.get_6dof_angle(constraint: bullet3d.constraint.BtTypedConstraint, axis: number): numberN
- Since Defold 1.13.2
Get a current 6-DOF angle
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based angular-axis index from 1 to 3. ⚠️ 1-based; passed to Defold unchanged.
Returns
angle:number— current angle in radians
bullet3d.constraint.get_6dof_axis(constraint: bullet3d.constraint.BtTypedConstraint, axis: number): Vector3N
- Since Defold 1.13.2
Get a current 6-DOF angular axis
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based angular-axis index from 1 to 3. ⚠️ 1-based; passed to Defold unchanged.
Returns
direction:Vector3— world-space unit axis
bullet3d.constraint.get_6dof_motor(constraint: bullet3d.constraint.BtTypedConstraint, axis: number): LuaMultiReturn<[boolean, number, number, number]>N
- Since Defold 1.13.2
Axes 1-3 are linear and axes 4-6 are angular. Generic 6-DOF, generic spring
6-DOF, and universal constraints support bounce only on angular axes; hinge2
supports it on every axis. Linear target velocity uses Defold units per
second and angular target velocity uses radians per second. max_force is a
force for linear axes and a torque in Defold squared units for angular axes.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.
Returns
enabled:boolean— motor statetarget_velocity:number— linear or angular target velocitymax_force:number— maximum motor force for linear axes or torque for angular axesbounce:number— bounce from 0 to 1
bullet3d.constraint.get_6dof_position(constraint: bullet3d.constraint.BtTypedConstraint, axis: number): numberN
- Since Defold 1.13.2
Get a current 6-DOF linear position
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based linear-axis index from 1 to 3. ⚠️ 1-based; passed to Defold unchanged.
Returns
position:number— relative position in Defold units
bullet3d.constraint.get_anchors(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Vector3]>N
- Since Defold 1.13.2
Get universal or hinge2 anchors
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— universal or hinge2 constraint
Returns
anchor_a:Vector3— world-space anchor on body Aanchor_b:Vector3— world-space anchor on body B
bullet3d.constraint.get_angles(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number]>N
- Since Defold 1.13.2
Get universal or hinge2 angles
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— universal or hinge2 constraint
Returns
angle_1:number— first angle in radiansangle_2:number— second angle in radians
bullet3d.constraint.get_axes(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Vector3]>N
- Since Defold 1.13.2
Get universal or hinge2 axes
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— universal or hinge2 constraint
Returns
axis_1:Vector3— first world-space unit axisaxis_2:Vector3— second world-space unit axis
bullet3d.constraint.get_body_a(constraint: bullet3d.constraint.BtTypedConstraint): Opaque<"btRigidBody">N
- Since Defold 1.13.2
Get the first linked body
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
Returns
body:Opaque<"btRigidBody">— first body
bullet3d.constraint.get_body_b(constraint: bullet3d.constraint.BtTypedConstraint): Opaque<"btRigidBody"> | undefinedN
- Since Defold 1.13.2
Get the second linked body
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
Returns
body:Opaque<"btRigidBody"> | undefined— second body, or nil for a world constraint
bullet3d.constraint.get_collide_connected(constraint: bullet3d.constraint.BtTypedConstraint): booleanN
- Since Defold 1.13.2
Get whether connected bodies can collide
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
Returns
collide:boolean— whether connected bodies can collide
bullet3d.constraint.get_cone_twist_limits(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number, number]>N
- Since Defold 1.13.2
Get cone-twist angular spans
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— cone-twist constraint
Returns
swing_span_1:number— first swing span in radiansswing_span_2:number— second swing span in radianstwist_span:number— twist span in radians
bullet3d.constraint.get_frame_a(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Quaternion]>N
- Since Defold 1.13.2
Supported constraint types are hinge, cone-twist, generic 6-DOF, generic
spring 6-DOF, slider, universal, and hinge2. Point-to-point constraints use
get_pivots instead.
Returns position and rotation. For one-body generic 6-DOF and slider
constraints this is the user-body frame, despite Bullet storing it as its
native frame B.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— framed constraint
Returns
position:Vector3— local positionrotation:Quaternion— local rotation
bullet3d.constraint.get_frame_b(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Quaternion]>N
- Since Defold 1.13.2
Supports the same constraint types as get_frame_a. For a one-body
constraint, this is the frame attached to the fixed world body.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— framed constraint
Returns
position:Vector3— local position or world frame positionrotation:Quaternion— local rotation or world frame rotation
bullet3d.constraint.get_hinge_angle(constraint: bullet3d.constraint.BtTypedConstraint): numberN
- Since Defold 1.13.2
Get the current hinge angle
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge constraint
Returns
angle:number— angle in radians
bullet3d.constraint.get_hinge_limits(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number]>N
- Since Defold 1.13.2
Get hinge angular limits
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge constraint
Returns
lower:number— lower angle in radiansupper:number— upper angle in radians
bullet3d.constraint.get_hinge_motor(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[boolean, number, number]>N
- Since Defold 1.13.2
Get hinge motor settings
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge constraint
Returns
enabled:boolean— motor statetarget_velocity:number— angular target velocity in radians per secondmax_impulse:number— maximum angular motor impulse in Defold squared units
bullet3d.constraint.get_limit(constraint: bullet3d.constraint.BtTypedConstraint, axis: number): LuaMultiReturn<[number, number]>N
- Since Defold 1.13.2
Axes 1-3 return linear limits in Defold units. Axes 4-6 return angular limits in radians.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.
Returns
lower:number— lower limitupper:number— upper limit
bullet3d.constraint.get_pivots(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[Vector3, Vector3]>N
- Since Defold 1.13.2
Get point-to-point pivots
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— point-to-point constraint
Returns
pivot_a:Vector3— local body-A pivotpivot_b:Vector3— local body-B pivot or world anchor
bullet3d.constraint.get_slider_limits(constraint: bullet3d.constraint.BtTypedConstraint): LuaMultiReturn<[number, number, number, number]>N
- Since Defold 1.13.2
Get slider limits
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— slider constraint
Returns
lower_linear:number— lower linear limit in Defold unitsupper_linear:number— upper linear limit in Defold unitslower_angular:number— lower angular limit in radiansupper_angular:number— upper angular limit in radians
bullet3d.constraint.get_slider_motor(constraint: bullet3d.constraint.BtTypedConstraint, motor: "linear" | "angular"): LuaMultiReturn<[boolean, number, number]>N
- Since Defold 1.13.2
The linear motor uses Defold units per second and maximum force. The angular motor uses radians per second and maximum torque in Defold squared units.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— slider constraintmotor:"linear" | "angular"—linearorangular
Returns
enabled:boolean— motor statetarget_velocity:number— linear or angular target velocitymax_force:number— maximum linear force or angular torque
bullet3d.constraint.get_slider_position(constraint: bullet3d.constraint.BtTypedConstraint): numberN
- Since Defold 1.13.2
Get the current slider position
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— slider constraint
Returns
position:number— current linear position in Defold units
bullet3d.constraint.get_twist_angle(constraint: bullet3d.constraint.BtTypedConstraint): numberN
- Since Defold 1.13.2
Get the current cone-twist twist angle
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— cone-twist constraint
Returns
angle:number— twist angle in radians
bullet3d.constraint.get_type(constraint: bullet3d.constraint.BtTypedConstraint): bullet3d.constraint.ConstraintTypeN
- Since Defold 1.13.2
Get the constraint type
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
Returns
type:bullet3d.constraint.ConstraintType— constraint type
bullet3d.constraint.get_type_name(constraint: bullet3d.constraint.BtTypedConstraint): stringN
- Since Defold 1.13.2
Returns a stable lowercase diagnostic name such as "hinge" or
"generic_6dof_spring".
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
Returns
name:string— constraint type name
bullet3d.constraint.get_use_linear_reference_frame_a(constraint: bullet3d.constraint.BtTypedConstraint): booleanN
- Since Defold 1.13.2
Get the slider linear reference-frame choice
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— slider constraint
Returns
use_frame_a:boolean— true when linear calculations reference frame A
bullet3d.constraint.get_world(constraint: bullet3d.constraint.BtTypedConstraint): bullet3d.BtDiscreteDynamicsWorldN
- Since Defold 1.13.2
Get the owning world
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
Returns
world:bullet3d.BtDiscreteDynamicsWorld— owning world
bullet3d.constraint.is_active(constraint: bullet3d.constraint.BtTypedConstraint): booleanN
- Since Defold 1.13.2
Test whether a constraint is active in its world
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint
Returns
active:boolean— false while a linked body is disabled
bullet3d.constraint.is_angular_only(constraint: bullet3d.constraint.BtTypedConstraint): booleanN
- Since Defold 1.13.2
Test angular-only mode
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge or cone-twist constraint
Returns
angular_only:boolean— angular-only state
bullet3d.constraint.is_limited(constraint: bullet3d.constraint.BtTypedConstraint, axis: number): booleanN
- Since Defold 1.13.2
Both a ranged and a locked axis are considered limited; a free axis is not.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.
Returns
limited:boolean— limit state
bullet3d.constraint.is_past_swing_limit(constraint: bullet3d.constraint.BtTypedConstraint): booleanN
- Since Defold 1.13.2
Test whether a cone-twist is past its swing limit
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— cone-twist constraint
Returns
past_limit:boolean— swing-limit state
bullet3d.constraint.is_valid(constraint: bullet3d.constraint.BtTypedConstraint): booleanN
- Since Defold 1.13.2
Test whether a constraint handle is valid
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— constraint handle
Returns
valid:boolean— true while the native constraint exists
bullet3d.constraint.set_6dof_motor(constraint: bullet3d.constraint.BtTypedConstraint, axis: number, enabled: boolean, target_velocity: number, max_force: number, bounce?: number): voidN
- Since Defold 1.13.2
Linear and angular values use the units described by get_6dof_motor.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.enabled:boolean— motor statetarget_velocity:number— linear or angular target velocitymax_force:number— non-negative maximum motor force for linear axes or torque for angular axesbounce?:number— optional bounce from 0 to 1; defaults to0
bullet3d.constraint.set_angular_only(constraint: bullet3d.constraint.BtTypedConstraint, angular_only: boolean): voidN
- Since Defold 1.13.2
Set angular-only mode
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge or cone-twist constraintangular_only:boolean— angular-only state
bullet3d.constraint.set_cone_twist_limits(constraint: bullet3d.constraint.BtTypedConstraint, swing_span_1: number, swing_span_2: number, twist_span: number, softness?: number, bias?: number, relaxation?: number): voidN
- Since Defold 1.13.2
Set cone-twist angular spans
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— cone-twist constraintswing_span_1:number— non-negative first swing span in radiansswing_span_2:number— non-negative second swing span in radianstwist_span:number— non-negative twist span in radianssoftness?:number— optional softness from 0 to 1; defaults to1bias?:number— optional bias from 0 to 1; defaults to0.3relaxation?:number— optional relaxation from 0 to 1; defaults to1
bullet3d.constraint.set_cone_twist_motor_target(constraint: bullet3d.constraint.BtTypedConstraint, target: Quaternion, constraint_space?: boolean): voidN
- Since Defold 1.13.2
By default, target is the desired rotation of body A relative to body B.
With constraint_space set, it is the desired rotation of frame A relative
to frame B in constraint space.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— cone-twist constrainttarget:Quaternion— finite, non-zero target orientation; normalized by the bindingconstraint_space?:boolean— optional target-is-in-constraint-space flag; defaults tofalse
bullet3d.constraint.set_frame_a(constraint: bullet3d.constraint.BtTypedConstraint, position: Vector3, rotation: Quaternion): voidN
- Since Defold 1.13.2
Frame mutation is supported for hinge, generic 6-DOF, generic spring 6-DOF, and slider constraints. Cone-twist, universal, and hinge2 frames are read-only through this API.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— mutable framed constraintposition:Vector3— finite local positionrotation:Quaternion— finite, non-zero local rotation; normalized by the binding
bullet3d.constraint.set_frame_b(constraint: bullet3d.constraint.BtTypedConstraint, position: Vector3, rotation: Quaternion): voidN
- Since Defold 1.13.2
Supports the same constraint types as set_frame_a. For a one-body
constraint, this changes the frame attached to the fixed world body.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— mutable framed constraintposition:Vector3— finite local position or world frame positionrotation:Quaternion— finite, non-zero local or world frame rotation; normalized by the binding
bullet3d.constraint.set_hinge_axis(constraint: bullet3d.constraint.BtTypedConstraint, axis: Vector3): voidN
- Since Defold 1.13.2
This function only supports hinges attached to the world. For a two-body
hinge, change both local frames with set_frame_a and set_frame_b.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— one-body hinge constraintaxis:Vector3— non-zero axis in body-A space
bullet3d.constraint.set_hinge_limits(constraint: bullet3d.constraint.BtTypedConstraint, lower: number, upper: number, bias?: number, relaxation?: number): voidN
- Since Defold 1.13.2
Set hinge angular limits
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge constraintlower:number— lower angle in radiansupper:number— upper angle in radiansbias?:number— optional limit bias from 0 to 1; defaults to0.3relaxation?:number— optional relaxation from 0 to 1; defaults to1
bullet3d.constraint.set_hinge_motor(constraint: bullet3d.constraint.BtTypedConstraint, enabled: boolean, target_velocity: number, max_impulse: number): voidN
- Since Defold 1.13.2
Set hinge motor settings
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge constraintenabled:boolean— motor statetarget_velocity:number— angular target velocity in radians per secondmax_impulse:number— non-negative maximum angular motor impulse in Defold squared units
bullet3d.constraint.set_hinge_motor_target(constraint: bullet3d.constraint.BtTypedConstraint, target_angle: number, time_step: number): voidN
- Since Defold 1.13.2
Set a hinge motor angle target
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— hinge constrainttarget_angle:number— target angle in radianstime_step:number— positive step duration in seconds
bullet3d.constraint.set_limit(constraint: bullet3d.constraint.BtTypedConstraint, axis: number, lower: number, upper: number): voidN
- Since Defold 1.13.2
Axes 1-3 use Defold units and axes 4-6 use radians. A lower value less than the upper value creates a limited range, equal values lock the axis, and a lower value greater than the upper value makes the axis free.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— 6-DOF-derived constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.lower:number— lower limitupper:number— upper limit
bullet3d.constraint.set_pivots(constraint: bullet3d.constraint.BtTypedConstraint, pivot_a: Vector3, pivot_b: Vector3): voidN
- Since Defold 1.13.2
Set point-to-point pivots
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— point-to-point constraintpivot_a:Vector3— local body-A pivotpivot_b:Vector3— local body-B pivot or world anchor
bullet3d.constraint.set_slider_limits(constraint: bullet3d.constraint.BtTypedConstraint, lower_linear: number, upper_linear: number, lower_angular: number, upper_angular: number): voidN
- Since Defold 1.13.2
Each lower/upper pair follows Bullet's limit convention: lower less than upper creates a limited range, equal values lock that axis, and lower greater than upper makes it free. Bullet normalizes the angular limits.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— slider constraintlower_linear:number— lower linear limit in Defold unitsupper_linear:number— upper linear limit in Defold unitslower_angular:number— lower angular limit in radiansupper_angular:number— upper angular limit in radians
bullet3d.constraint.set_slider_motor(constraint: bullet3d.constraint.BtTypedConstraint, motor: "linear" | "angular", enabled: boolean, target_velocity: number, max_force: number): voidN
- Since Defold 1.13.2
Linear and angular values use the units described by get_slider_motor.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— slider constraintmotor:"linear" | "angular"—linearorangularenabled:boolean— motor statetarget_velocity:number— linear or angular target velocitymax_force:number— non-negative maximum linear force or angular torque
bullet3d.constraint.set_spring_damping(constraint: bullet3d.constraint.BtTypedConstraint, axis: number, damping: number): voidN
- Since Defold 1.13.2
Generic spring 6-DOF constraints use a scale-independent damping factor from
0 to 1, where 1 means no damping. Hinge2 constraints use a damping coefficient
where 0 means no damping and any non-negative value is accepted. Hinge2
angular damping is automatically converted using physics.scale squared.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— spring 6-DOF or hinge2 constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.damping:number— damping value in the range required by the constraint type
bullet3d.constraint.set_spring_equilibrium_point(constraint: bullet3d.constraint.BtTypedConstraint, axis?: number, value?: number): voidN
- Since Defold 1.13.2
With no axis, captures all current transforms. With an axis and no value, captures that axis. Linear values use Defold units and angular values use radians.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— spring 6-DOF or hinge2 constraintaxis?:number— optional one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.value?:number— optional explicit equilibrium value
bullet3d.constraint.set_spring_stiffness(constraint: bullet3d.constraint.BtTypedConstraint, axis: number, stiffness: number): voidN
- Since Defold 1.13.2
Linear stiffness values are independent of physics.scale. Angular
stiffness values are automatically converted using physics.scale squared.
Parameters
constraint:bullet3d.constraint.BtTypedConstraint— spring 6-DOF or hinge2 constraintaxis:number— one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.stiffness:number— non-negative stiffness
Constants
bullet3d.constraint.CONSTRAINT_TYPE_CONE_TWIST: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_CONE_TWIST" }N
- Since Defold 1.13.2
Cone-twist constraint type
bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF" }N
- Since Defold 1.13.2
Generic 6-DOF constraint type
bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF_SPRING: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF_SPRING" }N
- Since Defold 1.13.2
Generic spring 6-DOF constraint type
bullet3d.constraint.CONSTRAINT_TYPE_HINGE: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_HINGE" }N
- Since Defold 1.13.2
Hinge constraint type
bullet3d.constraint.CONSTRAINT_TYPE_HINGE2: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_HINGE2" }N
- Since Defold 1.13.2
Hinge2 constraint type
bullet3d.constraint.CONSTRAINT_TYPE_POINT_TO_POINT: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_POINT_TO_POINT" }N
- Since Defold 1.13.2
Point-to-point constraint type
bullet3d.constraint.CONSTRAINT_TYPE_SLIDER: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_SLIDER" }N
- Since Defold 1.13.2
Slider constraint type
bullet3d.constraint.CONSTRAINT_TYPE_UNIVERSAL: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_UNIVERSAL" }N
- Since Defold 1.13.2
Universal constraint type