@loonylabs/create-game 0.1.0

package/template/apps/client/src/renderer/voxelChunkStreamer.ts

@@ -0,0 +1,79 @@
+/**
+ * Streams voxel terrain chunks around the player position.
+ * Generates Marching Cubes meshes on demand and disposes distant ones.
+ *
+ * Supports two modes:
+ * 1. Single VoxelTerrainOptions — uniform terrain (legacy sandbox)
+ * 2. TerrainQueryFn — per-column biome-blended terrain (overworld)
+ */
+import * as THREE from 'three';
+import type { VoxelTerrainOptions, VoxelChunk, TerrainQueryFn } from '@loonylabs/gamedev-core';
+import { VOXEL_CHUNK_X, VOXEL_CHUNK_Z, generateVoxelChunk } from '@loonylabs/gamedev-core';
+import { buildVoxelChunkMesh } from './voxelMesh.js';
+import type { VoxelMaterialVisual } from './shaders/TerrainShaderMaterial.js';
+
+export class VoxelChunkStreamer {
+  private meshes = new Map<string, THREE.Mesh>();
+  private chunkCache = new Map<string, VoxelChunk>();
+  private viewRadius = 3;
+
+  constructor(
+    private scene: THREE.Scene,
+    private seed: number,
+    private terrainOptions: VoxelTerrainOptions,
+    private materialVisuals: Record<number, VoxelMaterialVisual>,
+    private terrainQueryFn?: TerrainQueryFn,
+  ) {}
+
+  /** Get or generate a VoxelChunk (cached). Used by neighbor sampler. */
+  private getChunk = (cx: number, cz: number): VoxelChunk => {
+    const key = `${cx},${cz}`;
+    let chunk = this.chunkCache.get(key);
+    if (!chunk) {
+      chunk = generateVoxelChunk(cx, cz, this.seed, this.terrainOptions, this.terrainQueryFn);
+      this.chunkCache.set(key, chunk);
+    }
+    return chunk;
+  };
+
+  update(playerWorldX: number, playerWorldZ: number): void {
+    const pcx = Math.floor(playerWorldX / VOXEL_CHUNK_X);
+    const pcz = Math.floor(playerWorldZ / VOXEL_CHUNK_Z);
+
+    // Add missing chunks
+    for (let dx = -this.viewRadius; dx <= this.viewRadius; dx++) {
+      for (let dz = -this.viewRadius; dz <= this.viewRadius; dz++) {
+        const cx = pcx + dx;
+        const cz = pcz + dz;
+        const key = `${cx},${cz}`;
+        if (!this.meshes.has(key)) {
+          const mesh = buildVoxelChunkMesh(cx, cz, this.seed, this.terrainOptions, this.materialVisuals, this.getChunk);
+          this.scene.add(mesh);
+          this.meshes.set(key, mesh);
+        }
+      }
+    }
+
+    // Remove distant chunks
+    for (const [key, mesh] of this.meshes) {
+      const [cx, cz] = key.split(',').map(Number);
+      if (Math.abs(cx - pcx) > this.viewRadius + 1 || Math.abs(cz - pcz) > this.viewRadius + 1) {
+        this.scene.remove(mesh);
+        mesh.geometry.dispose();
+        (mesh.material as THREE.Material).dispose();
+        this.meshes.delete(key);
+        this.chunkCache.delete(key);
+      }
+    }
+  }
+
+  dispose(): void {
+    for (const [, mesh] of this.meshes) {
+      this.scene.remove(mesh);
+      mesh.geometry.dispose();
+      (mesh.material as THREE.Material).dispose();
+    }
+    this.meshes.clear();
+    this.chunkCache.clear();
+  }
+}

package/template/apps/client/src/renderer/voxelMesh.ts

