К основному содержанию
правило CX Codex

raycasting-optimization — правило для Claude Code

Правило raycasting-optimization для Claude Code описывает, как ускорить поиск пересечений и выбор объектов в Three.js. Сокращает проверки Raycaster в интерактивных сценах и на сложных мешах.

MIT ★ 4 719 обновлён 2026-10-24

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/rules/raycasting-optimization.md
Открыть на GitHub

Что делает 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 и 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

Похожие правила IDE

Все правила IDE по теме «Геймдев и 3D: Unity, Unreal, Godot, Blender» →
threejs-interaction CloudAI-X Скилл threejs-interaction учит агента настраивать выбор объектов, перемещение по плоскости и управление камерой в three.js для WebGL и WebGPU. CX Codex +1 20 100установок godot-raycasting-queries thedivergentai Скилл godot-raycasting-queries для Claude Code содержит шаблоны физических запросов Godot через RayCast, ShapeCast и DirectSpaceState. Помогает настроить обнаружение попаданий, выбор объектов мышью и зрение ботов. CX Codex +1 328установок deepmotion-animate-3d calesthio Скилл deepmotion-animate-3d для Claude Code помогает спланировать захват движений по видео через сервис DeepMotion Animate 3D. Подключается при настройке мокапа для 3D-персонажей. CX Codex +1 143установок RTK Motion Intelligence rtkmotion MCP-сервер RTK Motion Intelligence, который отдаёт агенту данные motion capture, биомеханики реабилитации, угроз для локаций и грузовых перевозчиков. Платные вызовы оплачиваются USDC. CX Codex +1 2 335установок threejs-fundamentals CloudAI-X Скилл threejs-fundamentals помогает настроить базовую сцену Three.js r186: рендерер, камеры, цикл анимации с THREE.Timer и import map для WebGL или WebGPU с TSL. CX Codex +1 24 100установок orbit-card heygen-com Скилл orbit-card для Claude Code добавляет в проект анимированную карточку, которая облетает сферу из точек. Блок HyperFrames подходит для feature-сцены размером 1920×1080 и длительностью 10 секунд. CX Codex +1 13 200установок

Из того же набора86

Весь набор →
tsl-compute-shaders Правило tsl-compute-shaders подсказывает агенту, как писать вычислительные шейдеры на Three.js TSL для WebGPU и настраивать GPGPU-симуляции вроде частиц с расчётом физики. CX Codex +1 ★ 4 719звёзд репо animation-system Правило animation-system объясняет систему анимации Three.js: от запуска и смешивания клипов до морфинга и управления костями. Пригодится при работе с анимированными 3D-моделями. CX Codex +1 ★ 4 719звёзд репо gltf-loading-optimization Правило gltf-loading-optimization для Claude Code содержит сниппеты и команды для загрузки glTF в Three.js, настройки декодеров, прогресса, ленивой подгрузки и сжатия моделей. CX Codex +1 ★ 4 719звёзд репо physics-integration Правило physics-integration задаёт правила связки Three.js с физическими движками Rapier и Cannon-es: настройка Vite, коллайдеры и синхронизация позиций. CX Codex +1 ★ 4 719звёзд репо mobile-optimization Правило mobile-optimization с готовыми паттернами для ускорения Three.js-сцен на смартфонах и планшетах. Снижает нагрузку на GPU, уменьшает потребление памяти и помогает держать стабильный FPS. CX Codex +1 ★ 4 719звёзд репо webxr-setup Правило webxr-setup для Claude Code задаёт настройку VR- и AR-сцен на Three.js через WebXR. Помогает агенту настроить рендерер, контроллеры и отслеживание рук. CX Codex +1 ★ 4 719звёзд репо error-handling-recovery Правило error-handling-recovery для Claude Code обрабатывает потерю WebGL-контекста, пересоздаёт ресурсы и показывает запасной интерфейс в Three.js-сценах. CX Codex +1 ★ 4 719звёзд репо vc-industry-research Скилл vc-industry-research собирает отраслевое исследование в стиле PE/VC: глубокий разбор сектора, инвестиционный меморандум или обзор рынка. На китайском или английском, по умолчанию в PDF. CX Codex +1 ★ 4 719звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой