@marble.fun/track-catalog 3.0.0

package/src/three/vampire-castle-appearance.ts

@@ -0,0 +1,258 @@
+import { createThemeMaterialSet, type MaterialRecipe, type TrackThemeDefinition } from './track-theme'
+import { createSharedObstacleMetalMaterials } from './shared-obstacle-metal'
+
+export const VAMPIRE_CASTLE_THEME_ID = 'vampire-castle'
+export const VAMPIRE_COBBLESTONE_FLOOR_ID = 'vampire-castle.cobblestone-floor'
+export const VAMPIRE_DARK_OAK_FLOOR_ID = 'vampire-castle.dark-oak-floor'
+export const VAMPIRE_CHECKER_MARBLE_FLOOR_ID = 'vampire-castle.checker-marble-floor'
+export const VAMPIRE_CRIMSON_CARPET_ID = 'vampire-castle.crimson-carpet'
+export const VAMPIRE_DARK_STONE_WALL_ID = 'vampire-castle.dark-stone-wall'
+export const VAMPIRE_CARVED_OAK_WALL_ID = 'vampire-castle.carved-oak-wall'
+
+const textureRoot = '/themes/textures/vampire-castle'
+
+function pbrRecipe(
+  stem: string,
+  options: {
+    kind?: 'standard' | 'physical'
+    roughness: number
+    envMapIntensity: number
+    textureWorldSize: readonly [number, number]
+    bumpScale: number
+    normalScale: readonly [number, number]
+    aoMapIntensity: number
+    clearcoat?: number
+    clearcoatRoughness?: number
+    version?: number
+  },
+): MaterialRecipe {
+  const version = options.version ?? 1
+  const shared = {
+    color: '#ffffff',
+    roughness: options.roughness,
+    metalness: 0,
+    envMapIntensity: options.envMapIntensity,
+    textureUrl: `${textureRoot}-${stem}-v${version}-albedo.webp`,
+    normalTextureUrl: `${textureRoot}-${stem}-v${version}-normal.png`,
+    heightTextureUrl: `${textureRoot}-${stem}-v${version}-height.png`,
+    roughnessTextureUrl: `${textureRoot}-${stem}-v${version}-roughness.png`,
+    aoTextureUrl: `${textureRoot}-${stem}-v${version}-ao.png`,
+    textureWorldSize: options.textureWorldSize,
+    bumpScale: options.bumpScale,
+    normalScale: options.normalScale,
+    aoMapIntensity: options.aoMapIntensity,
+  }
+  return options.kind === 'physical'
+    ? {
+        kind: 'physical',
+        ...shared,
+        clearcoat: options.clearcoat,
+        clearcoatRoughness: options.clearcoatRoughness,
+      }
+    : { kind: 'standard', ...shared }
+}
+
+export const VAMPIRE_COBBLESTONE_FLOOR_MATERIAL = pbrRecipe('cobblestone-floor', {
+  roughness: 0.84,
+  envMapIntensity: 0.5,
+  textureWorldSize: [3, 3],
+  bumpScale: 0.055,
+  normalScale: [0.72, 0.72],
+  aoMapIntensity: 0.62,
+})
+
+export const VAMPIRE_DARK_OAK_FLOOR_MATERIAL = pbrRecipe('dark-oak-floor', {
+  kind: 'physical',
+  roughness: 0.68,
+  envMapIntensity: 0.55,
+  textureWorldSize: [4, 5],
+  bumpScale: 0.026,
+  normalScale: [0.48, 0.48],
+  aoMapIntensity: 0.42,
+  clearcoat: 0.22,
+  clearcoatRoughness: 0.5,
+})
+
+export const VAMPIRE_CHECKER_MARBLE_FLOOR_MATERIAL = pbrRecipe('checker-marble-floor', {
+  kind: 'physical',
+  roughness: 0.24,
+  envMapIntensity: 0.96,
+  textureWorldSize: [2.88, 2.88],
+  bumpScale: 0.008,
+  normalScale: [0.18, 0.18],
+  aoMapIntensity: 0.24,
+  clearcoat: 0.88,
+  clearcoatRoughness: 0.13,
+})
+
+export const VAMPIRE_CRIMSON_CARPET_MATERIAL = pbrRecipe('crimson-carpet', {
+  roughness: 0.94,
+  envMapIntensity: 0.24,
+  textureWorldSize: [1.5, 1.5],
+  bumpScale: 0.014,
+  normalScale: [0.32, 0.32],
+  aoMapIntensity: 0.28,
+})
+
+export const VAMPIRE_DARK_STONE_WALL_MATERIAL = pbrRecipe('dark-stone-wall', {
+  roughness: 0.87,
+  envMapIntensity: 0.46,
+  textureWorldSize: [1.8, 1.8],
+  bumpScale: 0.055,
+  normalScale: [0.7, 0.7],
+  aoMapIntensity: 0.58,
+})
+
+export const VAMPIRE_CARVED_OAK_WALL_MATERIAL = pbrRecipe('plain-oak-wall', {
+  kind: 'physical',
+  version: 2,
+  roughness: 0.72,
+  envMapIntensity: 0.52,
+  textureWorldSize: [3.4, 1.28],
+  bumpScale: 0.014,
+  normalScale: [0.38, 0.38],
+  aoMapIntensity: 0.34,
+  clearcoat: 0.18,
+  clearcoatRoughness: 0.58,
+})
+
+export function isVampireCastleCarvedOakWallAppearance(id: string | undefined): boolean {
+  return id === VAMPIRE_CARVED_OAK_WALL_ID
+}
+
+/** Approved Track Lab theme. Lobby/race rotation remains a separate promotion. */
+export const VAMPIRE_CASTLE_THEME: TrackThemeDefinition = {
+  id: VAMPIRE_CASTLE_THEME_ID,
+  version: 1,
+  label: 'Vampire Castle',
+  shortLabel: 'Vampire',
+  description: 'Moonlit Gothic castle grounds, carved oak halls, dark stone, and crimson carpet.',
+  thumbnailUrl: '/themes/previews/vampire-castle-thumbnail.webp',
+  pickerPreviewUrl: '/themes/previews/vampire-castle-picker.webp',
+  loadingPreviewUrl: '/themes/previews/vampire-castle-loading.webp',
+  previewUrl: '/images/social/og/vampire-castle.webp',
+  panoramaUrl: '/themes/panoramas/vampire-castle.ktx2',
+  materials: {
+    ...createThemeMaterialSet(
+      {
+        laneSurface: '#323941',
+        laneEdge: '#2b1518',
+        laneGuard: '#ffffff',
+        structure: '#241614',
+        structureSecondary: '#202932',
+        mechanism: '#2d333b',
+        moving: '#761c28',
+        route: '#a32b3b',
+        hazard: '#c83d46',
+        finish: '#c9d6e4',
+        energy: '#b9d7ff',
+        portal: '#7b1f35',
+        glass: '#b7cce2',
+        worldGround: '#15191f',
+        worldPrimary: '#232a32',
+        worldSecondary: '#47242a',
+        foliage: '#22382f',
+        accent: '#8e2434',
+        dark: '#07090d',
+      },
+      {
+        trackRoughness: 0.84,
+        trackMetalness: 0,
+        guardMetalness: 0,
+      },
+    ),
+    'lane.surface': VAMPIRE_COBBLESTONE_FLOOR_MATERIAL,
+    'lane.guard': VAMPIRE_DARK_STONE_WALL_MATERIAL,
+    'lane.guard.backing': VAMPIRE_DARK_STONE_WALL_MATERIAL,
+    'structure.primary': VAMPIRE_CARVED_OAK_WALL_MATERIAL,
+    'structure.secondary': VAMPIRE_DARK_STONE_WALL_MATERIAL,
+    ...createSharedObstacleMetalMaterials({ light: '#a53845', dark: '#6f202b' }),
+  },
+  appearancePresets: {
+    floor: [
+      {
+        id: VAMPIRE_COBBLESTONE_FLOOR_ID,
+        label: 'Cobblestone',
+        default: true,
+        material: VAMPIRE_COBBLESTONE_FLOOR_MATERIAL,
+      },
+      {
+        id: VAMPIRE_DARK_OAK_FLOOR_ID,
+        label: 'Oak Boards',
+        material: VAMPIRE_DARK_OAK_FLOOR_MATERIAL,
+      },
+      {
+        id: VAMPIRE_CHECKER_MARBLE_FLOOR_ID,
+        label: 'Checker Marble',
+        material: VAMPIRE_CHECKER_MARBLE_FLOOR_MATERIAL,
+      },
+    ],
+    rail: [
+      {
+        id: VAMPIRE_CRIMSON_CARPET_ID,
+        label: 'Crimson Carpet',
+        detailStyle: 'centered-floor-runner',
+        material: VAMPIRE_CRIMSON_CARPET_MATERIAL,
+      },
+    ],
+    wall: [
+      {
+        id: VAMPIRE_DARK_STONE_WALL_ID,
+        label: 'Castle Masonry',
+        default: true,
+        detailStyle: 'shared-stone-block-shell',
+        material: VAMPIRE_DARK_STONE_WALL_MATERIAL,
+      },
+      {
+        id: VAMPIRE_CARVED_OAK_WALL_ID,
+        label: 'Carved Oak',
+        material: VAMPIRE_CARVED_OAK_WALL_MATERIAL,
+      },
+    ],
+  },
+  detailMaterials: {
+    [VAMPIRE_DARK_STONE_WALL_ID]: VAMPIRE_DARK_STONE_WALL_MATERIAL,
+    [VAMPIRE_CARVED_OAK_WALL_ID]: VAMPIRE_CARVED_OAK_WALL_MATERIAL,
+  },
+  environment: {
+    background: '#070a10',
+    fog: '#111a25',
+    fogNear: 48,
+    fogFar: 205,
+    environmentIntensity: 1.08,
+  },
+  lighting: {
+    skyColor: '#b9d2ee',
+    groundColor: '#090b10',
+    ambientIntensity: 2.32,
+    keyColor: '#d7e8ff',
+    keyIntensity: 4.65,
+    keyPosition: [-28, 38, 18],
+    rimColor: '#6d1727',
+    rimIntensity: 1.9,
+    rimPosition: [24, 14, -28],
+    exposure: 1.16,
+    practical: {
+      color: '#d67d68',
+      intensity: 12,
+      distance: 26,
+      decay: 2,
+      count: 4,
+      heightOffset: 2.1,
+    },
+  },
+  world: { kit: 'ancient-egypt', density: 0 },
+  particles: {
+    style: 'dust',
+    color: '#bdcee0',
+    secondaryColor: '#6f1828',
+    count: 110,
+    size: 0.11,
+    speed: 0.18,
+    opacity: 0.18,
+  },
+  ambience: { style: 'studio', volume: 0.035 },
+}
+
+/** Kept as a compatibility alias for the standalone material-proof page. */
+export const VAMPIRE_CASTLE_PREVIEW_THEME = VAMPIRE_CASTLE_THEME

