@loonylabs/create-game 0.1.0

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

@@ -0,0 +1,133 @@
+/**
+ * @file TerrainShaderMaterial.ts
+ * Custom ShaderMaterial for voxel terrain with procedural noise,
+ * material blending, height tinting, normal perturbation, and LOD.
+ */
+
+import * as THREE from 'three';
+import { TERRAIN_VERT_SHADER } from './terrain.vert.glsl.js';
+import { TERRAIN_FRAG_SHADER } from './terrain.frag.glsl.js';
+
+export interface VoxelMaterialVisual {
+  color: [number, number, number]; // RGB 0-1
+  noiseScale: number;
+  noiseStrength: number;
+  noiseType?: 'fbm' | 'cellular' | 'ridged';
+  fbmOctaves?: number;
+  fbmLacunarity?: number;
+  fbmGain?: number;
+  heightTintLow?: [number, number, number];
+  heightTintHigh?: [number, number, number];
+  bumpStrength?: number;
+}
+
+const QUALITY_PRESETS = [
+  { lodNear: 16, lodMid: 32 },   // Low
+  { lodNear: 32, lodMid: 64 },   // Medium
+  { lodNear: 48, lodMid: 96 },   // High
+  { lodNear: 80, lodMid: 160 },  // Ultra
+];
+
+/**
+ * Procedural terrain material using custom GLSL shaders.
+ * Supports up to 8 material types with per-material noise,
+ * smooth blending, height tinting, normal perturbation, and LOD.
+ */
+export class TerrainShaderMaterial extends THREE.ShaderMaterial {
+  constructor(
+    materialVisuals: Record<number, VoxelMaterialVisual>,
+    options?: {
+      slopeThreshold?: number;
+      fogColor?: THREE.Color;
+      fogDensity?: number;
+      blendNoiseScale?: number;
+      blendNoiseStrength?: number;
+      heightTintRange?: number;
+      qualityLevel?: number;
+    },
+  ) {
+    // Pack per-material uniform arrays (8 materials max)
+    const colorArray: THREE.Color[] = [];
+    const noiseTypes: number[] = [];
+    const noiseScales: number[] = [];
+    const noiseStrengths: number[] = [];
+    const fbmOctaves: number[] = [];
+    const fbmLacunarities: number[] = [];
+    const fbmGains: number[] = [];
+    const heightTintLows: THREE.Color[] = [];
+    const heightTintHighs: THREE.Color[] = [];
+    const bumpStrengths: number[] = [];
+
+    const typeMap: Record<string, number> = { fbm: 0, cellular: 1, ridged: 2 };
+    const zeroTint = [0, 0, 0] as [number, number, number];
+
+    for (let i = 0; i < 8; i++) {
+      const v = materialVisuals[i];
+      if (v) {
+        colorArray.push(new THREE.Color(v.color[0], v.color[1], v.color[2]));
+        noiseTypes.push(typeMap[v.noiseType ?? 'fbm'] ?? 0);
+        noiseScales.push(v.noiseScale);
+        noiseStrengths.push(v.noiseStrength);
+        fbmOctaves.push(v.fbmOctaves ?? 3);
+        fbmLacunarities.push(v.fbmLacunarity ?? 2.0);
+        fbmGains.push(v.fbmGain ?? 0.5);
+        const lo = v.heightTintLow ?? zeroTint;
+        const hi = v.heightTintHigh ?? zeroTint;
+        heightTintLows.push(new THREE.Color(lo[0], lo[1], lo[2]));
+        heightTintHighs.push(new THREE.Color(hi[0], hi[1], hi[2]));
+        bumpStrengths.push(v.bumpStrength ?? 0.0);
+      } else {
+        colorArray.push(new THREE.Color(1, 0, 1));
+        noiseTypes.push(0);
+        noiseScales.push(0.5);
+        noiseStrengths.push(0.15);
+        fbmOctaves.push(3);
+        fbmLacunarities.push(2.0);
+        fbmGains.push(0.5);
+        heightTintLows.push(new THREE.Color(0, 0, 0));
+        heightTintHighs.push(new THREE.Color(0, 0, 0));
+        bumpStrengths.push(0.0);
+      }
+    }
+
+    const quality = options?.qualityLevel ?? 2;
+    const preset = QUALITY_PRESETS[quality] ?? QUALITY_PRESETS[2];
+
+    super({
+      vertexShader: TERRAIN_VERT_SHADER,
+      fragmentShader: TERRAIN_FRAG_SHADER,
+      uniforms: {
+        uMaterialColors: { value: colorArray },
+        uNoiseTypes: { value: noiseTypes },
+        uNoiseScales: { value: noiseScales },
+        uNoiseStrengths: { value: noiseStrengths },
+        uFbmOctaves: { value: fbmOctaves },
+        uFbmLacunarity: { value: fbmLacunarities },
+        uFbmGain: { value: fbmGains },
+        uHeightTintLow: { value: heightTintLows },
+        uHeightTintHigh: { value: heightTintHighs },
+        uHeightTintRange: { value: options?.heightTintRange ?? 64.0 },
+        uBlendNoiseScale: { value: options?.blendNoiseScale ?? 2.0 },
+        uBlendNoiseStrength: { value: options?.blendNoiseStrength ?? 0.6 },
+        uBumpStrengths: { value: bumpStrengths },
+        uQualityLevel: { value: quality },
+        uLodDistances: { value: new THREE.Vector2(preset.lodNear, preset.lodMid) },
+        uSlopeThreshold: { value: options?.slopeThreshold ?? 0.5 },
+        uTime: { value: 0 },
+        uFogColor: { value: options?.fogColor ?? new THREE.Color(0.7, 0.8, 0.9) },
+        uFogDensity: { value: options?.fogDensity ?? 0.015 },
+      },
+      fog: false,
+    });
+  }
+
+  /** Update time and quality-dependent uniforms each frame. */
+  tick(time: number, qualityLevel?: number): void {
+    this.uniforms['uTime'].value = time;
+    if (qualityLevel !== undefined) {
+      this.uniforms['uQualityLevel'].value = qualityLevel;
+      const preset = QUALITY_PRESETS[qualityLevel] ?? QUALITY_PRESETS[2];
+      (this.uniforms['uLodDistances'].value as THREE.Vector2).set(preset.lodNear, preset.lodMid);
+    }
+  }
+}

