Raycasts

Cast a body-local ray once or keep a configured query object.

Verified against the project sources on 19 September 2026.

Syntax#

jolt_asset_get_raycast(asset, raycast_ref);
jolt_asset_raycast(asset, raycast_ref, owner_body, [options]);
jolt_asset_create_raycast(asset, raycast_ref, owner_body);

Factories return undefined on failure; inspect jolt_get_error() immediately. Authoring lookups return independent validated record copies. A reference is a canonical UUID or an exact, case-sensitive Key. Body owners must be live managed bodies in the current world.

World frame = current Body origin transform × authored local transform. The center of mass is not the authoring origin. Positions use metres and rotations use normalized XYZW quaternions. Refresh snapshots as the body moves.

Authoring defines position, rotation and length. Forward is local +Z. Length must be greater than 1e-6 and at most sqrt(FLT_MAX)/2 metres; extremely large world positions can still collapse endpoints. A cast samples the current world and is not a future trajectory or movement sweep.

Example#

// Create, once; Key "ground_front" must exist in the asset.
ground_ray = jolt_asset_create_raycast(asset, "ground_front", body_vehicle);
if (!is_undefined(ground_ray)) ground_ray.set_ignore(body_vehicle);
// Step, whenever a fresh result is needed:
if (!is_undefined(ground_ray)) {
    var hit = ground_ray.cast();
    if (hit.hit) show_debug_message(hit.distance);
    if (hit.error_code != 0) show_debug_message(hit.error_message);
}

The configured query stores a validated snapshot, follows current body transforms and rechecks owner/ignored-body validity on every cast. It allocates no native resource, has no automatic update and needs no destroy(). Drop references when finished. jolt_asset_raycast remains available for one-off calls with options.

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.