package/src/three/visual-frame-pacing.ts

@@ -0,0 +1,19 @@
+/**
+ * Accept browser callbacks just before the 60 Hz deadline. RAF timestamps are
+ * rounded and fluctuate around vsync; a strict comparison can drop a complete
+ * display frame (or alternate 8/25 ms intervals on a 120 Hz display).
+ * Keep deadlines on the original cadence, including after early frames or
+ * stalls, rather than moving the target with each callback's jitter.
+ */
+export function nextVisualFrameDeadline(
+  timeMs: number,
+  deadlineMs: number,
+  framesPerSecond: number,
+): number | undefined {
+  const intervalMs = 1_000 / framesPerSecond
+  const toleranceMs = Math.min(1, intervalMs * 0.1)
+  if (deadlineMs === 0) return timeMs + intervalMs
+  if (timeMs + toleranceMs < deadlineMs) return undefined
+  const elapsedIntervals = Math.max(1, Math.floor((timeMs - deadlineMs + toleranceMs) / intervalMs) + 1)
+  return deadlineMs + elapsedIntervals * intervalMs
+}

package/src/three/visual-geometry.ts

@@ -0,0 +1,120 @@
+import * as THREE from 'three'
+
+import { geometryDetailProfile } from './geometry-detail'
+
+/** Render tessellation only. Never use these constructors for Rapier inputs. */
+export const VISUAL_TRIANGLE_RATIO = geometryDetailProfile.triangleRatio
+const AXIS_RATIO = Math.sqrt(VISUAL_TRIANGLE_RATIO)
+
+function segments(value: number, minimum: number, ratio = AXIS_RATIO): number {
+  const profileMinimum = Math.max(Math.min(minimum, 3), Math.ceil(minimum * geometryDetailProfile.minimumScale))
+  return Math.min(value, Math.max(profileMinimum, Math.floor(value * ratio)))
+}
+
+export class VisualSphereGeometry extends THREE.SphereGeometry {
+  constructor(
+    radius = 1,
+    width = 32,
+    height = 16,
+    phiStart = 0,
+    phiLength = Math.PI * 2,
+    thetaStart = 0,
+    thetaLength = Math.PI,
+  ) {
+    super(radius, segments(width, 8), segments(height, 4), phiStart, phiLength, thetaStart, thetaLength)
+  }
+}
+
+export class VisualCylinderGeometry extends THREE.CylinderGeometry {
+  constructor(
+    top = 1,
+    bottom = 1,
+    height = 1,
+    radial = 32,
+    vertical = 1,
+    open = false,
+    start = 0,
+    length = Math.PI * 2,
+  ) {
+    super(
+      top,
+      bottom,
+      height,
+      segments(radial, 6, vertical === 1 ? VISUAL_TRIANGLE_RATIO : AXIS_RATIO),
+      segments(vertical, 1),
+      open,
+      start,
+      length,
+    )
+  }
+}
+
+export class VisualConeGeometry extends THREE.ConeGeometry {
+  constructor(radius = 1, height = 1, radial = 32, vertical = 1, open = false, start = 0, length = Math.PI * 2) {
+    super(
+      radius,
+      height,
+      segments(radial, 5, vertical === 1 ? VISUAL_TRIANGLE_RATIO : AXIS_RATIO),
+      segments(vertical, 1),
+      open,
+      start,
+      length,
+    )
+  }
+}
+
+export class VisualTorusGeometry extends THREE.TorusGeometry {
+  constructor(radius = 1, tube = 0.4, radial = 12, tubular = 48, arc = Math.PI * 2) {
+    super(radius, tube, segments(radial, 3), segments(tubular, 8), arc)
+  }
+}
+
+export class VisualTubeGeometry extends THREE.TubeGeometry {
+  constructor(path?: THREE.Curve<THREE.Vector3>, tubular = 64, radius = 1, radial = 8, closed = false) {
+    super(path, segments(tubular, 3), radius, segments(radial, 3), closed)
+  }
+}
+
+export class VisualLatheGeometry extends THREE.LatheGeometry {
+  constructor(points?: THREE.Vector2[], radial = 12, start = 0, length = Math.PI * 2) {
+    super(points, segments(radial, 8, VISUAL_TRIANGLE_RATIO), start, length)
+  }
+}
+
+export class VisualCapsuleGeometry extends THREE.CapsuleGeometry {
+  constructor(radius = 1, length = 1, caps = 4, radial = 8) {
+    super(radius, length, segments(caps, 2), segments(radial, 8))
+  }
+}
+
+export class VisualCircleGeometry extends THREE.CircleGeometry {
+  constructor(radius = 1, radial = 32, start = 0, length = Math.PI * 2) {
+    super(radius, segments(radial, 8, VISUAL_TRIANGLE_RATIO), start, length)
+  }
+}
+
+export class VisualIcosahedronGeometry extends THREE.IcosahedronGeometry {
+  constructor(radius = 1, detail = 0) {
+    super(radius, Math.max(0, Math.floor((detail + 1) * AXIS_RATIO) - 1))
+  }
+}
+
+/** Omit tiny architectural bevels while retaining the authoring call signature. */
+export class VisualBoxGeometry extends THREE.BoxGeometry {
+  constructor(width = 1, height = 1, depth = 1, _segments = 2, _radius = 0.1) {
+    super(width, height, depth)
+    void _segments
+    void _radius
+  }
+}
+
+export class VisualExtrudeGeometry extends THREE.ExtrudeGeometry {
+  constructor(shapes?: THREE.Shape | THREE.Shape[], options: THREE.ExtrudeGeometryOptions = {}) {
+    super(shapes, {
+      ...options,
+      curveSegments: segments(options.curveSegments ?? 12, 1, VISUAL_TRIANGLE_RATIO),
+      steps: segments(options.steps ?? 1, 1),
+      bevelSegments: options.bevelSegments === 0 ? 0 : 1,
+    })
+  }
+}