package/template/apps/client/src/renderer/shaders/floor.frag.glsl.ts

@@ -0,0 +1,17 @@
+import { NOISE_GLSL } from '@loonylabs/gamedev-client';
+
+/** Fragment shader for floor/door cells. Fine stone-slab noise pattern. */
+export const FLOOR_FRAG_SHADER = /* glsl */`
+uniform vec3 u_baseColor;
+uniform float u_noiseScale;
+varying vec2 v_uv;
+
+${NOISE_GLSL}
+
+void main() {
+  float n  = valueNoise(v_uv * u_noiseScale);
+  float n2 = valueNoise(v_uv * u_noiseScale * 3.0) * 0.3;
+  vec3 color = u_baseColor * (0.7 + n * 0.3 + n2);
+  gl_FragColor = vec4(color, 1.0);
+}
+`;

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

@@ -0,0 +1,18 @@
+import * as THREE from 'three';
+import type { ShaderConfig } from '@loonylabs/gamedev-client';
+import { FLOOR_FRAG_SHADER } from './floor.frag.glsl.js';
+import { WALL_FRAG_SHADER } from './wall.frag.glsl.js';
+import { SPAWN_FRAG_SHADER } from './spawn.frag.glsl.js';
+
+/** Game-specific shader config with optional glow color. */
+export interface DungeonShaderEntry extends ShaderConfig {
+  glowColor?: THREE.Color;
+}
+
+/** Game-specific shader configurations keyed by cell type. */
+export const DUNGEON_SHADERS: Record<string, DungeonShaderEntry> = {
+  floor: { fragmentShader: FLOOR_FRAG_SHADER, noiseScale: 6.0 },
+  wall:  { fragmentShader: WALL_FRAG_SHADER,  noiseScale: 3.0 },
+  spawn: { fragmentShader: SPAWN_FRAG_SHADER, noiseScale: 4.0, glowColor: new THREE.Color(0xffcc44) },
+  door:  { fragmentShader: FLOOR_FRAG_SHADER, noiseScale: 5.0 },
+};

