scene_queries_ray_casting

Ray-casting is a geometric query that finds one or several colliders intersecting a half-line. Ray-casting is an extremely common operation that covers a wide variety of use-cases: firing bullets, character controllers, rendering (for ray-tracing), etc.

A ray is defined by its origin and its direction: it can be interpreted as a single point moving in a straight line towards the ray direction.

info

In addition to the ray geometric information, ray-casting method allow additional control over the behavior of the ray cast like limiting the length of the ray and ignoring some colliders. See the detailed ray-cast arguments description after the next example.

There are multiple ray-casting methods yielding more or less detailed results (see example bellow). The more results you get, the more computationally expensive the ray-cast will be.

Example 2D

let ray = new RAPIER.Ray({ x: 1.0, y: 2.0 }, { x: 0.0, y: 1.0 });
let maxToi = 4.0;
let solid = true;

let hit = world.castRay(ray, maxToi, solid);
if (hit != null) {
    // The first collider hit has the handle `hit.colliderHandle` and it hit after
    // the ray travelled a distance equal to `ray.dir * toi`.
    let hitPoint = ray.pointAt(hit.timeOfImpact); // Same as: `ray.origin + ray.dir * toi`
    console.log("Collider", hit.collider, "hit at point", hitPoint);
}

let hitWithNormal = world.castRayAndGetNormal(ray, maxToi, solid);
if (hitWithNormal != null) {
    // This is similar to `QueryPipeline::cast_ray` illustrated above except
    // that it also returns the normal of the collider shape at the hit point.
    let hitPoint = ray.pointAt(hitWithNormal.timeOfImpact);
    console.log("Collider", hitWithNormal.collider, "hit at point", hitPoint, "with normal", hitWithNormal.normal);
}

world.intersectionsWithRay(ray, maxToi, solid, (hit) => {
    // Callback called on each collider hit by the ray.
    let hitPoint = ray.pointAt(hit.timeOfImpact);
    console.log("Collider", hit.collider, "hit at point", hitPoint, "with normal", hit.normal);
    return true; // Return `false` instead if we want to stop searching for other hits.
});

Example 3D

let ray = new RAPIER.Ray({ x: 1.0, y: 2.0, z: 3.0 }, { x: 0.0, y: 1.0, z: 0.0 });
let maxToi = 4.0;
let solid = true;

let hit = world.castRay(ray, maxToi, solid);
if (hit != null) {
    // The first collider hit has the handle `hit.colliderHandle` and it hit after
    // the ray travelled a distance equal to `ray.dir * toi`.
    let hitPoint = ray.pointAt(hit.timeOfImpact); // Same as: `ray.origin + ray.dir * toi`
    console.log("Collider", hit.collider, "hit at point", hitPoint);
}

let hitWithNormal = world.castRayAndGetNormal(ray, maxToi, solid);
if (hitWithNormal != null) {
    // This is similar to `QueryPipeline::cast_ray` illustrated above except
    // that it also returns the normal of the collider shape at the hit point.
    let hitPoint = ray.pointAt(hitWithNormal.timeOfImpact);
    console.log("Collider", hitWithNormal.collider, "hit at point", hitPoint, "with normal", hitWithNormal.normal);
}

world.intersectionsWithRay(ray, maxToi, solid, (hit) => {
    // Callback called on each collider hit by the ray.
    let hitPoint = ray.pointAt(hit.timeOfImpact);
    console.log("Collider", hit.collider, "hit at point", hitPoint, "with normal", hit.normal);
    return true; // Return `false` instead if we want to stop searching for other hits.
});

Aside from the ray being cast, all these ray-casting methods take a few extra parameters for controlling the behavior of the ray-cast:

• maxToi : is the maximum "time-of-impact" that can be reported by the ray-cast. The notion of "time-of-impact" refer to the fact that a ray can be seen as a point starting at ray.origin moving at a linear velocity equal to ray.dir. Therefore, max_toi limits the ray-cast to the segment: [ray.origin, ray.origin + ray.dir * max_toi].
• solid: this argument controls the behavior of the ray-cast if ray.origin is inside of a shape: if solid is true then the hit point will be the ray origin itself (toi = 0.0) because the interior of the shape will be assumed to be filled with material. If solid is false then the shape will be assumed to have an empty interior and the hit point will be the first time the ray hits the shape's boundary. The following 2D example illustrates the difference between the two scenarios. The ray is in green and the resulting hit point circled in red:

In addition, it is possible to only apply the scene query to a subsets of the colliders using a query filter.