# Passthrough Mixed Reality in the Player's Room with three.js (WebXR immersive-ar)

> A passthrough game on the studio's three.js kit: hide the virtual setting when xr.passthrough turns on, place the play area from the head, move it by pointing at the floor and pinching, ground things with contact shadows, keep every drawn pixel opaque, and fall back to a virtual room everywhere else.

- **Canonical page:** https://gamecrew.ai/techniques/three/passthrough-mixed-reality
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Three.js
- **Category:** vr
- **Tags:** `vr`, `xr`, `webxr`, `passthrough`, `mixed reality`, `mr`, `ar`, `immersive-ar`, `room`, `tabletop`, `placement`, `contact shadow`, `alpha`, `quest`
- **Verification:** Compile-verified pattern
- **Revision:** 1 (2026-11-13)
- **Demo:** No demo

## When to Use & Field Best Practices

A passthrough game (game.json `"passthrough": true`) plays in the player's own room on a headset whose browser can show it: the page starts an `immersive-ar` session, the kit clears to transparent and takes `scene.background` and `scene.fog` away for the session, and the headset shows the room wherever nothing is drawn. The same link plays as ordinary VR on a headset that can't, and flat on a computer or phone, so a passthrough game always keeps its virtual setting.

1. **One switch, read on enter**: `game.xr.passthrough` is true in a passthrough session; react in `xr.onEnter` and undo in `xr.onExit`. `xr.passthroughGame` says the game is one, whatever the browser can do.
2. **Hide the setting, keep the toys**: keep sky dome, walls, floor and far scenery under one `THREE.Group` (`setting`) and set `setting.visible = false`. Never set `scene.background` or `scene.fog` while `xr.passthrough`.
3. **The real floor is y = 0** under the rig (`local-floor`). Nothing knows where the furniture is: place the play area from the head at the start, and let the player move it.
4. **Move it by pointing**: a pinch while a hand points down at the floor puts the play area there, facing the player.
5. **No artificial locomotion**: `xr.locomotion('none')`; the player walks in their room.
6. **Belong in the room**: a soft round contact shadow under what rests or lands; even, warm light (a `HemisphereLight` plus one soft `DirectionalLight`); opaque materials.
7. **Alpha is the mask**: an opaque material writes alpha 1; a cleared pixel is alpha 0, the room. `AdditiveBlending` effects and `opacity: 0` glows let the room through.

## Mathematical & Algorithmic Core

- **Placement from the head**: head position $\mathbf{h}$, forward flattened $\hat{\mathbf{f}}_{xz} = \mathrm{normalize}(f_x, 0, f_z)$, eye height $e = h_y - y_{\text{floor}}$:
  $$\mathbf{p} = (h_x, y_{\text{floor}}, h_z) + d\,\hat{\mathbf{f}}_{xz} + (0, \mathrm{clamp}(k e, 0.7, 1.1), 0)$$
  with $d \approx 0.45$ m, $k \approx 0.85$; the play area faces the player (yaw $= \mathrm{atan2}(-f_x, -f_z)$).
- **Point-at-floor**: aim origin $\mathbf{o}$, direction $\hat{\mathbf{a}}$ with $a_y < -0.15$: $t = (y_{\text{floor}} - o_y)/a_y$, $0 < t \le 4$, hit $\mathbf{o} + t\hat{\mathbf{a}}$.
- **Contact shadow**: scale $s_0(1 + 0.6\,c)$ and opacity $\alpha_0(1 - c)$ with $c = \mathrm{clamp01}(y/1.5)$ for the object's height $y$ over the surface.

## Engine Implementation

### Passthrough stage (`Assets/Game/Scripts/passthrough-stage.ts`)

