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

bullet3d.constraint

Namespace: bullet3d.constraint Language: Lua Type: Defold Lua File: script_bullet3d_constraint.cpp Source: engine/gamesys/src/gamesys/scripts/bullet3d/script_bullet3d_constraint.cpp

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.

API

btTypedConstraint

Type: TYPEDEF Bullet typed constraint

Parameters

bullet3d.constraint.anchor_axes_params

Type: STRUCT Universal and hinge2 constraint parameters

Members

bullet3d.constraint.cone_twist_params

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

Members

bullet3d.constraint.CONSTRAINT_TYPE

Type: ENUM Constraint types

Members

bullet3d.constraint.create_cone_twist

Type: FUNCTION The world is derived from body_a.

Parameters

Returns

bullet3d.constraint.create_generic_6dof

Type: FUNCTION 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

Type: FUNCTION 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

Create a spring that moves along its first linear axis:

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

Type: FUNCTION The world is derived from body_a.

Parameters

Returns

Examples

Create a motorized hinge with a 90-degree range:

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

Type: FUNCTION 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

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

Parameters

Returns

Examples

Join two bodies at matching local pivots and explicitly destroy the constraint when the script is finalized:

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

Type: FUNCTION The world is derived from body_a.

Parameters

Returns

bullet3d.constraint.create_universal

Type: FUNCTION Both bodies are required. The world is derived from body_a.

Parameters

Returns

bullet3d.constraint.destroy

Type: FUNCTION Destroy a constraint

Parameters

bullet3d.constraint.enable_cone_twist_motor

Type: FUNCTION Enable or disable the cone-twist motor

Parameters

bullet3d.constraint.enable_spring

Type: FUNCTION Enable or disable a spring axis

Parameters

bullet3d.constraint.generic_6dof_params

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

Members

bullet3d.constraint.generic_6dof_spring_params

Type: STRUCT Generic spring 6-DOF constraint parameters

Members

bullet3d.constraint.get_6dof_angle

Type: FUNCTION Get a current 6-DOF angle

Parameters

Returns

bullet3d.constraint.get_6dof_axis

Type: FUNCTION Get a current 6-DOF angular axis

Parameters

Returns

bullet3d.constraint.get_6dof_motor

Type: FUNCTION 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

Type: FUNCTION Get a current 6-DOF linear position

Parameters

Returns

bullet3d.constraint.get_anchors

Type: FUNCTION Get universal or hinge2 anchors

Parameters

Returns

bullet3d.constraint.get_angles

Type: FUNCTION Get universal or hinge2 angles

Parameters

Returns

bullet3d.constraint.get_axes

Type: FUNCTION Get universal or hinge2 axes

Parameters

Returns

bullet3d.constraint.get_body_a

Type: FUNCTION Get the first linked body

Parameters

Returns

bullet3d.constraint.get_body_b

Type: FUNCTION Get the second linked body

Parameters

Returns

bullet3d.constraint.get_collide_connected

Type: FUNCTION Get whether connected bodies can collide

Parameters

Returns

bullet3d.constraint.get_cone_twist_limits

Type: FUNCTION Get cone-twist angular spans

Parameters

Returns

bullet3d.constraint.get_frame_a

Type: FUNCTION 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

Type: FUNCTION 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

Type: FUNCTION Get the current hinge angle

Parameters

Returns

bullet3d.constraint.get_hinge_limits

Type: FUNCTION Get hinge angular limits

Parameters

Returns

bullet3d.constraint.get_hinge_motor

Type: FUNCTION Get hinge motor settings

Parameters

Returns

bullet3d.constraint.get_limit

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

Parameters

Returns

bullet3d.constraint.get_pivots

Type: FUNCTION Get point-to-point pivots

Parameters

Returns

bullet3d.constraint.get_slider_limits

Type: FUNCTION Get slider limits

Parameters

Returns

bullet3d.constraint.get_slider_motor

Type: FUNCTION 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

Type: FUNCTION Get the current slider position

Parameters

Returns

bullet3d.constraint.get_twist_angle

Type: FUNCTION Get the current cone-twist twist angle

Parameters

Returns

bullet3d.constraint.get_type

Type: FUNCTION Get the constraint type

Parameters

Returns

bullet3d.constraint.get_type_name

Type: FUNCTION Returns a stable lowercase diagnostic name such as “hinge” or “generic_6dof_spring”.

Parameters

Returns

bullet3d.constraint.get_use_linear_reference_frame_a

Type: FUNCTION Get the slider linear reference-frame choice

Parameters

Returns

bullet3d.constraint.get_world

Type: FUNCTION Get the owning world

Parameters

Returns

bullet3d.constraint.hinge_params

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

Members

bullet3d.constraint.is_active

Type: FUNCTION Test whether a constraint is active in its world

Parameters

Returns

bullet3d.constraint.is_angular_only

Type: FUNCTION Test angular-only mode

Parameters

Returns

bullet3d.constraint.is_limited

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

Parameters

Returns

bullet3d.constraint.is_past_swing_limit

Type: FUNCTION Test whether a cone-twist is past its swing limit

Parameters

Returns

bullet3d.constraint.is_valid

Type: FUNCTION Test whether a constraint handle is valid

Parameters

Returns

bullet3d.constraint.point_to_point_params

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

Members

bullet3d.constraint.set_6dof_motor

Type: FUNCTION Linear and angular values use the units described by get_6dof_motor.

Parameters

bullet3d.constraint.set_angular_only

Type: FUNCTION Set angular-only mode

Parameters

bullet3d.constraint.set_cone_twist_limits

Type: FUNCTION Set cone-twist angular spans

Parameters

bullet3d.constraint.set_cone_twist_motor_target

Type: FUNCTION 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

Type: FUNCTION 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

Type: FUNCTION 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

Type: FUNCTION 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

Type: FUNCTION Set hinge angular limits

Parameters

bullet3d.constraint.set_hinge_motor

Type: FUNCTION Set hinge motor settings

Parameters

bullet3d.constraint.set_hinge_motor_target

Type: FUNCTION Set a hinge motor angle target

Parameters

bullet3d.constraint.set_limit

Type: FUNCTION 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

Type: FUNCTION Set point-to-point pivots

Parameters

bullet3d.constraint.set_slider_limits

Type: FUNCTION 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

Type: FUNCTION Linear and angular values use the units described by get_slider_motor.

Parameters

bullet3d.constraint.set_spring_damping

Type: FUNCTION 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

Type: FUNCTION 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

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

Parameters

bullet3d.constraint.slider_params

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

Members