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

physics-integration — правило для Claude Code

Правило physics-integration задаёт правила связки Three.js с физическими движками Rapier и Cannon-es: настройка Vite, коллайдеры и синхронизация позиций.

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

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

Что делает physics-integration

Правило регламентирует добавление физики в сцены на Three.js. Внутри собраны готовые шаблоны инициализации миров для @dimforge/rapier3d и cannon-es, перечни примитивов коллайдеров и типы тел. Для сборщика Vite зафиксированы плагины vite-plugin-wasm и vite-plugin-top-level-await, без которых Rapier в браузере не стартует.

Инструкция пресекает частую ошибку с двусторонней синхронизацией, которая зацикливает расчёт координат: данные передаются строго от физического тела к мешу Three.js, кроме кинематических объектов. Также здесь закреплены правила производительности: фиксированный шаг времени 1/60, включение спящего режима allowSleep и отладка через cannon-es-debugger.

Какие задачи решает

  • настроить Rapier с поддержкой WASM в Vite
  • привязать координаты физических тел к мешам Three.js
  • подобрать формы коллайдеров под сложную 3D-геометрию
  • подключить визуальную отладку контактов через cannon-es-debugger

Примеры запросов агенту

  • Добавь симуляцию падения шара на Three.js с использованием Rapier
  • Настрой мир cannon-es с гравитацией и свяжи его с существующим мешем
  • Сделай отладчик коллизий для сцены с помощью cannon-es-debugger

Как установить physics-integration

Вручную: положить файлы

.claude/rules/physics-integration.md

Поле paths во frontmatter ограничивает файлы

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о physics-integration

Как установить physics-integration в Claude Code?

Сохраните файл правила по пути .claude/rules/physics-integration.md в корне вашего проекта.

Что делает physics-integration?

Обучает ассистента правильным шаблонам интеграции движков Rapier и Cannon-es с Three.js, включая однонаправленную синхронизацию и фиксированный шаг симуляции.

Какой движок автор рекомендует для новых проектов?

Руководство выделяет Rapier на Rust/WASM как приоритетный вариант из-за детерминированности и высокой производительности.

Исходный текст

physics-integration.md · MIT
# Physics Integration

Guide to integrating physics engines with Three.js.

## Engine Comparison

| Engine | Language | Characteristics | Performance |
|--------|----------|-----------------|-------------|
| **Rapier** | Rust/WASM | Deterministic, modern | Very High |
| **Cannon-es** | JavaScript | Easy to use, maintained fork | High |
| **Ammo.js** | C++/WASM | Bullet port, softbody support | Medium-High |

## Rapier (Recommended for 2025+)

### Setup

```bash
npm install @dimforge/rapier3d
```

### Vite Configuration

```javascript
// vite.config.js
import wasm from 'vite-plugin-wasm';
import topLevelAwait from 'vite-plugin-top-level-await';

export default {
  plugins: [wasm(), topLevelAwait()]
};
```

### Basic Usage

```javascript
import RAPIER from '@dimforge/rapier3d';

await RAPIER.init();
const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });

// Create rigid body
const rigidBodyDesc = RAPIER.RigidBodyDesc.dynamic()
  .setTranslation(0, 5, 0);
const rigidBody = world.createRigidBody(rigidBodyDesc);

// Add collider
const colliderDesc = RAPIER.ColliderDesc.ball(0.5);
world.createCollider(colliderDesc, rigidBody);

// Sync with Three.js mesh
function animate() {
  world.step();

  const position = rigidBody.translation();
  const rotation = rigidBody.rotation();

  mesh.position.set(position.x, position.y, position.z);
  mesh.quaternion.set(rotation.x, rotation.y, rotation.z, rotation.w);
}
```

### Collider Shapes

```javascript
RAPIER.ColliderDesc.ball(radius)
RAPIER.ColliderDesc.cuboid(hx, hy, hz)
RAPIER.ColliderDesc.capsule(halfHeight, radius)
RAPIER.ColliderDesc.cylinder(halfHeight, radius)
RAPIER.ColliderDesc.cone(halfHeight, radius)
RAPIER.ColliderDesc.convexHull(vertices)
RAPIER.ColliderDesc.trimesh(vertices, indices)
```

## Cannon-es

### Setup

```bash
npm install cannon-es
```

### Basic Usage

```javascript
import * as CANNON from 'cannon-es';

const world = new CANNON.World();
world.gravity.set(0, -9.82, 0);

const sphereBody = new CANNON.Body({
  mass: 1,
  shape: new CANNON.Sphere(0.5),
  position: new CANNON.Vec3(0, 5, 0)
});
world.addBody(sphereBody);

function animate() {
  world.step(1/60);
  mesh.position.copy(sphereBody.position);
  mesh.quaternion.copy(sphereBody.quaternion);
}
```

### Body Types

```javascript
// Dynamic (affected by forces)
new CANNON.Body({ mass: 1 })

// Static (immovable, mass = 0)
new CANNON.Body({ mass: 0 })

// Kinematic (controlled programmatically)
new CANNON.Body({
  mass: 0,
  type: CANNON.Body.KINEMATIC
})
```