@@ -0,0 +1,86 @@
+/**
+ * Builds a Three.js mesh from a voxel chunk using Marching Cubes.
+ */
+import * as THREE from 'three';
+import { generateVoxelChunk, marchingCubes, VOXEL_CHUNK_X, VOXEL_CHUNK_Y, VOXEL_CHUNK_Z, getVoxel } from '@loonylabs/gamedev-core';
+import type { VoxelTerrainOptions, VoxelChunk, NeighborSampler } from '@loonylabs/gamedev-core';
+import { TerrainShaderMaterial } from './shaders/TerrainShaderMaterial.js';
+import type { VoxelMaterialVisual } from './shaders/TerrainShaderMaterial.js';
+
+/** Shared material instance — reused across all chunk meshes for uniform updates. */
+let sharedMaterial: TerrainShaderMaterial | null = null;
+
+/**
+ * Create a neighbor sampler that reads from adjacent chunks for seamless boundaries.
+ */
+function createNeighborSampler(
+  chunk: VoxelChunk,
+  getChunk: (cx: number, cz: number) => VoxelChunk,
+): NeighborSampler {
+  return (lx: number, ly: number, lz: number) => {
+    // Determine which neighbor chunk to read from
+    let ncx = chunk.cx;
+    let ncz = chunk.cz;
+    let nlx = lx;
+    let nlz = lz;
+
+    if (lx < 0) { ncx -= 1; nlx = lx + VOXEL_CHUNK_X; }
+    else if (lx >= VOXEL_CHUNK_X) { ncx += 1; nlx = lx - VOXEL_CHUNK_X; }
+    if (lz < 0) { ncz -= 1; nlz = lz + VOXEL_CHUNK_Z; }
+    else if (lz >= VOXEL_CHUNK_Z) { ncz += 1; nlz = lz - VOXEL_CHUNK_Z; }
+
+    // Y out of bounds — no vertical neighbors
+    if (ly < 0 || ly >= VOXEL_CHUNK_Y) {
+      return { density: 0, material: 0 };
+    }
+
+    const neighborChunk = getChunk(ncx, ncz);
+    const v = getVoxel(neighborChunk, Math.floor(nlx), Math.floor(ly), Math.floor(nlz));
+    return v;
+  };
+}
+
+/** Update the shared terrain material each frame. */
+export function tickTerrainMaterial(time: number, qualityLevel?: number): void {
+  sharedMaterial?.tick(time, qualityLevel);
+}
+
+/** Dispose the shared material. */
+export function disposeTerrainMaterial(): void {
+  sharedMaterial?.dispose();
+  sharedMaterial = null;
+}
+
+export function buildVoxelChunkMesh(
+  cx: number, cz: number,
+  seed: number,
+  terrainOptions: VoxelTerrainOptions,
+  materialVisuals: Record<number, VoxelMaterialVisual>,
+  getChunk?: (cx: number, cz: number) => VoxelChunk,
+): THREE.Mesh {
+  // Use cached chunk from getChunk if available (ensures biome-blended terrain matches physics)
+  const chunk = getChunk ? getChunk(cx, cz) : generateVoxelChunk(cx, cz, seed, terrainOptions);
+
+  const neighbor = getChunk ? createNeighborSampler(chunk, getChunk) : undefined;
+  const result = marchingCubes(chunk, neighbor);
+
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.BufferAttribute(result.positions, 3));
+  geometry.setAttribute('normal', new THREE.BufferAttribute(result.normals, 3));
+
+  // Material index — shader expects `attribute float materialIndex`
+  const matFloat = new Float32Array(result.materials.length);
+  for (let i = 0; i < result.materials.length; i++) matFloat[i] = result.materials[i];
+  geometry.setAttribute('materialIndex', new THREE.BufferAttribute(matFloat, 1));
+
+  // Reuse shared material across all chunks
+  if (!sharedMaterial) {
+    sharedMaterial = new TerrainShaderMaterial(materialVisuals);
+  }
+  const mesh = new THREE.Mesh(geometry, sharedMaterial);
+
+  // Position mesh at chunk world offset
+  mesh.position.set(cx * VOXEL_CHUNK_X, 0, cz * VOXEL_CHUNK_Z);
+
+  return mesh;
+}

package/template/apps/client/src/renderer/voxelTerrain.ts

