SwingTwist Constraint

Combines elliptical swing limits, a signed twist range, friction and independent native swing/twist motors.

jolt_swing_twist() exposes Jolt Physics 5.6 SwingTwistConstraint directly. It keeps two attachment points together while controlling the orientation between articulated links, limbs, rope-like chains and other joints that need more detail than Cone.

Syntax#

jolt_swing_twist(body_a, body_b, anchor_x, anchor_y, anchor_z, options=undefined)

Options#

Reference frame#

• The anchor and both axes are world-space values at creation.
• Twist Axis becomes constraint-space X. Plane Axis becomes constraint-space Z, and Jolt derives the normal/Y axis.
• Axes are normalized and the plane axis is orthogonalized around the twist axis.
• Zero-length or nearly parallel axes are rejected.
• Different normal and plane half-angles create a real elliptical swing range rather than a visual approximation.

Limits and state#

Independent motors#

Swing velocity components use constraint-space Y/Z. A swing position is an angle around a normalized axis in that Y/Z plane. Twist uses constraint-space X. These high-level motor velocities are degrees per second.

Example: articulated link#

var upper = jolt_box_create_dynamic(0, 0, 5, 0.5, 0.5, 1, { mass: 2 });
var lower = jolt_box_create_dynamic(0, 0, 4, 0.5, 0.5, 1, { mass: 2 });

var joint = jolt_swing_twist(upper, lower, 0, 0, 4.5, {
    twist_axis: { x:0, y:0, z:1 },
    plane_axis: { x:1, y:0, z:0 },
    normal_half_angle: 20,
    plane_half_angle: 60,
    twist_min: -30,
    twist_max: 30,
    friction_torque: 0.5,
    collision: false
});

Example: twist motor#

joint.set_twist_motor_max_torque(20);
joint.set_twist_motor_spring(3, 0.8);
joint.set_twist_motor_position(25);

var twist = joint.get_twist_angle();
var state = joint.get_twist_motor_state();

Lifecycle, debug and limitations#

• is_valid() / get_native_handle(): Checks the wrapper or returns its opaque native handle.
• destroy(): Idempotently releases the constraint without destroying either body.
• set_enabled() / get_enabled(): Changes solver participation while preserving the resource.
• set_collision_enabled() / get_collision_enabled(): Controls the connected-body pair filter.
• Destroying either body invalidates the generational constraint handle; jolt_stop() cleans it before bodies and world.
• JOLT_DEBUG_CONSTRAINTS draws the native frame, elliptical boundary, twist arc, current orientation and active motors.
• This creator supports body-to-body Cone swing only. There is no world convenience variant and no public rope/chain helper.
• Solver impulses are accumulated Lagrange multipliers from the latest step, not forces or torques per second.

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.