@marble.fun/track-catalog 3.0.0

package/src/three/track-theme.ts

@@ -0,0 +1,535 @@
+import type { MaterialSlot } from '@marble.fun/physics-engine'
+
+import type { TrackSkin } from '../pages/play/race/track-definition'
+
+export type ThemeId =
+  | 'neutral-studio'
+  | 'material-slot-debug'
+  | 'rocky-mountain-wild-west'
+  | 'ancient-egypt'
+  | 'japanese-sakura-lake'
+  | 'intergalactic-space-station'
+  | 'painted-valley'
+  | 'low-poly-jungle'
+  | 'vampire-castle'
+
+export type WorldMaterialSlot =
+  'world.ground' | 'world.primary' | 'world.secondary' | 'world.foliage' | 'world.accent' | 'world.dark'
+
+export type ThemeOnlyMaterialSlot =
+  | 'lane.guard.backing'
+  | 'obstacle.primary'
+  | 'obstacle.secondary'
+  | 'obstacle.base'
+  | 'mechanism.flipper.primary'
+  | 'mechanism.flipper.secondary'
+
+export type ThemeMaterialSlot = MaterialSlot | ThemeOnlyMaterialSlot | WorldMaterialSlot
+
+export type MaterialPatternKind =
+  | 'wood'
+  | 'rough-wood'
+  | 'railroad-planks'
+  | 'bridge-planks'
+  | 'fence-timber'
+  | 'sand'
+  | 'rock'
+  | 'gunmetal-silver'
+  | 'weathered-sheet-metal'
+  | 'braided-rope'
+  | 'painted-wood'
+  | 'painted-stone'
+  | 'watercolor'
+  | 'panels'
+  | 'grid'
+  | 'neon-net'
+  | 'holographic-hover-grid'
+  | 'waves'
+  | 'bark'
+  | 'jungle-vines'
+  | 'leaf-canopy'
+  | 'moss-bark'
+  | 'ancient-bricks'
+  | 'stick-fence'
+  | 'debug'
+
+export interface MaterialPatternRecipe {
+  kind: MaterialPatternKind
+  primary: string
+  secondary: string
+  /** Physical surface size, in track-world units, occupied by one texture tile. */
+  worldSize: readonly [number, number]
+}
+
+export interface MaterialSurfaceTreatment {
+  kind: 'floor-perimeter-overlay'
+  materialId: string
+  bandWidth: number
+  /** Physical width, in track-world units, over which the shoulder fades into the floor. */
+  featherWidth: number
+  normalOffset: number
+}
+
+interface MaterialRecipeBase {
+  color: string
+  roughness: number
+  metalness: number
+  emissive?: string
+  emissiveIntensity?: number
+  transparent?: boolean
+  opacity?: number
+  alphaTest?: number
+  depthWrite?: boolean
+  netSpacing?: number
+  netLineWidth?: number
+  netFillOpacity?: number
+  /** Hot-core half-width in track-world units for the holographic hover grid. */
+  hoverGridCoreWidth?: number
+  /** Exponential falloff coefficient for the hover-grid aura. */
+  hoverGridAuraFalloff?: number
+  /** Aura multiplier for the hover-grid shader. */
+  hoverGridAuraStrength?: number
+  /** Extra energy at line intersections without adding node geometry. */
+  hoverGridJunctionStrength?: number
+  envMapIntensity?: number
+  pattern?: MaterialPatternRecipe
+  textureUrl?: string
+  emissiveTextureUrl?: string
+  emissiveSurface?: 'all' | 'upward'
+  normalTextureUrl?: string
+  heightTextureUrl?: string
+  roughnessTextureUrl?: string
+  aoTextureUrl?: string
+  /** Physical surface size, in track-world units, occupied by one image tile. */
+  textureWorldSize?: readonly [number, number]
+  bumpScale?: number
+  normalScale?: readonly [number, number]
+  aoMapIntensity?: number
+  /** Declarative visual treatment applied to every canonical surface using this material. */
+  surfaceTreatment?: MaterialSurfaceTreatment
+  /**
+   * Optional height-map-driven macro relief for tessellated visual track shells.
+   * This never changes the corresponding Rapier collider.
+   */
+  visualRelief?: {
+    scale: number
+    bias: number
+    targetEdgeLength: number
+  }
+}
+
+export type MaterialRecipe =
+  | (MaterialRecipeBase & {
+      kind: 'standard'
+    })
+  | (MaterialRecipeBase & {
+      kind: 'physical'
+      clearcoat?: number
+      clearcoatRoughness?: number
+      transmission?: number
+      thickness?: number
+    })
+  | (MaterialRecipeBase & {
+      kind: 'toon'
+      gradientSteps?: number
+      inkColor?: string
+      inkStrength?: number
+    })
+
+export type TrackAppearanceSurface = 'floor' | 'wall' | 'rail' | 'support'
+
+export type TrackAppearanceDetailStyle =
+  | 'wild-west-railroad'
+  | 'centered-floor-runner'
+  | 'wild-west-short-ranch-fence'
+  | 'wild-west-tall-stockade'
+  | 'shared-rope-wall'
+  | 'jungle-flower-hedge'
+  | 'shared-stone-block-shell'
+  | 'japanese-sakura-castle-wall'
+  | 'japanese-sakura-vermilion-bridge-fence'
+  | 'space-station-armored-wall'
+
+export type TrackAppearanceCanopyStyle = 'wild-west-covered-mine' | 'japanese-sakura-roofed-gate'
+
+export type TrackAppearanceSupportStyle =
+  | 'wild-west-timber-trestle'
+  | 'wild-west-canyon-buttress'
+  | 'japanese-sakura-vermilion-underbridge'
+  | 'japanese-sakura-dragon-stone'
+
+export interface TrackAppearancePreset {
+  id: string
+  label: string
+  material: MaterialRecipe
+  /** The real theme default. Selecting it clears the saved override. */
+  default?: boolean
+  detailStyle?: TrackAppearanceDetailStyle
+  /** Visual-only overhead structure paired with this explicit wall choice. */
+  canopyStyle?: TrackAppearanceCanopyStyle
+  /** Visual-only structure beneath a compatible lane. It never adds collision geometry. */
+  supportStyle?: TrackAppearanceSupportStyle
+  /** Retained for loading older documents but omitted from new inspector choices. */
+  hidden?: boolean
+}
+
+export interface TrackAppearancePresets {
+  floor?: readonly TrackAppearancePreset[]
+  wall?: readonly TrackAppearancePreset[]
+  rail?: readonly TrackAppearancePreset[]
+  support?: readonly TrackAppearancePreset[]
+}
+
+export type ThemeWorldKit =
+  'studio' | 'wild-west' | 'ancient-egypt' | 'japanese-sakura-lake' | 'space-station' | 'jungle'
+export type ThemeParticleStyle = 'dust' | 'space-drift' | 'fireflies' | 'petals' | 'none'
+export type ThemeAmbienceStyle = 'studio' | 'desert' | 'space' | 'jungle' | 'meadow' | 'sakura-lake'
+
+export interface TrackThemeDefinition {
+  id: ThemeId | (string & {})
+  version: number
+  label: string
+  shortLabel: string
+  description: string
+  /** Small square crop for compact controls and history rows. */
+  thumbnailUrl?: string
+  /** Portrait crop used by the Track Lab theme carousel. */
+  pickerPreviewUrl?: string
+  /** Full-frame compressed background used while a world is loading. */
+  loadingPreviewUrl?: string
+  /** Full Open Graph composition retained for social and legacy consumers. */
+  previewUrl?: string
+  panoramaUrl?: string
+  materials: Readonly<Record<ThemeMaterialSlot, MaterialRecipe>>
+  appearancePresets?: TrackAppearancePresets
+  /** Theme-private materials used by decorative geometry rather than inspector choices. */
+  detailMaterials?: Readonly<Record<string, MaterialRecipe>>
+  environment: {
+    background: string
+    fog: string
+    fogNear: number
+    fogFar: number
+    environmentIntensity: number
+  }
+  lighting: {
+    skyColor: string
+    groundColor: string
+    ambientIntensity: number
+    keyColor: string
+    keyIntensity: number
+    keyPosition: readonly [number, number, number]
+    rimColor: string
+    rimIntensity: number
+    rimPosition: readonly [number, number, number]
+    exposure: number
+    practical?: {
+      color: string
+      intensity: number
+      distance: number
+      decay: number
+      count: number
+      heightOffset: number
+    }
+  }
+  world: {
+    kit: ThemeWorldKit
+    density: number
+  }
+  particles: {
+    style: ThemeParticleStyle
+    color: string
+    secondaryColor: string
+    count: number
+    size: number
+    speed: number
+    opacity: number
+  }
+  ambience: {
+    style: ThemeAmbienceStyle
+    volume: number
+  }
+}
+
+export function defaultAppearancePreset(
+  theme: TrackThemeDefinition,
+  surface: TrackAppearanceSurface,
+): TrackAppearancePreset | undefined {
+  return theme.appearancePresets?.[surface]?.find(preset => preset.default === true && !preset.hidden)
+}
+
+interface ThemePalette {
+  laneSurface: string
+  laneEdge: string
+  laneGuard: string
+  structure: string
+  structureSecondary: string
+  mechanism: string
+  moving: string
+  route: string
+  hazard: string
+  finish: string
+  energy: string
+  portal: string
+  glass: string
+  worldGround: string
+  worldPrimary: string
+  worldSecondary: string
+  foliage: string
+  accent: string
+  dark: string
+}
+
+interface MaterialSetOptions {
+  surfacePattern?: MaterialPatternRecipe
+  surfaceEmissive?: string
+  surfaceBumpScale?: number
+  guardPattern?: MaterialPatternRecipe
+  guardEmissive?: string
+  transparentGuardBacking?: boolean
+  structurePattern?: MaterialPatternRecipe
+  trackRoughness?: number
+  trackMetalness?: number
+  guardMetalness?: number
+  clearcoat?: number
+}
+
+export function createThemeMaterialSet(
+  palette: ThemePalette,
+  options: MaterialSetOptions = {},
+): Record<ThemeMaterialSlot, MaterialRecipe> {
+  const standard = (
+    color: string,
+    roughness: number,
+    metalness: number,
+    emissive?: string,
+    pattern?: MaterialPatternRecipe,
+  ): MaterialRecipe => ({
+    kind: 'standard',
+    color,
+    roughness,
+    metalness,
+    envMapIntensity: 0.9,
+    ...(emissive ? { emissive, emissiveIntensity: 0.52 } : {}),
+    ...(pattern ? { pattern } : {}),
+  })
+  const guardMaterial = standard(
+    palette.laneGuard,
+    options.guardPattern ? 0.86 : 0.3,
+    options.guardMetalness ?? 0.66,
+    options.guardEmissive,
+    options.guardPattern,
+  )
+  const laneEdgeMaterial = standard(
+    palette.laneEdge,
+    0.76,
+    Math.max(0.18, options.trackMetalness ?? 0.12),
+  )
+  const movingMaterial: MaterialRecipe = {
+    ...standard(palette.moving, 0.38, 0.28),
+    ...(options.clearcoat
+      ? {
+          kind: 'physical' as const,
+          clearcoat: options.clearcoat,
+          clearcoatRoughness: 0.2,
+        }
+      : {}),
+  }
+  const routeMaterial = standard(palette.route, 0.32, 0.12, palette.route)
+  const hazardMaterial = standard(palette.hazard, 0.38, 0.24, palette.hazard)
+
+  return {
+    'lane.surface': {
+      ...standard(
+        palette.laneSurface,
+        options.trackRoughness ?? 0.68,
+        options.trackMetalness ?? 0.12,
+        options.surfaceEmissive,
+        options.surfacePattern,
+      ),
+      ...(options.surfaceBumpScale ? { bumpScale: options.surfaceBumpScale } : {}),
+    },
+    'lane.edge': laneEdgeMaterial,
+    'lane.guard': guardMaterial,
+    'lane.guard.backing': options.transparentGuardBacking
+      ? { ...guardMaterial, transparent: true, opacity: 0, depthWrite: false }
+      : guardMaterial,
+    'structure.primary': standard(palette.structure, 0.72, 0.24, undefined, options.structurePattern),
+    'structure.secondary': standard(palette.structureSecondary, 0.74, 0.28),
+    'mechanism.body': standard(palette.mechanism, 0.56, 0.42, undefined, options.structurePattern),
+    'mechanism.moving': movingMaterial,
+    'mechanism.flipper.primary': movingMaterial,
+    'mechanism.flipper.secondary': movingMaterial,
+    'signal.route': routeMaterial,
+    'signal.hazard': hazardMaterial,
+    'obstacle.primary': hazardMaterial,
+    'obstacle.secondary': laneEdgeMaterial,
+    'obstacle.base': routeMaterial,
+    'signal.finish': standard(palette.finish, 0.28, 0.14, palette.finish),
+    'effect.energy': standard(palette.energy, 0.22, 0.12, palette.energy),
+    'effect.portal': standard(palette.portal, 0.18, 0.12, palette.portal),
+    glass: {
+      kind: 'physical',
+      color: palette.glass,
+      roughness: 0.1,
+      metalness: 0,
+      clearcoat: 1,
+      clearcoatRoughness: 0.08,
+      transparent: true,
+      opacity: 0.38,
+      depthWrite: false,
+      envMapIntensity: 1.35,
+    },
+    'world.ground': standard(
+      palette.worldGround,
+      options.trackRoughness ?? 0.78,
+      options.trackMetalness ?? 0.04,
+      undefined,
+      options.surfacePattern,
+    ),
+    'world.primary': standard(palette.worldPrimary, 0.72, 0.16, undefined, options.structurePattern),
+    'world.secondary': standard(palette.worldSecondary, 0.58, 0.28),
+    'world.foliage': standard(palette.foliage, 0.88, 0),
+    'world.accent': standard(palette.accent, 0.3, 0.18, palette.accent),
+    'world.dark': standard(palette.dark, 0.9, 0.08),
+  }
+}
+
+const neutralMaterials = createThemeMaterialSet({
+  laneSurface: '#aeb9be',
+  laneEdge: '#27313a',
+  laneGuard: '#e3eaeb',
+  structure: '#35414a',
+  structureSecondary: '#1d252c',
+  mechanism: '#55636d',
+  moving: '#ff765f',
+  route: '#dfff65',
+  hazard: '#ff765f',
+  finish: '#dfff65',
+  energy: '#61ddff',
+  portal: '#b173ff',
+  glass: '#c6ecff',
+  worldGround: '#161d22',
+  worldPrimary: '#3a474f',
+  worldSecondary: '#8b9ba4',
+  foliage: '#50665a',
+  accent: '#dfff65',
+  dark: '#0a0e12',
+})
+
+export const NEUTRAL_STUDIO_THEME: TrackThemeDefinition = {
+  id: 'neutral-studio',
+  version: 2,
+  label: 'Neutral Studio',
+  shortLabel: 'Studio',
+  description: 'A clean graphite studio for focused track construction.',
+  materials: neutralMaterials,
+  environment: {
+    background: '#080b10',
+    fog: '#0b1016',
+    fogNear: 45,
+    fogFar: 220,
+    environmentIntensity: 0.95,
+  },
+  lighting: {
+    skyColor: '#cbd7df',
+    groundColor: '#11161a',
+    ambientIntensity: 1.8,
+    keyColor: '#ffffff',
+    keyIntensity: 3.1,
+    keyPosition: [18, 30, 16],
+    rimColor: '#8eb7ff',
+    rimIntensity: 0.8,
+    rimPosition: [-24, 18, -20],
+    exposure: 1,
+  },
+  world: { kit: 'studio', density: 0.35 },
+  particles: {
+    style: 'none',
+    color: '#ffffff',
+    secondaryColor: '#ffffff',
+    count: 0,
+    size: 0.1,
+    speed: 0,
+    opacity: 0,
+  },
+  ambience: { style: 'studio', volume: 0.035 },
+}
+
+export const MATERIAL_SLOT_DEBUG_THEME: TrackThemeDefinition = {
+  ...NEUTRAL_STUDIO_THEME,
+  id: 'material-slot-debug',
+  version: 2,
+  label: 'Material Slot Debug',
+  shortLabel: 'Debug',
+  description: 'Every semantic surface role rendered as a distinct diagnostic colour.',
+  materials: createThemeMaterialSet({
+    laneSurface: '#00d9ff',
+    laneEdge: '#1747ff',
+    laneGuard: '#f7ff00',
+    structure: '#8038ff',
+    structureSecondary: '#de32ff',
+    mechanism: '#ff8a00',
+    moving: '#ff174d',
+    route: '#26ff72',
+    hazard: '#ff0033',
+    finish: '#ffffff',
+    energy: '#00fff0',
+    portal: '#ff40d6',
+    glass: '#89e9ff',
+    worldGround: '#242424',
+    worldPrimary: '#7c00ff',
+    worldSecondary: '#ff8a00',
+    foliage: '#00ff3c',
+    accent: '#fff000',
+    dark: '#050505',
+  }),
+  environment: {
+    background: '#050508',
+    fog: '#090913',
+    fogNear: 55,
+    fogFar: 220,
+    environmentIntensity: 1,
+  },
+  lighting: {
+    ...NEUTRAL_STUDIO_THEME.lighting,
+    ambientIntensity: 1.9,
+    keyIntensity: 3.4,
+  },
+}
+
+export function createTrackSkinTheme(skin: TrackSkin): TrackThemeDefinition {
+  const color = (value: number): string => `#${value.toString(16).padStart(6, '0')}`
+
+  return {
+    ...NEUTRAL_STUDIO_THEME,
+    id: skin.id,
+    label: skin.label,
+    shortLabel: skin.label,
+    materials: createThemeMaterialSet({
+      laneSurface: color(skin.trackTop),
+      laneEdge: color(skin.trackEdge),
+      laneGuard: color(skin.rail),
+      structure: color(skin.structure),
+      structureSecondary: color(skin.trackEdge),
+      mechanism: color(skin.structure),
+      moving: color(skin.hazard),
+      route: color(skin.signal),
+      hazard: color(skin.hazard),
+      finish: color(skin.signal),
+      energy: color(skin.signal),
+      portal: '#b173ff',
+      glass: '#c6ecff',
+      worldGround: color(skin.fog),
+      worldPrimary: color(skin.structure),
+      worldSecondary: color(skin.rail),
+      foliage: '#50665a',
+      accent: color(skin.signal),
+      dark: color(skin.background),
+    }),
+    environment: {
+      ...NEUTRAL_STUDIO_THEME.environment,
+      background: color(skin.background),
+      fog: color(skin.fog),
+    },
+  }
+}