Queries

Four query objects, all created from the physics system and all following the same shape: set up a caster, cast() it, read hits.

import { Raycaster, RaycastHit, useRaycaster } from '@react-three/jolt';
import { useEffect } from 'react';

export function Laser() {
    const raycaster: Raycaster = useRaycaster([0, 5, 0], [0, -10, 0]);

    useEffect(() => {
        raycaster.cast(
            (hit: RaycastHit) => {
                console.log(hit.position, hit.distance, hit.impactNormal, hit.bodyHandle);
            },
            () => console.log('no hit')
        );
    }, [raycaster]);

    return null;
}

useRaycaster(origin?, direction?, type?) creates a caster, applies the arguments, and destroys it when the component unmounts. direction is not normalised — its length is the length of the ray, exactly like THREE.Raycaster's far.

cast() also returns the hit (or the array of hits in 'all' mode), so the handlers are optional.

setCollector(type), or the third argument to useRaycaster, chooses what Jolt collects:

cullBackFaces (default true) skips triangles facing away from the ray.

The physics answer to THREE.Raycaster.setFromCamera(): it builds a world-space ray from the pointer and the camera and casts it against Jolt bodies instead of the three.js scene graph.

import { useMouseRaycaster } from '@react-three/jolt';
import { useFrame } from '@react-three/fiber';

export function Picker() {
    const { hit, raycaster } = useMouseRaycaster({
        onHit: (h) => {
            if (!Array.isArray(h) && h) console.log(h.bodyHandle);
        }
    });

    useFrame(() => {
        const current = hit.current;
        if (current && !Array.isArray(current)) highlight(current.bodyHandle);
    });

    raycaster.isDebugging = false;
    return null;
}

It returns { raycaster, hit }, where hit is a mutable ref updated in place — read hit.current from useFrame, an event handler or onHit. It is deliberately not React state: a fast-moving pointer would otherwise re-render every frame.

Unlike its siblings, this hook destroys its raycaster when type or filter change as well as on unmount — see Lifetime.

One raycaster, many origins or many origin/destination pairs — sweeps, foot probes, spread patterns:

import { useMulticaster } from '@react-three/jolt';
import { useEffect } from 'react';
import * as THREE from 'three';

export function Sweep() {
    const multicaster = useMulticaster();

    useEffect(() => {
        multicaster.positions = [new THREE.Vector3(-5, 5, 0), new THREE.Vector3(5, 5, 0)];
        multicaster.direction = new THREE.Vector3(0, -10, 0);
        multicaster.cast();
    }, [multicaster]);

    return null;
}

cast() walks positions with the shared direction; castRays() walks rays ({ origin, destination }[]). Both fill hits (flat) and results (grouped per ray), and both clear them first.

useAdvancedRaycaster() exposes Jolt's collector callbacks so you can filter or bail out during the cast:

import type Jolt from 'jolt-physics';

const caster = useAdvancedRaycaster();
caster.onBody((body: Jolt.Body) => {
    /* inspect each body the ray reaches */
});
caster.addHit((result: Jolt.RayCastResult) => {
    /* return truthy to shorten the cast to this hit */
});
caster.onReset(() => {
    /* also resets the collector's early-out fraction */
});

The callbacks hand you raw Jolt objects the collector owns. Read what you need and return — do not keep them, and never destroy() them. They are declared loosely, so annotate the parameters yourself as above.

cast() resets the collector before casting (resetting after would wipe the hits it just collected). In 'all' mode the success handler is called once per hit.

A shapecast sweeps a whole shape along a direction — "will this capsule fit through there", a thick ground probe, a camera collision test. There is no hook yet; take one from the physics system and destroy it yourself.

import { Shapecaster, ShapecastHit, useJolt } from '@react-three/jolt';
import { useEffect } from 'react';
import * as THREE from 'three';

export function GroundProbe() {
    const { physicsSystem } = useJolt();
    const shapecaster: Shapecaster = physicsSystem.getShapecaster();

    useEffect(() => () => shapecaster.destroy(), [shapecaster]);

    useEffect(() => {
        shapecaster.origin = new THREE.Vector3(0, 5, 0);
        shapecaster.direction = new THREE.Vector3(0, -6, 0);
        shapecaster.cast((hit: ShapecastHit) => {
            console.log(hit.position, hit.distance, hit.bodyHandle);
        });
    }, [shapecaster]);

    return null;
}

It casts a 0.5-radius sphere by default. shape takes any Jolt.Shape (build one with createShapeFromSettings); origin, rotation, scale and direction accept three.js values and rebuild the underlying cast for you. ignoreBackfaceTriangles and ignoreBackfaceConvex (both true) control back-face handling, and setCollector('closest' | 'any' | 'all') works as it does for rays.

ShapecastHit carries position, start, end, distance, normal/direction, impactNormal, bodyHandle, shapeIdValue and index — the same surface as RaycastHit.

