Bullet constraint API

btTypedConstraint

btTypedConstraint = userdata

Bullet typed constraint

bullet3d.constraint.anchor_axes_params

Universal and hinge2 constraint parameters

FIELDS

bullet3d.constraint.cone_twist_params

The frame-B fields are required for a two-body constraint.

FIELDS

bullet3d.constraint.generic_6dof_params

The frame-B fields are required for a two-body constraint.

FIELDS

bullet3d.constraint.generic_6dof_spring_params

Generic spring 6-DOF constraint parameters

FIELDS

bullet3d.constraint.hinge_params

The frame-B fields are required for a two-body constraint.

FIELDS

bullet3d.constraint.point_to_point_params

pivot_b is required for a two-body constraint. For a one-body constraint, it is an optional world-space anchor.

FIELDS

bullet3d.constraint.slider_params

The frame-B fields are required for a two-body constraint.

FIELDS

bullet3d.constraint.CONSTRAINT_TYPE

bullet3d.constraint.CONSTRAINT_TYPE: integer

Constraint types

VALUES

bullet3d.constraint.create_cone_twist()

bullet3d.constraint.create_cone_twist(body_a:btRigidBody, body_b:btRigidBody|nil, params:bullet3d.constraint.cone_twist_params)→constraint:btTypedConstraint

The world is derived from body_a.

PARAMETERS

RETURNS

bullet3d.constraint.create_generic_6dof()

bullet3d.constraint.create_generic_6dof(body_a:btRigidBody, body_b:btRigidBody|nil, params:bullet3d.constraint.generic_6dof_params)→constraint:btTypedConstraint

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.

PARAMETERS

RETURNS

bullet3d.constraint.create_generic_6dof_spring()

bullet3d.constraint.create_generic_6dof_spring(body_a:btRigidBody, body_b:btRigidBody, params:bullet3d.constraint.generic_6dof_spring_params)→constraint:btTypedConstraint

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.

PARAMETERS

RETURNS

EXAMPLES

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

bullet3d.constraint.create_hinge()

bullet3d.constraint.create_hinge(body_a:btRigidBody, body_b:btRigidBody|nil, params:bullet3d.constraint.hinge_params)→constraint:btTypedConstraint

The world is derived from body_a.

PARAMETERS

RETURNS

EXAMPLES

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()

bullet3d.constraint.create_hinge2(body_a:btRigidBody, body_b:btRigidBody, params:bullet3d.constraint.anchor_axes_params)→constraint:btTypedConstraint

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()

bullet3d.constraint.create_point_to_point(body_a:btRigidBody, body_b:btRigidBody|nil, params:bullet3d.constraint.point_to_point_params)→constraint:btTypedConstraint

The world is derived from body_a; both bodies must belong to that same world.

PARAMETERS

RETURNS

EXAMPLES

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()

bullet3d.constraint.create_slider(body_a:btRigidBody, body_b:btRigidBody|nil, params:bullet3d.constraint.slider_params)→constraint:btTypedConstraint

The world is derived from body_a.

PARAMETERS

RETURNS

bullet3d.constraint.create_universal()

bullet3d.constraint.create_universal(body_a:btRigidBody, body_b:btRigidBody, params:bullet3d.constraint.anchor_axes_params)→constraint:btTypedConstraint

Both bodies are required. The world is derived from body_a.

PARAMETERS

RETURNS

bullet3d.constraint.destroy()

bullet3d.constraint.destroy(constraint:btTypedConstraint)

Destroy a constraint

PARAMETERS

bullet3d.constraint.enable_cone_twist_motor()

bullet3d.constraint.enable_cone_twist_motor(constraint:btTypedConstraint, enabled:boolean)

Enable or disable the cone-twist motor

PARAMETERS

bullet3d.constraint.enable_spring()

bullet3d.constraint.enable_spring(constraint:btTypedConstraint, axis:integer, enabled:boolean)

Enable or disable a spring axis

PARAMETERS

bullet3d.constraint.get_6dof_angle()

bullet3d.constraint.get_6dof_angle(constraint:btTypedConstraint, axis:integer)→angle:number

Get a current 6-DOF angle

PARAMETERS

RETURNS

bullet3d.constraint.get_6dof_axis()

bullet3d.constraint.get_6dof_axis(constraint:btTypedConstraint, axis:integer)→direction:vector3

Get a current 6-DOF angular axis

PARAMETERS

RETURNS

bullet3d.constraint.get_6dof_motor()

bullet3d.constraint.get_6dof_motor(constraint:btTypedConstraint, axis:integer)→(enabled:boolean, target_velocity:number, max_force:number, bounce:number)

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

bullet3d.constraint.get_6dof_position()

bullet3d.constraint.get_6dof_position(constraint:btTypedConstraint, axis:integer)→position:number

Get a current 6-DOF linear position

PARAMETERS

RETURNS

