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

webxr-setup — правило для Claude Code: что делает и как установить

Правило webxr-setup для Claude Code задаёт настройку VR- и AR-сцен на Three.js через WebXR. Помогает агенту настроить рендерер, контроллеры и отслеживание рук.

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

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

Что делает webxr-setup

Правило задаёт стандарты внедрения WebXR в проектах с Three.js. Оно содержит готовые шаблоны подключения кнопок VRButton и ARButton, переключения пространств отсчёта вроде local-floor и обязательного использования renderer.setAnimationLoop() вместо ручного вызова requestAnimationFrame.

Внутри собраны сниппеты для отдельных подсистем: загрузка моделей контроллеров через XRControllerModelFactory, трекинг кистей рук, хит-тестинг в AR и перемещение через смещение XRRigidTransform. Также описана обработка событий сессии sessionstart и sessionend.

Safari на iOS технологию WebXR не поддерживает. Из-за этого тестировать решения придётся на гарнитурах вроде Meta Quest или в мобильных браузерах под Android.

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

  • Настроить сессию WebXR в Three.js с кнопками входа в VR и AR
  • Подключить модели контроллеров и обработать события захвата
  • Реализовать хит-тестинг и размещение прицела на поверхностях в AR
  • Сделать перемещение пользователя в VR через телепортацию

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

  • Добавь в Three.js сцену вход в AR с проверкой плоскостей через hit-test
  • Настрой телепортацию пользователя по клику на контроллер в VR
  • Подключи отслеживание рук через XRHandModelFactory

Как установить webxr-setup

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

.claude/rules/webxr-setup.md

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

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

Вопросы о webxr-setup

Как установить webxr-setup в Claude Code?

Добавьте файл правила по пути .claude/rules/webxr-setup.md в корень вашего проекта.

Что делает правило webxr-setup?

Оно даёт агенту инструкции по правильной архитектуре Three.js WebXR: циклам рендеринга, типам пространств, хит-тестам и контроллерам.

Почему в WebXR нельзя вызывать requestAnimationFrame вручную?

Спецификация WebXR требует использовать метод renderer.setAnimationLoop(), чтобы синхронизировать кадры с частотой обновления гарнитуры в диапазоне 72–90 fps.

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

webxr-setup.md · MIT
# WebXR Setup

Guide to implementing VR and AR experiences with Three.js WebXR.

## Basic Setup

```javascript
import { VRButton } from 'three/addons/webxr/VRButton.js';
import { ARButton } from 'three/addons/webxr/ARButton.js';

// Enable XR
renderer.xr.enabled = true;

// VR
document.body.appendChild(VRButton.createButton(renderer));

// AR
document.body.appendChild(ARButton.createButton(renderer, {
  requiredFeatures: ['hit-test']
}));

// Animation loop for XR (required)
renderer.setAnimationLoop(function() {
  renderer.render(scene, camera);
});
```

## Reference Spaces

```javascript
// AR - local space
renderer.xr.setReferenceSpaceType('local');

// VR - room-scale
renderer.xr.setReferenceSpaceType('local-floor');

// VR - seated
renderer.xr.setReferenceSpaceType('local');

// VR - unbounded (large areas)
renderer.xr.setReferenceSpaceType('unbounded');
```

## Controllers

```javascript
const controller1 = renderer.xr.getController(0);
const controller2 = renderer.xr.getController(1);
scene.add(controller1, controller2);

// Events
controller1.addEventListener('selectstart', onSelectStart);
controller1.addEventListener('selectend', onSelectEnd);
controller1.addEventListener('squeeze', onSqueeze);

// Controller models
import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';

const controllerModelFactory = new XRControllerModelFactory();

const controllerGrip1 = renderer.xr.getControllerGrip(0);
controllerGrip1.add(controllerModelFactory.createControllerModel(controllerGrip1));
scene.add(controllerGrip1);

const controllerGrip2 = renderer.xr.getControllerGrip(1);
controllerGrip2.add(controllerModelFactory.createControllerModel(controllerGrip2));
scene.add(controllerGrip2);
```

## Hand Tracking

```javascript
import { XRHandModelFactory } from 'three/addons/webxr/XRHandModelFactory.js';

const handModelFactory = new XRHandModelFactory();

const hand1 = renderer.xr.getHand(0);
hand1.add(handModelFactory.createHandModel(hand1, 'mesh'));
scene.add(hand1);

const hand2 = renderer.xr.getHand(1);
hand2.add(handModelFactory.createHandModel(hand2, 'mesh'));
scene.add(hand2);
```

## AR Hit Testing

```javascript
let hitTestSource = null;
let hitTestSourceRequested = false;

renderer.xr.addEventListener('sessionstart', async () => {
  const session = renderer.xr.getSession();
  const viewerSpace = await session.requestReferenceSpace('viewer');
  hitTestSource = await session.requestHitTestSource({ space: viewerSpace });
});

renderer.xr.addEventListener('sessionend', () => {
  hitTestSource = null;
  hitTestSourceRequested = false;
});

function animate(timestamp, frame) {
  if (frame && hitTestSource) {
    const referenceSpace = renderer.xr.getReferenceSpace();
    const hitTestResults = frame.getHitTestResults(hitTestSource);

    if (hitTestResults.length > 0) {
      const hit = hitTestResults[0];
      const pose = hit.getPose(referenceSpace);

      reticle.visible = true;
      reticle.matrix.fromArray(pose.transform.matrix);
    } else {
      reticle.visible = false;
    }
  }

  renderer.render(scene, camera);
}
```

