@marble.fun/track-catalog 3.0.0

package/src/three/painted-valley-appearance.ts

@@ -0,0 +1,270 @@
+import {
+  createThemeMaterialSet,
+  type MaterialPatternRecipe,
+  type MaterialRecipe,
+  type ThemeMaterialSlot,
+} from './track-theme'
+
+export const PAINTED_VALLEY_THEME_ID = 'painted-valley'
+export const PAINTED_VALLEY_GRASS_ORANGE_DIRT_PATH_FLOOR_ID =
+  'painted-valley.grass-orange-dirt-path'
+export const PAINTED_VALLEY_GRASS_SHOULDER_MATERIAL_ID = 'painted-valley.grass-shoulder'
+export const PAINTED_VALLEY_TROPICAL_FLOWER_HEDGE_WALL_ID =
+  'painted-valley.tropical-flower-hedge'
+export const LEGACY_JUNGLE_GRASS_DIRT_PATH_FLOOR_ID = 'jungle.grass-dirt-path'
+export const LEGACY_JUNGLE_FLOWER_HEDGE_WALL_ID = 'jungle.flower-hedge'
+
+export const PAINTED_VALLEY_GRASS_ORANGE_DIRT_PATH_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.9,
+  metalness: 0,
+  envMapIntensity: 0.52,
+  textureUrl: '/themes/textures/painted-valley-orange-dirt-v1-albedo.ktx2',
+  normalTextureUrl: '/themes/textures/painted-valley-orange-dirt-v1-normal.ktx2',
+  heightTextureUrl: '/themes/textures/painted-valley-orange-dirt-v1-height.ktx2',
+  roughnessTextureUrl: '/themes/textures/painted-valley-orange-dirt-v1-roughness.ktx2',
+  aoTextureUrl: '/themes/textures/painted-valley-orange-dirt-v1-ao.ktx2',
+  textureWorldSize: [4.8, 4.8],
+  normalScale: [0.58, 0.58],
+  bumpScale: 0.026,
+  aoMapIntensity: 0.52,
+  surfaceTreatment: {
+    kind: 'floor-perimeter-overlay',
+    materialId: PAINTED_VALLEY_GRASS_SHOULDER_MATERIAL_ID,
+    bandWidth: 0.62,
+    featherWidth: 0.36,
+    normalOffset: 0.004,
+  },
+}
+
+export const PAINTED_VALLEY_GRASS_SHOULDER_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.96,
+  metalness: 0,
+  envMapIntensity: 0.45,
+  textureUrl: '/themes/textures/painted-valley-grass-shoulder-v1-albedo.ktx2',
+  normalTextureUrl: '/themes/textures/painted-valley-grass-shoulder-v1-normal.ktx2',
+  heightTextureUrl: '/themes/textures/painted-valley-grass-shoulder-v1-height.ktx2',
+  roughnessTextureUrl: '/themes/textures/painted-valley-grass-shoulder-v1-roughness.ktx2',
+  aoTextureUrl: '/themes/textures/painted-valley-grass-shoulder-v1-ao.ktx2',
+  textureWorldSize: [2.8, 2.8],
+  normalScale: [0.7, 0.7],
+  bumpScale: 0.032,
+  aoMapIntensity: 0.58,
+}
+
+export const PAINTED_VALLEY_TROPICAL_FLOWER_HEDGE_CORE_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#3b5029',
+  roughness: 0.98,
+  metalness: 0,
+  emissive: '#0d180a',
+  emissiveIntensity: 0.24,
+  envMapIntensity: 0.38,
+}
+
+export const PAINTED_VALLEY_BIRCH_PLANK_MATERIAL: MaterialRecipe = {
+  kind: 'toon',
+  color: '#ffffff',
+  roughness: 0.9,
+  metalness: 0,
+  envMapIntensity: 0.72,
+  textureUrl: '/themes/textures/painted-valley-wild-west-birch-planks-v1-albedo.webp',
+  textureWorldSize: [2.4, 2.4],
+  bumpScale: 0.035,
+  gradientSteps: 5,
+  inkColor: '#73654a',
+  inkStrength: 0.055,
+}
+
+export const PAINTED_VALLEY_BIRCH_RANCH_FENCE_MATERIAL: MaterialRecipe = {
+  kind: 'toon',
+  color: '#ffffff',
+  roughness: 0.92,
+  metalness: 0,
+  envMapIntensity: 0.7,
+  textureUrl: '/themes/textures/painted-valley-wild-west-birch-fence-v1-albedo.webp',
+  textureWorldSize: [2.1, 2.1],
+  bumpScale: 0.04,
+  gradientSteps: 5,
+  inkColor: '#716248',
+  inkStrength: 0.06,
+}
+
+const paintedCedar: MaterialPatternRecipe = {
+  kind: 'painted-wood',
+  primary: '#ead7ad',
+  secondary: '#9d7b56',
+  worldSize: [1.4, 4.8],
+}
+
+const paintedStone: MaterialPatternRecipe = {
+  kind: 'painted-stone',
+  primary: '#c4c8a6',
+  secondary: '#728a6d',
+  worldSize: [2.2, 3.4],
+}
+
+const meadowWash: MaterialPatternRecipe = {
+  kind: 'watercolor',
+  primary: '#6f985d',
+  secondary: '#b8bd72',
+  worldSize: [2.6, 2.6],
+}
+
+function paintedToonMaterial(
+  recipe: MaterialRecipe,
+  options: {
+    pattern?: MaterialPatternRecipe
+    gradientSteps?: number
+    inkColor?: string
+    inkStrength?: number
+    transparent?: boolean
+    opacity?: number
+    depthWrite?: boolean
+  } = {},
+): MaterialRecipe {
+  const pattern = options.pattern ?? recipe.pattern
+  return {
+    kind: 'toon',
+    color: pattern ? '#ffffff' : recipe.color,
+    roughness: recipe.roughness,
+    metalness: 0,
+    ...(recipe.emissive ? { emissive: recipe.emissive } : {}),
+    ...(recipe.emissiveIntensity !== undefined ? { emissiveIntensity: recipe.emissiveIntensity } : {}),
+    transparent: options.transparent ?? recipe.transparent,
+    opacity: options.opacity ?? recipe.opacity,
+    depthWrite: options.depthWrite ?? recipe.depthWrite,
+    pattern,
+    bumpScale: recipe.bumpScale,
+    gradientSteps: options.gradientSteps ?? 4,
+    inkColor: options.inkColor ?? '#29352a',
+    inkStrength: options.inkStrength ?? 0.2,
+  }
+}
+
+export function createPaintedValleyMaterials(): Record<ThemeMaterialSlot, MaterialRecipe> {
+  const base = createThemeMaterialSet(
+    {
+      laneSurface: '#edc58d',
+      laneEdge: '#f7ebcf',
+      laneGuard: '#f1e7cf',
+      structure: '#aab7a0',
+      structureSecondary: '#617d79',
+      mechanism: '#91abb0',
+      moving: '#d66a4d',
+      route: '#e4c866',
+      hazard: '#c94432',
+      finish: '#fff0b6',
+      energy: '#78b8c9',
+      portal: '#8a78ad',
+      glass: '#b8d8d5',
+      worldGround: '#7fa45b',
+      worldPrimary: '#82634d',
+      worldSecondary: '#8d987b',
+      foliage: '#4f7f4c',
+      accent: '#cb5338',
+      dark: '#30443d',
+    },
+    {
+      surfacePattern: paintedCedar,
+      surfaceBumpScale: 0.045,
+      guardPattern: paintedCedar,
+      transparentGuardBacking: true,
+      structurePattern: paintedStone,
+      trackRoughness: 0.92,
+      trackMetalness: 0,
+      guardMetalness: 0,
+    },
+  )
+
+  const materials = Object.fromEntries(
+    (Object.entries(base) as [ThemeMaterialSlot, MaterialRecipe][]).map(([slot, recipe]) => [
+      slot,
+      paintedToonMaterial(recipe),
+    ]),
+  ) as Record<ThemeMaterialSlot, MaterialRecipe>
+
+  materials['lane.surface'] = PAINTED_VALLEY_GRASS_ORANGE_DIRT_PATH_MATERIAL
+  materials['lane.edge'] = {
+    ...paintedToonMaterial(base['lane.edge'], {
+      inkColor: '#88775f',
+      inkStrength: 0.05,
+    }),
+    emissive: '#705f45',
+    emissiveIntensity: 0.34,
+  }
+  // The theme-default guard is the same birch stock used by the canonical
+  // short ranch-fence helper. The backing stays transparent and visual-only.
+  materials['lane.guard'] = PAINTED_VALLEY_BIRCH_RANCH_FENCE_MATERIAL
+  materials['lane.guard.backing'] = {
+    ...paintedToonMaterial(base['lane.guard.backing'], {
+      pattern: paintedCedar,
+      inkColor: '#8d8069',
+      inkStrength: 0.035,
+      transparent: true,
+      opacity: 0,
+      depthWrite: false,
+    }),
+    emissive: '#665b48',
+    emissiveIntensity: 0.12,
+  }
+  materials['structure.primary'] = paintedToonMaterial(base['structure.primary'], {
+    pattern: paintedStone,
+    inkColor: '#53685f',
+    inkStrength: 0.1,
+  })
+  materials['structure.secondary'] = paintedToonMaterial(base['structure.secondary'], {
+    inkColor: '#3f5953',
+    inkStrength: 0.12,
+  })
+  materials['mechanism.body'] = paintedToonMaterial(base['mechanism.body'], {
+    pattern: paintedStone,
+    inkColor: '#4a6266',
+    inkStrength: 0.1,
+  })
+  materials['mechanism.moving'] = paintedToonMaterial(base['mechanism.moving'], {
+    inkColor: '#793d31',
+    inkStrength: 0.12,
+  })
+  materials['world.ground'] = paintedToonMaterial(base['world.ground'], {
+    pattern: meadowWash,
+    inkStrength: 0.12,
+  })
+  materials['world.primary'] = paintedToonMaterial(base['world.primary'], {
+    pattern: paintedCedar,
+    inkStrength: 0.2,
+  })
+  materials['world.secondary'] = paintedToonMaterial(base['world.secondary'], {
+    pattern: paintedStone,
+    inkStrength: 0.18,
+  })
+  materials['world.foliage'] = paintedToonMaterial(base['world.foliage'], {
+    pattern: meadowWash,
+    gradientSteps: 3,
+    inkStrength: 0.04,
+  })
+  materials['world.accent'] = paintedToonMaterial(base['world.accent'], {
+    gradientSteps: 3,
+    inkColor: '#653329',
+    inkStrength: 0.24,
+  })
+  materials.glass = paintedToonMaterial(base.glass, {
+    gradientSteps: 3,
+    inkColor: '#3d676b',
+    inkStrength: 0.26,
+    transparent: true,
+    opacity: 0.48,
+    depthWrite: false,
+  })
+  return materials
+}
+
+export function isTropicalFlowerHedgeAppearance(id: string | undefined): boolean {
+  return (
+    id === PAINTED_VALLEY_TROPICAL_FLOWER_HEDGE_WALL_ID ||
+    id === LEGACY_JUNGLE_FLOWER_HEDGE_WALL_ID
+  )
+}

