Distance Constraint

Keeps two attachment points within a configurable minimum and maximum separation.

Distance constraints create rigid rods, ropes with slack, or damped springs without rendering a rope. Body-to-body attachment points are supplied in world space at creation and stored relative to each body internally.

Syntax#

jolt_distance(body_a, body_b, options=undefined)
jolt_distance_world(body, anchor_x, anchor_y, anchor_z, min_distance, max_distance, options=undefined)

Body-to-body options#

World-variant arguments#

Methods#

Rigid, slack and spring behaviour#

• Equal minimum and maximum values create a fixed-length rod or tether.
• A range permits free motion until an attachment point reaches either boundary.
• A spring softens correction toward the permitted range; higher frequency is stiffer and damping suppresses oscillation.
• The constraint is mathematical geometry only: it has no rope collision, bending, wrapping or rendering.

Example: damped tether#

var anchor = jolt_box_create_static(0, 0, 6, 0.4, 0.4, 0.4);
var load   = jolt_box_create_dynamic(0, 0, 2, 1, 1, 1, { mass: 5 });

var tether = jolt_distance(anchor, load, {
    point_a: { x: 0, y: 0, z: 6 },
    point_b: { x: 0, y: 0, z: 2 },
    min_distance: 2,
    max_distance: 4,
    spring_frequency: 3,
    spring_damping: 0.65,
    collision: false
});

Example: attached directly to world#

var load = jolt_box_create_dynamic(0, 0, 2, 1, 1, 1, { mass: 5 });
var tether = jolt_distance_world(load, 0, 0, 6, 2, 4, {
    spring_frequency: 2,
    spring_damping: 0.7
});

Errors and lifecycle#

• Body-to-body creators require two different live managed JoltBody values in the same managed default world.
• At least one connected body must be movable; native Jolt rejects an unsupported static-static pair.
• Constructors return a managed JoltConstraint on success or undefined after a validation/native creation failure.
• Destroying either attached body automatically destroys and invalidates the constraint before releasing that body.
• Read jolt_get_error() after a failed creator or method when the values may be untrusted.
• Attachment structs must contain finite x, y and z values.
• Distance limits must be finite, non-negative and ordered minimum <= maximum.
• Frequency and damping must be finite and non-negative.

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.