Quest WebXR Performance & Draw-Call Instancing in Three.js
Stay under 200 draw calls and 300k stereo triangles per frame in WebXR via InstancedMesh batches, zero-alloc updates, and WorldPanel HUDs.
- webxr
- vr
- instancing
- performance
- quest
- draw-calls
- world-ui
When to Use & Field Best Practices
In WebXR, the GPU renders left and right eyes every frame at 72–90 Hz on mobile tile-based GPUs. A scene that coasts along on desktop can stall Quest frame timing if every lantern, balustrade post, crystal shard, or reed draws individually:
- Batch Repeats into
THREE.InstancedMesh: Group static and rhythmically swaying props of the same material into oneInstancedMesh, computing transforms through a single pre-allocatedTHREE.Object3Ddummy outsidegame.onUpdate. - Hard Stereo Ceiling (
<= 200Draws,<= 300kTriangles): Reserve real-time shadows for the main directional light on a compact shadow frustum (512–1024), useMeshLambertMaterialor lightweightMeshStandardMaterial, and disableEffectComposer/ bloom automatically whengame.xr.activeis true. - World-Space UI Only: DOM overlays never appear inside a headset. Render wave counters, scoreboards, and interactive buttons with
game.xr.panel(...)(WorldPanel) placed 1.2–2.0 m from eye height.
Mathematical & Algorithmic Core
- Total Vertex Shading Work: $
C_draw ≈ N_unique\_materials × 2_eyes, T_frame = 2 Σ_i tris(M_i) · instances(M_i)$ - Phase-Staggered Instance Matrix Update: Update only active animated instances (
visibleCount), using deterministic trig phaseφ_i = i · 1.618without allocating per-step matrices or quaternions.
Engine Implementation
Batched Prop Instancer & World HUD (Assets/Game/vr-instanced-stage.ts)
import * as THREE from 'three';
import type { Game, WorldPanel } from 'ccgd';
export interface SwayPropBatch {
readonly mesh: THREE.InstancedMesh;
readonly count: number;
readonly baseX: Float32Array;
readonly baseY: Float32Array;
readonly baseZ: Float32Array;
readonly baseYaw: Float32Array;
readonly phase: Float32Array;
}
const _dummy = new THREE.Object3D();
const _tint = new THREE.Color();
export function createSwayPropBatch(
scene: THREE.Scene,
geometry: THREE.BufferGeometry,
material: THREE.Material,
positions: ReadonlyArray<readonly [number, number, number, number]>,
): SwayPropBatch {
const count = positions.length;
const mesh = new THREE.InstancedMesh(geometry, material, count);
mesh.castShadow = false;
mesh.receiveShadow = true;
const baseX = new Float32Array(count);
const baseY = new Float32Array(count);
const baseZ = new Float32Array(count);
const baseYaw = new Float32Array(count);
const phase = new Float32Array(count);
for (let i = 0; i < count; i++) {
const [x, y, z, yaw] = positions[i];
baseX[i] = x;
baseY[i] = y;
baseZ[i] = z;
baseYaw[i] = yaw;
phase[i] = i * 1.6180339;
_dummy.position.set(x, y, z);
_dummy.rotation.set(0, yaw, 0);
_dummy.scale.setScalar(1);
_dummy.updateMatrix();
mesh.setMatrixAt(i, _dummy.matrix);
// Subtle per-instance warmth variation with zero extra materials
_tint.setHSL(0.08 + (i % 5) * 0.012, 0.28, 0.52 + (i % 3) * 0.06);
mesh.setColorAt(i, _tint);
}
mesh.instanceMatrix.needsUpdate = true;
if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
scene.add(mesh);
return { mesh, count, baseX, baseY, baseZ, baseYaw, phase };
}
export function mountVrStageBudget(
game: Game,
batch: SwayPropBatch,
): { readonly scoreboard: WorldPanel; setScore: (value: number) => void } {
let score = 0;
const scoreboard = game.xr.panel({ width: 0.72, height: 0.34 });
scoreboard.object.position.set(0, 1.55, -2.2);
game.scene.add(scoreboard.object);
const redrawBoard = () => {
scoreboard.draw((p) => {
p.panel(0, 0, p.w, p.h);
p.label('Sanctuary Resonance', 32, 30);
p.text(String(score), 32, 92, { size: 112, font: 'display', color: 'accent' });
p.text(
game.xr.active ? 'WebXR Stereo Active' : 'Desktop Flat Mode',
32,
240,
{ size: 32, color: 'muted' },
);
});
};
redrawBoard();
game.xr.onEnter(() => redrawBoard());
game.xr.onExit(() => redrawBoard());
let time = 0;
game.onUpdate((dt) => {
time += dt;
for (let i = 0; i < batch.count; i++) {
const sway = Math.sin(time * 2.1 + batch.phase[i]) * 0.06;
_dummy.position.set(batch.baseX[i], batch.baseY[i], batch.baseZ[i]);
_dummy.rotation.set(sway, batch.baseYaw[i], sway * 0.5);
_dummy.scale.setScalar(1);
_dummy.updateMatrix();
batch.mesh.setMatrixAt(i, _dummy.matrix);
}
batch.mesh.instanceMatrix.needsUpdate = true;
});
return {
scoreboard,
setScore: (value: number) => {
score = value;
redrawBoard();
},
};
}
Headset & Desktop Budgets
- Redraw World Panels On Change Only: Calling
scoreboard.redraw()when scores or states change — never insidegame.onUpdate— avoids 60 Hz Canvas2D texture uploads over the WebXR bridge. - Keep Dynamic Shadows Narrow: Disable
castShadowon small instanced foliage/debris so the shadow pass renders only major architecture and gameplay landmarks.
Verification Checklist
- Inspect
game.renderer.info.render.callsduring an emulated headset run (vr-check) and confirm total draw calls stay well under200and triangles under300,000. - Toggle
xr.sim.enter()/xr.sim.exit()and verify theWorldPanelboard updates cleanly without overlapping HTML or headset errors.
Official references
- Meta Quest WebXR Frame Budget Guidelines
- Khronos WebGL 2 Instanced Drawing Specification
Playable Three.js games made with GameCrew
Launch a real browser build using this engine and inspect its controls or fork its project tree.
More Three.js techniques
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.
Raymarched Volumetric Clouds & Atmospheric Sky Shaders in Three.js (WebGL 2) →
Self-contained THREE.ShaderMaterial sky dome in GLSL ES 3.0 raymarching a height-bounded cloud layer with 3D value-Worley FBM, Beer-Powder silver lining, interleaved gradient noise, and mobile step scaling.
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.
Use verified techniques inside a real game
Describe your game idea for free or connect an MCP assistant to search and contribute techniques.
