@loonylabs/create-game 0.1.0

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

@@ -0,0 +1,197 @@
+/**
+ * @file renderer/entities.ts
+ * Entity renderer — creates and updates Three.js meshes for game entities.
+ *
+ * Responsibilities:
+ *   - Maintain a mesh-per-entity map (create on first sight, remove when gone)
+ *   - Update mesh position, rotation (with smooth lerp) and color each frame
+ *   - Track previous positions to compute movement direction for rotation
+ *
+ * What does NOT belong here:
+ *   - Game logic / ECS (→ packages/core)
+ *   - Dungeon mesh building (→ renderer/dungeon.ts)
+ *   - Camera or input handling
+ */
+
+import * as THREE from 'three';
+import type { EntitySnapshot } from '@loonylabs/gamedev-protocol';
+import { store } from '../store.js';
+
+interface EnemyVisualDef {
+  bodyColor: number;
+  headColor: number;
+  scale: number;
+}
+
+const ENEMY_VISUALS: Record<string, EnemyVisualDef> = {
+  player:   { bodyColor: 0x4488ff, headColor: 0x66aaff, scale: 1.0 },
+  grunt:    { bodyColor: 0xcc4444, headColor: 0xee6666, scale: 1.0 },
+  wolf:     { bodyColor: 0x888888, headColor: 0x999999, scale: 0.7 },
+  bandit:   { bodyColor: 0x8B4513, headColor: 0xaa6633, scale: 1.0 },
+  skeleton: { bodyColor: 0xe8e0d0, headColor: 0xf0e8d8, scale: 0.9 },
+  golem:    { bodyColor: 0x607060, headColor: 0x708070, scale: 1.6 },
+  // Shooter enemies
+  rusher:   { bodyColor: 0xcc2222, headColor: 0xff4444, scale: 0.9 },
+  patrol:   { bodyColor: 0x8B6914, headColor: 0xaa8833, scale: 1.0 },
+  sniper:   { bodyColor: 0xcccccc, headColor: 0xeeeeee, scale: 1.1 },
+};
+
+const ITEM_WIDTH = 0.5;
+const ITEM_HEIGHT = 0.3;
+
+const ROTATION_SPEED = 12; // rad/s
+const MOVE_THRESHOLD = 0.001;
+
+/** Shortest-path angle lerp — avoids the 360° wrap-around spin */
+function lerpAngle(current: number, target: number, t: number): number {
+  let delta = ((target - current + Math.PI) % (Math.PI * 2)) - Math.PI;
+  if (delta < -Math.PI) delta += Math.PI * 2;
+  return current + Math.max(-Math.PI * t, Math.min(Math.PI * t, delta));
+}
+
+function buildEntityMesh(enemyDefId = 'player'): THREE.Group {
+  const vis = ENEMY_VISUALS[enemyDefId] ?? ENEMY_VISUALS['grunt'];
+  const group = new THREE.Group();
+
+  const body = new THREE.Mesh(
+    new THREE.CylinderGeometry(0.3 * vis.scale, 0.35 * vis.scale, 1.0 * vis.scale, 8),
+    new THREE.MeshLambertMaterial({ color: vis.bodyColor }),
+  );
+  body.position.y = 0.5 * vis.scale;
+
+  const head = new THREE.Mesh(
+    new THREE.SphereGeometry(0.25 * vis.scale, 8, 6),
+    new THREE.MeshLambertMaterial({ color: vis.headColor }),
+  );
+  head.position.y = (0.5 + 0.25 + 0.25) * vis.scale;
+
+  // Direction indicator — small cone pointing forward (along +Z in local space)
+  const coneGeo = new THREE.ConeGeometry(0.12 * vis.scale, 0.4 * vis.scale, 6);
+  coneGeo.rotateX(Math.PI / 2); // tip points along +Z
+  const coneMat = new THREE.MeshLambertMaterial({ color: 0x00ff88 });
+  const directionCone = new THREE.Mesh(coneGeo, coneMat);
+  directionCone.position.set(0, 0.5 * vis.scale, 0.4 * vis.scale);
+
+  group.add(body, head, directionCone);
+  return group;
+}
+
+function buildItemMesh(): THREE.Mesh {
+  const geo = new THREE.BoxGeometry(ITEM_WIDTH, ITEM_HEIGHT, ITEM_WIDTH);
+  const mat = new THREE.MeshLambertMaterial({ color: 0xffcc00 });
+  return new THREE.Mesh(geo, mat);
+}
+
+export class EntityRenderer {
+  private groups = new Map<number, THREE.Group>();
+  private itemMeshes = new Map<number, THREE.Mesh>();
+  private group = new THREE.Group();
+  private previousPositions = new Map<number, { x: number; y: number }>();
+  private targetRotations = new Map<number, number>();
+
+  constructor(private scene: THREE.Scene) {
+    scene.add(this.group);
+  }
+
+  update(entities: EntitySnapshot[], deltaTime: number): void {
+    const seen = new Set<number>();
+
+    for (const e of entities) {
+      seen.add(e.entityId);
+
+      if (e.type === 'item') {
+        let mesh = this.itemMeshes.get(e.entityId);
+        if (!mesh) {
+          mesh = buildItemMesh();
+          this.itemMeshes.set(e.entityId, mesh);
+          this.group.add(mesh);
+        }
+        mesh.position.set(e.x, (e.worldY ?? 0) + ITEM_HEIGHT / 2 + 0.1, e.y);
+        continue;
+      }
+
+      // All non-item entities use the cylinder+sphere group
+      let entityGroup = this.groups.get(e.entityId);
+      if (!entityGroup) {
+        entityGroup = buildEntityMesh(e.enemyDefId ?? e.type ?? 'player');
+        this.groups.set(e.entityId, entityGroup);
+        this.group.add(entityGroup);
+      }
+
+      const vis = ENEMY_VISUALS[e.enemyDefId ?? e.type ?? 'player'] ?? ENEMY_VISUALS['grunt'];
+      entityGroup.position.set(e.x, (e.worldY ?? 0) + 0.1, e.y);
+      this._updateGroupRotation(e, entityGroup, deltaTime, vis.scale);
+      this.previousPositions.set(e.entityId, { x: e.x, y: e.y });
+    }
+
+    // Remove entities no longer present
+    for (const [id, g] of this.groups) {
+      if (!seen.has(id)) {
+        this.group.remove(g);
+        g.traverse(obj => {
+          if (obj instanceof THREE.Mesh) {
+            obj.geometry.dispose();
+            (obj.material as THREE.Material).dispose();
+          }
+        });
+        this.groups.delete(id);
+        this.previousPositions.delete(id);
+        this.targetRotations.delete(id);
+      }
+    }
+    for (const [id, mesh] of this.itemMeshes) {
+      if (!seen.has(id)) {
+        this.group.remove(mesh);
+        mesh.geometry.dispose();
+        (mesh.material as THREE.Material).dispose();
+        this.itemMeshes.delete(id);
+      }
+    }
+  }
+
+  private _updateGroupRotation(e: EntitySnapshot, group: THREE.Group, dt: number, scale: number): void {
+    const prev = this.previousPositions.get(e.entityId);
+    if (prev) {
+      const dx = e.x - prev.x;
+      const dy = e.y - prev.y;
+      if (Math.sqrt(dx * dx + dy * dy) > MOVE_THRESHOLD) {
+        if (e.type === 'player') {
+          this._updatePlayerFacing(e.entityId, dx, dy);
+        } else {
+          this.targetRotations.set(e.entityId, Math.atan2(dx, dy));
+        }
+      }
+    }
+    const target = this.targetRotations.get(e.entityId) ?? group.rotation.y;
+    group.rotation.y = lerpAngle(group.rotation.y, target, ROTATION_SPEED * dt);
+  }
+
+  private _updatePlayerFacing(entityId: number, dx: number, dy: number): void {
+    if (store.gameMode.startsWith('wasd')) {
+      if (store.playerFacingAngle !== null) {
+        this.targetRotations.set(entityId, store.playerFacingAngle);
+      }
+      return;
+    }
+    // Diablo/click-to-move: derive facing from movement direction
+    const angle = Math.atan2(dx, dy);
+    this.targetRotations.set(entityId, angle);
+    store.playerFacingAngle = angle;
+  }
+
+  dispose(): void {
+    for (const g of this.groups.values()) {
+      g.traverse(obj => {
+        if (obj instanceof THREE.Mesh) {
+          obj.geometry.dispose();
+          (obj.material as THREE.Material).dispose();
+        }
+      });
+    }
+    for (const mesh of this.itemMeshes.values()) {
+      mesh.geometry.dispose();
+      (mesh.material as THREE.Material).dispose();
+    }
+    this.scene.remove(this.group);
+  }
+}

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

