jolt_raycast_all

Returns the closest intersection for every rigid body crossed by a ray, ordered nearest first.

jolt_raycast_all() uses the managed endpoint and filter contract but collects one public result per intersected BodyID. It is intended for penetration, ordered candidate selection and post-filtering that cannot be expressed by the native filter.

Syntax#

jolt_raycast_all(x1, y1, z1, x2, y2, z2, [filter]);

Returns#

Array of RaycastResult values. The closest hit per body, sorted by distance. An empty array can mean a miss or an error; distinguish them by reading jolt_get_error() immediately.

Example: basic query#

Prerequisite: the world has been started successfully with jolt_start().

var hits = jolt_raycast_all(0, 0, 2, 10, 0, 2);
var error = jolt_get_error();
if (error.code != JOLT_ERROR_NONE) {
    show_debug_message(error.message);
}
else {
    show_debug_message(array_length(hits));
}

The segment runs from (0, 0, 2) to (10, 0, 2). The example separates a failed query from a valid result before consuming it.

Ordered results#

var hits = jolt_raycast_all(0, 0, 2, 30, 0, 2, { ignore: player_body });
var error = jolt_get_error();

if (error.code == JOLT_ERROR_NONE) {
    for (var i = 0; i < array_length(hits); ++i) {
        show_debug_message(string(i) + ": " + string(hits[i].distance));
    }
}

Collection contract#

• Results are sorted from the origin by distance.
• Only the closest intersection for each rigid body is returned.
• A compound, mesh or other concave body contributes at most one public result.
• At most 256 native collector entries are considered; public mapping can produce fewer results.
• A successful query without hits returns an empty array.
• An error also returns an empty array and must be distinguished through jolt_get_error().

Find the first gameplay candidate#

var hits = jolt_raycast_all(x1, y1, z1, x2, y2, z2, { ignore: player_body });
var target = undefined;

if (jolt_get_error().code == JOLT_ERROR_NONE) {
    for (var i = 0; i < array_length(hits); ++i) {
        if (!is_undefined(hits[i].entity)) {
            target = hits[i];
            break;
        }
    }
}

Ignore more than one body#

The native filter ignores only one body. To exclude several bodies, query all hits and skip unwanted JoltBody values or user_data in GML. Remember that an excluded body can no longer act as an obstruction in that post-filtered result.

Penetration example#

var power = 12;
var hits = jolt_raycast_all(x1, y1, z1, x2, y2, z2, shot_layers);

if (jolt_get_error().code == JOLT_ERROR_NONE) {
    for (var i = 0; i < array_length(hits) && power > 0; ++i) {
        var hit = hits[i];
        if (is_struct(hit.body)) hit.body.add_impulse(dir_x * power, dir_y * power, dir_z * power);
        power -= 4;
    }
}

Sensors and triangle back faces#

Sensors are included unless excluded by layer or the one ignored body. Mesh and HeightField triangle queries use the current native default back-face behaviour, which ignores triangle back faces.

Related reference#

• RaycastResult›
• Layer Filtering›
• jolt_raycast›
• Choosing a query›

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.