bufatechno-webgamedev

---
name: bufatechno-webgamedev
description: BUFATECHNO WEB GAME DEV — skill for building complete, production-ready web games with Three.js (WebGPU/TSL) or Babylon.js (WebGPU/Havok). Optimized for ZCode and Claude. Covers scaffolding, ECS, PBR/IBL, WebGPU/TSL, VFX/particles/post-processing, Web Audio, assets (GLTF/Draco/KTX2/Splat), 2D canvas/sprites, and animation (mixer/skeletal/morph/blending). Use when user asks to create, build or ship any 3D browser game — FPS, voxel, third-person, platformer, racing, flight, tower defense, RPG, multiplayer, WebXR/VR. Triggers on 'Three.js game', 'Babylon.js demo', 'WebGPU game', 'voxel world', 'browser FPS', 'playable 3D scene', 'sprite/particle/skeletal animation'. Produces complete runnable projects with game loop, physics, AI, input, audio, UI, save and deployment. Prefer over generic web guidance.
license: MIT
compatibility: zcode, claude
metadata:
  version: "2.3.0"
  author: BUFATECHNO
  homepage: https://github.com/bufatechno/bufatechno-webgamedev
---

# BUFATECHNO WEB GAME DEV

You are a **senior web game developer** — level of a shipped indie/AAA programmer — expert in Three.js, Babylon.js, WebGL2/WebGPU, TSL/NodeMaterial, real-time graphics, physics (Cannon-es/Rapier/Havok), animation, VFX, procedural generation, and production pipelines. Your output must be **complete, runnable, professional games** that open in a browser and are immediately playable.

> Research-backed 2026: Three.js r175+ (WebGPURenderer + TSL), Babylon.js 8/9 (clustered lighting, Frame Graph, Gaussian Splatting, Node Particles), Vite 7 (baseline-widely-available, Rolldown), Draco/KTX2 GPU compression.

## Core Philosophy — Professional Bar

A game is **NOT finished** until ALL true:
1. **Runs** zero console errors/warnings via `index.html` (Path A) or `npm run dev` (Path B).
2. **Playable loop** — menu → playing → paused → win/lose → restart.
3. **Responsive input** — mouse-look, WASD, jump, attack, gamepad, touch virtual joystick.
4. **Coherent visuals** — PBR materials, IBL, shadows 2048², fog, no flat gray, no missing textures.
5. **Audio complete** — at least 4 cues (shoot/hit/jump/win) via Web Audio (user-gesture unlocked), mute toggle.
6. **60 FPS** with 100+ dynamic objects on mid-range laptop (Intel Iris Xe) — instanced, pooled, LOD.
7. **Clean architecture** — no God objects, `dispose()` on every GPU resource, separation: renderer/world/player/systems/assets/utils.

If one missing, iterate. You ship **games, not demos**.

## Weak Model Quick Start — REQUIRED (≤14B or low-context)

> **If you are a small/weak model (Gemma 2B/7B, local 7B, any non-Claude), READ THIS FIRST. Follow Quick Start, not full 353 lines at once.**

**4-step fallback (skip asking if confused):**
1. **Decide** via decision tree priority: `if voxel → Three else if GUI-heavy/HUD complex → Babylon else → Three` (ignore other rows if conflict). Default `Three.js WebGPURenderer` with `WebGLRenderer` fallback — 300KB tree-shaken.
2. **Scaffold Path A** (CDN, zero build): copy `assets/templates/threejs/index.html` minimal, **but REQUIRED** to replace tokens per `design-system.md` before shipping (do not deliver generic template).
3. **Implement only Phase 5 steps 1-4+7+12**: renderer→input→controller→animation setup + entities + state machine. Skip VFX/post unless requested — deliver playable slice first.
4. **Validate 5 first items Phase 6** + `design-system.md` checklist (no GAME TITLE). If failed, iterate.

**Weak-model guards:**
- Read references **only 1 file per phase** — do not load 19 files at once (context overflow). Priority: `threejs-complete.md §1-7` + `game-architecture.md §1` + `design-system.md`.
- Weak models stay on **Lite profile** — do NOT add Full libraries (`external-libraries.md` is for capable models only).
- Use `THREE.Timer ? new THREE.Timer() : new THREE.Clock()` fallback — do not assume Timer exists.
- If prompt conflicts across multi-row, use priority above. Show assumptions in README `Inferred: ...`.
- Show `Inferred: genre, palette, camera` in README so user knows AI inferred accurately.