package/src/three/railroad-appearance.ts

@@ -0,0 +1,71 @@
+import type { TrackPieceAppearance } from '@marble.fun/physics-engine'
+
+import { JAPANESE_SAKURA_REDWOOD_PLANKS_ID } from './japanese-sakura-appearance'
+import type { TrackThemeDefinition } from './track-theme'
+
+export const WILD_WEST_WOODEN_PLANKS_FLOOR_ID = 'wild-west.wooden-planks'
+export const WILD_WEST_WEATHERED_BOARDS_FLOOR_ID = 'wild-west.weathered-boards'
+export const WILD_WEST_RAIL_MATERIAL_ID = 'wild-west.railroad-iron'
+export const WILD_WEST_RAIL_TIE_MATERIAL_ID = 'wild-west.railroad-tie-timber'
+export const LEGACY_WILD_WEST_RAILROAD_FLOOR_ID = 'wild-west.railroad-planks'
+export const STANDARD_RAILROAD_LANE_WIDTH = 4
+export const STANDARD_RAILROAD_HALF_GAUGE = 1.16
+
+/**
+ * Half the visual railway gauge carried by a logical lane. Any lane at least
+ * as wide as the standard four-unit connector keeps one invariant gauge;
+ * widening carrier floors and routing unions must never spread the rails.
+ * Only an explicitly narrower corridor is allowed to reduce its gauge.
+ */
+export function railroadHalfGaugeForLaneWidth(width: number): number {
+  const safeWidth = Number.isFinite(width) ? Math.max(0, width) : STANDARD_RAILROAD_LANE_WIDTH
+  if (safeWidth >= STANDARD_RAILROAD_LANE_WIDTH) return STANDARD_RAILROAD_HALF_GAUGE
+  return Math.max(0.34, safeWidth * 0.29)
+}
+
+/**
+ * Rails are a routed floor treatment, not a `lane.edge` material slot. Every
+ * ordinary track piece can carry them; only the two vertical/bowl mechanisms
+ * have no continuous lane on which rails could be laid.
+ */
+export function supportsRailAppearanceChoices(runtimeKind: string): boolean {
+  return runtimeKind !== 'vortex' && runtimeKind !== 'conveyor'
+}
+
+export function resolvedBaseFloorMaterialId(materialId: string | undefined): string | undefined {
+  return materialId === LEGACY_WILD_WEST_RAILROAD_FLOOR_ID ? WILD_WEST_WOODEN_PLANKS_FLOOR_ID : materialId
+}
+
+export function usesSeparatedPlankFloorAppearance(materialId: string | undefined): boolean {
+  return (
+    materialId === WILD_WEST_WOODEN_PLANKS_FLOOR_ID ||
+    materialId === WILD_WEST_WEATHERED_BOARDS_FLOOR_ID ||
+    materialId === JAPANESE_SAKURA_REDWOOD_PLANKS_ID ||
+    materialId === LEGACY_WILD_WEST_RAILROAD_FLOOR_ID
+  )
+}
+
+/**
+ * Resolves a saved floor choice into the active theme by geometry family.
+ * This prevents a stale theme-specific id from combining plank geometry with
+ * the active theme's fallback surface material (or the reverse).
+ */
+export function resolvedFloorMaterialIdForTheme(
+  theme: TrackThemeDefinition,
+  materialId: string | undefined,
+): string | undefined {
+  const resolvedId = resolvedBaseFloorMaterialId(materialId)
+  if (!resolvedId) return undefined
+
+  const presets = (theme.appearancePresets?.floor ?? []).filter(preset => !preset.hidden)
+  if (presets.some(preset => preset.id === resolvedId)) return resolvedId
+
+  const wantsPlanks = usesSeparatedPlankFloorAppearance(resolvedId)
+  return presets.find(preset => usesSeparatedPlankFloorAppearance(preset.id) === wantsPlanks)?.id
+}
+
+export function resolvedRailMaterialId(appearance: TrackPieceAppearance | undefined): string | undefined {
+  if (appearance?.waterOverlayId) return undefined
+  if (appearance?.railMaterialId) return appearance.railMaterialId
+  return appearance?.floorMaterialId === LEGACY_WILD_WEST_RAILROAD_FLOOR_ID ? WILD_WEST_RAIL_MATERIAL_ID : undefined
+}

