Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

bullet3d.constraint67 new

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

  • Since Defold 1.13.2

The world is derived from body_a.

  1. (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

  2. (body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.ConeTwistParams)

    Parameters

Returns

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.

  1. (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

  2. (body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.Generic6DofParams)

    Parameters

Returns

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
end

Parameters

Returns

bullet3d.constraint.create_hinge(2 overloads): bullet3d.constraint.BtTypedConstraintN

  • Since Defold 1.13.2

The world is derived from body_a.

  1. (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

  2. (body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.HingeParams)

    Parameters

    • body_a: Opaque<"btRigidBody"> — first body
    • body_b: undefined — second body or world
    • params: bullet3d.constraint.HingeParams — local frames and options

Returns

// 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
end

bullet3d.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

Returns

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.

  1. (body_a: Opaque<"btRigidBody">, body_b: Opaque<"btRigidBody"> | undefined, params: bullet3d.constraint.PointToPointParams & Required<Pick<bullet3d.constraint.PointToPointParams, "pivot_b">>)

    Parameters

  2. (body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.PointToPointParams)

    Parameters

Returns

// 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
end

bullet3d.constraint.create_slider(2 overloads): bullet3d.constraint.BtTypedConstraintN

  • Since Defold 1.13.2

The world is derived from body_a.

  1. (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

  2. (body_a: Opaque<"btRigidBody">, body_b: undefined, params: bullet3d.constraint.SliderParams)

    Parameters

    • body_a: Opaque<"btRigidBody"> — first body
    • body_b: undefined — second body or world
    • params: bullet3d.constraint.SliderParams — local frames and options

Returns

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

Returns

bullet3d.constraint.destroy(constraint: bullet3d.constraint.BtTypedConstraint): voidN

  • Since Defold 1.13.2

Destroy a constraint

Parameters

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

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 constraint
  • axis: 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 constraint
  • axis: 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 constraint
  • axis: 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

Returns

  • enabled: boolean — motor state
  • target_velocity: number — linear or angular target velocity
  • max_force: number — maximum motor force for linear axes or torque for angular axes
  • bounce: 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 constraint
  • axis: 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

Returns

  • anchor_a: Vector3 — world-space anchor on body A
  • anchor_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

Returns

  • angle_1: number — first angle in radians
  • angle_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

Returns

  • axis_1: Vector3 — first world-space unit axis
  • axis_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

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

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

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

Returns

  • swing_span_1: number — first swing span in radians
  • swing_span_2: number — second swing span in radians
  • twist_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

Returns

  • position: Vector3 — local position
  • rotation: 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

Returns

  • position: Vector3 — local position or world frame position
  • rotation: 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

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

Returns

  • lower: number — lower angle in radians
  • upper: 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

Returns

  • enabled: boolean — motor state
  • target_velocity: number — angular target velocity in radians per second
  • max_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

Returns

  • lower: number — lower limit
  • upper: 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

Returns

  • pivot_a: Vector3 — local body-A pivot
  • pivot_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

Returns

  • lower_linear: number — lower linear limit in Defold units
  • upper_linear: number — upper linear limit in Defold units
  • lower_angular: number — lower angular limit in radians
  • upper_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

Returns

  • enabled: boolean — motor state
  • target_velocity: number — linear or angular target velocity
  • max_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

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

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

Returns

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

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

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

Returns

bullet3d.constraint.is_active(constraint: bullet3d.constraint.BtTypedConstraint): booleanN

  • Since Defold 1.13.2

Test whether a constraint is active in its world

Parameters

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

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

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

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

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 constraint
  • axis: number — one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.
  • enabled: boolean — motor state
  • target_velocity: number — linear or angular target velocity
  • max_force: number — non-negative maximum motor force for linear axes or torque for angular axes
  • bounce?: number — optional bounce from 0 to 1; defaults to 0

bullet3d.constraint.set_angular_only(constraint: bullet3d.constraint.BtTypedConstraint, angular_only: boolean): voidN

  • Since Defold 1.13.2

Set angular-only mode

Parameters

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 constraint
  • swing_span_1: number — non-negative first swing span in radians
  • swing_span_2: number — non-negative second swing span in radians
  • twist_span: number — non-negative twist span in radians
  • softness?: number — optional softness from 0 to 1; defaults to 1
  • bias?: number — optional bias from 0 to 1; defaults to 0.3
  • relaxation?: number — optional relaxation from 0 to 1; defaults to 1

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 constraint
  • target: Quaternion — finite, non-zero target orientation; normalized by the binding
  • constraint_space?: boolean — optional target-is-in-constraint-space flag; defaults to false

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 constraint
  • position: Vector3 — finite local position
  • rotation: 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 constraint
  • position: Vector3 — finite local position or world frame position
  • rotation: 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

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 constraint
  • lower: number — lower angle in radians
  • upper: number — upper angle in radians
  • bias?: number — optional limit bias from 0 to 1; defaults to 0.3
  • relaxation?: number — optional relaxation from 0 to 1; defaults to 1

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 constraint
  • enabled: boolean — motor state
  • target_velocity: number — angular target velocity in radians per second
  • max_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

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 constraint
  • axis: number — one-based axis from 1 to 6. ⚠️ 1-based; passed to Defold unchanged.
  • lower: number — lower limit
  • upper: 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

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 constraint
  • lower_linear: number — lower linear limit in Defold units
  • upper_linear: number — upper linear limit in Defold units
  • lower_angular: number — lower angular limit in radians
  • upper_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 constraint
  • motor: "linear" | "angular" — linear or angular
  • enabled: boolean — motor state
  • target_velocity: number — linear or angular target velocity
  • max_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 constraint
  • axis: 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 constraint
  • axis?: 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 constraint
  • axis: 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

Types

interface bullet3d.constraint.AnchorAxesParams { anchor: Vector3; axis1: Vector3; axis2: Vector3; collide_connected?: boolean; }

type bullet3d.constraint.BtTypedConstraint = Opaque<"btTypedConstraint">

interface bullet3d.constraint.ConeTwistParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; angular_only?: boolean; collide_connected?: boolean; }

type bullet3d.constraint.ConstraintType = typeof bullet3d.constraint.CONSTRAINT_TYPE_CONE_TWIST | typeof bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF | typeof bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF_SPRING | typeof bullet3d.constraint.CONSTRAINT_TYPE_HINGE | typeof bullet3d.constraint.CONSTRAINT_TYPE_HINGE2 | typeof bullet3d.constraint.CONSTRAINT_TYPE_POINT_TO_POINT | typeof bullet3d.constraint.CONSTRAINT_TYPE_SLIDER | typeof bullet3d.constraint.CONSTRAINT_TYPE_UNIVERSAL

interface bullet3d.constraint.Generic6DofParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; collide_connected?: boolean; }

interface bullet3d.constraint.Generic6DofSpringParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position: Vector3; frame_b_rotation: Quaternion; collide_connected?: boolean; }

interface bullet3d.constraint.HingeParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; use_reference_frame_a?: boolean; angular_only?: boolean; collide_connected?: boolean; }

