Debugging & Performance

Shows how to inspect rays visually and keep repeated queries predictable.

Raycasts are synchronous narrow-phase queries. Debug recording is optional and disabled work is avoided; when enabled, the GML debug renderer retains a bounded history that can be drawn with the rest of the physics diagnostics.

Enable ray visualization#

jolt_debug_enable(true);
jolt_debug_set(JOLT_DEBUG_RAYCASTS, true);

var hit = jolt_raycast(0, 0, 2, 10, 0, 2);
jolt_debug_draw();

Debug history#

• At most 32 recent raycast records are retained.
• A miss is drawn to the requested endpoint.
• A hit records its position and surface normal.
• jolt_raycast_all() records one line ending at the closest sorted hit, not every returned hit.
• Call jolt_debug_clear_raycasts() to discard the retained history.

Clear retained rays#

jolt_debug_clear_raycasts();

Diagnosing an unexpected miss#

• Check jolt_get_error() immediately after the call.
• Confirm jolt_start() completed and both endpoints are finite and different.
• Draw the ray and confirm the endpoint is in world space.
• Check the selected layer mask and remember that mask 0 means all layers.
• Check whether the target is CharacterVirtual or Cloth.
• For mesh geometry, test the triangle's front side and winding.
• If the ray begins in the source collider, ignore that body or adjust the origin.

Performance guidance#

• Prefer jolt_raycast() when only one closest body is required; it avoids constructing a public GML array.
• Use jolt_raycast_all() only when ordered secondary bodies or GML post-filtering are required.
• Reuse layer references and filter structs in hot loops instead of rebuilding arrays unnecessarily.
• Keep maximum distance and query count no larger than gameplay requires.
• Disable JOLT_DEBUG_RAYCASTS outside diagnostics.
• Profile representative scenes before running hundreds of rays every Step.

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.