# The YokoCoder:4B Master Guide to HTML/CSS/JS (2D Canvas) & Three.js (3D WebGL) Video Game Engineering

This guide serves both as a **reference manual for game developers** and as a **core architectural specification distilled into the `YokoCoder:4B` dataset**. Every pattern below is engineered to eliminate the most common failure modes in browser-based 2D and 3D games—such as `ReferenceError: dt is not defined`, stacked `requestAnimationFrame` loops, variable-framerate physics drift, hitbox mismatches, and Three.js memory leaks.

---

## 1. Single-File HTML/CSS/JS Game Architecture

A production-quality single-file HTML game must be 100% self-contained (zero external image or audio file dependencies that could fail to load via CORS) and strictly ordered into five deterministic layers inside `<script>`:

```text
┌──────────────────────────────────────────────────────────────────────┐
│ 1. CONFIGURATION & CONSTANTS (Immutable tuning parameters, colors)   │
├──────────────────────────────────────────────────────────────────────┤
│ 2. RUNTIME STATE & INPUT REGISTRY (Single source of truth, lexical)  │
├──────────────────────────────────────────────────────────────────────┤
│ 3. PROCEDURAL ASSETS & WEB AUDIO SYNTH (Lazy AudioContext, sprites)  │
├──────────────────────────────────────────────────────────────────────┤
│ 4. PURE UPDATE(dt) & COLLISION SOLVERS (Deterministic math, no DOM)  │
├──────────────────────────────────────────────────────────────────────┤
│ 5. RENDER(dt, alpha) & RAF SCHEDULER (Canvas/WebGL draw, single loop)│
└──────────────────────────────────────────────────────────────────────┘
```

### 1.1 The Responsive Canvas Shell (Smooth Vector vs. Crisp Pixel Art)

Always prevent mobile pinch-zoom, double-tap selection, and Space/Arrow page scrolling:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <title>YokoCoder Arcade Engine</title>
  <style>
    *, *::before, *::after {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
      user-select: none;
      -webkit-user-select: none;
    }
    html, body {
      width: 100%;
      height: 100%;
      overflow: hidden;
      background: #0b0f19;
      display: flex;
      align-items: center;
      justify-content: center;
      font-family: system-ui, -apple-system, sans-serif;
      touch-action: none;
    }
    canvas {
      display: block;
      touch-action: none;
      box-shadow: 0 20px 50px rgba(0, 0, 0, 0.7);
      /* Enable for low-res 8-bit pixel art games: */
      /* image-rendering: pixelated; image-rendering: crisp-edges; */
    }
  </style>
</head>
<body>
  <canvas id="game"></canvas>
  <script>
    // Game engine code goes here
  </script>