### Shapes

```javascript
new CANNON.Sphere(radius)
new CANNON.Box(new CANNON.Vec3(hx, hy, hz))
new CANNON.Cylinder(radiusTop, radiusBottom, height, segments)
new CANNON.Plane()
new CANNON.ConvexPolyhedron({ vertices, faces })
new CANNON.Trimesh(vertices, indices)
```

## Sync Pattern

### BAD - Bidirectional sync

```javascript
// Physics affects mesh
mesh.position.copy(body.position);
// Mesh affects physics (creates feedback loop)
body.position.copy(mesh.position);
```

### GOOD - Physics -> Visual only

```javascript
function syncPhysicsToMesh(body, mesh) {
  mesh.position.copy(body.position);
  mesh.quaternion.copy(body.quaternion);
}

// For kinematic bodies controlled by Three.js
function syncMeshToKinematic(mesh, body) {
  body.position.copy(mesh.position);
  body.quaternion.copy(mesh.quaternion);
}
```

## Best Practices

1. **Simple Shapes**: Use simple colliders (box, sphere) even for complex meshes

2. **Fixed Timestep**: Use fixed timestep for physics (1/60)
   ```javascript
   world.step(1/60, deltaTime, 3); // Fixed step, max substeps
   ```

3. **Sleep**: Enable sleep for static bodies
   ```javascript
   body.allowSleep = true;
   body.sleepSpeedLimit = 0.1;
   ```

4. **Broad Phase**: Configure appropriate broad phase
   ```javascript
   world.broadphase = new CANNON.SAPBroadphase(world);
   ```

5. **Material Friction**: Define physics materials
   ```javascript
   const material = new CANNON.Material('default');
   const contact = new CANNON.ContactMaterial(material, material, {
     friction: 0.3,
     restitution: 0.3
   });
   world.addContactMaterial(contact);
   ```

6. **Sync Direction**: Always sync physics -> visual, not reverse

7. **Compound Shapes**: Use compound shapes for complex objects
   ```javascript
   const body = new CANNON.Body({ mass: 1 });
   body.addShape(new CANNON.Box(size1), offset1);
   body.addShape(new CANNON.Sphere(radius), offset2);
   ```

## Debug Visualization

```javascript
import CannonDebugger from 'cannon-es-debugger';

const cannonDebugger = CannonDebugger(scene, world);

function animate() {
  world.step(1/60);
  cannonDebugger.update();
}
```

## References

- [Rapier Documentation](https://rapier.rs/)
- [Cannon-es GitHub](https://github.com/pmndrs/cannon-es)
- [Three.js + Physics Examples](https://threejs.org/examples/?q=physics)

© zebbern · MIT · zebbern/claude-code-guide

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

Все правила IDE по теме «Геймдев и 3D: Unity, Unreal, Godot, Blender» →
threejs-physics cesartevisual Скилл threejs-physics для Claude Code помогает связать Three.js с физическим движком вроде Rapier. Настраивает коллайдеры, фиксированный шаг симуляции и синхронизацию трансформаций с рендером. CX Codex +1 611установок threejs-gameplay-systems majidmanzarpour Скилл threejs-gameplay-systems разворачивает игровой цикл на Three.js, Vite и TypeScript с контролем физики, ввода и камеры. Пригодится при сборке прототипов и настройке гейм-фила. CX Codex +1 4 400установок r3f-physics EnzeD Скилл r3f-physics для Claude Code добавляет физику Rapier в проекты React Three Fiber. Он подключается к задачам с телами, столкновениями и движением под действием сил. CX Codex +1 2 100установок threejs-deployment cesartevisual Скилл threejs-deployment для Claude Code готовит и проверяет сборки веб-приложений на Three.js, работу хостинга, пути декодеров и кэширование. CX Codex +1 582установок physics-matter phaserjs Скилл physics-matter учит ИИ настраивать физику Matter.js в Phaser 4: твёрдые тела, ограничения, сенсоры и перетаскивание объектов мышью. CX Codex +1 937установок r3f-best-practices three-agent-skills Скилл r3f-best-practices для Claude Code содержит 70+ правил для написания, ревью и ускорения кода на React Three Fiber. Помогает избегать частых перерисовок и работать со стеком Poimandres. CX Codex +1 1 700установок

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

Весь набор →
tsl-post-processing Правило tsl-post-processing для Claude Code описывает постобработку Three.js на TSL: эффекты подключаются к postProcessing.outputNode без цепочки проходов EffectComposer. Агент обращается к нему при написании кода сцены. CX Codex +1 ★ 4 719звёзд репо 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звёзд репо raycasting-optimization Правило raycasting-optimization для Claude Code описывает, как ускорить поиск пересечений и выбор объектов в Three.js. Сокращает проверки Raycaster в интерактивных сценах и на сложных мешах. 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звёзд репо

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

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