@@ -0,0 +1,221 @@
+/**
+ * Runner track renderer + client-side track generator.
+ *
+ * The track generator here is a duplicate of apps/experiences/runner/track/trackGenerator.ts
+ * because Vite cannot resolve imports outside of apps/client/. Both use the same seed-based
+ * PRNG so they produce identical results.
+ */
+
+import * as THREE from 'three';
+import { mulberry32 } from '@loonylabs/gamedev-core';
+
+// ---------------------------------------------------------------------------
+// Track Generator (client-side duplicate — must match server exactly)
+// ---------------------------------------------------------------------------
+
+export interface SegmentDef {
+  type: string;
+  length: number;
+  lanes: [boolean, boolean, boolean];
+  gapLength?: number;
+  rampHeight?: number;
+}
+
+export interface PlacedSegment {
+  def: SegmentDef;
+  startZ: number;
+  endZ: number;
+  index: number;
+}
+
+export interface TrackGeneratorState {
+  seed: number;
+  nextZ: number;
+  nextIndex: number;
+  segments: PlacedSegment[];
+}
+
+const STRAIGHT: SegmentDef = { type: 'straight', length: 20, lanes: [true, true, true] };
+const GAP: SegmentDef = { type: 'gap', length: 20, lanes: [true, true, true], gapLength: 6 };
+const RAMP: SegmentDef = { type: 'ramp', length: 20, lanes: [true, true, true], rampHeight: 4 };
+const NARROW_L: SegmentDef = { type: 'narrow-left', length: 15, lanes: [false, true, true] };
+const NARROW_R: SegmentDef = { type: 'narrow-right', length: 15, lanes: [true, true, false] };
+const NARROW_C: SegmentDef = { type: 'narrow-center', length: 12, lanes: [false, true, false] };
+
+function pickSegment(seed: number, index: number): SegmentDef {
+  const rng = mulberry32(seed ^ (index * 31337));
+  rng(); rng();
+  const roll = rng();
+  const difficulty = Math.min(index / 50, 1);
+
+  if (index < 3) return { ...STRAIGHT };
+
+  const straightChance = 0.70 - 0.50 * difficulty;
+  const gapChance = 0.15 + 0.10 * difficulty;
+  const rampChance = 0.10 + 0.10 * difficulty;
+
+  if (roll < straightChance) {
+    const len = 15 + Math.floor(rng() * 15);
+    return { ...STRAIGHT, length: len };
+  } else if (roll < straightChance + gapChance) {
+    const gapLen = 4 + Math.floor(difficulty * 4);
+    return { ...GAP, gapLength: gapLen };
+  } else if (roll < straightChance + gapChance + rampChance) {
+    return { ...RAMP };
+  } else {
+    const narrowRoll = rng();
+    if (narrowRoll < 0.33) return { ...NARROW_L };
+    if (narrowRoll < 0.66) return { ...NARROW_R };
+    return { ...NARROW_C };
+  }
+}
+
+export function createTrackGenerator(seed: number): TrackGeneratorState {
+  return { seed, nextZ: 0, nextIndex: 0, segments: [] };
+}
+
+export function updateTrack(
+  state: TrackGeneratorState,
+  playerZ: number,
+  lookAhead: number = 200,
+  bufferBehind: number = 50,
+): void {
+  while (state.nextZ < playerZ + lookAhead) {
+    const def = pickSegment(state.seed, state.nextIndex);
+    state.segments.push({
+      def,
+      startZ: state.nextZ,
+      endZ: state.nextZ + def.length,
+      index: state.nextIndex,
+    });
+    state.nextZ += def.length;
+    state.nextIndex++;
+  }
+  state.segments = state.segments.filter(s => s.endZ > playerZ - bufferBehind);
+}
+
+// ---------------------------------------------------------------------------
+// Three.js Rendering
+// ---------------------------------------------------------------------------
+
+export interface TrackSegmentData {
+  type: string;
+  startZ: number;
+  endZ: number;
+  length: number;
+  lanes: [boolean, boolean, boolean];
+  gapLength?: number;
+  rampHeight?: number;
+  index: number;
+}
+
+const LANE_WIDTH = 2;
+const TRACK_WIDTH = LANE_WIDTH * 3; // 6 units total
+const TRACK_THICKNESS = 0.3;
+
+// Materials (reused across segments)
+const trackMaterial = new THREE.MeshStandardMaterial({ color: 0x334455, roughness: 0.8 });
+const rampMaterial = new THREE.MeshStandardMaterial({ color: 0x446655, roughness: 0.7 });
+const laneDividerMaterial = new THREE.MeshStandardMaterial({ color: 0x556677, roughness: 0.5 });
+
+/**
+ * Build a Three.js group containing the track visual for a single segment.
+ */
+export function buildSegmentMesh(seg: TrackSegmentData): THREE.Group {
+  const group = new THREE.Group();
+  group.userData.segmentIndex = seg.index;
+
+  if (seg.type === 'gap') {
+    // Two platform halves with a gap in the middle
+    const halfLen = (seg.length - (seg.gapLength ?? 6)) / 2;
+    if (halfLen > 0) {
+      const geo1 = new THREE.BoxGeometry(TRACK_WIDTH, TRACK_THICKNESS, halfLen);
+      const mesh1 = new THREE.Mesh(geo1, trackMaterial);
+      mesh1.position.set(0, -TRACK_THICKNESS / 2, seg.startZ + halfLen / 2);
+      group.add(mesh1);
+
+      const geo2 = new THREE.BoxGeometry(TRACK_WIDTH, TRACK_THICKNESS, halfLen);
+      const mesh2 = new THREE.Mesh(geo2, trackMaterial);
+      mesh2.position.set(0, -TRACK_THICKNESS / 2, seg.endZ - halfLen / 2);
+      group.add(mesh2);
+    }
+  } else if (seg.type === 'ramp') {
+    // Base platform
+    const geo = new THREE.BoxGeometry(TRACK_WIDTH, TRACK_THICKNESS, seg.length);
+    const mesh = new THREE.Mesh(geo, rampMaterial);
+    mesh.position.set(0, -TRACK_THICKNESS / 2, (seg.startZ + seg.endZ) / 2);
+    group.add(mesh);
+
+    // Ramp peak indicator
+    if (seg.rampHeight) {
+      const peakGeo = new THREE.BoxGeometry(TRACK_WIDTH, seg.rampHeight, 2);
+      const peakMesh = new THREE.Mesh(peakGeo, rampMaterial);
+      peakMesh.position.set(0, seg.rampHeight / 2 - TRACK_THICKNESS, (seg.startZ + seg.endZ) / 2);
+      group.add(peakMesh);
+    }
+  } else if (seg.type.startsWith('narrow')) {
+    // Build only the active lanes
+    for (let i = 0; i < 3; i++) {
+      if (!seg.lanes[i]) continue;
+      const laneX = (i - 1) * LANE_WIDTH;
+      const geo = new THREE.BoxGeometry(LANE_WIDTH, TRACK_THICKNESS, seg.length);
+      const mesh = new THREE.Mesh(geo, trackMaterial);
+      mesh.position.set(laneX, -TRACK_THICKNESS / 2, (seg.startZ + seg.endZ) / 2);
+      group.add(mesh);
+    }
+  } else {
+    // Straight — full width platform
+    const geo = new THREE.BoxGeometry(TRACK_WIDTH, TRACK_THICKNESS, seg.length);
+    const mesh = new THREE.Mesh(geo, trackMaterial);
+    mesh.position.set(0, -TRACK_THICKNESS / 2, (seg.startZ + seg.endZ) / 2);
+    group.add(mesh);
+  }
+
+  // Lane divider lines
+  for (let i = 0; i < 2; i++) {
+    const x = (i === 0 ? -1 : 1) * LANE_WIDTH / 2;
+    if (!seg.lanes[i] || !seg.lanes[i + 1]) continue;
+    if (seg.type === 'gap') continue;
+    const divGeo = new THREE.BoxGeometry(0.05, TRACK_THICKNESS + 0.01, seg.length);
+    const divMesh = new THREE.Mesh(divGeo, laneDividerMaterial);
+    divMesh.position.set(x, 0, (seg.startZ + seg.endZ) / 2);
+    group.add(divMesh);
+  }
+
+  return group;
+}
+
+/**
+ * Dispose a segment mesh group and its geometries.
+ */
+export function disposeSegmentMesh(group: THREE.Group): void {
+  group.traverse((child) => {
+    if (child instanceof THREE.Mesh) {
+      child.geometry.dispose();
+    }
+  });
+}
+
+/**
+ * Build the full runner scene group (lighting).
+ */
+export function buildRunnerScene(): THREE.Group {
+  const group = new THREE.Group();
+
+  const ambient = new THREE.AmbientLight(0xaabbcc, 0.6);
+  group.add(ambient);
+
+  const dirLight = new THREE.DirectionalLight(0xffffff, 0.8);
+  dirLight.position.set(0, 20, -10);
+  group.add(dirLight);
+
+  return group;
+}
+
+export function disposeRunnerScene(group: THREE.Group): void {
+  group.traverse((child) => {
+    if (child instanceof THREE.Mesh) {
+      child.geometry.dispose();
+    }
+  });
+}