</body>
</html>
```

### 1.2 HiDPI Scaling for Vector Games vs. Integer Scaling for Pixel Art

- **Smooth Vector Games (`400x600` logical space)**:
  Scale the physical canvas backing store by `dpr = Math.min(window.devicePixelRatio || 1, 2)` and call `ctx.setTransform(dpr, 0, 0, dpr, 0, 0)` so all game logic uses fixed logical coordinates (`W = 400`, `H = 600`) regardless of screen resolution.
- **Native Pixel-Art Games (`144x256` or `160x288` logical buffer)**:
  Keep `canvas.width = 144` and `canvas.height = 256`, set `ctx.imageSmoothingEnabled = false`, and scale the CSS width/height by an integer multiplier `scale = Math.max(1, Math.floor(Math.min(window.innerWidth / 144, window.innerHeight / 256)))`.

---

## 2. The Golden Game Loop & Why `ReferenceError: dt is not defined` Happens

### 2.1 Root Cause of `Uncaught ReferenceError: dt is not defined`

One of the most frequent bugs generated by small coding models is computing `const dt = ...` as a block-scoped local variable inside `loop(now)`, and then referencing `dt` inside `draw()` or `update()` **without passing `dt` as a function parameter**:

```javascript
// ❌ BROKEN: dt is block-scoped inside loop(), so draw() throws ReferenceError!
function draw() {
  wingPhase += dt * 10; // 💥 Uncaught ReferenceError: dt is not defined
}
function loop(now) {
  const dt = Math.min(0.1, (now - lastTime) / 1000);
  lastTime = now;
  update(dt);
  draw(); // ❌ Forgot to pass dt!
  requestAnimationFrame(loop);
}
```

### 2.2 The Invariant Fix: Explicit `update(dt)` and `draw(dt)` Signatures + Fixed-Step Accumulator

To guarantee that `dt` is **never** undefined and physics is **100% identical on 60Hz, 120Hz, 144Hz, and 240Hz monitors**:
1. Declare timing variables (`lastTime`, `accumulator`, `rafId`) in the module scope before `loop`.
2. Guard the first frame (`if (!lastTime) lastTime = now;`) so `now - lastTime` is never `NaN` or huge on startup.
3. Clamp `frameDt = Math.min(0.1, Math.max(0, (now - lastTime) / 1000))` so switching browser tabs never causes physics tunneling.
4. Step physics in fixed `FIXED_DT = 1 / 120` increments and pass `FIXED_DT` explicitly into `update(dt)` and `frameDt` explicitly into `draw(dt)`.

```javascript
const FIXED_DT = 1 / 120;
let lastTime = 0;
let accumulator = 0;
let rafId = null;

function update(dt = FIXED_DT) {
  // Pure physics & collision using explicit parameter `dt`
}

function draw(dt = FIXED_DT, alpha = 1) {
  // Visual animation timers (wing flap, particles, shaders) use explicit `dt`
}

function loop(now = performance.now()) {
  rafId = requestAnimationFrame(loop);

  if (lastTime === 0) lastTime = now;
  const frameDt = Math.min(0.1, Math.max(0, (now - lastTime) / 1000));
  lastTime = now;

  accumulator += frameDt;
  while (accumulator >= FIXED_DT) {
    update(FIXED_DT);
    accumulator -= FIXED_DT;
  }

  draw(frameDt, accumulator / FIXED_DT);
}

// Start the single persistent RAF loop once:
rafId = requestAnimationFrame(loop);
```

---

## 3. State Machine & Input Discipline

### 3.1 Never Spawn Duplicate `requestAnimationFrame` Loops on Restart

A classic bug occurs when `startGame()` or `resetGame()` calls `loop()` while a previous `requestAnimationFrame(loop)` is still running—doubling or tripling game speed after every death!

**Rule**: Either keep **one persistent `requestAnimationFrame` loop** running across all states (`READY`, `PLAYING`, `GAMEOVER`) and branch on `state` inside `update(dt)`, OR always call `if (rafId !== null) cancelAnimationFrame(rafId);` before scheduling a new frame.

### 3.2 Time-Based Game-Over Grace Period (Never Use `frames % 10 === 0`!)

Checking `if (frames % 10 === 0)` inside a click/keydown handler to "debounce" restarts drops **90% of user clicks** because input events fire asynchronously relative to frame ticks! Instead, track a time-based cooldown `gameOverLockTimer`:

```javascript
const STATE = { READY: 'READY', PLAYING: 'PLAYING', GAMEOVER: 'GAMEOVER' };
let state = STATE.READY;
let gameOverLockTimer = 0; // Seconds remaining before restart input is accepted

function enterGameOver() {
  if (state === STATE.GAMEOVER) return;
  state = STATE.GAMEOVER;
  gameOverLockTimer = 0.35; // 350ms grace period prevents accidental instant skip
  bestScore = Math.max(bestScore, score);
  saveHighScore(bestScore);
}

