raycasting-optimization — правило для Claude Code
Правило raycasting-optimization для Claude Code описывает, как ускорить поиск пересечений и выбор объектов в Three.js. Сокращает проверки Raycaster в интерактивных сценах и на сложных мешах.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/raycasting-optimization.mdЧто делает raycasting-optimization
Правило описывает способы отфильтровать объекты для Raycaster и сократить число проверок. Можно использовать слои для исключения декора, ограничить дальность через near и far, проверять только первое пересечение и не запускать Raycasting на каждом событии мыши.
Для сложных мешей правило предлагает three-mesh-bvh: установка выполняется через npm install three-mesh-bvh, затем для геометрии строится BVH. Для запросов по сцене описан Octree, а для скиннинговых мешей — подбор объекта по цвету через GPU. У этих вариантов разные задачи: Octree также рассматривает столкновения капсулы, а BVH ускоряет пересечения с мешем.
Без установленного three-mesh-bvh пример с BVH не заработает; для сцены с 80k+ полигонов правило предлагает рассмотреть этот вариант.
Какие задачи решает
- отфильтровать декорации при поиске пересечений
- сократить проверки сложного меша с помощью BVH
- ограничить частоту Raycasting при движении указателя
- находить объекты по пикселю через GPU
- проверять столкновение капсулы с Octree
Примеры запросов агенту
- Примени правило raycasting-optimization и настрой слои, чтобы Raycaster проверял только интерактивные объекты.
- Подскажи, как ускорить пересечения с этим сложным мешем с помощью
three-mesh-bvh. - Используй рекомендации raycasting-optimization, чтобы ограничить проверки при движении указателя.
Как установить raycasting-optimization
Вручную: положить файлы
.claude/rules/raycasting-optimization.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/raycasting-optimization.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/raycasting-optimization.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/raycasting-optimization.mdВручную: положить файлы
.clinerules/raycasting-optimization.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о raycasting-optimization
Как установить raycasting-optimization в Claude Code?
Добавь файл правила по пути .claude/rules/raycasting-optimization.md.
Что делает raycasting-optimization?
Правило описывает оптимизацию Raycasting в Three.js: фильтрацию по слоям, BVH, ограничение частоты проверок, Octree и GPU picking.
Когда использовать three-mesh-bvh, а когда Octree?
В правиле BVH предназначен для пересечений с мешами, а Octree — для запросов по сцене и проверки столкновений.
Исходный текст
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