package/src/three/visual-quality.ts

@@ -0,0 +1,83 @@
+export type VisualQualityTier = 'quality' | 'balanced' | 'performance' | 'low'
+
+export type PortalRenderMode = 'live' | 'reduced' | 'static'
+
+export interface VisualQualityPolicy {
+  tier: VisualQualityTier
+  visualFramesPerSecond: 60
+  pixelRatioScale: number
+  particleScale: number
+  shadowMapSize: 512 | 1024
+  shadowRefreshRate: 10 | 20 | 30
+  portal: {
+    mode: PortalRenderMode
+    refreshRate: number
+    renderTargetScale: number
+    viewsPerFrame: 0 | 1 | 2
+  }
+}
+
+// Every tier uses animated coloured rifts; destination cameras stay disabled.
+export const VISUAL_QUALITY_POLICIES: Readonly<Record<VisualQualityTier, VisualQualityPolicy>> = {
+  // Explicit diagnostic preset only: automatic adaptation never selects it.
+  low: {
+    tier: 'low',
+    visualFramesPerSecond: 60,
+    pixelRatioScale: 0.5,
+    particleScale: 0,
+    shadowMapSize: 512,
+    shadowRefreshRate: 10,
+    portal: {
+      mode: 'static',
+      refreshRate: 0,
+      renderTargetScale: 0.25,
+      viewsPerFrame: 0,
+    },
+  },
+  quality: {
+    tier: 'quality',
+    visualFramesPerSecond: 60,
+    pixelRatioScale: 1,
+    particleScale: 1,
+    shadowMapSize: 1024,
+    shadowRefreshRate: 30,
+    portal: {
+      mode: 'static',
+      refreshRate: 0,
+      renderTargetScale: 1,
+      viewsPerFrame: 0,
+    },
+  },
+  balanced: {
+    tier: 'balanced',
+    visualFramesPerSecond: 60,
+    pixelRatioScale: 0.9,
+    particleScale: 0.6,
+    shadowMapSize: 1024,
+    shadowRefreshRate: 20,
+    portal: {
+      mode: 'static',
+      refreshRate: 0,
+      renderTargetScale: 0.7,
+      viewsPerFrame: 0,
+    },
+  },
+  performance: {
+    tier: 'performance',
+    visualFramesPerSecond: 60,
+    pixelRatioScale: 0.72,
+    particleScale: 0.25,
+    shadowMapSize: 512,
+    shadowRefreshRate: 10,
+    portal: {
+      mode: 'static',
+      refreshRate: 0,
+      renderTargetScale: 0.45,
+      viewsPerFrame: 0,
+    },
+  },
+}
+
+export function visualQualityPolicy(tier: VisualQualityTier): VisualQualityPolicy {
+  return VISUAL_QUALITY_POLICIES[tier]
+}