function handleAction() {
  if (state === STATE.READY) {
    resetMatch();
    state = STATE.PLAYING;
    bird.flap();
  } else if (state === STATE.PLAYING) {
    bird.flap();
  } else if (state === STATE.GAMEOVER && gameOverLockTimer <= 0) {
    resetMatch();
    state = STATE.PLAYING;
    bird.flap();
  }
}
```

---

## 4. 2D Collision Detection Mathematics

### 4.1 AABB vs. AABB (Axis-Aligned Bounding Box)

Two rectangles $A = (x_A, y_A, w_A, h_A)$ and $B = (x_B, y_B, w_B, h_B)$ intersect if and only if projections on both axes overlap:

```javascript
function aabbOverlap(ax, ay, aw, ah, bx, by, bw, bh) {
  return ax < bx + bw && ax + aw > bx && ay < by + bh && ay + ah > by;
}
```

### 4.2 Forgiving Circle-vs-AABB Collision (Ideal for Rotating Sprites & Birds)

When a sprite rotates visually (like the Flappy Bird tilting between $-25^\circ$ and $+90^\circ$), an axis-aligned rectangle has sharp invisible corners that feel unfair to players. A **circle** of center $(c_x, c_y)$ and radius $r$ is invariant under rotation. Clamp $(c_x, c_y)$ to the rectangle $[x, x+w] \times [y, y+h]$ to find the closest point $(p_x, p_y)$:

```javascript
function circleIntersectsAABB(cx, cy, r, rx, ry, rw, rh) {
  const closestX = Math.max(rx, Math.min(cx, rx + rw));
  const closestY = Math.max(ry, Math.min(cy, ry + rh));
  const dx = cx - closestX;
  const dy = cy - closestY;
  return (dx * dx + dy * dy) < (r * r);
}
```

### 4.3 Preventing the "Fly Over Top Pipe" Bypass Bug

In scrolling obstacle games, if the player flaps near $y = 0$ and the pipe collision check only tests `bird.y < pipe.top` while `bird.y` is allowed to go negative (or if top pipe caps start at $y = 0$), always:
1. Clamp the player ceiling: `if (bird.y - bird.r < 0) { bird.y = bird.r; bird.vy = 0; }`, **and**
2. Treat any horizontal overlap with a pipe while `bird.y - bird.r < pipe.gapTop` as a collision, even if `bird.y < 0`.

---

## 5. Three.js 3D Game Engineering Guide

### 5.1 Modern Import Map & Scene Setup

Use ES Module Import Maps or explicit CDN script tags with a locked Three.js version (`0.160.0`) so `THREE` is reliably available without a bundler:

```html
<script type="importmap">
{
  "imports": {
    "three": "https://unpkg.com/three@0.160.0/build/three.module.js",
    "three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/"
  }
}
</script>
<script type="module">
import * as THREE from 'three';
</script>
```

### 5.2 Preventing the Three.js "Black Screen" Bug

Four mistakes cause a blank or black Three.js canvas:
1. **Using `MeshStandardMaterial` or `MeshPhysicalMaterial` without lights**: PBR materials require at least an ambient/hemisphere light (`THREE.HemisphereLight`) and a directional/point light (`THREE.DirectionalLight`). Only `MeshBasicMaterial` renders without lights.
2. **Camera inside the geometry or looking the wrong way**: Always set `camera.position.set(x, y, z)` and `camera.lookAt(targetX, targetY, targetZ)` explicitly.
3. **Zero-height container**: Ensure `html, body { width: 100%; height: 100%; margin: 0; }` and size the renderer via `renderer.setSize(window.innerWidth, window.innerHeight)`.
4. **Missing `camera.updateProjectionMatrix()` on resize**:

```javascript
window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});
```

### 5.3 Hierarchical Joint Rigging (`THREE.Group` Pivot Pattern)

By default, Three.js primitives (`BoxGeometry`, `CylinderGeometry`) rotate around their geometric center $(0, 0, 0)$. To animate limbs, wings, or doors around a **joint hinge** (shoulder, hip, wing root):
1. Create a `const joint = new THREE.Group()` positioned at the hinge coordinates on the parent body.
2. Create the limb mesh and offset its local position by half its length (`limbMesh.position.y = -limbLength / 2`).
3. Rotate `joint.rotation.x`—never the offset child mesh directly!

### 5.4 Preventing WebGL GPU Memory Leaks (`dispose()` Lifecycle)

Unlike JavaScript objects, Three.js `BufferGeometry`, `Material`, and `Texture` instances allocate GPU buffers in WebGL that are **not** freed by the browser's garbage collector when removed from a `Scene`.
- **Rule 1**: Pre-allocate shared geometries and materials once at startup and reuse them across spawned obstacles, bullets, and particles (`const sharedPipeGeo = new THREE.CylinderGeometry(...)`).
- **Rule 2**: For high-count particles or voxel chunks, use `THREE.InstancedMesh` or merged face buffers.
- **Rule 3**: Whenever a unique mesh is permanently destroyed, dispose its GPU resources if not shared:

```javascript
function removeAndDispose(scene, mesh) {
  scene.remove(mesh);
  if (mesh.geometry && !mesh.userData.sharedGeo) mesh.geometry.dispose();
  if (mesh.material && !mesh.userData.sharedMat) {
    if (Array.isArray(mesh.material)) mesh.material.forEach(m => m.dispose());
    else mesh.material.dispose();
  }
}
```

---

## 6. Zero-Asset Procedural Web Audio Synthesizer

Browsers block audio until the first user gesture (`keydown` or `pointerdown`). Use a lazy-initialized `AudioContext` helper to synthesize crisp retro arcade sound effects in pure code:

```javascript
const SFX = (() => {
  let ctx = null;
  function unlock() {
    if (!ctx) {
      const AC = window.AudioContext || window.webkitAudioContext;
      if (AC) ctx = new AC();
    }
    if (ctx && ctx.state === 'suspended') ctx.resume();
    return ctx;
  }
  function tone(type, fStart, fEnd, duration, gainVal = 0.12) {
    const c = unlock();
    if (!c) return;
    const now = c.currentTime;
    const osc = c.createOscillator();
    const gain = c.createGain();
    osc.type = type;
    osc.frequency.setValueAtTime(fStart, now);
    osc.frequency.exponentialRampToValueAtTime(Math.max(20, fEnd), now + duration);
    gain.gain.setValueAtTime(gainVal, now);
    gain.gain.exponentialRampToValueAtTime(0.0001, now + duration);
    osc.connect(gain).connect(c.destination);
    osc.start(now);
    osc.stop(now + duration);
  }
  return {
    flap:  () => tone('sine', 320, 640, 0.09, 0.12),
    score: () => { tone('triangle', 587.33, 587.33, 0.07, 0.12); setTimeout(() => tone('triangle', 880, 880, 0.14, 0.12), 65); },
    hit:   () => tone('sawtooth', 160, 38, 0.26, 0.18),
  };
})();
```

---

## 7. Pre-Flight Verification Checklist for Every Game

Before emitting the final `</html>` tag, verify all 8 invariants:
1. **Scope Audit**: Every parameter used in `update(dt)` and `draw(dt)` is either declared in its signature or in module-level state.
2. **First-Frame Timestamp Guard**: `if (!lastTime) lastTime = now;` prevents `NaN` or huge initial `dt`.
3. **Tab-Switch Clamp**: `frameDt = Math.min(0.1, (now - lastTime) / 1000)` prevents teleporting through walls.
4. **Single RAF Loop**: Restarting a match resets state variables without spawning a second concurrent `requestAnimationFrame(loop)`.
5. **Input Responsiveness**: Restart works reliably after a short time-based grace period (`0.35s`), never gated on `frames % N === 0`.
6. **Zero-Allocation Hot Loop**: Particle and projectile pools use swap-and-pop (`pool[i] = pool[pool.length - 1]; pool.pop()`) instead of `Array.shift()` or `Array.filter()` inside 60fps loops.
7. **Safe Storage**: All `localStorage.getItem` / `setItem` calls are wrapped in `try { ... } catch {}` so sandboxed iframes and `file://` origins never throw `SecurityError`.
8. **Three.js Resource Hygiene**: Geometries and materials are shared across obstacle instances, lights are present for PBR materials, and window resize updates both `camera.aspect` and `camera.updateProjectionMatrix()`.