@marble.fun/track-catalog 3.0.0

package/src/three/geometry-attribute-aliases.ts

@@ -0,0 +1,24 @@
+import type * as THREE from 'three'
+
+/** Preserve intentional attribute aliases when Three copies/merges buffers. */
+export function preserveGeometryAttributeAliases(
+  target: THREE.BufferGeometry,
+  sources: readonly THREE.BufferGeometry[],
+): void {
+  if (sources.length === 0) return
+  const names = Object.keys(target.attributes)
+  for (let index = 1; index < names.length; index += 1) {
+    const name = names[index]!
+    for (let previous = 0; previous < index; previous += 1) {
+      const other = names[previous]!
+      if (
+        sources.every(
+          source => source.getAttribute(name) !== undefined && source.getAttribute(name) === source.getAttribute(other),
+        )
+      ) {
+        target.setAttribute(name, target.getAttribute(other))
+        break
+      }
+    }
+  }
+}

package/src/three/geometry-detail.ts

@@ -0,0 +1,36 @@
+/** Development experiment: geometry only; renderer policy stays at High. */
+export type GeometryDetail = 'max' | 'mid' | 'lo'
+export const GEOMETRY_DETAIL_STORAGE_KEY = 'marble.geometry-detail'
+export const GEOMETRY_DETAIL_PROFILES = {
+  max: { triangleRatio: 0.2, minimumScale: 1, surfaceSpacing: 1, ribbonTolerance: 1 },
+  mid: { triangleRatio: 0.08, minimumScale: 0.75, surfaceSpacing: 2, ribbonTolerance: 1.5 },
+  lo: { triangleRatio: 0.025, minimumScale: 0.5, surfaceSpacing: 4, ribbonTolerance: 2.5 },
+} as const
+
+export function parseGeometryDetail(value: string | null | undefined): GeometryDetail | undefined {
+  return value === 'max' || value === 'mid' || value === 'lo' ? value : undefined
+}
+
+function initialGeometryDetail(): GeometryDetail {
+  const query = parseGeometryDetail(new URLSearchParams(globalThis.location?.search ?? '').get('geometryDetail'))
+  if (query) return query
+  try {
+    return parseGeometryDetail(globalThis.localStorage?.getItem(GEOMETRY_DETAIL_STORAGE_KEY)) ?? 'max'
+  } catch {
+    return 'max'
+  }
+}
+
+// Deliberately immutable for the page lifetime: caches and async model loads
+// must use the same profile. Changing the dial requires a full page reload.
+export const geometryDetail = initialGeometryDetail()
+export const geometryDetailProfile = GEOMETRY_DETAIL_PROFILES[geometryDetail]
+
+export function geometryDetailModelUrl(url: string): string {
+  return geometryDetail === 'max' ? url : url.replace('/models/', `/models/geometry/${geometryDetail}/`)
+}
+
+/** Counts for custom render-only grids. Never use for collision geometry. */
+export function geometryDetailSegments(current: number, minimum = 1): number {
+  return Math.max(minimum, Math.floor(current / geometryDetailProfile.surfaceSpacing))
+}

package/src/three/homepage-marble-geometry.ts

@@ -0,0 +1,15 @@
+import { SphereGeometry } from 'three'
+
+const geometries = new Map<string, SphereGeometry>()
+
+/** Original authored homepage tessellation, independent of course detail. */
+export function homepageMarbleGeometry(radius: number, width: number, height: number): SphereGeometry {
+  const key = `${radius}:${width}:${height}`
+  let geometry = geometries.get(key)
+  if (!geometry) {
+    geometry = new SphereGeometry(radius, width, height)
+    geometry.userData.shared = true
+    geometries.set(key, geometry)
+  }
+  return geometry
+}

package/src/three/japanese-sakura-appearance.ts