CollideShape asks a different question: not "what will I hit if I move", but "what am I overlapping right now, and by how much". This is what you want for triggers, spawn checks and push-out resolution.

import { ShapeCollider, useJolt } from '@react-three/jolt';
import { useEffect } from 'react';
import * as THREE from 'three';

export function Overlap() {
    const { physicsSystem } = useJolt();
    const collider: ShapeCollider = physicsSystem.getShapeCollider();

    useEffect(() => () => collider.destroy(), [collider]);

    useEffect(() => {
        collider.position = new THREE.Vector3(0, 1, 0);
        collider.setCollector('all');
        collider.cast((hits: typeof collider.hits) => {
            hits.forEach((hit) => console.log(hit.penetrationDepth, hit.contactNormal));
        });
    }, [collider]);

    return null;
}

Set position, rotation or matrix and the world transform is rebuilt in place — no allocation per frame, which is what makes it safe to drive from useFrame (the camera rig does).

cast() returns the single hit when there is exactly one, the hits array when there are more, and false on a miss.

collider.shape is reference counted, not owned outright:

const shape = generateShape({ type: 'box', size: [1, 1, 1] });
collider.shape = shape; // the collider takes its own reference (AddRef)
releaseShape(shape); // you can drop yours immediately; the collider still holds one

Assigning a new shape AddRefs it and Releases the previous one; destroy() releases the current one rather than hard-destroying it. So a caller that also holds — and later frees — a reference to the same shape never ends up with a dangling pointer. Assigning the shape it already has is a no-op.

Shapecaster.shape does not do this: it writes the shape straight into the cast, so keep your own reference alive for as long as the shapecaster uses it.

Casters draw themselves when you ask — they deliberately ignore <Physics debug>, because a caster can fire thousands of times a second.

raycaster.initDebugging(scene);   // adds a debug object to the scene
raycaster.drawPoints = true;      // start/hit/end points
raycaster.drawMarkers = true;     // markers at each hit
raycaster.lineColor = '#68D8D6';
raycaster.stopDebugging();

Raycasters, shapecasters and the multicaster's inner raycaster all share this API.

A Raycaster's markers are a small ring plus a normal-indicator line, oriented along the hit surface normal (Quaternion.setFromUnitVectors((0, 1, 0), hit.impactNormal)) rather than axis-aligned to the world. A degenerate normal falls back to world up.

The debug objects are pooled per caster: one shared material per drawing type, geometry reused through setFromPoints, and one marker group per hit index, so repeated drawMarker() / cast() calls update an existing group's transform instead of allocating. Markers past the current hit count are hidden rather than destroyed. destroy() and clearDebugging() dispose the pools.

Shapecaster behaves the same way: it has the same pooled drawing and the same normal-oriented markers, and its destroy() / clearDebugging() dispose the pools too.

Raycaster, Shapecaster, ShapeCollider and Multicaster used to each duplicate the same filter setup, destroy bookkeeping and (for the ray-like casters) debug-drawing code (issue #217). They now all extend a small hierarchy instead — useful mainly if you're building a fifth query type, or want to know exactly what destroy() covers:

Raycaster and Shapecaster extend CastQueryBase (and AdvancedRaycaster extends Raycaster); ShapeCollider and Multicaster extend QueryBase directly since neither uses the ray-cast collector family. RaycastHit and ShapecastHit both extend HitBase, which is why their fields line up exactly (see RaycastHit above).

QueryBase implements destroy() once, as a template: it flips an internal destroyed flag and calls the abstract releaseResources() every subclass implements for whatever else it allocated. This means destroy() is idempotent on every query type now — Raycaster, Shapecaster, ShapeCollider and Multicaster alike, not just ShapeCollider as before #217. Calling it twice is safe and the second call does nothing, because Raw.module.destroy() on an already-freed object does not throw — it silently double-frees.

successHandler/failHandler on cast()/castFrom()/castTo()/castBetween() stay untyped (any) rather than a (hit?: THit | THit[]) => void alias: TypeScript checks a plain function-type parameter's parameter list contravariantly, so a caller passing a narrower callback — (hit: RaycastHit) => void, the shape every example above uses — would stop compiling even though cast() never actually calls it with undefined or an array unless the hit shape says so. Annotate your own handler's parameter as shown in the examples on this page.

Every caster allocates Jolt filters, a collector and settings objects on the WASM heap. They are freed only by destroy().

useRaycaster's origin and direction are compared by identity, so passing an inline array or Vector3 re-creates the caster on every render. Hoist them, or use raycaster.set(...).

Some query surfaces give you real Jolt objects: AdvancedRaycaster's collector callbacks, CollisionResult.subShapeId1/2, BodyState.body, anything reached through useJolt().jolt.

Full rules in Memory & lifecycle.