jolt_stop

Destroys managed physics resources, the default world, and the native runtime.

jolt_stop() performs complete high-level teardown. It invalidates managed handles, releases native and GameMaker-side resources, clears event data and timing state, destroys the default world, and shuts Jolt down.

Syntax#

jolt_stop();

Returns#

Boolean. true after successful teardown, including when the world is already stopped. false on a teardown error; jolt_get_error() retains the first failure.

Typical cleanup#

// Cleanup event of the persistent physics controller.
if (!jolt_stop()) {
    var error = jolt_get_error();
    show_debug_message(error.context + ": " + error.message);
}

Cleanup order#

• Cloths are destroyed and their vertex/debug buffers are deleted.
• Characters are destroyed, invalidated, unbound from owners, and lose contact arrays.
• Constraints and path resources are destroyed and invalidated.
• Bodies are destroyed and their geometry metadata, compound children, and collision arrays are released.
• Managed shape resources and compounds are released.
• Every JoltLayer is invalidated and event arrays and dropped counters are cleared.
• The default world is destroyed, the native runtime is shut down, and debug resources are reset.
• started becomes false, world becomes 0, and accumulator and simulation-step counter return to 0.

Errors during teardown#

The function remembers the first cleanup error but continues attempting the remaining teardown. After all resources and state have been processed it returns false and exposes that first error through jolt_get_error(). A successful teardown returns true.

Stale managed values#

User variables may still reference old JoltBody, JoltLayer, JoltConstraint, JoltShape, or other wrapper structs after stop. Their valid flags are cleared and native handles are set to 0 where applicable. Treat them as stale and do not reuse them after a restart.

Restarting#

jolt_stop();

// Creates a completely fresh default world.
jolt_start({gravity_z: -3.71});

// Recreate layers, bodies, shapes, and constraints for the new world.

A new start creates a new world and fresh registries. Collision layers and every resource tied to the previous world must be recreated.

When to stop#

• Call jolt_stop() when leaving the part of the game that owns the physics world.
• For a persistent global controller, use its Cleanup event or another single authoritative shutdown point.
• Avoid stopping while other gameplay objects still expect their body bindings to be valid.
• Stopping is not required merely to remove one body; use that JoltBody's destroy operation for individual resources.

Low-Level / Advanced API#

jolt_world_destroy(world)
jolt_shutdown()

jolt_world_destroy() removes one explicit native world. jolt_shutdown() is also idempotent at native level and clears every remaining world, the job system, temporary allocator, registered Jolt types, cached raycast/contact bridge state, and the Jolt factory.

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.