package/src/three/renderer-resize.ts

@@ -0,0 +1,32 @@
+interface DrawingBufferRenderer {
+  readonly domElement: Pick<HTMLCanvasElement, 'height' | 'width'>
+  getPixelRatio(): number
+  setDrawingBufferSize(width: number, height: number, pixelRatio: number): void
+}
+
+/**
+ * Resize a renderer with at most one drawing-buffer allocation.
+ *
+ * WebGLRenderer.setPixelRatio() calls setSize() internally, so pairing those
+ * methods reallocates and clears the canvas twice. Comparing physical buffer
+ * dimensions first also keeps duplicate ResizeObserver notifications inert.
+ */
+export function resizeRendererDrawingBuffer(
+  renderer: DrawingBufferRenderer,
+  width: number,
+  height: number,
+  pixelRatio: number,
+): boolean {
+  const drawingBufferWidth = Math.floor(width * pixelRatio)
+  const drawingBufferHeight = Math.floor(height * pixelRatio)
+  if (
+    renderer.domElement.width === drawingBufferWidth &&
+    renderer.domElement.height === drawingBufferHeight &&
+    renderer.getPixelRatio() === pixelRatio
+  ) {
+    return false
+  }
+
+  renderer.setDrawingBufferSize(width, height, pixelRatio)
+  return true
+}