interface bullet3d.constraint.PointToPointParams { pivot_a: Vector3; pivot_b?: Vector3; collide_connected?: boolean; }

interface bullet3d.constraint.SliderParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; use_linear_reference_frame_a?: boolean; collide_connected?: boolean; }

On this page

Functionsbullet3d.constraint.create_cone_twist(2 overloads): bullet3d.constraint.BtTypedConstraintNbullet3d.constraint.create_generic_6dof(2 overloads): bullet3d.constraint.BtTypedConstraintNbullet3d.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.BtTypedConstraintNbullet3d.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): voidNConstantsbullet3d.constraint.CONSTRAINT_TYPE_CONE_TWIST: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_CONE_TWIST" }Nbullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF" }Nbullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF_SPRING: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF_SPRING" }Nbullet3d.constraint.CONSTRAINT_TYPE_HINGE: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_HINGE" }Nbullet3d.constraint.CONSTRAINT_TYPE_HINGE2: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_HINGE2" }Nbullet3d.constraint.CONSTRAINT_TYPE_POINT_TO_POINT: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_POINT_TO_POINT" }Nbullet3d.constraint.CONSTRAINT_TYPE_SLIDER: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_SLIDER" }Nbullet3d.constraint.CONSTRAINT_TYPE_UNIVERSAL: number & { readonly __brand: "bullet3d.constraint.CONSTRAINT_TYPE_UNIVERSAL" }NTypesinterface bullet3d.constraint.AnchorAxesParams { anchor: Vector3; axis1: Vector3; axis2: Vector3; collide_connected?: boolean; }type bullet3d.constraint.BtTypedConstraint = Opaque<"btTypedConstraint">interface bullet3d.constraint.ConeTwistParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; angular_only?: boolean; collide_connected?: boolean; }type bullet3d.constraint.ConstraintType = typeof bullet3d.constraint.CONSTRAINT_TYPE_CONE_TWIST | typeof bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF | typeof bullet3d.constraint.CONSTRAINT_TYPE_GENERIC_6DOF_SPRING | typeof bullet3d.constraint.CONSTRAINT_TYPE_HINGE | typeof bullet3d.constraint.CONSTRAINT_TYPE_HINGE2 | typeof bullet3d.constraint.CONSTRAINT_TYPE_POINT_TO_POINT | typeof bullet3d.constraint.CONSTRAINT_TYPE_SLIDER | typeof bullet3d.constraint.CONSTRAINT_TYPE_UNIVERSALinterface bullet3d.constraint.Generic6DofParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; collide_connected?: boolean; }interface bullet3d.constraint.Generic6DofSpringParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position: Vector3; frame_b_rotation: Quaternion; collide_connected?: boolean; }interface bullet3d.constraint.HingeParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; use_reference_frame_a?: boolean; angular_only?: boolean; collide_connected?: boolean; }interface bullet3d.constraint.PointToPointParams { pivot_a: Vector3; pivot_b?: Vector3; collide_connected?: boolean; }interface bullet3d.constraint.SliderParams { frame_a_position: Vector3; frame_a_rotation: Quaternion; frame_b_position?: Vector3; frame_b_rotation?: Quaternion; use_linear_reference_frame_a?: boolean; collide_connected?: boolean; }