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.
- vr
- xr
- webxr
- passthrough
- mixed reality
- mr
- ar
- immersive-ar
- room
- tabletop
- placement
- contact shadow
- alpha
- quest
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.
- One switch, read on enter:
game.xr.passthroughis true in a passthrough session; react inxr.onEnterand undo inxr.onExit.xr.passthroughGamesays the game is one, whatever the browser can do. - Hide the setting, keep the toys: keep sky dome, walls, floor and far scenery under one
THREE.Group(setting) and setsetting.visible = false. Never setscene.backgroundorscene.fogwhilexr.passthrough. - 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. - Move it by pointing: a pinch while a hand points down at the floor puts the play area there, facing the player.
- No artificial locomotion:
xr.locomotion('none'); the player walks in their room. - Belong in the room: a soft round contact shadow under what rests or lands; even, warm light (a
HemisphereLightplus one softDirectionalLight); opaque materials. - Alpha is the mask: an opaque material writes alpha 1; a cleared pixel is alpha 0, the room.
AdditiveBlendingeffects andopacity: 0glows let the room through.
Mathematical & Algorithmic Core
- Placement from the head: head position
h, forward flattenedf_xz = normalize(f_x, 0, f_z), eye heighte = h_y - y_floor: $p = (h_x, y_floor, h_z) + d\,f_xz + (0, 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
o, directionawitha_y < -0.15:t = (y_floor - o_y)/a_y,0 < t ≤ 4, hito + ta. - Contact shadow: scale
s_0(1 + 0.6\,c)and opacityα_0(1 - c)withc = clamp01(y/1.5)for the object's height $y$ over the surface.
Engine Implementation
Passthrough stage (Assets/Game/Scripts/passthrough-stage.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)
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.backgroundor fog each frame undoes the kit's clearing: checkxr.passthroughfirst. - 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()andxr.sim.enter({ passthrough: true }).
Official references
- Meta Mixed Reality Design Guidelines (Passthrough, Scene placement)
- WebXR Device API environmentBlendMode
- three.js WebXRManager
More Three.js games
Games made with GameCrew on the same engine. No game has been built with this guide yet: these show what Three.js games here look like.
More Three.js techniques
Baked 3D Volumetric Cloud Sea, World-Anchored Marching & TAA in Three.js →
Endless fly-above volumetric cloud sea in Three.js r183 WebGL 2 using a GPU-baked WebGL3DRenderTarget SDF and lighting volume, anti-boiling world-anchored z-plane marching, 3-octave Henyey-Greenstein scattering, and variance-clamped depth-packed TAA.
BVH Mesh & Character Capsule Collision in Three.js →
Fast capsule-vs-triangle pushout and slope resolution using three-mesh-bvh shapecasts, pre-allocated scratch vectors, and CollisionWorld.
Zero-Allocation Context Steering, Patrol Loops & Telegraphed AI in Three.js →
Deterministic 60 Hz enemy and companion AI in Three.js using 8-slot context steering against CollisionWorld, level.json patrol loops, attack-token pacing, and telegraphed strikes.
Instanced Wind Foliage, Object-Pooled Particles & Spring Feel in Three.js →
Single-draw-call THREE.InstancedMesh wind foliage with player bend, zero-GC pooled burst particles, and dt-invariant second-order springs that keep 60 Hz steps under 2 ms.
Use verified techniques inside a real game
Describe your game idea for free or connect an MCP assistant to search and contribute techniques.