package/src/three/rope-wall-appearance.ts

@@ -0,0 +1,91 @@
+import type { MaterialRecipe } from './track-theme'
+
+export const SHARED_ROPE_WALL_MATERIAL_ID = 'shared.rope-wall'
+export const SHARED_ROPE_WALL_BACKING_MATERIAL_ID = 'shared.rope-wall-backing'
+export const SHARED_ROPE_WALL_TIMBER_MATERIAL_ID = 'shared.rope-wall-timber'
+export const SHARED_ROPE_WALL_END_GRAIN_MATERIAL_ID = 'shared.rope-wall-end-grain'
+
+export const ROPE_WALL_SUPPORTED_THEME_IDS = ['low-poly-jungle', 'ancient-egypt'] as const
+
+/** One art-directed recipe shared verbatim by the Jungle and Egyptian themes. */
+export const SHARED_ROPE_WALL_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#c49a6d',
+  roughness: 0.92,
+  metalness: 0,
+  envMapIntensity: 0.28,
+  pattern: {
+    kind: 'braided-rope',
+    primary: '#c58a38',
+    secondary: '#56300f',
+    worldSize: [0.18, 0.22],
+  },
+  textureUrl: '/themes/textures/old-assets/shared-rope-bridge-fibre-v2-albedo.webp',
+  normalTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-fibre-v2-normal.png',
+  roughnessTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-fibre-v2-roughness.png',
+  aoTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-fibre-v2-ao.png',
+  textureWorldSize: [0.42, 0.58],
+  normalScale: [1, 1],
+  aoMapIntensity: 0.62,
+}
+
+export const SHARED_ROPE_WALL_TIMBER_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#b59a82',
+  roughness: 0.78,
+  metalness: 0,
+  envMapIntensity: 0.26,
+  pattern: {
+    kind: 'rough-wood',
+    primary: '#59331d',
+    secondary: '#160b07',
+    worldSize: [0.72, 1.55],
+  },
+  textureUrl: '/themes/textures/old-assets/shared-rope-bridge-post-timber-v2-albedo.webp',
+  normalTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-post-timber-v2-normal.png',
+  roughnessTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-post-timber-v2-roughness.png',
+  aoTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-post-timber-v2-ao.png',
+  textureWorldSize: [0.55, 0.85],
+  normalScale: [0.82, 0.82],
+  aoMapIntensity: 0.62,
+}
+
+export const SHARED_ROPE_WALL_END_GRAIN_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#c39a72',
+  roughness: 0.72,
+  metalness: 0,
+  envMapIntensity: 0.24,
+  pattern: {
+    kind: 'wood',
+    primary: '#bc8247',
+    secondary: '#4b2916',
+    worldSize: [1, 1],
+  },
+  textureUrl: '/themes/textures/old-assets/shared-rope-bridge-end-grain-v2-albedo.webp',
+  normalTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-end-grain-v2-normal.png',
+  roughnessTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-end-grain-v2-roughness.png',
+  aoTextureUrl: '/themes/textures/old-assets/shared-rope-bridge-end-grain-v2-ao.png',
+  textureWorldSize: [1, 1],
+  normalScale: [0.72, 0.72],
+  aoMapIntensity: 0.58,
+}
+
+/**
+ * The existing continuous wall remains the sole physical barrier. This
+ * transparent recipe hides only its visual shell behind the open rope work.
+ */
+export const SHARED_ROPE_WALL_BACKING_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 1,
+  metalness: 0,
+  transparent: true,
+  opacity: 0,
+  depthWrite: false,
+  envMapIntensity: 0,
+}
+
+export function isSharedRopeWallAppearance(materialId: string | undefined): boolean {
+  return materialId === SHARED_ROPE_WALL_MATERIAL_ID
+}