@@ -0,0 +1,252 @@
+import type { MaterialRecipe } from './track-theme'
+
+export const JAPANESE_SAKURA_CASTLE_WALL_ID = 'japanese-sakura.castle-wall'
+export const JAPANESE_SAKURA_CASTLE_TIMBER_ID = 'japanese-sakura.castle-wall-timber'
+export const JAPANESE_SAKURA_CASTLE_MASONRY_ID = 'japanese-sakura.castle-wall-masonry'
+export const JAPANESE_SAKURA_CASTLE_KAWARA_ID = 'japanese-sakura.castle-wall-kawara'
+export const JAPANESE_SAKURA_BRIDGE_FENCE_ID = 'japanese-sakura.vermilion-bridge-fence'
+export const JAPANESE_SAKURA_BRIDGE_TIMBER_ID = 'japanese-sakura.vermilion-bridge-timber'
+export const JAPANESE_SAKURA_BRIDGE_HARDWARE_ID = 'japanese-sakura.vermilion-bridge-hardware'
+export const JAPANESE_SAKURA_CASTLE_PAVERS_ID = 'japanese-sakura.castle-pavers'
+export const JAPANESE_SAKURA_REDWOOD_PLANKS_ID = 'japanese-sakura.redwood-planks'
+export const JAPANESE_SAKURA_PORTAL_FOUNDATION_STONE_ID = 'japanese-sakura.portal-foundation-stone'
+export const JAPANESE_SAKURA_VERMILION_UNDERBRIDGE_SUPPORT_ID = 'japanese-sakura.vermilion-underbridge-support'
+export const JAPANESE_SAKURA_DRAGON_STONE_SUPPORT_ID = 'japanese-sakura.dragon-stone-support'
+
+const textureRoot = '/themes/textures/japanese-sakura-castle'
+
+/** Weathered bridge-plank grain recolored as deep Japanese vermilion redwood. */
+export const JAPANESE_SAKURA_REDWOOD_PLANKS_MATERIAL: MaterialRecipe = {
+  kind: 'physical',
+  color: '#ffffff',
+  roughness: 0.48,
+  metalness: 0,
+  envMapIntensity: 0.86,
+  clearcoat: 0.34,
+  clearcoatRoughness: 0.42,
+  pattern: {
+    kind: 'bridge-planks',
+    primary: '#8f2f25',
+    secondary: '#2c0d0a',
+    worldSize: [24, 14.4],
+  },
+  textureUrl: '/themes/textures/japanese-sakura-redwood-planks-v1-albedo.webp',
+  normalTextureUrl: '/themes/textures/japanese-sakura-redwood-planks-v1-normal.png',
+  heightTextureUrl: '/themes/textures/japanese-sakura-redwood-planks-v1-height.png',
+  roughnessTextureUrl: '/themes/textures/japanese-sakura-redwood-planks-v1-roughness.png',
+  aoTextureUrl: '/themes/textures/japanese-sakura-redwood-planks-v1-ao.png',
+  textureWorldSize: [5.4, 2.16],
+  normalScale: [0.62, 0.62],
+  bumpScale: 0.025,
+  aoMapIntensity: 0.38,
+}
+
+export const JAPANESE_SAKURA_CASTLE_PLASTER_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.88,
+  metalness: 0,
+  envMapIntensity: 0.68,
+  pattern: {
+    kind: 'painted-stone',
+    primary: '#f3e4c4',
+    secondary: '#d8c29b',
+    worldSize: [1.6, 1.6],
+  },
+  textureUrl: `${textureRoot}-plaster-v1-albedo.webp`,
+  normalTextureUrl: `${textureRoot}-plaster-v1-normal.png`,
+  heightTextureUrl: `${textureRoot}-plaster-v1-height.png`,
+  roughnessTextureUrl: `${textureRoot}-plaster-v1-roughness.png`,
+  aoTextureUrl: `${textureRoot}-plaster-v1-ao.png`,
+  textureWorldSize: [1.6, 1.6],
+  normalScale: [0.32, 0.32],
+  bumpScale: 0.024,
+  aoMapIntensity: 0.42,
+}
+
+export const JAPANESE_SAKURA_CASTLE_TIMBER_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.74,
+  metalness: 0,
+  envMapIntensity: 0.72,
+  pattern: {
+    kind: 'wood',
+    primary: '#57311f',
+    secondary: '#21130e',
+    worldSize: [0.55, 1.8],
+  },
+  textureUrl: `${textureRoot}-timber-v1-albedo.webp`,
+  normalTextureUrl: `${textureRoot}-timber-v1-normal.png`,
+  heightTextureUrl: `${textureRoot}-timber-v1-height.png`,
+  roughnessTextureUrl: `${textureRoot}-timber-v1-roughness.png`,
+  aoTextureUrl: `${textureRoot}-timber-v1-ao.png`,
+  textureWorldSize: [0.55, 1.8],
+  normalScale: [0.4, 0.4],
+  bumpScale: 0.035,
+  aoMapIntensity: 0.5,
+}
+
+export const JAPANESE_SAKURA_CASTLE_MASONRY_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.8,
+  metalness: 0,
+  envMapIntensity: 0.6,
+  pattern: {
+    kind: 'ancient-bricks',
+    primary: '#75402b',
+    secondary: '#301d18',
+    worldSize: [1.4, 0.7],
+  },
+  textureUrl: `${textureRoot}-masonry-sill-v1-albedo.webp`,
+  normalTextureUrl: `${textureRoot}-masonry-sill-v1-normal.png`,
+  heightTextureUrl: `${textureRoot}-masonry-sill-v1-height.png`,
+  roughnessTextureUrl: `${textureRoot}-masonry-sill-v1-roughness.png`,
+  aoTextureUrl: `${textureRoot}-masonry-sill-v1-ao.png`,
+  textureWorldSize: [1.4, 0.7],
+  normalScale: [0.58, 0.58],
+  bumpScale: 0.055,
+  aoMapIntensity: 0.62,
+}
+
+export const JAPANESE_SAKURA_PORTAL_FOUNDATION_STONE_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.84,
+  metalness: 0,
+  envMapIntensity: 0.66,
+  pattern: {
+    kind: 'painted-stone',
+    primary: '#34363a',
+    secondary: '#1f2125',
+    worldSize: [1.6, 1.6],
+  },
+  textureUrl: '/themes/textures/japanese-sakura-portal-foundation-stone-v1-albedo.webp',
+  normalTextureUrl: '/themes/textures/japanese-sakura-portal-foundation-stone-v1-normal.png',
+  heightTextureUrl: '/themes/textures/japanese-sakura-portal-foundation-stone-v1-height.png',
+  roughnessTextureUrl: '/themes/textures/japanese-sakura-portal-foundation-stone-v1-roughness.png',
+  aoTextureUrl: '/themes/textures/japanese-sakura-portal-foundation-stone-v1-ao.png',
+  textureWorldSize: [1.6, 1.6],
+  normalScale: [0.42, 0.42],
+  bumpScale: 0.028,
+  aoMapIntensity: 0.5,
+}
+
+export const JAPANESE_SAKURA_CASTLE_KAWARA_MATERIAL: MaterialRecipe = {
+  kind: 'physical',
+  color: '#ffffff',
+  roughness: 0.5,
+  metalness: 0,
+  envMapIntensity: 0.9,
+  clearcoat: 0.22,
+  clearcoatRoughness: 0.46,
+  pattern: {
+    kind: 'panels',
+    primary: '#4d5054',
+    secondary: '#202328',
+    worldSize: [2.7, 1.8],
+  },
+  textureUrl: `${textureRoot}-kawara-v1-albedo.webp`,
+  normalTextureUrl: `${textureRoot}-kawara-v1-normal.png`,
+  heightTextureUrl: `${textureRoot}-kawara-v1-height.png`,
+  roughnessTextureUrl: `${textureRoot}-kawara-v1-roughness.png`,
+  aoTextureUrl: `${textureRoot}-kawara-v1-ao.png`,
+  textureWorldSize: [2.7, 1.8],
+  normalScale: [0.7, 0.7],
+  bumpScale: 0.07,
+  aoMapIntensity: 0.58,
+}
+
+/** Dedicated low-contrast vermilion lacquer; deliberately independent of the castle timber. */
+export const JAPANESE_SAKURA_BRIDGE_TIMBER_MATERIAL: MaterialRecipe = {
+  kind: 'physical',
+  color: '#ffffff',
+  roughness: 0.3,
+  metalness: 0,
+  envMapIntensity: 1.3,
+  clearcoat: 0.84,
+  clearcoatRoughness: 0.14,
+  pattern: {
+    kind: 'wood',
+    primary: '#8a2119',
+    secondary: '#651611',
+    worldSize: [3.2, 3.2],
+  },
+  textureUrl: '/themes/textures/japanese-sakura-vermilion-lacquer-v2-albedo.webp',
+  normalTextureUrl: '/themes/textures/japanese-sakura-vermilion-lacquer-v2-normal.png',
+  heightTextureUrl: '/themes/textures/japanese-sakura-vermilion-lacquer-v2-height.png',
+  roughnessTextureUrl: '/themes/textures/japanese-sakura-vermilion-lacquer-v2-roughness.png',
+  aoTextureUrl: '/themes/textures/japanese-sakura-vermilion-lacquer-v2-ao.png',
+  textureWorldSize: [3.2, 3.2],
+  normalScale: [0.18, 0.18],
+  bumpScale: 0.004,
+  aoMapIntensity: 0.08,
+}
+
+export const JAPANESE_SAKURA_BRIDGE_HARDWARE_MATERIAL: MaterialRecipe = {
+  kind: 'physical',
+  color: '#6d7476',
+  roughness: 0.3,
+  metalness: 0.92,
+  envMapIntensity: 1.3,
+  clearcoat: 0.12,
+  clearcoatRoughness: 0.24,
+  pattern: {
+    kind: 'gunmetal-silver',
+    primary: '#8e9799',
+    secondary: '#252a2c',
+    worldSize: [0.42, 0.42],
+  },
+  bumpScale: 0.008,
+}
+
+/** Pale aligned ashlar used by the approved castle under-track support. */
+export const JAPANESE_SAKURA_DRAGON_STONE_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.78,
+  metalness: 0,
+  envMapIntensity: 0.58,
+  textureUrl: '/themes/textures/japanese-sakura-castle-ashlar-albedo-v1.png',
+  normalTextureUrl: '/themes/textures/japanese-sakura-castle-ashlar-normal-v1.png',
+  heightTextureUrl: '/themes/textures/japanese-sakura-castle-ashlar-height-v1.png',
+  roughnessTextureUrl: '/themes/textures/japanese-sakura-castle-ashlar-roughness-v1.png',
+  aoTextureUrl: '/themes/textures/japanese-sakura-castle-ashlar-ao-v1.png',
+  textureWorldSize: [4, 4],
+  normalScale: [0.38, 0.38],
+  bumpScale: 0.03,
+  aoMapIntensity: 0.42,
+}
+
+export const JAPANESE_SAKURA_CASTLE_PAVERS_MATERIAL: MaterialRecipe = {
+  kind: 'standard',
+  color: '#ffffff',
+  roughness: 0.78,
+  metalness: 0,
+  envMapIntensity: 0.72,
+  pattern: {
+    kind: 'ancient-bricks',
+    primary: '#ead6aa',
+    secondary: '#c7ad7f',
+    worldSize: [3.8, 3.8],
+  },
+  textureUrl: '/themes/textures/japanese-sakura-castle-pavers-v1-albedo.webp',
+  normalTextureUrl: '/themes/textures/japanese-sakura-castle-pavers-v1-normal.png',
+  heightTextureUrl: '/themes/textures/japanese-sakura-castle-pavers-v1-height.png',
+  roughnessTextureUrl: '/themes/textures/japanese-sakura-castle-pavers-v1-roughness.png',
+  aoTextureUrl: '/themes/textures/japanese-sakura-castle-pavers-v1-ao.png',
+  textureWorldSize: [3.8, 3.8],
+  normalScale: [0.48, 0.48],
+  bumpScale: 0.035,
+  aoMapIntensity: 0.48,
+  visualRelief: { scale: 0.12, bias: -0.11, targetEdgeLength: 0.09 },
+}
+
+export function isJapaneseSakuraCastleWallAppearance(appearanceId: string | undefined): boolean {
+  return appearanceId === JAPANESE_SAKURA_CASTLE_WALL_ID
+}
+
+export function isJapaneseSakuraBridgeFenceAppearance(appearanceId: string | undefined): boolean {
+  return appearanceId === JAPANESE_SAKURA_BRIDGE_FENCE_ID
+}