bullet3d.constraint.get_anchors()

bullet3d.constraint.get_anchors(constraint:btTypedConstraint)→(anchor_a:vector3, anchor_b:vector3)

Get universal or hinge2 anchors

PARAMETERS

RETURNS

bullet3d.constraint.get_angles()

bullet3d.constraint.get_angles(constraint:btTypedConstraint)→(angle_1:number, angle_2:number)

Get universal or hinge2 angles

PARAMETERS

RETURNS

bullet3d.constraint.get_axes()

bullet3d.constraint.get_axes(constraint:btTypedConstraint)→(axis_1:vector3, axis_2:vector3)

Get universal or hinge2 axes

PARAMETERS

RETURNS

bullet3d.constraint.get_body_a()

bullet3d.constraint.get_body_a(constraint:btTypedConstraint)→body:btRigidBody

Get the first linked body

PARAMETERS

RETURNS

bullet3d.constraint.get_body_b()

bullet3d.constraint.get_body_b(constraint:btTypedConstraint)→body:btRigidBody|nil

Get the second linked body

PARAMETERS

RETURNS

bullet3d.constraint.get_collide_connected()

bullet3d.constraint.get_collide_connected(constraint:btTypedConstraint)→collide:boolean

Get whether connected bodies can collide

PARAMETERS

RETURNS

bullet3d.constraint.get_cone_twist_limits()

bullet3d.constraint.get_cone_twist_limits(constraint:btTypedConstraint)→(swing_span_1:number, swing_span_2:number, twist_span:number)

Get cone-twist angular spans

PARAMETERS

RETURNS

bullet3d.constraint.get_frame_a()

bullet3d.constraint.get_frame_a(constraint:btTypedConstraint)→(position:vector3, rotation:quaternion)

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

bullet3d.constraint.get_frame_b()

bullet3d.constraint.get_frame_b(constraint:btTypedConstraint)→(position:vector3, rotation:quaternion)

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

bullet3d.constraint.get_hinge_angle()

bullet3d.constraint.get_hinge_angle(constraint:btTypedConstraint)→angle:number

Get the current hinge angle

PARAMETERS

RETURNS

bullet3d.constraint.get_hinge_limits()

bullet3d.constraint.get_hinge_limits(constraint:btTypedConstraint)→(lower:number, upper:number)

Get hinge angular limits

PARAMETERS

RETURNS

bullet3d.constraint.get_hinge_motor()

bullet3d.constraint.get_hinge_motor(constraint:btTypedConstraint)→(enabled:boolean, target_velocity:number, max_impulse:number)

Get hinge motor settings

PARAMETERS

RETURNS

bullet3d.constraint.get_limit()

bullet3d.constraint.get_limit(constraint:btTypedConstraint, axis:integer)→(lower:number, upper:number)

Axes 1-3 return linear limits in Defold units. Axes 4-6 return angular limits in radians.

PARAMETERS

RETURNS

bullet3d.constraint.get_pivots()

bullet3d.constraint.get_pivots(constraint:btTypedConstraint)→(pivot_a:vector3, pivot_b:vector3)

Get point-to-point pivots

PARAMETERS

RETURNS

bullet3d.constraint.get_slider_limits()

bullet3d.constraint.get_slider_limits(constraint:btTypedConstraint)→(lower_linear:number, upper_linear:number, lower_angular:number, upper_angular:number)

Get slider limits

PARAMETERS

RETURNS

bullet3d.constraint.get_slider_motor()

bullet3d.constraint.get_slider_motor(constraint:btTypedConstraint, motor:string)→(enabled:boolean, target_velocity:number, max_force:number)

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

bullet3d.constraint.get_slider_position()

bullet3d.constraint.get_slider_position(constraint:btTypedConstraint)→position:number

Get the current slider position

PARAMETERS

RETURNS

bullet3d.constraint.get_twist_angle()

bullet3d.constraint.get_twist_angle(constraint:btTypedConstraint)→angle:number

Get the current cone-twist twist angle

PARAMETERS

RETURNS

bullet3d.constraint.get_type()

bullet3d.constraint.get_type(constraint:btTypedConstraint)→type:bullet3d.constraint.CONSTRAINT_TYPE

Get the constraint type

PARAMETERS

RETURNS

bullet3d.constraint.get_type_name()

bullet3d.constraint.get_type_name(constraint:btTypedConstraint)→name:string

Returns a stable lowercase diagnostic name such as "hinge" or "generic_6dof_spring".

PARAMETERS

RETURNS

bullet3d.constraint.get_use_linear_reference_frame_a()

bullet3d.constraint.get_use_linear_reference_frame_a(constraint:btTypedConstraint)→use_frame_a:boolean

Get the slider linear reference-frame choice

PARAMETERS

RETURNS

bullet3d.constraint.get_world()

bullet3d.constraint.get_world(constraint:btTypedConstraint)→world:btDiscreteDynamicsWorld