package/template/apps/client/src/renderer/shaders/SkyShader.ts

@@ -0,0 +1,190 @@
+/**
+ * @file renderer/shaders/SkyShader.ts
+ * Procedural gradient sky dome — replaces solid scene background color.
+ *
+ * A large inside-facing sphere with a GLSL shader that blends between
+ * a top color and a horizon color based on the normalized world-space Y.
+ */
+
+import * as THREE from 'three';
+
+const vertexShader = /* glsl */ `
+varying vec3 vWorldPos;
+void main() {
+  vWorldPos = (modelMatrix * vec4(position, 1.0)).xyz;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+
+const fragmentShader = /* glsl */ `
+uniform vec3 u_topColor;
+uniform vec3 u_horizonColor;
+uniform float u_offset;
+uniform float u_time;
+uniform vec3 u_sunDirection;
+uniform float u_sunEnabled;
+uniform float u_cloudsEnabled;
+varying vec3 vWorldPos;
+
+// Simple hash-based noise for clouds
+vec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec2 mod289(vec2 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec3 permute(vec3 x) { return mod289(((x * 34.0) + 1.0) * x); }
+
+float snoise2D(vec2 v) {
+  const vec4 C = vec4(0.211324865405187, 0.366025403784439,
+                     -0.577350269189626, 0.024390243902439);
+  vec2 i  = floor(v + dot(v, C.yy));
+  vec2 x0 = v - i + dot(i, C.xx);
+  vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+  vec4 x12 = x0.xyxy + C.xxzz;
+  x12.xy -= i1;
+  i = mod289(i);
+  vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));
+  vec3 m = max(0.5 - vec3(dot(x0,x0), dot(x12.xy,x12.xy), dot(x12.zw,x12.zw)), 0.0);
+  m = m * m; m = m * m;
+  vec3 x = 2.0 * fract(p * C.www) - 1.0;
+  vec3 h = abs(x) - 0.5;
+  vec3 ox = floor(x + 0.5);
+  vec3 a0 = x - ox;
+  m *= 1.79284291400159 - 0.85373472095314 * (a0*a0 + h*h);
+  vec3 g;
+  g.x = a0.x * x0.x + h.x * x0.y;
+  g.yz = a0.yz * x12.xz + h.yz * x12.yw;
+  return 130.0 * dot(m, g);
+}
+
+float fbm(vec2 p) {
+  float f = 0.0;
+  f += 0.5000 * snoise2D(p); p *= 2.02;
+  f += 0.2500 * snoise2D(p); p *= 2.03;
+  f += 0.1250 * snoise2D(p); p *= 2.01;
+  f += 0.0625 * snoise2D(p);
+  return f / 0.9375;
+}
+
+void main() {
+  vec3 dir = normalize(vWorldPos);
+  float h = dir.y;
+  float t = clamp(h + u_offset, 0.0, 1.0);
+  vec3 skyColor = mix(u_horizonColor, u_topColor, t);
+
+  // Sun disc + glow
+  if (u_sunEnabled > 0.5) {
+    float sunDot = max(dot(dir, u_sunDirection), 0.0);
+    // Sharp disc
+    float sunDisc = smoothstep(0.9995, 0.9998, sunDot);
+    vec3 sunColor = vec3(1.0, 0.95, 0.8);
+    skyColor = mix(skyColor, sunColor, sunDisc);
+    // Soft glow
+    float sunGlow = pow(sunDot, 64.0) * 0.4;
+    skyColor += vec3(1.0, 0.8, 0.5) * sunGlow;
+    // Horizon scatter near sun
+    float horizonGlow = pow(sunDot, 8.0) * max(0.0, 1.0 - abs(h) * 4.0) * 0.3;
+    skyColor += vec3(1.0, 0.6, 0.3) * horizonGlow;
+  }
+
+  // Procedural clouds
+  if (u_cloudsEnabled > 0.5 && h > 0.0) {
+    // Project onto a dome
+    vec2 cloudUV = dir.xz / (h + 0.1) * 0.3;
+    float drift = u_time * 0.01;
+    float n = fbm(cloudUV + vec2(drift, drift * 0.5));
+    // Shape clouds: threshold + soft edges
+    float cloud = smoothstep(0.1, 0.5, n);
+    // Fade at horizon to avoid hard cutoff
+    float horizonFade = smoothstep(0.0, 0.15, h);
+    cloud *= horizonFade * 0.7;
+    // Cloud color: bright white, slightly shaded
+    vec3 cloudColor = vec3(1.0, 1.0, 1.0);
+    if (u_sunEnabled > 0.5) {
+      float sunLight = max(dot(dir, u_sunDirection), 0.0);
+      cloudColor = mix(vec3(0.8, 0.85, 0.9), vec3(1.0, 1.0, 0.98), sunLight);
+    }
+    skyColor = mix(skyColor, cloudColor, cloud);
+  }
+
+  gl_FragColor = vec4(skyColor, 1.0);
+}
+`;
+
+export interface SkyColors {
+  top: string;
+  horizon: string;
+  /** 0–1: how far above the equator the horizon line sits. Default 0.1 */
+  offset?: number;
+  /** Enable sun disc + glow. Default false. */
+  sun?: boolean;
+  /** Sun direction (normalized). Default: upper-right. */
+  sunDirection?: [number, number, number];
+  /** Enable procedural clouds. Default false. */
+  clouds?: boolean;
+}
+
+const SKY_PRESETS: Record<string, SkyColors> = {
+  overworld: { top: '#87ceeb', horizon: '#ddeeff', offset: 0.15, sun: true, clouds: true, sunDirection: [0.4, 0.7, 0.3] },
+  dungeon:   { top: '#0a0010', horizon: '#050005', offset: 0.05 },
+};
+
+export class SkyMesh {
+  private mesh: THREE.Mesh;
+  private uniforms: {
+    u_topColor: { value: THREE.Color };
+    u_horizonColor: { value: THREE.Color };
+    u_offset: { value: number };
+    u_time: { value: number };
+    u_sunDirection: { value: THREE.Vector3 };
+    u_sunEnabled: { value: number };
+    u_cloudsEnabled: { value: number };
+  };
+
+  constructor(scene: THREE.Scene) {
+    this.uniforms = {
+      u_topColor:       { value: new THREE.Color('#87ceeb') },
+      u_horizonColor:   { value: new THREE.Color('#ddeeff') },
+      u_offset:         { value: 0.15 },
+      u_time:           { value: 0 },
+      u_sunDirection:   { value: new THREE.Vector3(0.4, 0.7, 0.3).normalize() },
+      u_sunEnabled:     { value: 0 },
+      u_cloudsEnabled:  { value: 0 },
+    };
+
+    const geo = new THREE.SphereGeometry(500, 32, 16);
+    const mat = new THREE.ShaderMaterial({
+      vertexShader,
+      fragmentShader,
+      uniforms: this.uniforms,
+      side: THREE.BackSide,
+      depthWrite: false,
+    });
+
+    this.mesh = new THREE.Mesh(geo, mat);
+    scene.add(this.mesh);
+  }
+
+  /** Call each frame with elapsed time in seconds. */
+  tick(time: number): void {
+    this.uniforms.u_time.value = time;
+  }
+
+  setSkyColors(colors: SkyColors): void {
+    this.uniforms.u_topColor.value.set(colors.top);
+    this.uniforms.u_horizonColor.value.set(colors.horizon);
+    this.uniforms.u_offset.value = colors.offset ?? 0.1;
+    this.uniforms.u_sunEnabled.value = colors.sun ? 1 : 0;
+    this.uniforms.u_cloudsEnabled.value = colors.clouds ? 1 : 0;
+    if (colors.sunDirection) {
+      this.uniforms.u_sunDirection.value.set(...colors.sunDirection).normalize();
+    }
+  }
+
+  setSkyForArea(areaId: string): void {
+    const preset = SKY_PRESETS[areaId] ?? SKY_PRESETS['dungeon'];
+    this.setSkyColors(preset);
+  }
+
+  dispose(): void {
+    this.mesh.geometry.dispose();
+    (this.mesh.material as THREE.Material).dispose();
+  }
+}