Low-Level Raycasting

Queries an explicit world with origin, direction and maximum distance.

The low-level API is intended for projects that manage worlds directly. Unlike the managed endpoint form, it accepts a selected world handle, a direction vector that the bridge normalizes, and a separate positive maximum distance.

Functions#

jolt_world_raycast(world, ox, oy, oz, dx, dy, dz, max_distance)

jolt_world_raycast_filtered(world, ox, oy, oz, dx, dy, dz,
    max_distance, layer_mask=0, ignore_body=0)

jolt_world_raycast_all(world, ox, oy, oz, dx, dy, dz,
    max_distance, layer_mask=0, ignore_body=0)

Argument contract#

Explicit-world example#

var result = jolt_world_raycast_filtered(
    world,
    origin_x, origin_y, origin_z,
    direction_x, direction_y, direction_z,
    50,
    layer_mask,
    ignored_body_handle
);

if (result.error_code != JOLT_ERROR_NONE) {
    show_debug_message(result.error_message);
}
else if (result.hit) {
    show_debug_message("Body handle: " + string(result.body));
}

Low-level return contract#

Closest queries return a complete struct with component and convenience fields. jolt_world_raycast_all() returns sorted low-level structs and an empty array for either no hits or failure; inspect jolt_get_last_error_code() and jolt_get_last_error_message() immediately when that distinction matters.

Managed compatibility overload#

// Legacy explicit-world overload:
jolt_raycast(world, ox, oy, oz, dx, dy, dz, max_distance)

// Managed endpoint overload:
jolt_raycast(x1, y1, z1, x2, y2, z2, filter=undefined)

Eight arguments select the legacy explicit-world overload. Six or seven arguments select the managed endpoint form. Prefer the named jolt_world_raycast* functions in new low-level code so the coordinate contract is unambiguous.

Snapshot consumption#

The native bridge uses its internal current-raycast snapshot while the GML wrapper assembles the public struct synchronously. Consume the returned GML value rather than attempting to call bridge getters separately.

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.