Pulley Constraint

Couples two straight segment lengths through a configurable positive ratio without simulating a rope or wheel.

jolt_pulley() is a direct managed wrapper around Jolt Physics 5.6 PulleyConstraint. It constrains two bodies through two fixed world points and two body attachment points.

Syntax#

jolt_pulley(body_a, body_b,
    fixed_a_x, fixed_a_y, fixed_a_z,
    fixed_b_x, fixed_b_y, fixed_b_z,
    options=undefined)

Physical equation#

min_length <= L1 + ratio * L2 <= max_length

L1 = distance(body_point_a, fixed_point_a)
L2 = distance(body_point_b, fixed_point_b)

The ratio multiplies Body B / segment 2. With ratio 2, a two-unit change in L1 corresponds to an opposite one-unit change in L2 while the taut total remains conserved.

Arguments and options#

Methods#

Example: equal pulley#

var box_a = jolt_box_create_dynamic(-2, 0, 3, 1, 1, 1, { mass:20 });
var box_b = jolt_box_create_dynamic( 2, 0, 3, 1, 1, 1, { mass:5 });

var pulley = jolt_pulley(
    box_a, box_b,
    -2, 0, 6,
     2, 0, 6,
    { ratio:1, min_length:-1, max_length:-1, collision:false }
);

Slack and runtime length#

var current = pulley.get_current_length();

// Make the current total taut, half a unit shorter.
pulley.set_length(current - 0.5, current - 0.5);

// A range instead permits slack.
pulley.set_length(0, 10);

Off-centre attachment#

var pulley = jolt_pulley(a, b, -2,0,6, 2,0,6, {
    body_point_a: { x:0.45, y:0, z:0.25 },
    body_point_b: { x:0, y:0, z:0 }
});

The off-centre material point rotates with Body A. Tension acts at that point and can therefore create a real angular response.

Limitations and lifecycle#

• ratio is creation-only because Jolt exposes no safe runtime ratio setter.
• The two outer segments are straight mathematical constraints: there is no rope collision, wrapping, flexible rope or simulated wheel.
• The signed impulse is not a force. An approximate average magnitude is abs(impulse) / fixed_dt.
• Extremely large ratios, extreme mass ratios, very short lengths or large time steps can require more solver iterations.
• Destroying either body invalidates the pulley; destroy() and jolt_stop() remain safe.
• JOLT_DEBUG_CONSTRAINTS draws both live segments, fixed points and an explanatory span between the fixed points.

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.