## AR Features

```javascript
// Request specific AR features
document.body.appendChild(ARButton.createButton(renderer, {
  requiredFeatures: ['hit-test'],
  optionalFeatures: ['dom-overlay', 'light-estimation'],
  domOverlay: { root: document.body }
}));

// Light estimation
renderer.xr.addEventListener('sessionstart', () => {
  const session = renderer.xr.getSession();
  session.requestLightProbe().then((lightProbe) => {
    // Use light probe data
  });
});
```

## Teleportation (VR)

```javascript
const marker = new THREE.Mesh(
  new THREE.CircleGeometry(0.25, 32).rotateX(-Math.PI / 2),
  new THREE.MeshBasicMaterial({ color: 0x00ff00 })
);

controller.addEventListener('selectstart', () => {
  const intersects = getIntersections(controller);
  if (intersects.length > 0) {
    const point = intersects[0].point;
    // Move user to point
    baseReferenceSpace = renderer.xr.getReferenceSpace();
    const offsetPosition = { x: -point.x, y: 0, z: -point.z, w: 1 };
    const transform = new XRRigidTransform(offsetPosition);
    const teleportSpace = baseReferenceSpace.getOffsetReferenceSpace(transform);
    renderer.xr.setReferenceSpace(teleportSpace);
  }
});
```

## Session Events

```javascript
renderer.xr.addEventListener('sessionstart', () => {
  console.log('XR session started');
});

renderer.xr.addEventListener('sessionend', () => {
  console.log('XR session ended');
});

// Check if in XR
if (renderer.xr.isPresenting) {
  // Currently in XR
}
```

## Browser Support (2025)

| Browser | VR | AR |
|---------|----|----|
| Chrome (Android) | Yes | Yes |
| Samsung Internet | Yes | Yes |
| Meta Quest Browser | Yes | Limited |
| Safari (iOS) | No | No |
| Firefox Reality | Yes | Yes |

## Best Practices

1. **setAnimationLoop**: Always use `renderer.setAnimationLoop()` for XR, not manual RAF

2. **Reference Space**: Choose appropriate reference space for your experience

3. **Controller Fallback**: Provide gaze/pointer fallback for devices without controllers

4. **Performance**: Target 72-90 fps for comfortable VR experience

5. **Comfort**: Avoid artificial locomotion; prefer teleportation

6. **UI**: Place UI at comfortable distance (1-3 meters)

7. **Testing**: Test on actual devices, not just emulators

## References

- [Three.js WebXR Examples](https://threejs.org/examples/?q=webxr)
- [WebXR Device API](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API)
- [Immersive Web](https://immersiveweb.dev/)

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

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

Все правила IDE по теме «Фронтенд и UI» →
aframe-webxr freshtechbro Скилл aframe-webxr для сборки браузерных 3D-, VR- и AR-сцен на A-Frame: агент пишет декларативную разметку вместо длинного JavaScript. CX Codex +1 2 600установок threejs-xr cesartevisual Скилл threejs-xr для Claude Code помогает добавлять VR- и AR-сессии в проекты на Three.js. Он подключается к задачам про XR-ввод, пространства отсчёта и жизненный цикл сессии. CX Codex +1 577установок spatial-developer daffy0208 Скилл spatial-developer для Claude Code даёт агенту приёмы для разработки пространственных интерфейсов: WebXR-сцен, AR с hit-test, приложений для visionOS и 3D на Three.js. CX Codex +1 175установок ar-vr-xr travisjneuman Скилл ar-vr-xr для Claude Code помогает проектировать AR-, VR- и XR-приложения для Unity, WebXR и устройств Apple и Meta. Помогает продумывать взаимодействия, интерфейс и производительность в пространстве. CX Codex +1 125установок 3D AR Studio nirholas MCP-сервер 3D AR Studio собирает 3D-модели в дополненную реальность прямо в браузере и отдаёт человеку одну ссылку, которая открывает сцену в его комнате. CX Codex +1 ★ 11звёзд репо aframe-webxr-architect Claude Design Skillstack Субагент aframe-webxr-architect проектирует сцены A-Frame WebXR, настраивает освещение и оптимизирует рендеринг для браузеров. Пригодится при сборке трёхмерных веб-приложений. CX Codex ★ 1 428звёзд репо

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

Весь набор →
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звёзд репо 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звёзд репо 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звёзд репо tsl-complete-reference Правило tsl-complete-reference для Claude Code даёт справочник по TSL и помогает писать нодовые шейдеры без ошибок в типах и вызовах. CX Codex +1 ★ 4 719звёзд репо test-suite-architect Скилл test-suite-architect разворачивает QA-процессы по стандартам Google и OWASP: шаблоны тест-кейсов AAA, трекинг дефектов P0–P4, расчёт метрик и прогон тестов через LLM. CX Codex +1 ★ 4 719звёзд репо

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

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