package/template/apps/client/src/renderer/shaders/spawn.frag.glsl.ts

@@ -0,0 +1,19 @@
+import { NOISE_GLSL } from '@loonylabs/gamedev-client';
+
+/** Fragment shader for spawn cell. Pulsing emissive gold glow over stone base. */
+export const SPAWN_FRAG_SHADER = /* glsl */`
+uniform vec3 u_baseColor;
+uniform vec3 u_glowColor;
+uniform float u_noiseScale;
+uniform float u_time;
+varying vec2 v_uv;
+
+${NOISE_GLSL}
+
+void main() {
+  float n = valueNoise(v_uv * u_noiseScale);
+  float pulse = sin(u_time * 2.0) * 0.5 + 0.5;
+  vec3 color = mix(u_baseColor * (0.7 + n * 0.3), u_glowColor, pulse * 0.4 + n * 0.1);
+  gl_FragColor = vec4(color, 1.0);
+}
+`;

package/template/apps/client/src/renderer/shaders/terrain.frag.glsl.ts

@@ -0,0 +1,314 @@
+/**
+ * Terrain fragment shader — procedural material rendering.
+ *
+ * Features:
+ * - Per-material noise type: FBM, Cellular (Voronoi), or Ridged
+ * - Smooth material blending with noise-perturbed transitions
+ * - Height-based color tinting per material
+ * - Normal perturbation for surface bumps (per-material bumpStrength)
+ * - Distance-based LOD (fewer octaves + skip perturbation at distance)
+ * - Quality level control (Low/Medium/High/Ultra)
+ * - Slope-based rock blending
+ */
+export const TERRAIN_FRAG_SHADER = /* glsl */ `
+precision highp float;
+
+uniform vec3 uMaterialColors[8];
+uniform float uNoiseTypes[8];     // 0.0=fbm, 1.0=cellular, 2.0=ridged
+uniform float uNoiseScales[8];
+uniform float uNoiseStrengths[8];
+uniform float uFbmOctaves[8];
+uniform float uFbmLacunarity[8];
+uniform float uFbmGain[8];
+uniform vec3 uHeightTintLow[8];
+uniform vec3 uHeightTintHigh[8];
+uniform float uHeightTintRange;
+uniform float uBlendNoiseScale;
+uniform float uBlendNoiseStrength;
+uniform float uBumpStrengths[8];
+uniform float uQualityLevel;      // 0=low, 1=medium, 2=high, 3=ultra
+uniform vec2 uLodDistances;       // x=near, y=mid
+uniform float uSlopeThreshold;
+uniform float uTime;
+uniform vec3 uFogColor;
+uniform float uFogDensity;
+
+varying vec3 vWorldPosition;
+varying vec3 vNormal;
+varying float vMaterialIndex;
+
+// ---- Simplex-like noise (hash-based, fast) ----
+
+vec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec4 mod289(vec4 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec4 permute(vec4 x) { return mod289(((x * 34.0) + 1.0) * x); }
+vec4 taylorInvSqrt(vec4 r) { return 1.79284291400159 - 0.85373472095314 * r; }
+
+float snoise(vec3 v) {
+  const vec2 C = vec2(1.0 / 6.0, 1.0 / 3.0);
+  const vec4 D = vec4(0.0, 0.5, 1.0, 2.0);
+
+  vec3 i  = floor(v + dot(v, C.yyy));
+  vec3 x0 = v - i + dot(i, C.xxx);
+
+  vec3 g = step(x0.yzx, x0.xyz);
+  vec3 l = 1.0 - g;
+  vec3 i1 = min(g.xyz, l.zxy);
+  vec3 i2 = max(g.xyz, l.zxy);
+
+  vec3 x1 = x0 - i1 + C.xxx;
+  vec3 x2 = x0 - i2 + C.yyy;
+  vec3 x3 = x0 - D.yyy;
+
+  i = mod289(i);
+  vec4 p = permute(permute(permute(
+    i.z + vec4(0.0, i1.z, i2.z, 1.0))
+    + i.y + vec4(0.0, i1.y, i2.y, 1.0))
+    + i.x + vec4(0.0, i1.x, i2.x, 1.0));
+
+  float n_ = 0.142857142857;
+  vec3 ns = n_ * D.wyz - D.xzx;
+  vec4 j = p - 49.0 * floor(p * ns.z * ns.z);
+  vec4 x_ = floor(j * ns.z);
+  vec4 y_ = floor(j - 7.0 * x_);
+  vec4 x = x_ * ns.x + ns.yyyy;
+  vec4 y = y_ * ns.x + ns.yyyy;
+  vec4 h = 1.0 - abs(x) - abs(y);
+  vec4 b0 = vec4(x.xy, y.xy);
+  vec4 b1 = vec4(x.zw, y.zw);
+  vec4 s0 = floor(b0) * 2.0 + 1.0;
+  vec4 s1 = floor(b1) * 2.0 + 1.0;
+  vec4 sh = -step(h, vec4(0.0));
+  vec4 a0 = b0.xzyw + s0.xzyw * sh.xxyy;
+  vec4 a1 = b1.xzyw + s1.xzyw * sh.zzww;
+  vec3 p0 = vec3(a0.xy, h.x);
+  vec3 p1 = vec3(a0.zw, h.y);
+  vec3 p2 = vec3(a1.xy, h.z);
+  vec3 p3 = vec3(a1.zw, h.w);
+
+  vec4 norm = taylorInvSqrt(vec4(dot(p0,p0), dot(p1,p1), dot(p2,p2), dot(p3,p3)));
+  p0 *= norm.x; p1 *= norm.y; p2 *= norm.z; p3 *= norm.w;
+
+  vec4 m = max(0.6 - vec4(dot(x0,x0), dot(x1,x1), dot(x2,x2), dot(x3,x3)), 0.0);
+  m = m * m;
+  return 42.0 * dot(m * m, vec4(dot(p0,x0), dot(p1,x1), dot(p2,x2), dot(p3,x3)));
+}
+
+// ---- Hash function for cellular noise ----
+
+vec3 hash33(vec3 p) {
+  p = vec3(
+    dot(p, vec3(127.1, 311.7, 74.7)),
+    dot(p, vec3(269.5, 183.3, 246.1)),
+    dot(p, vec3(113.5, 271.9, 124.6))
+  );
+  return fract(sin(p) * 43758.5453123);
+}
+
+// ---- FBM — fractal Brownian motion ----
+
+float fbm(vec3 p, float scale, int octaves, float lacunarity, float gain) {
+  float value = 0.0;
+  float amplitude = 1.0;
+  float frequency = scale;
+  float maxAmp = 0.0;
+  for (int i = 0; i < 6; i++) {
+    if (i >= octaves) break;
+    value += amplitude * snoise(p * frequency);
+    maxAmp += amplitude;
+    frequency *= lacunarity;
+    amplitude *= gain;
+  }
+  return value / maxAmp;
+}
+
+// ---- Cellular / Voronoi noise ----
+
+float cellular(vec3 p, float scale) {
+  vec3 sp = p * scale;
+  vec3 i = floor(sp);
+  vec3 f = fract(sp);
+  float minDist = 1.0;
+  for (int x = -1; x <= 1; x++) {
+    for (int y = -1; y <= 1; y++) {
+      for (int z = -1; z <= 1; z++) {
+        vec3 neighbor = vec3(float(x), float(y), float(z));
+        vec3 point = hash33(i + neighbor);
+        vec3 diff = neighbor + point - f;
+        float d = dot(diff, diff);
+        minDist = min(minDist, d);
+      }
+    }
+  }
+  return sqrt(minDist) * 2.0 - 1.0;
+}
+
+// ---- Ridged noise ----
+
+float ridged(vec3 p, float scale, int octaves, float lacunarity, float gain) {
+  float value = 0.0;
+  float amplitude = 1.0;
+  float frequency = scale;
+  float maxAmp = 0.0;
+  for (int i = 0; i < 6; i++) {
+    if (i >= octaves) break;
+    float n = 1.0 - abs(snoise(p * frequency));
+    value += amplitude * n * n;
+    maxAmp += amplitude;
+    frequency *= lacunarity;
+    amplitude *= gain;
+  }
+  return value / maxAmp * 2.0 - 1.0;
+}
+
+// ---- LOD helpers ----
+
+int getMaxOctaves() {
+  int q = int(uQualityLevel + 0.5);
+  if (q == 0) return 2;
+  if (q == 1) return 3;
+  if (q == 2) return 4;
+  return 6;
+}
+
+int getEffectiveOctaves(int baseOctaves, float dist) {
+  int maxOct = getMaxOctaves();
+  // Far: minimal noise
+  if (dist > uLodDistances.y) return 1;
+  // Mid: reduced
+  if (dist > uLodDistances.x) return min(baseOctaves, max(maxOct - 2, 1));
+  // Near: full
+  return min(baseOctaves, maxOct);
+}
+
+bool shouldPerturb(float dist) {
+  return uQualityLevel >= 1.5 && dist < uLodDistances.x;
+}
+
+bool shouldBlend(float dist) {
+  return uQualityLevel >= 0.5 && dist < uLodDistances.y;
+}
+
+// ---- Per-material noise dispatch (LOD-aware) ----
+
+float getNoiseForMaterial(int matIdx, vec3 worldPos, float dist) {
+  float scale = uNoiseScales[matIdx];
+  int noiseType = int(uNoiseTypes[matIdx] + 0.5);
+  int baseOctaves = int(uFbmOctaves[matIdx] + 0.5);
+  int octaves = getEffectiveOctaves(baseOctaves, dist);
+  float lac = uFbmLacunarity[matIdx];
+  float gain = uFbmGain[matIdx];
+
+  float n;
+  if (noiseType == 1) {
+    // Cellular is expensive — skip at far distance
+    if (dist > uLodDistances.y) {
+      n = snoise(worldPos * scale);
+    } else {
+      n = cellular(worldPos, scale);
+    }
+  } else if (noiseType == 2) {
+    n = ridged(worldPos, scale, octaves, lac, gain);
+  } else {
+    n = fbm(worldPos, scale, octaves, lac, gain);
+  }
+  return n * uNoiseStrengths[matIdx];
+}
+
+// ---- Height tint ----
+
+vec3 applyHeightTint(vec3 color, int matIdx, float worldY) {
+  float heightFactor = clamp(worldY / uHeightTintRange, 0.0, 1.0);
+  vec3 tint = mix(uHeightTintLow[matIdx], uHeightTintHigh[matIdx], heightFactor);
+  return color * (1.0 + tint);
+}
+
+// ---- Full material color ----
+
+vec3 getMaterialColor(int matIdx, vec3 worldPos, float dist) {
+  vec3 base = uMaterialColors[matIdx];
+  float noise = getNoiseForMaterial(matIdx, worldPos, dist);
+  base *= 1.0 + noise;
+  base = applyHeightTint(base, matIdx, worldPos.y);
+  return base;
+}
+
+// ---- Material blending (LOD-aware) ----
+
+vec3 blendMaterials(float rawMatIdx, vec3 worldPos, float dist) {
+  int matA = clamp(int(floor(rawMatIdx)), 0, 7);
+  int matB = clamp(matA + 1, 0, 7);
+  float blendFactor = fract(rawMatIdx);
+
+  // No fractional part or blending disabled — single material
+  if (blendFactor < 0.01 || !shouldBlend(dist)) {
+    return getMaterialColor(matA, worldPos, dist);
+  }
+
+  // Noise-perturb the blend boundary for organic, irregular edges
+  float blendNoise = snoise(worldPos * uBlendNoiseScale) * 0.5 + 0.5;
+  blendFactor = smoothstep(0.2, 0.8, blendFactor + (blendNoise - 0.5) * uBlendNoiseStrength);
+
+  vec3 colorA = getMaterialColor(matA, worldPos, dist);
+  vec3 colorB = getMaterialColor(matB, worldPos, dist);
+  return mix(colorA, colorB, blendFactor);
+}
+
+// ---- Normal perturbation ----
+
+vec3 perturbNormal(vec3 normal, vec3 worldPos, int matIdx, float bumpStr) {
+  float eps = 0.1;
+  float scale = uNoiseScales[matIdx] * 2.0;
+
+  // Finite differences: sample noise at 6 offset positions
+  float nx = snoise((worldPos + vec3(eps, 0.0, 0.0)) * scale)
+           - snoise((worldPos - vec3(eps, 0.0, 0.0)) * scale);
+  float ny = snoise((worldPos + vec3(0.0, eps, 0.0)) * scale)
+           - snoise((worldPos - vec3(0.0, eps, 0.0)) * scale);
+  float nz = snoise((worldPos + vec3(0.0, 0.0, eps)) * scale)
+           - snoise((worldPos - vec3(0.0, 0.0, eps)) * scale);
+
+  vec3 grad = vec3(nx, ny, nz) * bumpStr;
+  return normalize(normal + grad);
+}
+
+void main() {
+  float dist = length(vWorldPosition - cameraPosition);
+
+  // 1. Blend between adjacent materials (LOD-aware)
+  vec3 baseColor = blendMaterials(vMaterialIndex, vWorldPosition, dist);
+
+  // 2. Slope-based rock override with noise-perturbed boundary
+  float slope = 1.0 - vNormal.y;
+  float slopeNoise = snoise(vWorldPosition * 1.5) * 0.15;
+  float rockBlend = smoothstep(uSlopeThreshold - 0.15, uSlopeThreshold + 0.25, slope + slopeNoise);
+  if (rockBlend > 0.0) {
+    vec3 rockColor = getMaterialColor(3, vWorldPosition, dist);
+    baseColor = mix(baseColor, rockColor, rockBlend);
+  }
+
+  // 3. Normal perturbation for lighting (near + high quality only)
+  vec3 lightNormal = vNormal;
+  if (shouldPerturb(dist)) {
+    int matIdx = clamp(int(floor(vMaterialIndex + 0.5)), 0, 7);
+    float bumpStr = uBumpStrengths[matIdx];
+    if (bumpStr > 0.0) {
+      // Fade perturbation smoothly toward LOD boundary
+      float perturbFade = 1.0 - smoothstep(uLodDistances.x * 0.7, uLodDistances.x, dist);
+      lightNormal = perturbNormal(vNormal, vWorldPosition, matIdx, bumpStr * perturbFade);
+    }
+  }
+
+  // 4. Lighting: directional sun + ambient (uses perturbed normal)
+  vec3 lightDir = normalize(vec3(0.5, 1.0, 0.3));
+  float diffuse = max(dot(lightNormal, lightDir), 0.0);
+  vec3 ambient = baseColor * 0.4;
+  vec3 lit = ambient + baseColor * diffuse * 0.6;
+
+  // 5. Fog (exponential, matches scene fog)
+  float fogFactor = 1.0 - exp(-uFogDensity * gl_FragCoord.z / gl_FragCoord.w);
+  lit = mix(lit, uFogColor, clamp(fogFactor, 0.0, 1.0));
+
+  gl_FragColor = vec4(lit, 1.0);
+}
+`;