@@ -0,0 +1,74 @@
+/**
+ * @file renderer/voxelTerrain.ts
+ * Builds a Three.js mesh from a VoxelChunk using Marching Cubes.
+ *
+ * Uses TerrainShaderMaterial for procedural noise detail, triplanar
+ * projection, and slope-based rock blending.
+ */
+
+import * as THREE from 'three';
+import { marchingCubes, VOXEL_CHUNK_X, VOXEL_CHUNK_Z } from '@loonylabs/gamedev-core';
+import type { VoxelChunk } from '@loonylabs/gamedev-core';
+import { TerrainShaderMaterial } from './shaders/TerrainShaderMaterial.js';
+import { VOXEL_MATERIAL_VISUALS } from '../../../game-data/src/voxel/materials.js';
+
+/** Shared terrain material — reused across all chunk meshes. */
+let sharedMaterial: TerrainShaderMaterial | null = null;
+
+function getSharedMaterial(): TerrainShaderMaterial {
+  if (!sharedMaterial) {
+    sharedMaterial = new TerrainShaderMaterial(VOXEL_MATERIAL_VISUALS);
+  }
+  return sharedMaterial;
+}
+
+/** Update the shared terrain material's time + quality uniforms (call once per frame). */
+export function tickTerrainMaterial(time: number, qualityLevel?: number): void {
+  sharedMaterial?.tick(time, qualityLevel);
+}
+
+/** Dispose the shared material (call on cleanup). */
+export function disposeTerrainMaterial(): void {
+  sharedMaterial?.dispose();
+  sharedMaterial = null;
+}
+
+/**
+ * Build a Three.js mesh from a voxel chunk using Marching Cubes.
+ */
+export function buildVoxelChunkMesh(chunk: VoxelChunk): THREE.Mesh {
+  const result = marchingCubes(chunk);
+
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.BufferAttribute(result.positions, 3));
+  geometry.setAttribute('normal', new THREE.BufferAttribute(result.normals, 3));
+
+  // Material index as a custom float attribute for the shader
+  const matFloat = new Float32Array(result.vertexCount);
+  for (let i = 0; i < result.vertexCount; i++) {
+    matFloat[i] = result.materials[i];
+  }
+  geometry.setAttribute('materialIndex', new THREE.BufferAttribute(matFloat, 1));
+
+  const mesh = new THREE.Mesh(geometry, getSharedMaterial());
+
+  // Position mesh at chunk world offset
+  mesh.position.set(
+    chunk.cx * VOXEL_CHUNK_X,
+    0,
+    chunk.cz * VOXEL_CHUNK_Z,
+  );
+
+  return mesh;
+}
+
+/**
+ * Build a THREE.Group containing the voxel terrain mesh.
+ * Compatible with ChunkStreamer's DirectMeshBuilder signature.
+ */
+export function buildVoxelChunkGroup(chunk: VoxelChunk): THREE.Group {
+  const group = new THREE.Group();
+  const mesh = buildVoxelChunkMesh(chunk);
+  group.add(mesh);
+  return group;
+}

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