package/src/three/jungle-flower-hedge-appearance.ts

@@ -0,0 +1,7 @@
+export {
+  PAINTED_VALLEY_TROPICAL_FLOWER_HEDGE_CORE_MATERIAL as JUNGLE_FLOWER_HEDGE_CORE_MATERIAL,
+  PAINTED_VALLEY_TROPICAL_FLOWER_HEDGE_WALL_ID as JUNGLE_FLOWER_HEDGE_WALL_ID,
+  PAINTED_VALLEY_GRASS_ORANGE_DIRT_PATH_FLOOR_ID as JUNGLE_GRASS_DIRT_PATH_FLOOR_ID,
+  PAINTED_VALLEY_GRASS_ORANGE_DIRT_PATH_MATERIAL as JUNGLE_GRASS_DIRT_PATH_MATERIAL,
+  isTropicalFlowerHedgeAppearance as isJungleFlowerHedgeAppearance,
+} from './painted-valley-appearance'

package/src/three/jungle-temple-appearance.ts

@@ -0,0 +1,5 @@
+export const JUNGLE_TEMPLE_STONE_MATERIAL_ID = 'jungle.temple-stone'
+export const JUNGLE_TEMPLE_FACADE_MATERIAL_ID = 'jungle.temple-serpent-facade'
+export const JUNGLE_TEMPLE_TIMBER_MATERIAL_ID = 'jungle.temple-timber'
+export const JUNGLE_TEMPLE_PLATFORM_MATERIAL_ID = 'jungle.temple-platform'
+export const JUNGLE_TEMPLE_BRONZE_MATERIAL_ID = 'jungle.temple-bronze'