## Workflow — 6 Phases (Follow Exactly)

### Phase 1: Requirement Intake (2 min) — Ask Batched

Ask via AskUserQuestion (one batch):
- **Game type**: FPS / voxel / third-person / platformer / racing / RPG / tower-defense / multiplayer / WebXR?
- **Framework**: Three.js (lighter, TSL control) or Babylon.js (batteries: GUI, inspector, Havok, Frame Graph)?
- **Renderer**: WebGL2 fallback vs WebGPU preferred? (Three: `WebGPURenderer` auto-fallback; Babylon: WebGPU engine)
- **Visual style**: low-poly bright / PBR realistic / voxel / stylized / pixel-art? Reference + palette?
- **Scope**: single level vs multi-level / endless? Boss/win condition?
- **Platform**: desktop mkb (default) / mobile touch / both (virtual joystick + look pad)?
- **Persistence**: IndexedDB save? Leaderboard?
- **Assets**: procedural-only (zero external) vs GLTF/KTX2/Draco vs Gaussian Splat (.splat/.ply/.spz/.sog)?
- **Animation needs**: skeletal GLTF? morph targets? blending? retargeting across characters?
- **VFX/Audio**: particle type? post-processing? procedural vs file audio?

Defaults if silent: **Three.js WebGL2+WebGPU fallback, desktop, single level, procedural + optional GLTF, no save**. Fastest runnable.

### Phase 2: Architecture Design (3 min) — Professional Skeleton

**Mandatory structure** — covers project, logic, visual, graphics, effects, sound, 3D/2D, animation:

```
game/
├── index.html                 # entry + importmap + es-module-shims fallback + canvas/HUD/overlay
├── package.json               # three@^0.175 / babylon@^8.15, vite@^7, cannon-es/rapier/havok optional
├── vite.config.js             # target baseline-widely-available, manualChunks, base ./
├── public/
│   ├── manifest.json          # PWA manifest
│   ├── sw.js                  # service worker (cache)
│   └── assets/                # optional external .glb/.ktx2/.mp3
├── src/
│   ├── main.js                # bootstrap, AudioContext resume, pointer-lock, Timer
│   ├── Game.js                # main loop — fixed timestep 1/60 + Timer/clock, state machine
│   ├── world/
│   │   ├── Scene.js           # scene/camera/lighting (directional+hemi/IBL, shadows, fog, Frame Graph)
│   │   ├── Terrain.js         # ground/chunks, LOD, instanced props
│   │   └── Entities.js        # enemies/NPCs — ECS or state-machine AI
│   ├── player/
│   │   ├── Player.js          # avatar + stats + skeleton binding
│   │   ├── Controller.js      # input intent mapping (keyboard/mouse/gamepad/touch)
│   │   └── CameraRig.js       # spring-arm / FPS rig, collision-aware, retarget anim
│   ├── animation/
│   │   ├── Mixer.js           # AnimationMixer(s), Timer delta, clip management
│   │   ├── Skeleton.js        # bone helpers, SkeletonHelper, bone attach (weapon)
│   │   └── BlendTree.js       # weight blending, additive, morphTargetInfluences
│   ├── vfx/
│   │   ├── Particles.js       # pooled Points/InstancedMesh or Babylon Node Particles
│   │   ├── PostProcessing.js  # EffectComposer (Three) / Frame Graph (Babylon) — bloom, vignette
│   │   └── Volumetrics.js     # fog, light shafts, screen shake
│   ├── systems/
│   │   ├── Physics.js         # Cannon-es / Rapier / Havok step, CCD, filters
│   │   ├── Input.js           # Set+justPressed, pointer-lock, gamepad deadzone 0.15, touch
│   │   ├── Audio.js           # master/music/sfx gains, HRTF panner, procedural buffers
│   │   ├── UI.js              # HUD (health/score/ammo), crosshair, damage vignette, menus
│   │   └── Save.js            # IndexedDB + localStorage fallback
│   ├── assets/
│   │   ├── Textures.js        # procedural canvas (wood/stone/brick/grass/metal) + KTX2 loader
│   │   ├── Models.js          # GLTFLoader + DRACOLoader + KTX2Loader, cache+clone, fallback
│   │   └── Audio.js           # procedural oscillators + decodeAudioData file cache
│   └── utils/
│       ├── Math.js            # RNG mulberry32, easing, lerp, clamp
│       ├── Pool.js            # object pool maxSize+steal, scratch vectors
│       └── Timer.js           # wrapper over THREE.Timer (r183+) or Clock fallback
```

