Raycasting

jolt_raycast

Returns the closest managed rigid body intersected by a line segment in the default world.

jolt_raycast() converts two public Z-up world-space endpoints into a normalized direction and positive maximum distance, runs a filtered rigid-body query, and maps the closest valid public body handle back to a JoltBody and its current user_data.

Syntax#

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

Argument	Type	Description
x1	Real	Finite world-space X coordinate of the segment start; Z points up.
y1	Real	Finite world-space Y coordinate of the segment start; Z points up.
z1	Real	Finite world-space Z coordinate of the segment start; Z points up.
x2	Real	Finite world-space X coordinate of the segment end; Z points up.
y2	Real	Finite world-space Y coordinate of the segment end; Z points up.
z2	Real	Finite world-space Z coordinate of the segment end; Z points up.
filter	JoltLayer \| Array \| Real \| Struct \| undefined	OPTIONAL. Defaults to undefined: all layers, no ignored body. See Layer Filtering.

Returns#

Struct (RaycastResult). With no error, hit=true means a hit and hit=false means a valid miss. A validation error may return only {hit:false}; read jolt_get_error() before accessing hit fields.

Example: basic query#

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

var result = jolt_raycast(0, 0, 2, 10, 0, 2);
var error = jolt_get_error();
if (error.code != JOLT_ERROR_NONE) {
    show_debug_message(error.message);
}
else if (result.hit) {
    show_debug_message(result.distance);
}
else {
    show_debug_message("No hit.");
}

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

Simple interaction#

var hit = jolt_raycast(0, 0, 1.5, 12, 0, 1.5, {
    ignore: player_body
});
var error = jolt_get_error();

if (error.code == JOLT_ERROR_NONE && hit.hit) {
    show_debug_message("Hit at " + string(hit.position));
    if (is_struct(hit.body)) hit.body.add_impulse(3, 0, 0);
}

Validation#

Call jolt_start() first.
All six coordinates must be finite.
The endpoints must differ by more than approximately 0.000001 world units.
Every supplied layer and ignored body must still be live.
A stale ignored body fails the query instead of silently removing the ignore rule.

Query behaviour#

The query is instantaneous and read-only.
It sees Dynamic, Static, Kinematic, sleeping and sensor rigid bodies unless filtered out.
It does not step the world, generate contact events, wake bodies or apply collision response.
CharacterVirtual and Cloth are outside this rigid-body query.

Line of sight#

var obstruction = jolt_raycast(eye.x, eye.y, eye.z, target.x, target.y, target.z, {
    layers: [world_layer],
    ignore: observer_body
});
var visible = jolt_get_error().code == JOLT_ERROR_NONE && !obstruction.hit;

Use jolt_raycast_all() when objects behind the first body matter. Use a Shape Cast for a swept volume, an overlap query for an existing volume, or jolt_closest_point() when there is no desired ray direction.

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.

Symbol / owner	Signature	Operation contract
jolt_raycast	jolt_raycast(a, b, c, d, e, f, g = undefined, h = undefined)	Managed form takes two WORLD ENDPOINTS (x1, y1, z1, x2, y2, z2), not a direction. Optional filter is layers or options per query documentation. Raycast returns a hit struct, all an array; no hit is hit=false/[]. Eight arguments only on jolt_raycast select legacy world+origin+direction+distance with a numeric body handle. Managed hits contain JoltBody and original-ray metadata.