raycasting-optimization — Claude Code rule for faster picking
The raycasting-optimization rule covers ways to reduce Three.js raycasting work, from filtering objects by layer to using BVH or GPU picking. Useful when a scene has complex meshes or frequent pointer checks.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/raycasting-optimization.mdWhat raycasting-optimization does
The rule shows how to narrow raycaster queries with object layers, near and far limits, and first-hit checks. It also recommends throttling pointer-triggered raycasts rather than checking on every mouse event. Simple changes first.
For complex meshes, it describes adding three-mesh-bvh, building a BVH for geometry, and clearing the bounds tree when done. Octree examples cover scene queries and capsule collisions. For skinned meshes, the rule outlines GPU picking: render objects with distinct colors, read the pixel beneath the pointer, then map its color back to an object.
The BVH example depends on three-mesh-bvh, installed with npm install three-mesh-bvh. The rule suggests considering BVH for meshes with 80k+ polygons; Octree serves a different purpose, including collision checks.
What it helps with
- filter decorative objects out of raycaster queries
- accelerate intersections with complex meshes using BVH
- throttle pointer-driven raycasts
- pick objects by pixel color on the GPU
- check capsule collisions with an Octree
Example prompts for the agent
- Apply the raycasting-optimization rule and filter raycaster queries to interactive objects only.
- Use the rule to speed up intersections with this complex mesh using
three-mesh-bvh. - Apply raycasting-optimization to throttle raycasts triggered by pointer movement.
How to install raycasting-optimization
Manually: put the files in place
.claude/rules/raycasting-optimization.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/raycasting-optimization.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/raycasting-optimization.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/raycasting-optimization.mdManually: put the files in place
.clinerules/raycasting-optimization.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about raycasting-optimization
How do I install raycasting-optimization in Claude Code?
Add the rule file at .claude/rules/raycasting-optimization.md.
What does raycasting-optimization do?
It describes Three.js raycasting techniques, including layer filtering, BVH acceleration, throttling, Octree queries, and GPU picking.
When should I use three-mesh-bvh instead of Octree?
The rule presents BVH for ray-mesh intersections and Octree for scene queries and collision checks.
Source text
raycasting-optimization.md · MIT
# Raycasting Optimization
Efficient picking and intersection testing in Three.js.
## Basic Raycaster
```javascript
const raycaster = new THREE.Raycaster();
const pointer = new THREE.Vector2();
function onPointerMove(event) {
pointer.x = (event.clientX / window.innerWidth) * 2 - 1;
pointer.y = -(event.clientY / window.innerHeight) * 2 + 1;
}
function checkIntersections() {
raycaster.setFromCamera(pointer, camera);
const intersects = raycaster.intersectObjects(scene.children, true);
if (intersects.length > 0) {
const hit = intersects[0];
console.log('Object:', hit.object.name);
console.log('Point:', hit.point);
console.log('Face:', hit.face);
console.log('Distance:', hit.distance);
}
}
```
## Layers for Filtering
```javascript
// Define layers
const LAYER_INTERACTIVE = 1;
const LAYER_DECORATIVE = 2;
// Assign objects to layers
interactiveObject.layers.set(LAYER_INTERACTIVE);
decorativeObject.layers.set(LAYER_DECORATIVE);
// Raycaster only checks specific layer
raycaster.layers.set(LAYER_INTERACTIVE);
// Multiple layers
raycaster.layers.enable(LAYER_INTERACTIVE);
raycaster.layers.enable(2);
```
## three-mesh-bvh (High Performance)
For complex meshes (80k+ polygons), use BVH acceleration:
```bash
npm install three-mesh-bvh
```
```javascript
import { MeshBVH, acceleratedRaycast } from 'three-mesh-bvh';
// Extend Mesh prototype
THREE.Mesh.prototype.raycast = acceleratedRaycast;
// Generate BVH for mesh
mesh.geometry.boundsTree = new MeshBVH(mesh.geometry);
// Now raycasting is ~100x faster
const intersects = raycaster.intersectObject(mesh);
// Dispose when done
mesh.geometry.boundsTree = null;
```
### BVH Options
```javascript
mesh.geometry.boundsTree = new MeshBVH(mesh.geometry, {
maxLeafTris: 10, // Triangles per leaf node
maxDepth: 40, // Max tree depth
strategy: CENTER // SAH, CENTER, or AVERAGE
});
```
## Throttling
```javascript
// Don't raycast on every mousemove
let lastRaycast = 0;
const RAYCAST_INTERVAL = 50; // ms
function onPointerMove(event) {
const now = performance.now();
if (now - lastRaycast < RAYCAST_INTERVAL) return;
lastRaycast = now;
updatePointer(event);
checkIntersections();
}
```
## Octree for Scenes
```javascript
import { Octree } from 'three/addons/math/Octree.js';
const octree = new Octree();
// Add meshes to octree
scene.traverse((object) => {
if (object.isMesh) {
octree.fromGraphNode(object);
}
});
// Optimized raycast
const result = octree.rayIntersect(ray);
// Capsule collision (for character controllers)
const capsuleInfo = {
radius: 0.5,
segment: new THREE.Line3(
new THREE.Vector3(0, 0.5, 0),
new THREE.Vector3(0, 1.5, 0)
)
};
const collision = octree.capsuleIntersect(capsuleInfo);
```
## GPU Picking
For skinned meshes or when BVH isn't enough:
```javascript
// Concept:
// 1. Render each object with unique color
// 2. Read pixel under mouse
// 3. Map color -> object
const pickingScene = new THREE.Scene();
const pickingTexture = new THREE.WebGLRenderTarget(1, 1);
const idToObject = new Map();
// Assign unique colors
let id = 1;
scene.traverse((object) => {
if (object.isMesh) {
const color = new THREE.Color(id);
const pickingMaterial = new THREE.MeshBasicMaterial({
color: color
});
const pickingMesh = object.clone();
pickingMesh.material = pickingMaterial;
pickingScene.add(pickingMesh);
idToObject.set(id, object);
id++;
}
});
function gpuPick(x, y) {
camera.setViewOffset(
renderer.domElement.width, renderer.domElement.height,
x, y, 1, 1
);
renderer.setRenderTarget(pickingTexture);
renderer.render(pickingScene, camera);
camera.clearViewOffset();
const pixelBuffer = new Uint8Array(4);
renderer.readRenderTargetPixels(pickingTexture, 0, 0, 1, 1, pixelBuffer);
const id = (pixelBuffer[0] << 16) | (pixelBuffer[1] << 8) | pixelBuffer[2];
return idToObject.get(id);
}
```
## Best Practices
1. **Layers**: Use layers to filter non-interactive objects
2. **BVH**: Use three-mesh-bvh for complex meshes
3. **Throttle**: Don't raycast on every mouse event
4. **Bounding Box**: Three.js already optimizes with bounding box/sphere checks
5. **Recursive**: Use `recursive=true` only when needed
6. **First Hit**: If you only need first hit, check `intersects[0]`
7. **Near/Far**: Set raycaster.near and raycaster.far to limit range
```javascript
raycaster.near = 0.1;
raycaster.far = 100;
```
## Spatial Partitioning Comparison
| Structure | Best For |
|-----------|----------|
| BVH | Ray-mesh intersection |
| Octree | Scene queries, collision |
| KD-Tree | Point queries |
| Grid | Uniform distribution |
## References
- [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh)
- [Three.js Raycaster](https://threejs.org/docs/#api/en/core/Raycaster)
- [Three.js Octree](https://threejs.org/examples/?q=octree)
© zebbern · MIT · zebbern/claude-code-guide