package/src/three/low-quality-scene-renderer.ts

@@ -0,0 +1,132 @@
+import * as THREE from 'three'
+
+import type { VisualQualityPolicy } from './visual-quality'
+
+type LitMaterial =
+  THREE.MeshStandardMaterial | THREE.MeshPhongMaterial | THREE.MeshLambertMaterial | THREE.MeshToonMaterial
+
+/** Render-only experiment. Source materials, geometry and simulation are never edited. */
+export class LowQualitySceneRenderer {
+  private readonly materials = new Map<
+    LitMaterial,
+    { material: THREE.MeshBasicMaterial; release: () => void; frame: number }
+  >()
+  private readonly arrays = new WeakMap<THREE.Material[], THREE.Material[]>()
+  private readonly meshes: THREE.Mesh[] = []
+  private readonly originals: Array<THREE.Material | THREE.Material[]> = []
+  private readonly particles: THREE.Points[] = []
+  private frame = 0
+  private cameraLayers = 1
+
+  render(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, policy: VisualQualityPolicy): void {
+    if (policy.tier !== 'low') {
+      renderer.render(scene, camera)
+      return
+    }
+    this.frame += 1
+    this.cameraLayers = camera.layers.mask
+    const shadowsEnabled = renderer.shadowMap.enabled
+    renderer.shadowMap.enabled = false
+    try {
+      scene.traverseVisible(this.prepareObject)
+      renderer.render(scene, camera)
+    } finally {
+      for (let index = 0; index < this.meshes.length; index += 1) {
+        this.meshes[index]!.material = this.originals[index]!
+      }
+      for (const particle of this.particles) particle.visible = true
+      this.meshes.length = 0
+      this.originals.length = 0
+      this.particles.length = 0
+      renderer.shadowMap.enabled = shadowsEnabled
+    }
+  }
+
+  dispose(): void {
+    for (const { release } of this.materials.values()) release()
+    this.materials.clear()
+  }
+
+  private readonly prepareObject = (object: THREE.Object3D): void => {
+    if (object instanceof THREE.Points) {
+      this.particles.push(object)
+      object.visible = false
+    } else if (object instanceof THREE.Mesh && (object.layers.mask & this.cameraLayers) !== 0) {
+      const original = object.material
+      let replacement: THREE.Material | THREE.Material[]
+      if (Array.isArray(original)) {
+        let array = this.arrays.get(original)
+        if (!array) {
+          array = []
+          this.arrays.set(original, array)
+        }
+        array.length = original.length
+        for (let index = 0; index < original.length; index += 1) array[index] = this.simplify(original[index]!)
+        replacement = array
+      } else {
+        replacement = this.simplify(original)
+      }
+      if (replacement === original) return
+      this.meshes.push(object)
+      this.originals.push(original)
+      object.material = replacement
+    }
+  }
+
+  private simplify(source: THREE.Material): THREE.Material {
+    if (!(
+      source instanceof THREE.MeshStandardMaterial ||
+      source instanceof THREE.MeshPhongMaterial ||
+      source instanceof THREE.MeshLambertMaterial ||
+      source instanceof THREE.MeshToonMaterial
+    ))
+      return source
+    let entry = this.materials.get(source)
+    if (!entry) {
+      const material = new THREE.MeshBasicMaterial()
+      material.name = `low:${source.name}`
+      const release = (): void => {
+        source.removeEventListener('dispose', release)
+        material.dispose()
+        this.materials.delete(source)
+      }
+      source.addEventListener('dispose', release)
+      entry = { material, release, frame: -1 }
+      this.materials.set(source, entry)
+    }
+    // Synchronize shared materials once per render, not once per mesh.
+    if (entry.frame === this.frame) return entry.material
+    entry.frame = this.frame
+    const target = entry.material
+    // Keep labels, foliage cutouts, vertex colors and presentation fades. Normal,
+    // roughness, metalness, environment, transmission and lighting are omitted.
+    if (
+      target.map !== source.map ||
+      target.alphaMap !== source.alphaMap ||
+      target.vertexColors !== source.vertexColors ||
+      target.side !== source.side ||
+      target.transparent !== source.transparent ||
+      target.alphaTest !== source.alphaTest
+    )
+      target.needsUpdate = true
+    target.color.copy(source.color)
+    target.map = source.map
+    target.alphaMap = source.alphaMap
+    target.vertexColors = source.vertexColors
+    target.side = source.side
+    target.transparent = source.transparent
+    target.opacity = source.opacity
+    target.alphaTest = source.alphaTest
+    target.depthTest = source.depthTest
+    target.depthWrite = source.depthWrite
+    target.colorWrite = source.colorWrite
+    target.blending = source.blending
+    target.polygonOffset = source.polygonOffset
+    target.polygonOffsetFactor = source.polygonOffsetFactor
+    target.polygonOffsetUnits = source.polygonOffsetUnits
+    target.visible = source.visible
+    target.toneMapped = source.toneMapped
+    target.fog = source.fog
+    return target
+  }
+}

