Raycasting

Step 1 -- Understand automatic raycasting

When you add onClick or onPointerOver to a mesh, R3F automatically raycasts against that object. You do not need to set up a raycaster yourself. Only meshes with event handlers are tested -- everything else is invisible to the ray.

// R3F raycasts against this mesh automatically
<mesh onClick={(e) => {
  console.log('Hit at:', e.point)
  console.log('Distance:', e.distance)
}}>
  <sphereGeometry args={[1, 32, 32]} />
  <meshStandardMaterial />
</mesh>

The event object gives you the exact 3D hit position, the distance from the camera, the face that was hit, and more. No manual setup required.

Step 2 -- Use meshBounds for fast approximate hits

For complex geometry where pixel-perfect accuracy is not critical, drei's meshBounds replaces per-triangle raycasting with a single bounding-box test. Thousands of times faster.

import { meshBounds } from '@react-three/drei'

<mesh
  raycast={meshBounds}
  onClick={() => console.log('Bounding box hit!')}
>
  <torusKnotGeometry args={[1, 0.3, 256, 64]} />
  <meshStandardMaterial color="purple" />
</mesh>

For a 16,000-triangle torus knot, this turns 16,000 intersection tests into just 1 box test. Clicks near the edges may register outside the actual geometry, but for buttons and UI that is fine.

Step 3 -- Cast rays manually for custom mechanics

For shooting, line-of-sight, or ground detection, create a Raycaster yourself and cast rays in any direction, not just from the mouse.

const raycaster = useRef(new THREE.Raycaster())
const down = useRef(new THREE.Vector3(0, -1, 0))

useFrame(() => {
  raycaster.current.set(player.position, down.current)
  const hits = raycaster.current.intersectObjects(ground)
  if (hits.length > 0) {
    player.position.y = hits[0].point.y + 1
  }
})

This casts a ray straight down from the player to find the ground, then snaps the player to the surface. The same idea powers shooters (ray from gun barrel), AI vision (ray toward target), and physics (collision probes).