package/template/apps/client/src/renderer/shaders/terrain.vert.glsl.ts

@@ -0,0 +1,16 @@
+/** Terrain vertex shader — passes world position, normal, and material index to fragment. */
+export const TERRAIN_VERT_SHADER = /* glsl */ `
+attribute float materialIndex;
+
+varying vec3 vWorldPosition;
+varying vec3 vNormal;
+varying float vMaterialIndex;
+
+void main() {
+  vec4 worldPos = modelMatrix * vec4(position, 1.0);
+  vWorldPosition = worldPos.xyz;
+  vNormal = normalize(mat3(modelMatrix) * normal);
+  vMaterialIndex = materialIndex;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;

package/template/apps/client/src/renderer/shaders/wall.frag.glsl.ts

@@ -0,0 +1,20 @@
+import { NOISE_GLSL } from '@loonylabs/gamedev-client';
+
+/** Fragment shader for wall cells. Coarser noise, brick-like dark palette. */
+export const WALL_FRAG_SHADER = /* glsl */`
+uniform vec3 u_baseColor;
+uniform float u_noiseScale;
+varying vec2 v_uv;
+
+${NOISE_GLSL}
+
+void main() {
+  float n  = valueNoise(v_uv * u_noiseScale);
+  float n2 = valueNoise(v_uv * u_noiseScale * 2.0) * 0.2;
+  // Subtle horizontal brick lines
+  float brick = smoothstep(0.45, 0.5, fract(v_uv.y * 0.5 + floor(v_uv.x) * 0.5));
+  float brightness = 0.6 + n * 0.25 + n2 - brick * 0.1;
+  vec3 color = u_baseColor * brightness;
+  gl_FragColor = vec4(color, 1.0);
+}
+`;

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

@@ -0,0 +1,102 @@
+/**
+ * @file renderer/shooterArena.ts
+ * Builds Three.js meshes for the Shooter arena from server payload data.
+ */
+
+import * as THREE from 'three';
+
+interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+interface AABB {
+  min: Vec3;
+  max: Vec3;
+}
+
+interface CoverBlock {
+  position: Vec3;
+  width: number;
+  depth: number;
+  height: number;
+  aabb: AABB;
+}
+
+export interface ArenaPayload {
+  arena: {
+    width: number;
+    depth: number;
+    walls: AABB[];
+    covers: CoverBlock[];
+    spawnPoints: Vec3[];
+  };
+}
+
+/**
+ * Build the arena scene group from EXPERIENCE_CHANGE payload data.
+ * Returns a disposable THREE.Group containing floor, walls, covers, and lighting.
+ */
+export function buildArenaScene(payload: ArenaPayload): THREE.Group {
+  const group = new THREE.Group();
+
+  // Floor
+  const floorGeo = new THREE.PlaneGeometry(payload.arena.width, payload.arena.depth);
+  const floorMat = new THREE.MeshStandardMaterial({ color: 0x333333, roughness: 0.9 });
+  const floor = new THREE.Mesh(floorGeo, floorMat);
+  floor.rotation.x = -Math.PI / 2;
+  group.add(floor);
+
+  // Walls
+  for (const wall of payload.arena.walls) {
+    const w = wall.max.x - wall.min.x;
+    const h = wall.max.y - wall.min.y;
+    const d = wall.max.z - wall.min.z;
+    const geo = new THREE.BoxGeometry(w, h, d);
+    const mat = new THREE.MeshStandardMaterial({ color: 0x555555 });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.position.set(
+      (wall.min.x + wall.max.x) / 2,
+      (wall.min.y + wall.max.y) / 2,
+      (wall.min.z + wall.max.z) / 2,
+    );
+    group.add(mesh);
+  }
+
+  // Covers
+  for (const cover of payload.arena.covers) {
+    const geo = new THREE.BoxGeometry(cover.width, cover.height, cover.depth);
+    const mat = new THREE.MeshStandardMaterial({ color: 0x886644, roughness: 0.7 });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.position.set(cover.position.x, cover.height / 2, cover.position.z);
+    group.add(mesh);
+  }
+
+  // Ambient light
+  const ambient = new THREE.AmbientLight(0xffffff, 0.5);
+  group.add(ambient);
+
+  // Directional light (sun-like)
+  const dirLight = new THREE.DirectionalLight(0xffffff, 0.8);
+  dirLight.position.set(10, 20, 10);
+  group.add(dirLight);
+
+  return group;
+}
+
+/**
+ * Dispose all geometry and materials in an arena group.
+ */
+export function disposeArenaScene(group: THREE.Group): void {
+  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();
+      }
+    }
+  });
+}