```ts
import * as THREE from 'three';
import type { Game } from '../../CCGD/kit/game';

const _h = new THREE.Vector3(), _f = new THREE.Vector3(), _o = new THREE.Vector3(), _d = new THREE.Vector3();

/** The play area in the player's room: placed from the head in passthrough, moved by pointing at the floor and pinching. */
export function passthroughStage(game: Game, setting: THREE.Object3D, stage: THREE.Object3D, o = { reach: 0.45, heightShare: 0.85 }): void {
  const xr = game.xr;
  let placed = false;
  const pinched = { left: false, right: false };

  xr.onEnter(() => {
    if (!xr.passthrough) return;
    setting.visible = false;
    xr.locomotion('none');
    placed = false;
  });
  xr.onExit(() => {
    setting.visible = true;
    placed = false;
  });

  game.onUpdate(() => {
    if (!xr.active || !xr.passthrough) return;
    const floor = xr.rig.position.y;
    xr.head.getWorldPosition(_h);
    if (!placed) {
      xr.forward(_f).setY(0);
      if (_f.lengthSq() < 1e-4) _f.set(0, 0, -1);
      _f.normalize();
      const y = floor + THREE.MathUtils.clamp((_h.y - floor) * o.heightShare, 0.7, 1.1);
      stage.position.set(_h.x + _f.x * o.reach, y, _h.z + _f.z * o.reach);
      stage.rotation.set(0, Math.atan2(-_f.x, -_f.z), 0);
      placed = true;
    }
    for (const side of ['left', 'right'] as const) {
      const hand = xr.hands[side];
      const now = hand.connected && hand.pinching;
      if (now && !pinched[side]) {
        hand.aim.getWorldPosition(_o);
        hand.aim.getWorldDirection(_d).negate(); // an aim pose looks down its -Z
        if (_d.y < -0.15) {
          const t = (floor - _o.y) / _d.y;
          if (t > 0 && t <= 4) {
            const x = _o.x + _d.x * t, z = _o.z + _d.z * t;
            stage.position.set(x, stage.position.y, z);
            stage.rotation.set(0, Math.atan2(_h.x - x, _h.z - z), 0);
            hand.pulse(0.4, 30);
          }
        }
      }
      pinched[side] = now;
    }
  });
}

/** A soft round shadow on a surface under a thing: wider and fainter as it rises. */
export function contactShadow(target: THREE.Object3D, surfaceY: number, size = 0.12, strength = 0.55): THREE.Mesh {
  const c = document.createElement('canvas');
  c.width = c.height = 64;
  const g = c.getContext('2d')!;
  const grad = g.createRadialGradient(32, 32, 0, 32, 32, 32);
  grad.addColorStop(0, 'rgba(0,0,0,1)');
  grad.addColorStop(1, 'rgba(0,0,0,0)');
  g.fillStyle = grad;
  g.fillRect(0, 0, 64, 64);
  const mat = new THREE.MeshBasicMaterial({ map: new THREE.CanvasTexture(c), transparent: true, depthWrite: false, opacity: strength });
  const quad = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), mat);
  quad.rotation.x = -Math.PI / 2;
  quad.onBeforeRender = () => {
    const k = THREE.MathUtils.clamp((target.position.y - surfaceY) / 1.5, 0, 1);
    quad.position.set(target.position.x, surfaceY + 0.002, target.position.z);
    quad.scale.setScalar(size * (1 + 0.6 * k));
    mat.opacity = strength * (1 - k);
  };
  return quad;
}
```

### Test with the simulated passthrough session (`Assets/Game/Tests/play/passthrough.test.ts`)

```ts
import { test } from 'ccgd';
import * as THREE from 'three';

test('passthrough hides the setting and places the stage in front at hand height', async (t) => {
  const xr = t.game.xr;
  const setting = t.game.get<THREE.Object3D>('setting')!;
  const stage = t.game.get<THREE.Object3D>('stage')!;
  xr.sim.enter({ passthrough: true });
  await t.steps(3);
  t.ok(xr.passthrough, 'a passthrough session');
  t.ok(!setting.visible, 'the setting is hidden');
  t.eq(t.game.scene.background, null, 'no background over the room');
  const head = xr.head.getWorldPosition(new THREE.Vector3());
  const ahead = stage.position.clone().sub(head).dot(xr.forward(new THREE.Vector3()));
  t.gt(ahead, 0.2, 'the stage is in front of the player');
  xr.sim.exit();
  await t.steps(2);
  t.ok(setting.visible, 'the setting is back after the session');
});
```

## Pitfalls

- **A sky or backdrop in passthrough** covers the room; the save's check samples the headset's layer and fails when nothing is transparent.
- **Setting `scene.background` or fog each frame** undoes the kit's clearing: check `xr.passthrough` first.
- **Assuming a table**: the kit has no plane detection; a stage floating at hand height in front of the player is honest.
- **Locomotion in a real room** moves the virtual things away from the room; walking is the player's.
- **Forgetting the fallback**: test both `xr.sim.enter()` and `xr.sim.enter({ passthrough: true })`.

## Official references

- Meta Mixed Reality Design Guidelines (Passthrough, Scene placement)
- WebXR Device API environmentBlendMode
- three.js WebXRManager