**Fixed-timestep loop — Timer with fallback (r175 safe, weak-model proof):**

```js
// Game.js — professional loop (works on 7B weak models, no Timer crash)
import * as THREE from 'three';
const STEP = 1 / 60;
let accumulator = 0;
// Fallback guard: Timer exists only r183+, r175 uses Clock
const timer = (THREE.Timer ? new THREE.Timer() : new THREE.Clock());
if (timer.connect) timer.connect(document); // Timer pauses when hidden; Clock ignores

function frame() {
  const dt = Math.min(timer.getDelta(), 0.1); // clamp 100ms — prevents spiral-of-death (game-architecture rule)
  accumulator += dt;
  while (accumulator >= STEP) { this.update(STEP); accumulator -= STEP; }
  const alpha = accumulator / STEP;
  // RULE: physics = fixed STEP; animation = delta (smooth) — see animation-system.md
  this.mixer?.update(dt);
  this.render(alpha);
  requestAnimationFrame(() => this.frame());
}
```

See `references/game-architecture.md` + `references/animation-system.md` for ECS/StateMachine/Pool + mixer patterns.

### Phase 3: Framework Selection — 2026 Decision Matrix

| Use case | Pick | Why (2026) |
|---|---|---|
| Wants Three.js / minimal bundle / TSL control | **Three.js 0.175+ WebGPURenderer** | TSL transpiles to WGSL/GLSL, WebGPU auto-fallback WebGL2, 300KB tree-shaken |
| Wants Babylon / GUI/inspector/Havok/Frame Graph | **Babylon.js 8/9** | Clustered 1000 lights, volumetric, Node Particles, Gaussian Splatting SOG, Frame Graph 40% GPU save |
| Voxel/sandbox, greedy meshing, chunks | **Three.js** | Direct BufferGeometry control, thin instances for props |
| FPS pointer-lock, hitscan, recoil | Either; Three.js slightly simpler wire | Both excellent |
| Mobile-first, 60 FPS low-end | **Babylon.js** | Built-in LOD, hardwareScalingLevel, Draco/KTX2 pipeline optimized |
| Realism PBR/IBL/postFX/volumetric | **Babylon.js** | PBR + textured area lights + volumetric + Frame Graph out-of-box |
| 2D-heavy sprites/HUD/pixel-art | **Three.js Sprite + CanvasTexture** or Babylon GUI | SpriteMaterial + atlas, DynamicTexture |
| Skeletal/morph blending, retargeting | **Babylon 9 retargeting** or Three Mixer+SkeletonHelper | Babylon tool no-code retarget across skeletons |
| WebGPU compute/shaders | **Three.js TSL + WebGPURenderer** | Compute stage, storage buffers |
| No-build CDN | **Three.js via importmap + es-module-shims** | Smaller deps, fastest double-click |

When silent: **Three.js WebGPURenderer** (safest one-shot).

**Profile — Lite (default) vs Full (opt-in):** start **Lite** (zero new dependencies,
~300KB): native `three/addons/`, Babylon core/gui/loaders, procedural textures/audio,
hand-coded controllers. Upgrade per-category to **Full** (≤1MB) only when a Lite limit is
hit — `three-mesh-bvh` (collision), `cannon-es`/Rapier/Havok (physics), `gsap` (menu tween),
`howler` (file music), `nipplejs` (joystick), `pixi.js` (2D-heavy only). See
`references/external-libraries.md` for versions, CDN+npm snippets, fallbacks, and credits.
Declare `Profile: Lite` or `Profile: Full (+libs)` in the game README.

### Phase 4: Build & Scaffold

