@loonylabs/create-game 0.1.0

package/template/apps/client/src/game.ts

@@ -0,0 +1,918 @@
+/**
+ * @file game.ts
+ * Game orchestrator — the single owner of the game loop and all runtime systems.
+ *
+ * Responsibilities:
+ *   - Own and drive the requestAnimationFrame loop
+ *   - Create and hot-swap InputController + CameraController on mode changes
+ *   - Manage dungeon mesh lifecycle (build on load, dispose on swap)
+ *   - Own EntityRenderer and feed it interpolated snapshots each frame
+ *
+ * What does NOT belong here:
+ *   - Svelte mounting (→ main.ts)
+ *   - Socket.io connection management (→ socket.ts)
+ *   - Pure game logic / ECS (→ packages/core)
+ *   - UI state (→ store.ts)
+ *
+ * Extension points for future stories:
+ *   - Story 15 (VFX): instantiate particle system here, subscribe to eventBus
+ */
+
+import { subscribe } from 'valtio';
+import * as THREE from 'three';
+import { store } from './store.js';
+import type { GameMode } from './store.js';
+import { snapshotBuffer, sendMessage } from './socket.js';
+import { buildDungeonMesh, disposeMesh } from './renderer/dungeon.js';
+import { EntityRenderer } from './renderer/entities.js';
+import {
+  ShaderManager,
+  getInterpolatedEntities,
+  initScene,
+  VFXRenderer,
+  ClickToMoveController,
+  WASDController,
+  ThirdPersonCameraController,
+  FirstPersonCameraController,
+  FollowCameraController,
+  updateAim,
+  AmbientEmitter,
+} from '@loonylabs/gamedev-client';
+import type { InputController, CameraController, SceneContext, EntitySnapshot } from '@loonylabs/gamedev-client';
+import { soundManager, musicManager, CombatDetector } from './lib/audio/index.js';
+import soundConfig from '../../game-data/src/audio/sound-config.json';
+import musicConfig from '../../game-data/src/audio/music-config.json';
+import biomes from '../../game-data/src/world/biomes.json';
+import { createBiomeBlendFn, getTerrainHeight, generateVoxelChunk, VOXEL_CHUNK_X, VOXEL_CHUNK_Z } from '@loonylabs/gamedev-core';
+import type { BiomeDef, TileInfo, VoxelTerrainOptions } from '@loonylabs/gamedev-core';
+import { SkyMesh } from './renderer/shaders/SkyShader.js';
+import { VoxelChunkStreamer } from './renderer/voxelChunkStreamer.js';
+import { tickTerrainMaterial } from './renderer/voxelMesh.js';
+import { VOXEL_MATERIAL_VISUALS } from '../../game-data/src/voxel/materials.js';
+import { parseOverworldLayout, getTileAt, getBiomeTerrainOptions, getStructureFlatZones, TILE_SIZE } from '../../game-data/src/world/overworld-layout.js';
+import { createBasecampMeshes } from './renderer/basecamp.js';
+import { createDungeonPortal } from './renderer/dungeonPortal.js';
+import { buildArenaScene, disposeArenaScene } from './renderer/shooterArena.js';
+import type { ArenaPayload } from './renderer/shooterArena.js';
+import { buildRunnerScene, buildSegmentMesh, disposeSegmentMesh, disposeRunnerScene, createTrackGenerator, updateTrack } from './renderer/runnerTrack.js';
+import type { TrackGeneratorState } from './renderer/runnerTrack.js';
+
+export class GameOrchestrator {
+  private sceneContext: SceneContext;
+  private scene: THREE.Scene;
+  private camera: THREE.PerspectiveCamera;
+  private renderer: THREE.WebGLRenderer;
+  private entityRenderer: EntityRenderer;
+  private shaderManager: ShaderManager;
+  private vfxRenderer: VFXRenderer;
+  private cameraController: CameraController;
+  private inputController: InputController;
+  private dungeonGroup: THREE.Group | null = null;
+  private voxelChunkStreamer: VoxelChunkStreamer | null = null;
+  private structureMeshes: THREE.Group[] = [];
+  private skyMesh: SkyMesh | null = null;
+  private ambientEmitter: AmbientEmitter | null = null;
+  private latestInterpolated: EntitySnapshot[] = [];
+  private lastTime = performance.now();
+  private lastMode: GameMode;
+  private lastDungeon = store.dungeon;
+  private combatDetector: CombatDetector;
+  private combatCheckTimer = 0;
+  private audioInitialized = false;
+  private aimDebugLine: THREE.Line | null = null;
+  private jumpInputId = 0;
+  private shooterArenaGroup: THREE.Group | null = null;
+  private shooterKeys: Record<string, boolean> = {};
+  private shooterInputCleanup: (() => void) | null = null;
+  private runnerSceneGroup: THREE.Group | null = null;
+  private runnerSegmentMeshes = new Map<number, THREE.Group>(); // index -> mesh group
+  private runnerKeys: Record<string, boolean> = {};
+  private runnerInputCleanup: (() => void) | null = null;
+  private runnerSeed = 0;
+  private runnerTrackState: TrackGeneratorState | null = null;
+  private _onKeyDown: ((e: KeyboardEvent) => void) | null = null;
+
+  constructor(canvas: HTMLCanvasElement) {
+    const ctx = initScene(canvas);
+    this.sceneContext = ctx;
+    this.scene = ctx.scene;
+    this.camera = ctx.camera;
+    this.renderer = ctx.renderer;
+    this.entityRenderer = new EntityRenderer(this.scene);
+    this.shaderManager = new ShaderManager();
+    this.vfxRenderer = new VFXRenderer(this.scene);
+
+    // Initial controllers — Diablo-style auto-follow + click-to-move
+    this.cameraController = new FollowCameraController(
+      this.camera, canvas,
+      () => this.getInterpolatedPlayerPosition(),
+      { defaultElevation: 1.05, defaultDistance: 10, minDistance: 3, maxDistance: 20 },
+    );
+    this.inputController = new ClickToMoveController(canvas, this.camera, (msg) => sendMessage(msg));
+    this.lastMode = store.gameMode;
+
+    // Subscribe to mode changes
+    subscribe(store, () => {
+      if (store.gameMode !== this.lastMode) {
+        this.lastMode = store.gameMode;
+        this.setMode(store.gameMode);
+      }
+    });
+
+    // Subscribe to dungeon changes
+    subscribe(store, () => {
+      if (store.dungeon !== this.lastDungeon) {
+        this.lastDungeon = store.dungeon;
+        this.onDungeonLoaded();
+      }
+    });
+
+    // Sky dome — procedural gradient, no texture assets needed
+    this.skyMesh = new SkyMesh(this.scene);
+    this.scene.background = null; // sky shader handles background
+
+    this.combatDetector = new CombatDetector(
+      (musicConfig as { combatExitDelay: number }).combatExitDelay,
+      (state) => musicManager.setState(state),
+    );
+  }
+
+  /** Start the animation loop. Called once from main.ts after socket is ready. */
+  start(): void {
+    // Defer audio init until first user interaction (browser autoplay policy)
+    const initOnInteraction = () => {
+      if (this.audioInitialized) return;
+      this.audioInitialized = true;
+      this.initAudio();
+      window.removeEventListener('keydown', initOnInteraction);
+      window.removeEventListener('click', initOnInteraction);
+    };
+    window.addEventListener('keydown', initOnInteraction);
+    window.addEventListener('click', initOnInteraction);
+
+    // Global key handlers for voxel sandbox
+    this._onKeyDown = (e: KeyboardEvent) => {
+      // F8 — debug teleport to overworld
+      if (e.code === 'F8') {
+        e.preventDefault();
+        sendMessage({ type: 'DEBUG_TELEPORT', targetArea: 'overworld' });
+        return;
+      }
+      // Space — jump (only in voxel/dungeon areas, not shooter — shooter handles its own jump)
+      if (e.code === 'Space' && !e.repeat && store.hasPhysics && store.currentArea !== 'shooter') {
+        e.preventDefault();
+        sendMessage({ type: 'PLAYER_JUMP', inputId: ++this.jumpInputId });
+      }
+    };
+    window.addEventListener('keydown', this._onKeyDown);
+
+    this.animate();
+  }
+
+  /** Initialize audio managers. Called after first user interaction. */
+  private initAudio(): void {
+    soundManager.init(soundConfig as Parameters<typeof soundManager.init>[0]);
+    musicManager.init(musicConfig as Parameters<typeof musicManager.init>[0]);
+    musicManager.setBiome('dungeon');
+  }
+
+  /** Hot-swap input + camera controllers on mode change. */
+  setMode(mode: GameMode): void {
+    this.inputController.dispose();
+    this.cameraController.dispose();
+
+    const getPos = () => {
+      const predicted = this.inputController instanceof WASDController
+        ? this.inputController.getPredictedPosition()
+        : null;
+      const interpolated = this.getInterpolatedPlayerPosition();
+      if (predicted) return { ...predicted, worldY: interpolated?.worldY };
+      return interpolated;
+    };
+
+    if (mode === 'click+orbit') {
+      // Diablo-style: auto-follow camera with high elevation + click-to-move
+      this.cameraController = new FollowCameraController(
+        this.camera, this.renderer.domElement, getPos,
+        { defaultElevation: 1.05, defaultDistance: 10, minDistance: 3, maxDistance: 20 },
+      );
+      this.inputController = new ClickToMoveController(this.renderer.domElement, this.camera, (msg) => sendMessage(msg));
+    } else {
+      if (mode === 'wasd+thirdperson') {
+        this.cameraController = new ThirdPersonCameraController(this.camera, getPos);
+      } else if (mode === 'wasd+firstperson') {
+        this.cameraController = new FirstPersonCameraController(this.camera, this.renderer.domElement, getPos);
+      } else {
+        // wasd+follow
+        this.cameraController = new FollowCameraController(this.camera, this.renderer.domElement, getPos);
+      }
+
+      this.inputController = new WASDController(
+        this.renderer.domElement,
+        this.cameraController,
+        (msg) => sendMessage(msg),
+        () => this.getRawPlayerPosition(),
+        () => store.dungeon,
+        {},
+        {
+          getWorldManager: () => store.worldManager,
+          setPlayerFacingAngle: (angle) => { store.playerFacingAngle = angle; },
+          getLocalEntityId: () => store.localEntityId,
+          getPlayerWorldY: () => this.getInterpolatedPlayerPosition()?.worldY ?? 0,
+          isVoxelArea: () => store.isVoxelArea,
+          suppressRaycast: () => store.currentArea === 'shooter',
+        },
+      );
+    }
+  }
+
+  /** Called when a new dungeon arrives (store.dungeon changed). */
+  onDungeonLoaded(): void {
+    if (this.dungeonGroup) {
+      this.scene.remove(this.dungeonGroup);
+      disposeMesh(this.dungeonGroup, this.shaderManager);
+      this.shaderManager.clear();
+    }
+    if (store.dungeon) {
+      this.dungeonGroup = buildDungeonMesh(store.dungeon, this.shaderManager);
+      this.scene.add(this.dungeonGroup);
+      this.centerOrbit();
+    }
+  }
+
+  /** Called by socket.ts when the server sends AREA_CHANGE. */
+  onAreaChange(msg: { targetArea: string; spawnX: number; spawnY: number; dungeon?: any; biomeId?: string; seed?: number; voxelConfig?: { terrainOptions?: Record<string, unknown>; tileLayout?: boolean } }): void {
+    const isVoxel = msg.voxelConfig !== undefined;
+    const isDungeon = msg.targetArea === 'dungeon';
+
+    // --- Dispose previous area state ---
+    this.disposeShooterArena();
+    if (this.dungeonGroup) {
+      this.scene.remove(this.dungeonGroup);
+      disposeMesh(this.dungeonGroup, this.shaderManager);
+      this.dungeonGroup = null;
+      this.shaderManager.clear();
+    }
+    if (this.voxelChunkStreamer) {
+      this.voxelChunkStreamer.dispose();
+      this.voxelChunkStreamer = null;
+    }
+    for (const group of this.structureMeshes) {
+      this.scene.remove(group);
+      group.traverse((child) => {
+        if (child instanceof THREE.Mesh) {
+          child.geometry.dispose();
+          if (Array.isArray(child.material)) child.material.forEach(m => m.dispose());
+          else child.material.dispose();
+        }
+      });
+    }
+    this.structureMeshes = [];
+
+    // Update area flags
+    store.isVoxelArea = isVoxel;
+    store.hasPhysics = isVoxel || isDungeon;
+
+    if (isVoxel) {
+      // --- Voxel Overworld ---
+      const seed = msg.seed ?? 0;
+
+      // Build biome blend function from tile layout (client-side reconstruction)
+      const layout = parseOverworldLayout();
+      const tileInfoGrid: TileInfo[][] = layout.tiles.map(row =>
+        row.map(tile => ({
+          terrainOptions: getBiomeTerrainOptions(tile.def.biomeId),
+        })),
+      );
+      const flatZones = getStructureFlatZones(layout);
+      const blendFn = createBiomeBlendFn(tileInfoGrid, TILE_SIZE, TILE_SIZE, flatZones);
+
+      this.voxelChunkStreamer = new VoxelChunkStreamer(
+        this.scene,
+        seed,
+        {},
+        VOXEL_MATERIAL_VISUALS,
+        blendFn,
+      );
+      store.voxelConfig = { seed, terrainOptions: {} as VoxelTerrainOptions };
+      store.worldManager = null;
+      store.currentBiomeId = null;
+
+      // Force WASD mode for voxel areas
+      if (!store.gameMode.startsWith('wasd')) {
+        store.gameMode = 'wasd+follow';
+      }
+
+      // Place overworld structures
+      this.setupOverworldStructures(seed, layout);
+
+    } else if (isDungeon && msg.dungeon !== undefined) {
+      // --- Dungeon (grid-based) ---
+      this.dungeonGroup = buildDungeonMesh(msg.dungeon, this.shaderManager);
+      this.scene.add(this.dungeonGroup);
+
+      store.worldManager = null;
+      store.currentBiomeId = null;
+
+      // Force WASD mode for dungeons (3D movement with jump)
+      if (!store.gameMode.startsWith('wasd')) {
+        store.gameMode = 'wasd+thirdperson';
+      }
+    }
+
+    // Update fog
+    if (isDungeon) {
+      const dungeonBiome = (biomes as Record<string, { fogColor: string; fogDensity: number }>)['dungeon'];
+      if (dungeonBiome) this.sceneContext.setFog(dungeonBiome.fogColor, dungeonBiome.fogDensity);
+    } else if (isVoxel) {
+      // Light fog for overworld
+      this.sceneContext.setFog('#a0b8d0', 0.008);
+    }
+
+    // Update sky dome
+    this.skyMesh?.setSkyForArea(msg.targetArea);
+
+    // Swap ambient particle emitter
+    this.ambientEmitter?.dispose();
+    this.ambientEmitter = null;
+    const particlePreset = isDungeon ? 'embers' : 'leaves';
+    const particleCentre = new THREE.Vector3(msg.spawnX ?? 16, 0, msg.spawnY ?? 16);
+    this.ambientEmitter = new AmbientEmitter(this.scene, particlePreset, particleCentre);
+
+    // Reset entity renderer
+    this.entityRenderer.dispose();
+    this.entityRenderer = new EntityRenderer(this.scene);
+  }
+
+  /** Called by socket.ts when joining the Shooter experience. */
+  onShooterJoin(msg: { spawnX: number; spawnY: number; spawnZ: number; localEntityId: number; payload: ArenaPayload }): void {
+    // Dispose previous scene state
+    this.disposeShooterArena();
+    if (this.dungeonGroup) {
+      this.scene.remove(this.dungeonGroup);
+      disposeMesh(this.dungeonGroup, this.shaderManager);
+      this.dungeonGroup = null;
+      this.shaderManager.clear();
+    }
+    if (this.voxelChunkStreamer) {
+      this.voxelChunkStreamer.dispose();
+      this.voxelChunkStreamer = null;
+    }
+    for (const group of this.structureMeshes) {
+      this.scene.remove(group);
+      group.traverse((child) => {
+        if (child instanceof THREE.Mesh) {
+          child.geometry.dispose();
+          if (Array.isArray(child.material)) child.material.forEach(m => m.dispose());
+          else child.material.dispose();
+        }
+      });
+    }
+    this.structureMeshes = [];
+    this.ambientEmitter?.dispose();
+    this.ambientEmitter = null;
+
+    // Build arena
+    this.shooterArenaGroup = buildArenaScene(msg.payload);
+    this.scene.add(this.shooterArenaGroup);
+
+    // Light fog for arena
+    this.sceneContext.setFog('#1a1a2e', 0.015);
+    this.skyMesh?.setSkyForArea('shooter');
+
+    // Reset entity renderer
+    this.entityRenderer.dispose();
+    this.entityRenderer = new EntityRenderer(this.scene);
+
+    // Position camera at spawn
+    this.camera.position.set(msg.spawnX, 8, (msg.spawnZ ?? msg.spawnY) + 8);
+    this.camera.lookAt(msg.spawnX, 0, msg.spawnZ ?? msg.spawnY);
+
+    // Force WASD third-person mode
+    this.setMode('wasd+thirdperson');
+
+    // Set up shooter-specific input
+    this.setupShooterInput();
+  }
+
+  /** Set up shooter-specific input handlers (click to shoot, R to reload, Space to jump). */
+  private setupShooterInput(): void {
+    this.disposeShooterInput();
+    this.shooterKeys = {};
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (store.currentArea !== 'shooter') return;
+      this.shooterKeys[e.code] = true;
+      if (e.code === 'KeyR') {
+        sendMessage({ type: 'RELOAD' });
+      }
+      if (e.code === 'Space' && !e.repeat) {
+        e.preventDefault();
+        sendMessage({ type: 'SHOOTER_JUMP' });
+      }
+    };
+    const onKeyUp = (e: KeyboardEvent) => {
+      this.shooterKeys[e.code] = false;
+    };
+    const onClick = (e: MouseEvent) => {
+      if (store.currentArea !== 'shooter' || store.shooterDead) return;
+      if (e.button !== 0) return;
+
+      const playerPos = this.getInterpolatedPlayerPosition();
+      const EYE_HEIGHT = 1.7;
+      const eyePos = playerPos
+        ? new THREE.Vector3(playerPos.x, (playerPos.worldY ?? 0) + EYE_HEIGHT, playerPos.y)
+        : this.camera.position.clone();
+
+      // Third-person parallax fix: cast ray from camera through crosshair
+      // to find the world-space aim point, then shoot from player eye toward it
+      const cameraDir = new THREE.Vector3(0, 0, -1).applyQuaternion(this.camera.quaternion);
+      const aimPoint = this.camera.position.clone().addScaledVector(cameraDir, 200);
+      const shootDir = new THREE.Vector3().subVectors(aimPoint, eyePos).normalize();
+
+      sendMessage({
+        type: 'SHOOT',
+        originX: eyePos.x,
+        originY: eyePos.y,
+        originZ: eyePos.z,
+        dirX: shootDir.x,
+        dirY: shootDir.y,
+        dirZ: shootDir.z,
+      });
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+    this.renderer.domElement.addEventListener('click', onClick);
+
+    this.shooterInputCleanup = () => {
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('keyup', onKeyUp);
+      this.renderer.domElement.removeEventListener('click', onClick);
+    };
+  }
+
+  private disposeShooterInput(): void {
+    this.shooterInputCleanup?.();
+    this.shooterInputCleanup = null;
+    this.shooterKeys = {};
+  }
+
+  /** Send SHOOTER_MOVE based on current key state. Called each frame when in shooter. */
+  private tickShooterInput(): void {
+    if (store.currentArea !== 'shooter' || store.shooterDead) return;
+
+    const forward = this.cameraController.getForward();
+    const right = new THREE.Vector3().crossVectors(forward, new THREE.Vector3(0, 1, 0)).normalize();
+
+    const dir = new THREE.Vector3();
+    if (this.shooterKeys['KeyW'] || this.shooterKeys['ArrowUp']) dir.addScaledVector(forward, 1);
+    if (this.shooterKeys['KeyS'] || this.shooterKeys['ArrowDown']) dir.addScaledVector(forward, -1);
+    if (this.shooterKeys['KeyA'] || this.shooterKeys['ArrowLeft']) dir.addScaledVector(right, -1);
+    if (this.shooterKeys['KeyD'] || this.shooterKeys['ArrowRight']) dir.addScaledVector(right, 1);
+
+    const sprint = this.shooterKeys['ShiftLeft'] || this.shooterKeys['ShiftRight'] || false;
+    const facingAngle = Math.atan2(forward.x, forward.z);
+    store.playerFacingAngle = facingAngle;
+
+    if (dir.lengthSq() > 0) {
+      dir.normalize();
+    }
+
+    sendMessage({
+      type: 'SHOOTER_MOVE',
+      x: dir.x,
+      z: dir.z,
+      sprint,
+      facingAngle,
+    });
+  }
+
+  /** Dispose shooter arena meshes and input. */
+  private disposeShooterArena(): void {
+    if (this.shooterArenaGroup) {
+      this.scene.remove(this.shooterArenaGroup);
+      disposeArenaScene(this.shooterArenaGroup);
+      this.shooterArenaGroup = null;
+    }
+    this.disposeShooterInput();
+  }
+
+  /** Called by socket.ts when joining the Runner experience. */
+  onRunnerJoin(msg: { spawnX: number; spawnY: number; spawnZ: number; localEntityId: number; seed: number; payload: { laneWidth: number; trackWidth: number } }): void {
+    // Dispose previous scene state
+    this.disposeRunnerScene();
+    this.disposeShooterArena();
+    if (this.dungeonGroup) {
+      this.scene.remove(this.dungeonGroup);
+      disposeMesh(this.dungeonGroup, this.shaderManager);
+      this.dungeonGroup = null;
+      this.shaderManager.clear();
+    }
+    if (this.voxelChunkStreamer) {
+      this.voxelChunkStreamer.dispose();
+      this.voxelChunkStreamer = null;
+    }
+    for (const group of this.structureMeshes) {
+      this.scene.remove(group);
+      group.traverse((child) => {
+        if (child instanceof THREE.Mesh) {
+          child.geometry.dispose();
+          if (Array.isArray(child.material)) child.material.forEach(m => m.dispose());
+          else child.material.dispose();
+        }
+      });
+    }
+    this.structureMeshes = [];
+    this.ambientEmitter?.dispose();
+    this.ambientEmitter = null;
+
+    // Build runner scene (lighting)
+    this.runnerSceneGroup = buildRunnerScene();
+    this.scene.add(this.runnerSceneGroup);
+    this.runnerSeed = msg.seed;
+
+    // Init client-side track generator (same seed as server = identical track)
+    this.runnerTrackState = createTrackGenerator(msg.seed);
+    updateTrack(this.runnerTrackState, 0, 200, 50);
+    // Build initial segment meshes
+    for (const seg of this.runnerTrackState.segments) {
+      const mesh = buildSegmentMesh({
+        type: seg.def.type,
+        startZ: seg.startZ,
+        endZ: seg.endZ,
+        length: seg.def.length,
+        lanes: seg.def.lanes,
+        gapLength: seg.def.gapLength,
+        rampHeight: seg.def.rampHeight,
+        index: seg.index,
+      });
+      this.scene.add(mesh);
+      this.runnerSegmentMeshes.set(seg.index, mesh);
+    }
+
+    // Set fog and sky
+    this.sceneContext.setFog('#0a0a1e', 0.008);
+    this.skyMesh?.setSkyForArea('runner');
+
+    // Reset entity renderer
+    this.entityRenderer.dispose();
+    this.entityRenderer = new EntityRenderer(this.scene);
+
+    // Position camera behind the start
+    this.camera.position.set(0, 8, -10);
+    this.camera.lookAt(0, 0, 10);
+
+    // Force follow mode
+    this.setMode('wasd+follow');
+
+    // Set up runner-specific input
+    this.setupRunnerInput();
+  }
+
+  /** Called when runner is restarted after death. */
+  onRunnerRestart(): void {
+    // Clear segment meshes
+    for (const [, mesh] of this.runnerSegmentMeshes) {
+      this.scene.remove(mesh);
+      disposeSegmentMesh(mesh);
+    }
+    this.runnerSegmentMeshes.clear();
+
+    // Reset track generator and rebuild initial segments
+    this.runnerTrackState = createTrackGenerator(this.runnerSeed);
+    updateTrack(this.runnerTrackState, 0, 200, 50);
+    for (const seg of this.runnerTrackState.segments) {
+      const mesh = buildSegmentMesh({
+        type: seg.def.type,
+        startZ: seg.startZ,
+        endZ: seg.endZ,
+        length: seg.def.length,
+        lanes: seg.def.lanes,
+        gapLength: seg.def.gapLength,
+        rampHeight: seg.def.rampHeight,
+        index: seg.index,
+      });
+      this.scene.add(mesh);
+      this.runnerSegmentMeshes.set(seg.index, mesh);
+    }
+
+    // Reset camera
+    this.camera.position.set(0, 8, -10);
+    this.camera.lookAt(0, 0, 10);
+  }
+
+  /** Set up runner-specific input handlers. */
+  private setupRunnerInput(): void {
+    this.disposeRunnerInput();
+    this.runnerKeys = {};
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (store.currentArea !== 'runner') return;
+      this.runnerKeys[e.code] = true;
+
+      if (e.code === 'Space' && !e.repeat) {
+        e.preventDefault();
+        sendMessage({ type: 'RUNNER_INPUT', left: false, right: false, jump: true, glide: false });
+      }
+      if ((e.code === 'KeyA' || e.code === 'ArrowLeft') && !e.repeat) {
+        sendMessage({ type: 'RUNNER_INPUT', left: true, right: false, jump: false, glide: false });
+      }
+      if ((e.code === 'KeyD' || e.code === 'ArrowRight') && !e.repeat) {
+        sendMessage({ type: 'RUNNER_INPUT', left: false, right: true, jump: false, glide: false });
+      }
+    };
+    const onKeyUp = (e: KeyboardEvent) => {
+      this.runnerKeys[e.code] = false;
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+
+    this.runnerInputCleanup = () => {
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('keyup', onKeyUp);
+    };
+  }
+
+  private disposeRunnerInput(): void {
+    this.runnerInputCleanup?.();
+    this.runnerInputCleanup = null;
+    this.runnerKeys = {};
+  }
+
+  /** Send glide state each frame when in runner. */
+  private tickRunnerInput(): void {
+    if (store.currentArea !== 'runner' || store.runnerDead) return;
+
+    // Glide state: hold space while airborne
+    const isGliding = this.runnerKeys['Space'] || false;
+    sendMessage({ type: 'RUNNER_INPUT', left: false, right: false, jump: false, glide: isGliding });
+  }
+
+  /** Update track segment meshes based on player position. */
+  private updateRunnerTrack(): void {
+    if (store.currentArea !== 'runner' || !this.runnerTrackState) return;
+
+    const playerPos = this.getInterpolatedPlayerPosition();
+    if (!playerPos) return;
+
+    // playerPos.y is the forward Z in 2D mapping
+    const playerZ = playerPos.y;
+
+    // Remember which segments existed before update
+    const prevIndices = new Set(this.runnerTrackState.segments.map(s => s.index));
+
+    // Stream track — generate ahead, dispose behind
+    updateTrack(this.runnerTrackState, playerZ, 200, 50);
+
+    // Build meshes for new segments
+    for (const seg of this.runnerTrackState.segments) {
+      if (!this.runnerSegmentMeshes.has(seg.index)) {
+        const mesh = buildSegmentMesh({
+          type: seg.def.type,
+          startZ: seg.startZ,
+          endZ: seg.endZ,
+          length: seg.def.length,
+          lanes: seg.def.lanes,
+          gapLength: seg.def.gapLength,
+          rampHeight: seg.def.rampHeight,
+          index: seg.index,
+        });
+        this.scene.add(mesh);
+        this.runnerSegmentMeshes.set(seg.index, mesh);
+      }
+    }
+
+    // Dispose meshes for removed segments
+    const currentIndices = new Set(this.runnerTrackState.segments.map(s => s.index));
+    for (const [idx, mesh] of this.runnerSegmentMeshes) {
+      if (!currentIndices.has(idx)) {
+        this.scene.remove(mesh);
+        disposeSegmentMesh(mesh);
+        this.runnerSegmentMeshes.delete(idx);
+      }
+    }
+
+    this.updateRunnerCamera(playerPos);
+  }
+
+  /** Update camera to follow runner player. */
+  private updateRunnerCamera(playerPos: { x: number; y: number; worldY?: number }): void {
+    const px = playerPos.x;
+    const pz = playerPos.y; // forward
+    const py = (playerPos.worldY ?? 0);
+
+    // Camera: behind and above the player, looking forward
+    const camOffsetY = 6;
+    const camOffsetZ = -10;
+    this.camera.position.set(px * 0.3, py + camOffsetY, pz + camOffsetZ);
+    this.camera.lookAt(px * 0.3, py + 1, pz + 15);
+  }
+
+  private disposeRunnerScene(): void {
+    if (this.runnerSceneGroup) {
+      this.scene.remove(this.runnerSceneGroup);
+      disposeRunnerScene(this.runnerSceneGroup);
+      this.runnerSceneGroup = null;
+    }
+    for (const [, mesh] of this.runnerSegmentMeshes) {
+      this.scene.remove(mesh);
+      disposeSegmentMesh(mesh);
+    }
+    this.runnerSegmentMeshes.clear();
+    this.runnerTrackState = null;
+    this.disposeRunnerInput();
+  }
+
+  /** Place basecamp structures and dungeon portal in the overworld. */
+  private setupOverworldStructures(
+    seed: number,
+    layout: ReturnType<typeof parseOverworldLayout>,
+  ): void {
+    // Terrain height lookup using client-side chunk generation
+    const tileInfoGrid: TileInfo[][] = layout.tiles.map(row =>
+      row.map(tile => ({ terrainOptions: getBiomeTerrainOptions(tile.def.biomeId) })),
+    );
+    const flatZones = getStructureFlatZones(layout);
+    const blendFn = createBiomeBlendFn(tileInfoGrid, TILE_SIZE, TILE_SIZE, flatZones);
+
+    // Simple chunk cache for height queries
+    const chunkCache = new Map<string, import('@loonylabs/gamedev-core').VoxelChunk>();
+    const getChunkFn = (cx: number, cz: number) => {
+      const key = `${cx},${cz}`;
+      let chunk = chunkCache.get(key);
+      if (!chunk) {
+        chunk = generateVoxelChunk(cx, cz, seed, {}, blendFn);
+        chunkCache.set(key, chunk);
+      }
+      return chunk;
+    };
+    const getHeight = (x: number, z: number) =>
+      getTerrainHeight(getChunkFn, x, z) ?? 32;
+
+    // Find basecamp center
+    const basecampTiles = layout.tiles.flat().filter(t => t.def.type === 'B');
+    if (basecampTiles.length > 0) {
+      const cx = basecampTiles.reduce((s, t) => s + (t.col + 0.5) * TILE_SIZE, 0) / basecampTiles.length;
+      const cz = basecampTiles.reduce((s, t) => s + (t.row + 0.5) * TILE_SIZE, 0) / basecampTiles.length;
+      const basecampGroup = createBasecampMeshes({
+        center: { x: cx, z: cz },
+        getTerrainHeight: getHeight,
+      });
+      this.scene.add(basecampGroup);
+      this.structureMeshes.push(basecampGroup);
+    }
+
+    // Find dungeon entrance
+    const dungeonTile = layout.tiles.flat().find(t => t.def.type === 'D');
+    if (dungeonTile) {
+      const portalX = (dungeonTile.col + 0.5) * TILE_SIZE;
+      const portalZ = (dungeonTile.row + 0.5) * TILE_SIZE;
+      const portal = createDungeonPortal(portalX, portalZ, getHeight);
+      this.scene.add(portal);
+      this.structureMeshes.push(portal);
+    }
+  }
+
+  /** Called by socket.ts with server reconciliation data. */
+  acknowledgeInput(pos: { x: number; y: number }, inputId: number): void {
+    if (this.inputController instanceof WASDController) {
+      this.inputController.acknowledgeInput(pos, inputId);
+    }
+  }
+
+  addTracer(origin: { x: number; y: number; z: number }, endPoint: { x: number; y: number; z: number }, hit: boolean, color?: number): void {
+    this.vfxRenderer.addTracer(origin, endPoint, hit, color);
+  }
+
+  dispose(): void {
+    this.inputController.dispose();
+    this.cameraController.dispose();
+    this.sceneContext.dispose();
+    this.combatDetector.dispose();
+    soundManager.dispose();
+    musicManager.dispose();
+    this.skyMesh?.dispose();
+    this.ambientEmitter?.dispose();
+    this.voxelChunkStreamer?.dispose();
+    this.disposeShooterArena();
+    this.disposeRunnerScene();
+    if (this._onKeyDown) {
+      window.removeEventListener('keydown', this._onKeyDown);
+    }
+  }
+
+  private animate(): void {
+    requestAnimationFrame(() => this.animate());
+    const now = performance.now();
+    const dt = Math.min((now - this.lastTime) / 1000, 0.1);
+    this.lastTime = now;
+
+    this.shaderManager.tick(now / 1000);
+    this.skyMesh?.tick(now / 1000);
+    tickTerrainMaterial(now / 1000, store.terrainQuality);
+    this.latestInterpolated = getInterpolatedEntities(snapshotBuffer);
+    this.cameraController.update(dt);
+    if (store.currentArea === 'shooter') {
+      this.tickShooterInput();
+    }
+    if (store.currentArea === 'runner') {
+      this.tickRunnerInput();
+      this.updateRunnerTrack();
+    }
+    this.inputController.update(dt);
+    this.entityRenderer.update(this.latestInterpolated, dt);
+    this.ambientEmitter?.update(dt);
+
+    // Update voxel chunk streamer if active
+    if (this.voxelChunkStreamer) {
+      const playerPos = this.getInterpolatedPlayerPosition();
+      if (playerPos) {
+        this.voxelChunkStreamer.update(playerPos.x, playerPos.y);
+      }
+    }
+
+    this.renderer.render(this.scene, this.camera);
+
+    // Update shared aim state for skill bar / dev tools
+    // Use player eye position as origin so skills fire from the player, not the camera
+    const dir = new THREE.Vector3();
+    this.camera.getWorldDirection(dir);
+    const aimPlayerPos = this.getInterpolatedPlayerPosition();
+    const aimOrigin = aimPlayerPos
+      ? { x: aimPlayerPos.x, y: (aimPlayerPos.worldY ?? 0) + 1.7, z: aimPlayerPos.y }
+      : { x: this.camera.position.x, y: this.camera.position.y, z: this.camera.position.z };
+    updateAim(aimOrigin, { x: dir.x, y: dir.y, z: dir.z });
+
+    // Aim debug line — starts at player position, points in facing direction
+    if (store.showAimDebug) {
+      if (!this.aimDebugLine) {
+        const mat = new THREE.LineBasicMaterial({ color: 0xff0000 });
+        const geo = new THREE.BufferGeometry();
+        this.aimDebugLine = new THREE.Line(geo, mat);
+        this.scene.add(this.aimDebugLine);
+      }
+      const playerPos = this.getInterpolatedPlayerPosition();
+      if (playerPos) {
+        const angle = store.playerFacingAngle ?? 0;
+        const aimDir = new THREE.Vector3(Math.sin(angle), 0, Math.cos(angle));
+        const origin = new THREE.Vector3(playerPos.x, (playerPos.worldY ?? 0) + 1.0, playerPos.y);
+        const end = origin.clone().addScaledVector(aimDir, 30);
+        (this.aimDebugLine.geometry as THREE.BufferGeometry).setFromPoints([origin, end]);
+        this.aimDebugLine.visible = true;
+      }
+    } else if (this.aimDebugLine) {
+      this.aimDebugLine.visible = false;
+    }
+
+    // Combat detection — run every 500ms
+    this.combatCheckTimer += dt;
+    if (this.combatCheckTimer >= 0.5) {
+      this.combatCheckTimer = 0;
+      const playerPos = this.getInterpolatedPlayerPosition();
+      if (playerPos && this.audioInitialized) {
+        this.combatDetector.check(
+          playerPos,
+          this.latestInterpolated as Array<{ type?: string; x: number; y: number }>,
+          (musicConfig as { combatDetectionRadius: number }).combatDetectionRadius,
+        );
+      }
+    }
+  }
+
+  private getInterpolatedPlayerPosition(): { x: number; y: number; worldY?: number } | null {
+    const id = store.localEntityId;
+    if (!id) return null;
+    const entity = this.latestInterpolated.find(e => e.entityId === id);
+    if (!entity) return null;
+    return { x: entity.x, y: entity.y, worldY: entity.worldY };
+  }
+
+  private getRawPlayerPosition(): { x: number; y: number } | null {
+    const id = store.localEntityId;
+    if (!id) return null;
+    const entity = store.entities.find(e => e.entityId === id);
+    if (!entity) return null;
+    return { x: entity.x, y: entity.y };
+  }
+
+  private centerOrbit(): void {
+    if (!store.dungeon || !('centerOn' in this.cameraController)) return;
+    let minX = Infinity, minZ = Infinity, maxX = -Infinity, maxZ = -Infinity;
+    for (const room of store.dungeon.rooms) {
+      const x1 = room.worldOffset.x;
+      const z1 = room.worldOffset.y;
+      const x2 = x1 + room.grid.width;
+      const z2 = z1 + room.grid.height;
+      if (x1 < minX) minX = x1;
+      if (z1 < minZ) minZ = z1;
+      if (x2 > maxX) maxX = x2;
+      if (z2 > maxZ) maxZ = z2;
+    }
+    const cx = (minX + maxX) / 2;
+    const cz = (minZ + maxZ) / 2;
+    const span = Math.max(maxX - minX, maxZ - minZ);
+    (this.cameraController as any).centerOn(cx, 0, cz, span);
+  }
+}