Constraint Lifecycle

Explains validity, ownership, disabling, collision filtering, dependency invalidation and safe cleanup.

A managed JoltConstraint owns one world-scoped generational native handle. It references connected bodies but never owns their GML wrappers or gameplay data.

States#

Ownership rules#

• destroy() destroys only the constraint, never either body.
• destroy() is idempotent and safe to repeat on an already released wrapper.
• A stale generational handle cannot address a later constraint that reuses the same internal slot.
• All body-to-body constraints must remain in the same managed default world as their bodies.
• World constraints reference Jolt's immutable fixed body internally and one user body externally.

Disable versus destroy#

joint.set_enabled(false); // keep limits and motor settings

// Later:
joint.set_enabled(true);

// Permanent release:
joint.destroy();

Disabling is appropriate for a mechanism that will be reused. Destroying is appropriate when the relationship has ended and should release its native solver resource.

Connected-body collision#

• collision:false or set_collision_enabled(false) suppresses only the connected user-body pair.
• Suppression is reference-counted: destroying one of several suppressing constraints does not re-enable the pair prematurely.
• Changing the setting invalidates cached contacts and wakes the affected bodies.
• World constraints always report collision disabled because there is no second user collision body.

Safe cleanup#

if (is_struct(joint) && joint.is_valid()) {
    joint.destroy();
}

body_a.destroy();
body_b.destroy();

// Global managed cleanup is also ordered and idempotent.
jolt_stop();

Error handling#

var joint = jolt_hinge(a, b, 0,0,2, 0,0,1);
if (is_undefined(joint)) {
    var error = jolt_get_error();
    show_debug_message(string(error.code) + " / " + error.context + ": " + error.message);
}

Manual cleanup order#

Release dependent constraints before their bodies, then release reusable shape/layer resources before the world and runtime. jolt_stop() performs the managed order automatically and safely when repeated.

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.