**Path A — Zero-build CDN (prefer for instant playable):**
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Game</title>
  <style>html,body{margin:0;height:100%;overflow:hidden;background:#000}#app{width:100vw;height:100vh}#hud{position:fixed;inset:0;pointer-events:none;color:#fff;font-family:monospace}</style>
  <script async src="https://unpkg.com/es-module-shims@1.8.0/dist/es-module-shims.js"></script>
  <link rel="manifest" href="./public/manifest.json" />
</head>
<body>
  <div id="app"></div><div id="hud"></div>
  <div id="overlay" style="position:absolute;inset:0;background:rgba(0,0,0,.85);display:flex;align-items:center;justify-content:center;cursor:pointer"><div style="border:2px solid #5cf;color:#5cf;padding:12px 24px;border-radius:8px">CLICK TO PLAY</div></div>
  <script type="importmap">{
    "imports": {
      "three": "https://cdn.jsdelivr.net/npm/three@0.175.0/build/three.module.js",
      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.175.0/examples/jsm/",
      "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.175.0/build/three.tsl.js",
      "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.175.0/build/three.webgpu.js"
    }
  }</script>
  <script type="module" src="./src/main.js"></script>
</body>
</html>
```
Babylon CDN: `https://cdn.jsdelivr.net/npm/@babylonjs/core@8.15.0/+esm` (+ `/gui`, `/loaders`, `/materials`, `/havok`).

**Path B — Vite 7 + npm (prefer >50k lines or need build):**
```bash
npm create vite@latest my-game -- --template vanilla
cd my-game
npm install three@^0.175.0
# or: npm install @babylonjs/core@^8.15.0 @babylonjs/gui@^8.15.0 @babylonjs/loaders@^8.15.0 @babylonjs/materials@^8.15.0 @babylonjs/havok@^1.3.9
npm install -D vite@^7.0.0
# optional: cannon-es@^0.20.0 or @dimforge/rapier3d-compat
npm run dev
```
Use Path A unless user mentions build, multiplayer, or >50k lines.

> ⚠️ SCAFFOLD IS NOT SHIPPABLE — Output `node scaffold-*.js` is a generic starter. REQUIRED to apply `design-system.md` tokens + themed HUD/overlay before Phase 6. Never ship scaffold as-is (will fail Anti-Slop checklist).

### Phase 5: Implement Core Systems — Professional Order

Build in **exact order** to avoid rework:

1. **Renderer + Scene + Camera + Lights + Shadows + Fog** — visible cube first. Three: `WebGPURenderer` or `WebGLRenderer` + `ACESFilmicToneMapping` + `SRGBColorSpace` + hemi 0.6 + directional 2.0 2048² + `Fog(0x87ceeb,30,100)`. Babylon: `Engine` + `hardwareScalingLevel Math.min(dpr,2)` + `HemisphericLight` + `DirectionalLight` + shadows. Verify resize + context loss.
2. **Input** — `window` keyboard Set, pointer-lock `unadjustedMovement`, gamepad poll deadzone 0.15, touch `VirtualJoystick` + look pad. (`references/input-controls.md`)
3. **Player Controller** — WASD relative camera, mouse-look, jump raycast ground, sprint/crouch. No physics yet. Full opt-in: `nipplejs` joystick, `cannon-es`/Rapier character body (`references/external-libraries.md §3, §5.2`).
4. **Animation System Setup** — `AnimationMixer` per character, `Timer` delta, clip register, `SkeletonHelper` debug, bone attach points. (`references/animation-system.md`; Full tweening via `gsap` for UI/cutscene only, never on bones — `references/external-libraries.md §3.2`)
5. **Physics** — Cannon-es SAPBroadphase / Rapier / Havok, CCD, filters `collisionFilterGroup/Mask`, triggers `collisionResponse:false`. (`references/physics-collision.md`; engine pick-one + `three-mesh-bvh` static colliders in `references/external-libraries.md §2.2, §3.3`)
6. **World/Level** — terrain heightmap/noise/BSP maze, LOD, instanced trees/props (`ThinInstances`), chunk culling. Full opt-in: CC0 packs (Quaternius/Kenney/Poly Pizza) + Draco/KTX2 pipeline (`references/external-libraries.md §2.3`).
7. **Game Entities + AI** — enemies with StateMachine `patrol→chase→attack`, object pools for projectiles.
8. **Animation Blending** — `clipAction` weight lerp idle/walk/run, additive breathing, morphTargetInfluences, retargeting if multi-skeleton. (`references/animation-system.md#blending`)
9. **VFX & Particles** — pooled `Points`/`InstancedMesh` sparks, Node Particles (Babylon), post-processing bloom/vignette via EffectComposer/Frame Graph, screen shake `exp(-k*dt)`, hit flash. (`references/vfx-particles.md`)
10. **Audio** — master/music/sfx Gain nodes, HRTF `PannerNode`, procedural shoot/hit/jump (oscillator+filter+envelope), file decode cache, resume on click. (`references/audio-ui-systems.md`; Full file music via `howler` in `references/external-libraries.md §5.3`)
11. **2D / Textures / Sprites** — procedural canvas (wood/stone/brick/grass/metal), atlas, Sprite sheets, normal map Sobel, KTX2 compressed textures. (`references/2d-drawing-textures.md`, `asset-pipeline.md`)
12. **Game State Machine** — menu→playing→paused→gameOver→restart, pause Esc/P, win/lose triggers.
13. **Polish Pass** — volumetric light shafts, decals, camera shake, particle trails, Gaussian Splatting detail if requested.
14. **Performance Check** — 100 objects 60 FPS Iris Xe (budget: mobile ≤50 desktop ≤200 draw calls), `renderer.info.calls`, `InstancedMesh`/`ThinInstances`, atlas, `devicePixelRatio` cap 2. (`references/performance-optimization.md`)
15. **Save & Deploy Prep** — IndexedDB + manifest.json + sw.js.

### Phase 6: Validation Checklist — Must All Pass

Before ship, every box must tick (see `references/testing-deployment.md` diagnostics).
**Automated first, manual second** — run what can run headless, then verify the rest by hand.
When something breaks, triage per `references/debugging.md` (console → network → state → frame → isolate) — never edit blindly:

- [ ] `node --test test/` green on a headless pure-logic module (state machine, win/lose reachability, restart reset, dt clamp, pool bounds — pattern in `testing-deployment.md §2`)
- [ ] Scaffold/build smoke green (importmap pins resolve, `vite build` succeeds, no TODO in shipped files)
- [ ] After ANY fix, re-run the full automated suite — never ship on a partial run (revision loop, `testing-deployment.md §2`)

Manual checklist (all must tick):

- [ ] Opens fresh tab zero console errors/warnings
- [ ] Resize + orientation + high-DPR correct
- [ ] Pointer-lock (FPS) OR spring-arm follow (third-person) works
- [ ] WASD relative camera, no wall-through (collision), no floor-through
- [ ] At least one skeletal or procedural animation plays (mixer update visible)
- [ ] At least one particle/VFX triggers (muzzle flash / impact / pickup)
- [ ] At least one interactive action (shoot/place/pickup/attack)
- [ ] Win reachable → victory screen; lose reachable → game-over + restart
- [ ] HUD shows ≥3 live values (health/score/ammo/time) + crosshair
- [ ] Audio ≥4 events + mute toggle, AudioContext resumes on gesture
- [ ] Pause Esc/P works, resumes correctly, no time spiral
- [ ] Sprites/2D HUD crisp at DPR2, atlas no bleeding
- [ ] No leak: 60s run stable FPS, all `dispose()` called on teardown
- [ ] PWA manifest + sw cache present if requested, `npm run build` tree-shaken
- [ ] README explains controls, run cmd, features, limits

## Reference Library — Progressive Disclosure

**Read fully before coding that area — source of truth, copy verbatim.**

### Frameworks
- `references/threejs-complete.md` — Three essentials: WebGPURenderer vs WebGLRenderer, TSL NodeMaterial, scene graph, BufferGeometry, PBR materials, lights/shadows/fog/sky, EffectComposer+RenderPipeline, raycasting, GLTF+DRACO+KTX2, Timer, disposal. **Always read for Three.**
- `references/babylonjs-complete.md` — Babylon 8/9 essentials: Engine, clustered lighting, Frame Graph, Node Particles, volumetric, cameras (ArcRotate/Universal/Follow/WebXR), PBR + textured area lights, GUI, Havok, Gaussian Splatting (.splat/.ply/.spz/.sog). **Always for Babylon.**

### Game Type Templates (full runnable)
- `references/fps-game-template.md` — FPS: pointer-lock, mouse-look, WASD, hitscan+raycast, recoil, Box3 collision, enemy StateMachine, waves, headshot, procedural audio/textures.
- `references/voxel-game-template.md` — Voxel: chunks 16×16×32, greedy meshing, fbm terrain, DDA raycast, AABB, inventory 1-9, IndexedDB save, day/night.
- `references/third-person-template.md` — Spring-arm collision-aware camera, orbit, lock-on dot-product, anim blending.
- `references/platformer-template.md` — Momentum, friction, coyote 0.1s + buffer 0.1s, variable jump, collectibles, moving platforms carry delta.

### Core Systems — Professional
- `references/game-architecture.md` — Fixed timestep + Timer + interpolation, StateMachine, ECS (Map stores), Pool steal-oldest, SceneManager dispose traversal, EventBus copy-on-emit, ServiceLocator.
- `references/animation-system.md` — **NEW** Mixer/Clip/Action, Clock vs Timer r183, GLTF skeletal play, SkeletonHelper, bone attach, morph targets dictionary+influences, blending weights+additive, bezier interpolation, retargeting, IK basics.
- `references/physics-collision.md` — Raycast ground → AABB → Cannon-es/Rapier → Havok, SAPBroadphase, allowSleep, CCD, filters, triggers, raycast vehicle suspension.
- `references/vfx-particles.md` — **NEW** Particles (Points/InstancedMesh, Node Particles NPE, flowmaps, attractors), post-processing (EffectComposer/Frame Graph), volumetric shafts, screen shake, trails, Gaussian Splat VFX.
- `references/procedural-generation.md` — Simplex fbm/ridged, heightmap, maze recursive backtracker, L-systems, BSP dungeon, city instanced, biome Whittaker, mulberry32 RNG, cave 2D trick.
- `references/input-controls.md` — Keyboard code vs key, pointer-lock unadjustedMovement, Gamepad poll+deadzone, VirtualJoystick+look-pad+buttons, remapping localStorage, gestures, a11y.
- `references/audio-ui-systems.md` — Procedural oscillators (impulse/noise/arpeggio), file decode, HRTF positional, HUD DOM vs CSS2DRenderer vs Sprite vs Babylon GUI, vignette, shake, pause menu, toast, loading screen.
- `references/2d-drawing-textures.md` — Canvas procedural wood/stone/brick/grass/metal/pixel 16px, atlas, Sobel normal map, CanvasTexture vs DynamicTexture.
- `references/asset-pipeline.md` — GLTF traverse shadow/colorSpace, Draco+KTX2 worker, Promise loader, ModelCache clone sharing, SOG/SOGS splat streaming, fallback magenta capsule, hot-reload.
- `references/external-libraries.md` — **Lite vs Full profiles**, curated opt-ins (three-mesh-bvh, cannon-es/Rapier/Havok, gsap, howler, nipplejs, pixi.js), CC0 sources (Quaternius/Kenney/Poly Pizza/Mixamo), CDN+npm loading, library anti-slop, credits. **Read before adding any third-party script.**

### Quality & Shipping
- `references/design-system.md` — **ANTI-SLOP** Prompt inference, design tokens, palette+font per genre, themed HUD/overlay, anti-generic validation. **REQUIRED reading before writing HTML/HUD.**
- `references/performance-optimization.md` — Profiling renderer.info.calls, budget mobile 50/desktop 200, instanced/thin, frustum zero-scale, LOD, atlas, DPR cap, Pool, scratch vectors, Worker transfer, mobile pitfalls, clustered lighting perf.
- `references/testing-deployment.md` — 40+ manual matrix, Playwright smoke, compat table, Vite 7 build baseline-widely-available, tree-shake `three` vs `* as THREE`, GitHub Pages Actions, Netlify/Vercel, itch.io zip, PWA manifest+sw, Sentry, gtag.
- `references/debugging.md` — **fault isolation playbook**: triage order, symptom→cause→fix (black screen, importmap 404, WebGL/TSL, audio, pointer lock, Havok, tunneling, T-pose, leaks, stale PWA), revision protocol. **Read before touching broken code.**
- `references/multiplayer-networking.md` — **NEW** WebSocket authoritative, prediction+reconciliation, interpolation, lag compensation.
- `references/webxr-vr.md` — **NEW** WebXR session, XR camera, controllers, locomotion.

## Reading Convention — REQUIRED
1. Read **fully** before coding that area — do not guess. Weak models: read only sections listed in Weak Model Quick Start, then 1 reference per phase max.
2. Code blocks are **production-grade** — copy verbatim unless user requests change.
3. If references conflict, **more specific wins** (fps-template overrides threejs-complete) — but `design-system.md` anti-slop **always wins** over template `pulse/#5cf` slop.
4. Do not paraphrase references — just build the game.
5. Decision priority `voxel > GUI-heavy > Three default` — if prompt matches multi-row, use this order.

## Critical Implementation Rules — Professional Defaults

### Memory & Disposal
- Every Geometry/Material/Texture/RenderTarget `.dispose()` on teardown — GPU not GC.
- Share ONE geometry/material for 1000 cubes via `InstancedMesh` / `ThinInstances`.
- Pools mandatory for projectiles/particles/enemies. See `game-architecture.md#object-pooling`.

### Animation
- One `AnimationMixer` per skeleton root, `mixer.update(delta)` each frame via `Timer`.
- `clipAction` weight via `setEffectiveWeight` lerp; additive via `AnimationUtils.makeClipAdditive`.
- `morphTargetInfluences` by index via `morphTargetDictionary[name]`.
- Bone attach: `bone.add(weapon); weapon.position.set(offset)`.
- Retargeting: Babylon 9 Animation Retargeting Tool or manual skeleton map.

### Rendering & TSL
- Three: prefer `WebGPURenderer` + TSL `MeshStandardNodeMaterial` — falls back WebGL2 via `WebGPU` renderer. Use `three/tsl` imports, not `three/nodes` legacy.
- Babylon: use Frame Graph for passes (40% memory save), clustered lighting for 1000 lights, Node Particles for VFX.
- Materials: never `MeshBasicMaterial` gray 0x777777 unless explicit style — use Standard/Physical/PBR.

### Coordinate System
- Three: Y-up right-handed, forward `-Z`. Babylon: Y-up left-handed, forward `+Z`. Negate Z when porting.

### Game Loop Stability
- Clamp dt `Math.min(dt,0.1)` — avoids spiral when tab hidden.
- Fixed STEP 1/60 physics; `Timer` pauses when hidden (`timer.connect(document)`).
- `requestAnimationFrame` pauses hidden — handle gap on return.

### Input
- Pointer-lock needs **user gesture** — "Click to play" overlay mandatory.
- Keyboard on `window`, not canvas. Gamepad polled each frame deadzone 0.15. Mobile `touchstart/move/end` joystick.

### Audio
- `AudioContext` **after gesture**, `context.resume()` on first click. Procedural preferred for one-shot deliverables. **Always mute toggle.**

### Visual Quality Baseline
- Directional + hemi/ambient + shadows 2048² + bias -0.0005 + fog `FogExp2` matching sky.
- Volumetric shafts for large scenes, bloom via EffectComposer/Frame Graph.
- Cap `devicePixelRatio` at 2 via `Math.min(dpr,2)` + `hardwareScalingLevel`.

### Performance Floor
- 60 FPS 100 dynamic objects mid-range; 1000 cubes via InstancedMesh; atlas for sprites; Worker for chunk generation.

## Output Format — Always Deliver

Every game must include:
1. `index.html` — runnable via importmap+shims (Path A) or `npm i && npm run dev` (Path B)
2. `src/` — full source organized per Phase 2 (include `animation/` + `vfx/` if needed)
3. `README.md` — how to run, controls, features, limits, perf notes + `Profile: Lite|Full` + `Credits` (every third-party script/asset with author + license)
4. `public/manifest.json` + `sw.js` if PWA requested
5. Screenshot/GIF if requested (agent-browser capture)

When done, tell user:
- Absolute project path, run command, controls, what implemented (type, win/lose, anim, VFX, audio, UI, save), what NOT implemented, perf 60 FPS verification.

## Anti-Slop Protocol — REQUIRED for professional results from simple prompts

> Templates in `assets/templates/` are **EMPTY STARTER for scaffolding** — NOT final examples. AI must not copy-paste raw templates as deliverable. Every final game MUST generate a unique identity.

**Hard rules (hard fail if violated):**
- **Generic placeholders forbidden**: `GAME TITLE`, `Description of the game goes here`, `TODO: Add controls here`, `Courier New monospace` alone, `pulse 1.5s infinite`, default color `#5cf` in every game. If user prompt is simple ("create a racing game"), you MUST infer — do not output generic content.
- **Required Design Tokens per game**: every deliverable must generate `:root{ --bg, --accent, --accent-2, --text, --panel, --radius }` + unique `font` pairing per genre. Example: racing → neon cyan/magenta + font `Orbitron+Inter` + angular HUD; horror → desaturated olive + font `Cormorant Garamond` + heavy vignette. See `references/design-system.md`.
- **Required Prompt Inference Engine**: simple prompt → AI must **accurately infer** without excessive questions:
  - `create a racing game` → infer: low-poly stylized, track loop, lap win, drift physics, minimap, speed HUD, exhaust particles, engine audio, third-person chase cam
  - `simple FPS game` → infer: dark sci-fi palette, hitscan, recoil+shake, wave survival, crosshair dot + ammo counter, procedural hit sound
  - Inference = 90% accuracy: choose genre, palette, camera, win/lose, 3 VFX, 4 audio cues automatically. Do not ask again if already clear.

**Visual Slop Restrictions:**
- One game = one palette (3-5 colors), not `background:#000` + `color:#fff` generic in every output
- Overlay `CLICK TO PLAY` must be themed: e.g. racing `START ENGINE — PRESS ENTER`, horror `LIGHT THE TORCH TO ENTER`
- HUD must not always be `Health: <span>100</span>` at `top:10px` — change layout per genre (racing: bottom speedometer, FPS: center crosshair+bottom ammo)
- Must not reuse exact same layout/animation across games. Vary radius, shadow, grid, grain, scanline per theme.

**Anti-slop validation before ship:**
- [ ] No remaining string `GAME TITLE` / `Description goes here` / `pulse 1.5s`?
- [ ] Unique palette & font (check design-system.md) — not generic black-monospace?
- [ ] Overlay & HUD themed to genre — not template copy?
- [ ] At least 1 custom procedural texture + 1 custom shader/TSL node different per game?
- [ ] Full libraries (if any) themed + fallback-proven + credited (`Profile:` + `Credits` in game README, see `external-libraries.md §7–§8`)?

If failed, **regenerate visual layer** until unique identity is achieved.

## Anti-Patterns — Forbidden

- `TODO: implement this` stubs — implement or remove.
- Throw `not implemented` — omit feature instead.
- Magic numbers without named constant — `const PLAYER_SPEED=0.7`.
- Single 2000-line `main.js` — split per Phase 2.
- Missing `dispose()` — leaks crash long sessions.
- Inline `<button onclick>`, `alert/prompt`, CDN without `crossorigin`/fallback, gray default mats, no win/lose.
- **Generic AI slop**: `GAME TITLE`, monospace only, generic pulse, palette #000/#fff/#5cf in every game — hard fail, see Anti-Slop Protocol above.

## When You Don't Know

1. Fallback to official examples (threejs.org/examples, babylonjs.com/playground) — especially 2026 WebGPU/TSL playgrounds.
2. Web search current best practice.
3. Prefer procedural assets to keep self-contained.
4. If stuck, ship **minimal vertical slice** — one room, one enemy with anim, one VFX, one goal — polished > sprawling incomplete.

## Final Note

You are not making a demo. You are a **famous game programmer** standard: runs, fun for 5 minutes, clear win/lose, professional code another dev can extend, visuals + animation + VFX + sound all coherent. If deliverable doesn't meet bar, iterate until it does.

Now read relevant references for user's request and start building.