@@ -0,0 +1,268 @@
+/**
+ * @file socket.ts
+ * Socket.io connection management and inbound message routing.
+ *
+ * Responsibilities:
+ *   - Establish and maintain the socket connection
+ *   - Receive server messages and update store.ts (entities, dungeon, HP, inventory)
+ *   - Forward input acknowledgements to GameOrchestrator
+ *
+ * What does NOT belong here:
+ *   - Game loop logic
+ *   - Three.js / rendering
+ *   - Controller instantiation
+ */
+
+import { io } from 'socket.io-client';
+import { store } from './store.js';
+import type { SnapshotEntry } from '@loonylabs/gamedev-client';
+import type { GameOrchestrator } from './game.js';
+import { eventBus } from '@loonylabs/gamedev-client';
+
+const SERVER_URL = 'http://localhost:3000';
+
+export let snapshotBuffer: SnapshotEntry[] = [];
+export let sendMessage: (msg: unknown) => void = () => {};
+
+// Tracks previous grunt entity IDs for enemy_killed detection
+let prevGruntIds = new Set<number>();
+
+function getOrCreatePlayerId(): string {
+  const key = 'gamedev_player_id';
+  let id = localStorage.getItem(key);
+  if (!id) {
+    id = `p_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    localStorage.setItem(key, id);
+  }
+  return id;
+}
+
+export function initSocket(game: GameOrchestrator): void {
+  const socket = io(SERVER_URL, { transports: ['websocket'] });
+  sendMessage = (msg: unknown) => socket.emit('message', msg);
+
+  socket.on('connect', () => {
+    store.connected = true;
+    socket.emit('message', { type: 'PLAYER_CONNECT', playerId: getOrCreatePlayerId() });
+  });
+
+  socket.on('disconnect', () => {
+    store.connected = false;
+    snapshotBuffer = [];
+  });
+
+  socket.on('message', (msg: Record<string, unknown>) => {
+    if (msg.type === 'WORLD_STATE') {
+      store.dungeon = msg.dungeon as typeof store.dungeon;
+      if (msg.localEntityId !== undefined) {
+        store.localEntityId = msg.localEntityId as number;
+      }
+      if (msg.currentArea !== undefined) {
+        store.currentArea = msg.currentArea as string;
+      }
+      snapshotBuffer = [];
+    } else if (msg.type === 'ENTITY_SYNC') {
+      const entities = msg.entities as Array<{ entityId: number; x: number; y: number; hp?: number; maxHp?: number; type?: 'player' | 'grunt' | 'item' }>;
+      const entry: SnapshotEntry = {
+        tick: msg.tick as number,
+        timestamp: performance.now(),
+        entities,
+      };
+      snapshotBuffer.push(entry);
+      if (snapshotBuffer.length > 10) snapshotBuffer.shift();
+      store.entities = entities;
+
+      // Detect enemy kills: grunts present in prev snapshot but gone now
+      const currentGruntIds = new Set(entities.filter(e => e.type === 'grunt').map(e => e.entityId));
+      if (prevGruntIds.size > 0) {
+        for (const id of prevGruntIds) {
+          if (!currentGruntIds.has(id)) {
+            eventBus.emit({ type: 'enemy_killed', enemyId: id });
+          }
+        }
+      }
+      prevGruntIds = currentGruntIds;
+
+      const localPlayer = entities.find(e => e.type === 'player');
+      if (localPlayer && localPlayer.hp !== undefined && localPlayer.maxHp !== undefined) {
+        store.playerHP.current = localPlayer.hp;
+        store.playerHP.max = localPlayer.maxHp;
+      }
+    } else if (msg.type === 'INPUT_ACK') {
+      game.acknowledgeInput({ x: msg.x as number, y: msg.y as number }, msg.lastProcessedInputId as number);
+    } else if (msg.type === 'INVENTORY_UPDATE') {
+      const newItems = (msg.items as typeof store.inventory) ?? [];
+      const prev = store.inventory;
+      store.inventory = newItems;
+      // Detect newly picked-up items (present in new list but not in prev by id+slot)
+      const added = newItems.filter(i => !prev.find(p => p.id === i.id && p.slot === i.slot));
+      for (const item of added) {
+        eventBus.emit({ type: 'item_pickup', item: { id: item.id, name: item.name, rarity: item.rarity } });
+      }
+    } else if (msg.type === 'CRAFT_RESULT') {
+      if (msg.success && msg.item) {
+        const crafted = msg.item as { id: string; name: string; rarity?: string };
+        eventBus.emit({ type: 'item_crafted', item: { id: crafted.id, name: crafted.name, rarity: crafted.rarity ?? 'common' } });
+      } else if (!msg.success) {
+        console.warn('[craft] failed:', msg.error);
+      }
+    } else if (msg.type === 'EQUIPMENT_UPDATE') {
+      store.equipped = (msg.equipped as typeof store.equipped) ?? {};
+    } else if (msg.type === 'AREA_CHANGE') {
+      store.dungeonCleared = false;
+      store.countdownSeconds = 0;
+      store.currentArea = msg.targetArea as string;
+      if (msg.localEntityId !== undefined) {
+        store.localEntityId = msg.localEntityId as number;
+      }
+      if (msg.dungeon !== undefined) {
+        store.dungeon = msg.dungeon as typeof store.dungeon;
+      }
+      snapshotBuffer = [];
+      game.onAreaChange(msg as { targetArea: string; spawnX: number; spawnY: number; dungeon?: unknown; biomeId?: string; seed?: number; voxelConfig?: { terrainOptions?: Record<string, unknown> } });
+    } else if (msg.type === 'DUNGEON_CLEAR') {
+      store.dungeonCleared = true;
+      store.countdownSeconds = msg.countdownSeconds as number;
+    } else if (msg.type === 'COUNTDOWN_TICK') {
+      store.countdownSeconds = msg.secondsRemaining as number;
+    } else if (msg.type === 'ZONE_TYPE_CHANGE') {
+      store.zoneType = msg.zoneType as typeof store.zoneType;
+    } else if (msg.type === 'EXPERIENCE_LIST') {
+      store.availableExperiences = (msg.experiences as typeof store.availableExperiences) ?? [];
+    } else if (msg.type === 'EXPERIENCE_CHANGE') {
+      store.currentExperience = msg.experienceId as string;
+      store.experienceLoading = false;
+
+      // Shooter-specific scene setup
+      if (msg.experienceId === 'shooter' && msg.payload) {
+        store.currentArea = 'shooter';
+        store.isVoxelArea = false;
+        store.hasPhysics = true;
+        store.localEntityId = msg.localEntityId as number;
+        store.shooterDead = false;
+        store.shooterWaveReached = 0;
+        store.shooterWave = 0;
+        store.shooterWaveClear = false;
+        if (!store.gameMode.startsWith('wasd')) {
+          store.gameMode = 'wasd+thirdperson';
+        }
+        game.onShooterJoin(msg as any);
+      }
+      // Runner-specific scene setup
+      if (msg.experienceId === 'runner' && msg.payload) {
+        store.currentArea = 'runner';
+        store.isVoxelArea = false;
+        store.hasPhysics = true;
+        store.localEntityId = msg.localEntityId as number;
+        store.runnerDead = false;
+        store.runnerDistance = 0;
+        store.runnerSpeed = 0;
+        store.runnerScore = 0;
+        store.runnerCoins = 0;
+        store.runnerCombo = 0;
+        store.runnerGems = 0;
+        store.runnerBestCombo = 0;
+        store.runnerMagnetActive = false;
+        store.runnerHasSpeedBoost = false;
+        store.runnerHasLowGravity = false;
+        store.runnerCollectFlash = '';
+        store.runnerPowerupFlash = '';
+        if (!store.gameMode.startsWith('wasd')) {
+          store.gameMode = 'wasd+follow';
+        }
+        game.onRunnerJoin(msg as any);
+      }
+      // Diablo scene setup is handled by the follow-up AREA_CHANGE message
+    } else if (msg.type === 'WEAPON_STATE') {
+      store.shooterAmmo = {
+        current: msg.currentAmmo as number,
+        max: (msg as any).maxAmmo ?? store.shooterAmmo.max,
+      };
+      store.shooterReloading = msg.isReloading as boolean;
+    } else if (msg.type === 'WAVE_CLEAR') {
+      store.shooterWave = msg.waveNumber as number;
+      store.shooterWaveClear = true;
+      setTimeout(() => { store.shooterWaveClear = false; }, 2000);
+    } else if (msg.type === 'PLAYER_DAMAGED') {
+      store.playerHP.current = msg.hp as number;
+      store.playerHP.max = msg.maxHp as number;
+      eventBus.emit({ type: 'player_damaged', damage: msg.damage as number });
+    } else if (msg.type === 'ENEMY_KILLED') {
+      eventBus.emit({ type: 'enemy_killed', enemyId: msg.entityId as number });
+    } else if (msg.type === 'HIT_CONFIRM') {
+      eventBus.emit({
+        type: 'hit_confirm',
+        targetEntityId: msg.targetEntityId as number,
+        damage: msg.damage as number,
+        hitX: msg.hitX as number,
+        hitY: msg.hitY as number,
+        hitZ: msg.hitZ as number,
+      });
+    } else if (msg.type === 'PLAYER_DEAD') {
+      store.shooterDead = true;
+      store.shooterWaveReached = msg.waveReached as number;
+    } else if (msg.type === 'SHOOTER_RESTARTED') {
+      store.shooterDead = false;
+      store.shooterWaveReached = 0;
+      store.playerHP.current = msg.hp as number;
+      store.playerHP.max = msg.maxHp as number;
+      store.shooterWave = 0;
+      store.shooterAmmo = { current: msg.maxAmmo as number ?? 12, max: msg.maxAmmo as number ?? 12 };
+      store.shooterReloading = false;
+    } else if (msg.type === 'RUNNER_STATE') {
+      store.runnerDistance = msg.distance as number;
+      store.runnerSpeed = msg.speed as number;
+      if (msg.score !== undefined) store.runnerScore = msg.score as number;
+      if (msg.coins !== undefined) store.runnerCoins = msg.coins as number;
+      if (msg.combo !== undefined) store.runnerCombo = msg.combo as number;
+      if (msg.magnetActive !== undefined) store.runnerMagnetActive = msg.magnetActive as boolean;
+      if (msg.hasSpeedBoost !== undefined) store.runnerHasSpeedBoost = msg.hasSpeedBoost as boolean;
+      if (msg.hasLowGravity !== undefined) store.runnerHasLowGravity = msg.hasLowGravity as boolean;
+    } else if (msg.type === 'RUNNER_DEAD') {
+      store.runnerDead = true;
+      store.runnerDistance = msg.distance as number;
+      if (msg.score !== undefined) store.runnerScore = msg.score as number;
+      if (msg.coins !== undefined) store.runnerCoins = msg.coins as number;
+      if (msg.gems !== undefined) store.runnerGems = msg.gems as number;
+      if (msg.bestCombo !== undefined) store.runnerBestCombo = msg.bestCombo as number;
+      if (msg.highScore !== undefined) store.runnerHighScore = msg.highScore as number;
+    } else if (msg.type === 'RUNNER_COLLECT') {
+      const comboVal = msg.combo as number;
+      store.runnerCombo = comboVal;
+      const label = msg.collectibleType === 'gem' ? 'GEM' : 'COIN';
+      const multi = (msg.multiplier as number) > 1 ? ` x${msg.multiplier}` : '';
+      store.runnerCollectFlash = `+${msg.value}${multi} ${label}`;
+      setTimeout(() => { store.runnerCollectFlash = ''; }, 600);
+    } else if (msg.type === 'RUNNER_POWERUP') {
+      const names: Record<string, string> = { 'speed-boost': 'SPEED BOOST', 'low-gravity': 'LOW GRAVITY', 'magnet': 'MAGNET' };
+      store.runnerPowerupFlash = names[msg.powerupType as string] || (msg.powerupType as string);
+      setTimeout(() => { store.runnerPowerupFlash = ''; }, 1500);
+    } else if (msg.type === 'RUNNER_RESTARTED') {
+      store.runnerDead = false;
+      store.runnerDistance = 0;
+      store.runnerSpeed = 0;
+      store.runnerScore = 0;
+      store.runnerCoins = 0;
+      store.runnerCombo = 0;
+      store.runnerGems = 0;
+      store.runnerBestCombo = 0;
+      store.runnerMagnetActive = false;
+      store.runnerHasSpeedBoost = false;
+      store.runnerHasLowGravity = false;
+      store.runnerCollectFlash = '';
+      store.runnerPowerupFlash = '';
+      game.onRunnerRestart();
+    } else if (msg.type === 'COMBAT_VFX') {
+      if (msg.vfxType === 'tracer') {
+        // Enemy tracers: orange-red, player tracers: yellow/red
+        const color = msg.isEnemy ? 0xff6622 : undefined;
+        game.addTracer(
+          msg.origin as { x: number; y: number; z: number },
+          msg.endPoint as { x: number; y: number; z: number },
+          msg.hit as boolean,
+          color,
+        );
+      }
+    }
+  });
+}

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

@@ -0,0 +1,74 @@
+/**
+ * @file store.ts
+ * Valtio reactive store — the single source of truth for all client UI state.
+ *
+ * Responsibilities:
+ *   - Hold all reactive state (connection, dungeon, entities, HP, inventory, game mode)
+ *   - Expose the store proxy for Svelte components and game systems to read/write
+ *
+ * What does NOT belong here:
+ *   - Game logic or calculations
+ *   - Socket communication
+ *   - Three.js / rendering
+ *   - Controller instantiation
+ */
+
+import { proxy } from 'valtio';
+import type { Dungeon, WorldManager, VoxelTerrainOptions } from '@loonylabs/gamedev-core';
+import type { EntitySnapshot, InventoryItem } from '@loonylabs/gamedev-protocol';
+import type { ExperienceManifest } from '@loonylabs/gamedev-core';
+
+export type GameMode = 'click+orbit' | 'wasd+thirdperson' | 'wasd+firstperson' | 'wasd+follow';
+
+export const store = proxy({
+  connected: false,
+  /** null = in hub, string = in experience */
+  currentExperience: null as string | null,
+  availableExperiences: [] as ExperienceManifest[],
+  experienceLoading: false,
+  dungeon: null as Dungeon | null,
+  worldManager: null as WorldManager | null,
+  currentBiomeId: null as string | null,
+  entities: [] as EntitySnapshot[],
+  playerHP: { current: 100, max: 100 },
+  inventory: [] as InventoryItem[],
+  equipped: {} as Record<string, InventoryItem>,
+  equipInteraction: 'both' as 'drag' | 'doubleclick' | 'both',
+  localEntityId: 0,
+  gameMode: 'click+orbit' as GameMode,
+  playerFacingAngle: null as number | null,
+  skillCooldowns: {} as Record<string, number>, // skillId -> lastUsedAt (ms), client-side prediction
+  currentArea: 'overworld' as string,
+  zoneType: 'basecamp' as 'basecamp' | 'wilderness',
+  dungeonCleared: false,
+  countdownSeconds: 0,
+  showAimDebug: false,
+  terrainQuality: 2, // 0=Low, 1=Medium, 2=High, 3=Ultra
+  isVoxelArea: false,
+  hasPhysics: false, // true for any area with jump/gravity (voxel + dungeon)
+  voxelConfig: null as { seed: number; terrainOptions: VoxelTerrainOptions } | null,
+  // Runner experience state
+  runnerDistance: 0,
+  runnerSpeed: 0,
+  runnerDead: false,
+  runnerScore: 0,
+  runnerCoins: 0,
+  runnerCombo: 0,
+  runnerHighScore: 0,
+  runnerBestCombo: 0,
+  runnerGems: 0,
+  runnerMagnetActive: false,
+  runnerHasSpeedBoost: false,
+  runnerHasLowGravity: false,
+  /** Brief flash when collecting something */
+  runnerCollectFlash: '' as string,
+  /** Powerup notification */
+  runnerPowerupFlash: '' as string,
+  // Shooter experience state
+  shooterAmmo: { current: 0, max: 0 },
+  shooterReloading: false,
+  shooterWave: 0,
+  shooterWaveClear: false,
+  shooterDead: false,
+  shooterWaveReached: 0,
+});

package/template/apps/client/src/style.css

@@ -0,0 +1,60 @@
+:root {
+  --color-hp-high: #44cc44;
+  --color-hp-mid:  #cccc44;
+  --color-hp-low:  #cc4444;
+  --color-rarity-common: #888888;
+  --color-rarity-rare:   #4488cc;
+  --color-rarity-unique: #ccaa22;
+  --color-slot-empty:    #1a1a1a;
+  --color-slot-border:   #333333;
+}
+
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  background: #000;
+  overflow: hidden;
+  width: 100vw;
+  height: 100vh;
+}
+
+#game-canvas {
+  position: fixed;
+  inset: 0;
+  width: 100vw;
+  height: 100vh;
+  display: block;
+  z-index: 0;
+}
+
+#ui {
+  position: fixed;
+  inset: 0;
+  z-index: 10;
+  pointer-events: none;
+  font-family: 'Courier New', monospace;
+  font-size: 0.75rem;
+}
+
+.status {
+  padding: 4px 10px;
+  border-radius: 3px;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+
+.status.connected {
+  background: rgba(68, 204, 68, 0.2);
+  color: #44cc44;
+  border: 1px solid #44cc44;
+}
+
+.status.disconnected {
+  background: rgba(204, 68, 68, 0.2);
+  color: #cc4444;
+  border: 1px solid #cc4444;
+}

package/template/apps/client/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}

package/template/apps/client/vite.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+
+export default defineConfig({
+  clearScreen: false,
+  plugins: [svelte()],
+  server: {
+    port: 3200,
+  },
+});

package/template/apps/client/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    environment: 'node',
+  },
+});