package/src/three/rugged-track-appearance.ts

@@ -0,0 +1,2 @@
+export const WILD_WEST_ANTIQUE_BRASS_MATERIAL_ID = 'wild-west.antique-brass'
+export const WILD_WEST_GUNMETAL_FLIPPER_MATERIAL_ID = 'wild-west.gunmetal-flipper'

package/src/three/scene-lighting.ts

@@ -0,0 +1,183 @@
+import * as THREE from 'three'
+
+import { usesMobileRenderingBudget } from './mobile-rendering-budget'
+
+import type { ThemeId, TrackThemeDefinition } from './track-theme'
+
+export const SCENE_LIGHTING_MOBILE_BREAKPOINT = 700
+export const STATIC_SHADOW_PROXY_LAYER = 31
+
+export function usesMobileSceneLighting(viewportWidth: number): boolean {
+  return viewportWidth < SCENE_LIGHTING_MOBILE_BREAKPOINT || usesMobileRenderingBudget(Number.POSITIVE_INFINITY)
+}
+
+export function resolveDynamicShadowRefreshRate(
+  viewportWidth: number,
+  deltaSeconds: number,
+  currentRate = 60,
+): 30 | 60 {
+  if (usesMobileSceneLighting(viewportWidth)) return 30
+  // Hysteresis keeps crisp shadow motion on fast desktops but backs off
+  // before shadow rendering can amplify an already slow frame.
+  if (deltaSeconds >= 1 / 45) return 30
+  if (deltaSeconds <= 1 / 55) return 60
+  return currentRate === 30 ? 30 : 60
+}
+
+export interface SceneLightingRig {
+  environmentIntensity: number
+  exposure: number
+  hemisphere: {
+    skyColor: string
+    groundColor: string
+    intensity: number
+  }
+  key: {
+    color: string
+    intensity: number
+    position: readonly [number, number, number]
+  }
+  rim: {
+    color: string
+    intensity: number
+    position: readonly [number, number, number]
+  }
+  shadow: {
+    mapSize: number
+    extent: number
+    near: number
+    far: number
+    bias: number
+    normalBias: number
+    intensity: number
+    focusDistance: number
+  }
+}
+
+const SHADOW_INTENSITY_BY_THEME: Partial<Record<ThemeId, number>> = {
+  'rocky-mountain-wild-west': 0.82,
+  'ancient-egypt': 0.82,
+  'japanese-sakura-lake': 0.8,
+  'intergalactic-space-station': 0.74,
+  'low-poly-jungle': 0.82,
+  'vampire-castle': 0.58,
+}
+
+const GAMEPLAY_ENVIRONMENT_SCALE = 0.72
+const GAMEPLAY_HEMISPHERE_SCALE = 0.34
+const GAMEPLAY_KEY_SCALE = 0.82
+const GAMEPLAY_RIM_SCALE = 0.28
+const GAMEPLAY_EXPOSURE_SCALE = 0.97
+
+export function resolveSceneLightingRig(theme: TrackThemeDefinition, mobile: boolean): SceneLightingRig {
+  const vampireCastle = theme.id === 'vampire-castle'
+  const spaceStation = theme.id === 'intergalactic-space-station'
+  return {
+    environmentIntensity: THREE.MathUtils.clamp(
+      theme.environment.environmentIntensity * GAMEPLAY_ENVIRONMENT_SCALE,
+      0.38,
+      vampireCastle ? 0.92 : 0.86,
+    ),
+    exposure: THREE.MathUtils.clamp(
+      theme.lighting.exposure * GAMEPLAY_EXPOSURE_SCALE,
+      0.82,
+      vampireCastle || spaceStation ? 1.15 : 1.05,
+    ),
+    hemisphere: {
+      skyColor: theme.lighting.skyColor,
+      groundColor: theme.lighting.groundColor,
+      intensity: THREE.MathUtils.clamp(
+        theme.lighting.ambientIntensity * GAMEPLAY_HEMISPHERE_SCALE,
+        0.3,
+        vampireCastle ? 0.82 : 0.62,
+      ),
+    },
+    key: {
+      color: theme.lighting.keyColor,
+      intensity: theme.lighting.keyIntensity * GAMEPLAY_KEY_SCALE,
+      position: theme.lighting.keyPosition,
+    },
+    rim: {
+      color: theme.lighting.rimColor,
+      intensity: theme.lighting.rimIntensity * GAMEPLAY_RIM_SCALE,
+      position: theme.lighting.rimPosition,
+    },
+    shadow: {
+      mapSize: mobile ? 1024 : 1536,
+      extent: mobile ? 36 : 52,
+      near: 1,
+      far: 220,
+      bias: -0.00008,
+      normalBias: 0.028,
+      intensity: SHADOW_INTENSITY_BY_THEME[theme.id as ThemeId] ?? 0.8,
+      focusDistance: mobile ? 12 : 18,
+    },
+  }
+}
+
+export function configureSceneRenderer(renderer: THREE.WebGLRenderer, exposure = 1): void {
+  renderer.outputColorSpace = THREE.SRGBColorSpace
+  renderer.toneMapping = THREE.ACESFilmicToneMapping
+  renderer.toneMappingExposure = exposure
+  renderer.shadowMap.enabled = true
+  renderer.shadowMap.type = THREE.PCFShadowMap
+  renderer.shadowMap.autoUpdate = false
+  renderer.shadowMap.needsUpdate = true
+}
+
+export function configureKeyShadow(light: THREE.DirectionalLight, rig: SceneLightingRig): void {
+  const shadow = rig.shadow
+  light.castShadow = true
+  light.shadow.mapSize.set(shadow.mapSize, shadow.mapSize)
+  light.shadow.camera.left = -shadow.extent
+  light.shadow.camera.right = shadow.extent
+  light.shadow.camera.top = shadow.extent
+  light.shadow.camera.bottom = -shadow.extent
+  light.shadow.camera.near = shadow.near
+  light.shadow.camera.far = shadow.far
+  light.shadow.bias = shadow.bias
+  light.shadow.normalBias = shadow.normalBias
+  light.shadow.intensity = shadow.intensity
+  light.shadow.camera.layers.enable(STATIC_SHADOW_PROXY_LAYER)
+  light.shadow.camera.updateProjectionMatrix()
+}
+
+/** Dispose GPU shadow targets before removing a themed light rig. */
+export function disposeSceneLightShadows(root: THREE.Object3D): void {
+  root.traverse(object => {
+    if (
+      object instanceof THREE.DirectionalLight ||
+      object instanceof THREE.PointLight ||
+      object instanceof THREE.SpotLight
+    ) {
+      object.shadow.dispose()
+    }
+  })
+}
+
+export function computeShadowFocus(
+  camera: THREE.Camera,
+  rig: SceneLightingRig,
+  target = new THREE.Vector3(),
+  focusPoint?: THREE.Vector3,
+  shadowMapSize = rig.shadow.mapSize,
+): THREE.Vector3 {
+  if (focusPoint) {
+    target.copy(focusPoint)
+  } else {
+    camera.getWorldDirection(target).multiplyScalar(rig.shadow.focusDistance)
+    const cameraMatrix = camera.matrixWorld.elements
+    target.x += cameraMatrix[12]
+    target.y += cameraMatrix[13]
+    target.z += cameraMatrix[14]
+  }
+
+  // Stable, texel-sized steps prevent the shadow projection from shimmering as the camera eases forward.
+  const texelWorldSize = (rig.shadow.extent * 2) / shadowMapSize
+  target.set(
+    Math.round(target.x / texelWorldSize) * texelWorldSize,
+    Math.round(target.y / texelWorldSize) * texelWorldSize,
+    Math.round(target.z / texelWorldSize) * texelWorldSize,
+  )
+  return target
+}