Get the owning world

PARAMETERS

RETURNS

bullet3d.constraint.is_active()

bullet3d.constraint.is_active(constraint:btTypedConstraint)→active:boolean

Test whether a constraint is active in its world

PARAMETERS

RETURNS

bullet3d.constraint.is_angular_only()

bullet3d.constraint.is_angular_only(constraint:btTypedConstraint)→angular_only:boolean

Test angular-only mode

PARAMETERS

RETURNS

bullet3d.constraint.is_limited()

bullet3d.constraint.is_limited(constraint:btTypedConstraint, axis:integer)→limited:boolean

Both a ranged and a locked axis are considered limited; a free axis is not.

PARAMETERS

RETURNS

bullet3d.constraint.is_past_swing_limit()

bullet3d.constraint.is_past_swing_limit(constraint:btTypedConstraint)→past_limit:boolean

Test whether a cone-twist is past its swing limit

PARAMETERS

RETURNS

bullet3d.constraint.is_valid()

bullet3d.constraint.is_valid(constraint:btTypedConstraint)→valid:boolean

Test whether a constraint handle is valid

PARAMETERS

RETURNS

bullet3d.constraint.set_6dof_motor()

bullet3d.constraint.set_6dof_motor(constraint:btTypedConstraint, axis:integer, enabled:boolean, target_velocity:number, max_force:number, [bounce:number|nil])

Linear and angular values use the units described by get_6dof_motor.

PARAMETERS

bullet3d.constraint.set_angular_only()

bullet3d.constraint.set_angular_only(constraint:btTypedConstraint, angular_only:boolean)

Set angular-only mode

PARAMETERS

bullet3d.constraint.set_cone_twist_limits()

bullet3d.constraint.set_cone_twist_limits(constraint:btTypedConstraint, swing_span_1:number, swing_span_2:number, twist_span:number, [softness:number|nil], [bias:number|nil], [relaxation:number|nil])

Set cone-twist angular spans

PARAMETERS

bullet3d.constraint.set_cone_twist_motor_target()

bullet3d.constraint.set_cone_twist_motor_target(constraint:btTypedConstraint, target:quaternion, [constraint_space:boolean|nil])

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

bullet3d.constraint.set_frame_a()

bullet3d.constraint.set_frame_a(constraint:btTypedConstraint, position:vector3, rotation:quaternion)

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

bullet3d.constraint.set_frame_b()

bullet3d.constraint.set_frame_b(constraint:btTypedConstraint, position:vector3, rotation:quaternion)

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

bullet3d.constraint.set_hinge_axis()

bullet3d.constraint.set_hinge_axis(constraint:btTypedConstraint, axis:vector3)

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()

bullet3d.constraint.set_hinge_limits(constraint:btTypedConstraint, lower:number, upper:number, [bias:number|nil], [relaxation:number|nil])

Set hinge angular limits

PARAMETERS

bullet3d.constraint.set_hinge_motor()

bullet3d.constraint.set_hinge_motor(constraint:btTypedConstraint, enabled:boolean, target_velocity:number, max_impulse:number)

Set hinge motor settings

PARAMETERS

bullet3d.constraint.set_hinge_motor_target()

bullet3d.constraint.set_hinge_motor_target(constraint:btTypedConstraint, target_angle:number, time_step:number)

Set a hinge motor angle target

PARAMETERS

bullet3d.constraint.set_limit()

bullet3d.constraint.set_limit(constraint:btTypedConstraint, axis:integer, lower:number, upper:number)

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

bullet3d.constraint.set_pivots()

bullet3d.constraint.set_pivots(constraint:btTypedConstraint, pivot_a:vector3, pivot_b:vector3)

Set point-to-point pivots

PARAMETERS

bullet3d.constraint.set_slider_limits()

bullet3d.constraint.set_slider_limits(constraint:btTypedConstraint, lower_linear:number, upper_linear:number, lower_angular:number, upper_angular:number)

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

bullet3d.constraint.set_slider_motor()

bullet3d.constraint.set_slider_motor(constraint:btTypedConstraint, motor:string, enabled:boolean, target_velocity:number, max_force:number)

Linear and angular values use the units described by get_slider_motor.

PARAMETERS

bullet3d.constraint.set_spring_damping()

bullet3d.constraint.set_spring_damping(constraint:btTypedConstraint, axis:integer, damping:number)

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

bullet3d.constraint.set_spring_equilibrium_point()

bullet3d.constraint.set_spring_equilibrium_point(constraint:btTypedConstraint, [axis:integer|nil], [value:number|nil])

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

bullet3d.constraint.set_spring_stiffness()

bullet3d.constraint.set_spring_stiffness(constraint:btTypedConstraint, axis:integer, stiffness:number)

Linear stiffness values are independent of physics.scale. Angular stiffness values are automatically converted using physics.scale squared.

PARAMETERS