Skip to main content
rule CX Codex

webxr-setup — Claude Code rule: what it does, how to install

The webxr-setup rule for Claude Code guides building VR and AR scenes in Three.js WebXR. It helps coding agents set up render loops, controllers, and hit-testing.

MIT ★ 4,719 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/webxr-setup.md
Open on GitHub

What webxr-setup does

This rule provides implementation guidelines for WebXR projects using Three.js. It covers initialisation with VRButton and ARButton, selecting reference spaces like local-floor, and enforcing renderer.setAnimationLoop() instead of standard animation frames.

The guide details controller event handling, XRControllerModelFactory setup, hand tracking meshes, and AR hit-testing using requestHitTestSource. It also includes code for VR teleportation using XRRigidTransform to shift the reference space.

Safari on iOS does not support WebXR at all, meaning mobile testing requires Android browsers or dedicated headsets like Meta Quest.

What it helps with

  • Configure Three.js renderers for immersive VR and AR modes
  • Add VR controller event listeners and visual models
  • Implement AR surface hit-testing with reticle tracking
  • Build locomotion through controller-based teleportation

Example prompts for the agent

  • Set up an AR scene in Three.js with hit-testing enabled
  • Add VR teleportation using controller raycasting and offset reference space
  • Configure hand tracking models using XRHandModelFactory

How to install webxr-setup

Manually: put the files in place

.claude/rules/webxr-setup.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about webxr-setup

How to install webxr-setup in Claude Code?

Save the rule file to .claude/rules/webxr-setup.md inside your repository.

What does webxr-setup do?

It teaches your coding agent standard patterns for Three.js WebXR, including animation loops, reference spaces, AR hit-tests, and controller models.

Which browsers support WebXR according to this guide?

Chrome on Android, Samsung Internet, and Firefox Reality support both VR and AR, while Safari on iOS does not support either.

Source text

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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set86

The whole set →
gltf-loading-optimization gltf-loading-optimization is a Claude Code rule with Three.js snippets and commands for glTF loading, decoder setup, progress reporting, lazy loading and model compression. CX Codex +1 ★ 4,719repo stars physics-integration physics-integration guides Three.js integration with Rapier and Cannon-es: Vite setup, collider primitives, and mesh synchronization patterns. CX Codex +1 ★ 4,719repo stars raycasting-optimization 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. CX Codex +1 ★ 4,719repo stars mobile-optimization mobile-optimization is a rule for accelerating Three.js scenes on smartphones and tablets. It reduces GPU load and memory use, helping maintain a stable frame rate. CX Codex +1 ★ 4,719repo stars error-handling-recovery The error-handling-recovery rule covers WebGL context loss, resource rebuilding, and fallback UI. Use it when a Three.js scene must recover from graphics failures. CX Codex +1 ★ 4,719repo stars vc-industry-research vc-industry-research turns a prompt into a PE/VC-style industry report: sector deep-dive, investment memo or market analysis, in Chinese or English, PDF by default. CX Codex +1 ★ 4,719repo stars tsl-complete-reference The tsl-complete-reference rule for Claude Code provides a TSL reference for writing node shaders without invalid syntax. CX Codex +1 ★ 4,719repo stars test-suite-architect test-suite-architect sets up QA infrastructure based on Google Testing Standards and OWASP: AAA test case templates, P0-P4 bug tracking, quality gate checks, and LLM test execution. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open