package/src/three/water-appearance.ts

@@ -0,0 +1,29 @@
+import type { MaterialSlot } from '@marble.fun/physics-engine'
+
+export const FLOWING_WATER_APPEARANCE_ID = 'effect.flowing-water'
+
+export type FluidSurfaceStyle = 'water'
+
+export function supportsFlowingWaterOverlay(runtimeKind: string, materialSlots: readonly MaterialSlot[]): boolean {
+  return runtimeKind !== 'vortex' && materialSlots.includes('lane.surface')
+}
+
+export function isFlowingWaterAppearance(materialId: string | undefined): boolean {
+  return materialId === FLOWING_WATER_APPEARANCE_ID
+}
+
+export function fluidSurfaceStyleFromId(materialId: string | undefined): FluidSurfaceStyle | undefined {
+  if (materialId === FLOWING_WATER_APPEARANCE_ID) return 'water'
+  return undefined
+}
+
+export function isFluidSurfaceAppearance(materialId: string | undefined): boolean {
+  return fluidSurfaceStyleFromId(materialId) !== undefined
+}
+
+export function supportsFloorAppearanceChoices(runtimeKind: string, materialSlots: readonly string[]): boolean {
+  // These mechanisms expose their own bowl/lift surface treatment. They have
+  // short lane collars, but no continuous base floor that can truthfully be
+  // replaced by a routed plank/sand family.
+  return runtimeKind !== 'vortex' && runtimeKind !== 'conveyor' && materialSlots.includes('lane.surface')
+}

package/src/three/wild-west-sand-appearance.ts

@@ -0,0 +1,2 @@
+export const WILD_WEST_SAND_FLOOR_ID = 'wild-west.sandy-track'
+export const WILD_WEST_SAND_SHOULDER_MATERIAL_ID = 'wild-west.sand-shoulder'