Raycasting

Raycast Results

Explains the managed result fields and the safe distinction between a hit, a miss and an error.

A normal closest-hit query returns a complete managed struct. Early high-level validation failures can return a minimal {hit:false} value, so jolt_get_error() must be read immediately after the call before relying on optional result fields.

Closest-hit results now also carry ray:{world,origin,target} metadata on a valid hit or miss. Pass the complete fresh result to JoltRenderSurface.set_touch_raycast(), never result.hit. Contact fields still require hit=true; early validation failures may lack ray metadata.

Normal closest-hit fields#

Field	Type	Meaning
hit	Boolean	true when a managed rigid body was intersected.
body	JoltBody \| undefined	Resolved JoltBody, or undefined on a miss or failed mapping.
body_handle	Real	Opaque public generational body handle owned by the extension; not a Jolt BodyID.
entity	Any	Current JoltBody.user_data value, or undefined.
position	Struct {x:Real, y:Real, z:Real}	World-space public Z-up hit point {x,y,z}.
normal	Struct {x:Real, y:Real, z:Real}	World-space public Z-up surface normal {x,y,z}.
fraction	Real	Normalized position along the segment, normally 0 through 1.
distance	Real	World-space distance from the origin.
error_code	Real	Native result status for a normal low-level query.
error_message	String	Native message; empty on a valid hit or miss.

Authoritative state check#

var result = jolt_raycast(x1, y1, z1, x2, y2, z2, filter);
var error = jolt_get_error(); // Read before another Jolt call.

if (error.code != JOLT_ERROR_NONE) {
    show_debug_message(error.context + ": " + error.message);
}
else if (!result.hit) {
    // Valid miss. Do not read contact fields as a hit.
}
else {
    var point = result.position;
    var normal = result.normal;
    var body = result.body;
    var data = result.entity;
}

Result states#

State	Recognition
Closest hit	jolt_get_error().code is NONE and result.hit is true.
Closest miss	Error code is NONE and result.hit is false.
Closest error	jolt_get_error().code is non-zero; result may contain only hit=false.
All-hit success	Error code is NONE; the array may contain zero or more hits.
All-hit error	Error code is non-zero; the returned array is empty.

Fraction and distance#

For the endpoint form, maximum distance is the length from the origin to the endpoint. distance equals fraction multiplied by that length. position is already the world-space point, so it normally does not need to be reconstructed.

Body, handle and user data#

The native body stores the extension's public handle in its user-data slot. The wrapper validates that handle against the managed registry, exposes it as body_handle, resolves body to JoltBody and then copies JoltBody.user_data into entity. entity is caller-owned and is not guaranteed to be a GameMaker instance.

Fields that are not exposed#

Jolt BodyID
SubShapeID or compound child
Triangle or face index
Physics material
Motion type, layer or sensor flag

Low-level result shape#

{
    hit, error_code, error_message, body,
    x, y, z,
    normal_x, normal_y, normal_z,
    fraction, distance,
    position, normal
}

Low-level body is the numeric public extension handle. The managed form resolves it to JoltBody and preserves the number as body_handle.

Surface input