package/src/three/marble-sphere-geometry.ts

@@ -0,0 +1,13 @@
+import { SphereGeometry } from 'three'
+
+/** Preserve the pre-experiment High marble silhouette at every course detail. */
+export class MarbleSphereGeometry extends SphereGeometry {
+  constructor(radius: number, width: number, height: number) {
+    const highAxisRatio = Math.sqrt(0.2)
+    super(
+      radius,
+      Math.min(width, Math.max(8, Math.floor(width * highAxisRatio))),
+      Math.min(height, Math.max(4, Math.floor(height * highAxisRatio))),
+    )
+  }
+}

package/src/three/mobile-rendering-budget.ts

@@ -0,0 +1,11 @@
+export const MOBILE_STATIC_BATCH_ALLOCATION_BUDGET_BYTES = 32 * 1024 * 1024
+
+/** Phone/tablet rendering budgets must survive landscape and browser rotation. */
+export function usesMobileRenderingBudget(
+  viewportWidth: number = typeof window === 'undefined' ? Number.POSITIVE_INFINITY : window.innerWidth,
+  coarsePrimaryPointer: boolean = typeof matchMedia !== 'undefined' && matchMedia('(pointer: coarse)').matches,
+): boolean {
+  // Narrow desktop windows retain the existing compact budget. Device input
+  // capability is independent of layout width, unlike a CSS breakpoint.
+  return viewportWidth < 768 || coarsePrimaryPointer
+}