@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-definition.ts

@@ -0,0 +1,443 @@
+export {
+  DEFAULT_TRACK_TROUGH_FLAT_FRACTION,
+  TRACK_RAIL_CROSS_SECTION_SEGMENTS,
+  TRACK_RAIL_WALL_THICKNESS,
+  defaultTrackTroughDepth,
+  railSurfacePoseAt,
+  railTroughCrossSectionOffset,
+  railTroughDepthAt,
+  railTroughFlatFraction,
+  railWidthAt,
+  type RailSurfacePose,
+} from '@marble.fun/physics-engine/browser'
+import type {
+  PhysicsConveyorPieceDefinition,
+  PhysicsDipperPieceDefinition,
+  PhysicsFinishPieceDefinition,
+  PhysicsFlipperBankPieceDefinition,
+  PhysicsJumpPieceDefinition,
+  PhysicsPegFieldPieceDefinition,
+  PhysicsPortalPieceDefinition,
+  PhysicsRailPieceDefinition,
+  PhysicsReboundPieceDefinition,
+  PhysicsRisingWallForestPieceDefinition,
+  PhysicsSplitterPieceDefinition,
+  PhysicsTrackDefinition,
+  PhysicsTurntablePieceDefinition,
+  PhysicsVortexPieceDefinition,
+  TrackDocument,
+  TrackPieceAppearance,
+} from '@marble.fun/physics-engine/browser'
+
+export type TrackVector = readonly [x: number, y: number, z: number]
+
+export interface TrackSkin {
+  id: string
+  label: string
+  background: number
+  fog: number
+  trackTop: number
+  trackEdge: number
+  rail: number
+  structure: number
+  signal: number
+  hazard: number
+}
+
+interface TrackPieceBase {
+  id: string
+  label: string
+  appearance?: TrackPieceAppearance
+  /** Visual-only absolute metric offset inherited across connected pieces. */
+  materialConnectionPhase?: number
+  /** Hidden previews can defer expensive masonry until continuity supplies its final phase. */
+  deferStoneArchitectureUntilMaterialContinuity?: boolean
+}
+
+export interface RailPieceDefinition extends TrackPieceBase, PhysicsRailPieceDefinition {
+  type: 'rail'
+  /** Visual-only topology capability. Vortex-owned rails reject roof/canopy wall architecture. */
+  supportsAppearanceCanopy?: boolean
+  /** Track Lab-only bounds and ray-picking meshes; runtime race worlds omit them. */
+  editorProxies?: boolean
+  /** Visual-only connector locations in the same coordinate space as `points`, used to inherit exact material frames. */
+  materialConnectors?: readonly {
+    id: string
+    position: TrackVector
+  }[]
+  /**
+   * Visual-only longitudinal sampling for a non-physical overview preview.
+   * Runtime rails and colliders always retain the canonical 2.5 cm sampling.
+   */
+  previewProfileSamplePitch?: number
+  /** Visual-only fluid continuity at the first/input terminal. */
+  waterFlowStartConnected?: boolean
+  /** Visual-only fluid continuity at the last/output terminal. */
+  waterFlowEndConnected?: boolean
+  /** Keep the selected floor recipe on one continuous carrier mesh instead of material-authored separated boards. */
+  continuousFloorMaterialOnly?: boolean
+  /** Visual race landmark role. This never changes rail physics. */
+  raceRole?: 'start' | 'finish'
+  /** Optional visual railway topology for themed raised rails. */
+  railroadProfile?: 'routing-split' | 'routing-merge' | 'intersection-merge'
+  /**
+   * Turns one continuous ribbon into two standard lane troughs without
+   * stacking separate floor meshes or colliders. Used by passive routing
+   * pieces whose terminal is a pair of side-by-side connectors.
+   */
+  routingBranchProfile?: {
+    mode: 'split' | 'merge'
+    branchOffset: number
+    branchWidth: number
+    startProgress: number
+    endProgress: number
+    /** Metric radius of each circular half of the branch S-bend. */
+    bendRadius?: number
+  }
+  /**
+   * Additional ingress centerlines that are fused with `points` into one
+   * junction floor and one floor collider. They are geometry, not separate
+   * track pieces, so intersections cannot leave coplanar overlapping shells.
+   */
+  junctionBranches?: readonly {
+    connectorId: string
+    /** Visual-only absolute metric phase at this branch input connector. */
+    materialConnectionPhase?: number
+    /** Visual-only fluid continuity at this branch input connector. */
+    waterFlowStartConnected?: boolean
+    points: readonly TrackVector[]
+    startTangent?: TrackVector
+    endTangent?: TrackVector
+    startPortWidth?: number
+    startPortTroughDepth?: number
+    startPortTroughFlatFraction?: number
+    /** Whether the branch input wall volumes close at their exposed terminal. */
+    capStart?: boolean
+  }[]
+  /** Connector that owns the first point of the junction's primary route. */
+  junctionMainConnectorId?: string
+  points: readonly TrackVector[]
+  /** Exact forward tangent at the first port. Prevents sampled curves from rotating their terminal cross-section. */
+  startTangent?: TrackVector
+  /** Exact forward tangent at the last port. Prevents sampled curves from rotating their terminal cross-section. */
+  endTangent?: TrackVector
+  /** Negotiated width of the first connected port, independent of the rail's interior width. */
+  startPortWidth?: number
+  /** Negotiated width of the last connected port, independent of the rail's interior width. */
+  endPortWidth?: number
+  /** Negotiated trough depth of the first connected port. */
+  startPortTroughDepth?: number
+  /** Negotiated trough depth of the last connected port. */
+  endPortTroughDepth?: number
+  /** Negotiated flat-bottom fraction of the first connected trough. */
+  startPortTroughFlatFraction?: number
+  /** Negotiated flat-bottom fraction of the last connected trough. */
+  endPortTroughFlatFraction?: number
+  /** Whether the floor and wall shells close across the first cross-section. Connected ports leave this open. */
+  capStart?: boolean
+  /** Whether the floor and wall shells close across the last cross-section. Connected ports leave this open. */
+  capEnd?: boolean
+  width: number
+  startWidth?: number
+  pointWidths?: readonly number[]
+  widthProfile?: 'linear' | 'smoothstep'
+  startTroughDepth?: number
+  troughDepth?: number
+  pointTroughDepths?: readonly number[]
+  /** Optional per-control-point trough profiles, interpolated with the floor geometry. */
+  pointTroughFlatFractions?: readonly number[]
+  troughProfile?: 'full' | 'fade-in' | 'fade-out' | 'fade-both'
+  troughFadeFraction?: number
+  troughFlatFraction?: number
+  wallHeight?: number
+  /** Optional side-wall collider height, independent of the rendered wall height. */
+  wallColliderHeight?: number
+  verticalWalls?: boolean
+  floorFriction?: number
+  wallFriction?: number
+  openFirstSegment?: boolean
+  openLastSegment?: boolean
+  openNegativeWallSegments?: readonly number[]
+  openPositiveWallSegments?: readonly number[]
+  closedStart?: boolean
+  closedEnd?: boolean
+  /** Optional collider height for a closed start, independent of the side-wall height. */
+  closedStartHeight?: number
+  /** Optional collider height for a closed end, independent of the side-wall height. */
+  closedEndHeight?: number
+  centerDivider?: {
+    /** A divider is independent geometry; this controls whether it looks like a wall or an obstacle. */
+    visualRole?: 'wall' | 'obstacle'
+    startProgress: number
+    endProgress: number
+    startWidth: number
+    endWidth: number
+    /** Floor-profile span used to anchor the start edge before wall-thickness overhang. */
+    startSurfaceWidth?: number
+    /** Floor-profile span used to anchor the end edge before wall-thickness overhang. */
+    endSurfaceWidth?: number
+    /** Total terminal span whose excess over endWidth closes adjacent wall ends. */
+    endWallClosureWidth?: number
+    startHeight: number
+    endHeight: number
+    lateralOffset?: number
+    distanceBased?: boolean
+  }
+}
+export interface VortexPieceDefinition extends TrackPieceBase, PhysicsVortexPieceDefinition {
+  type: 'vortex'
+  /** The negotiated input is carrying the same fluid style into this Vortex. */
+  waterFlowInputConnected?: boolean
+  center: TrackVector
+  entry: TrackVector
+  entryWidth: number
+  integratedEntry?: boolean
+  dropEntry?: boolean
+  outerRadius: number
+  innerRadius: number
+  depth: number
+  profileExponent?: number
+  /** Smooths the bowl into its outer apron while preserving an inward drain slope. */
+  smoothProfile?: boolean
+  floorFriction?: number
+  segmentCount: number
+  exitFunnel?: {
+    mouthRadius: number
+    throatRadius: number
+    depth: number
+    ringCount: number
+    friction?: number
+    tunnelFriction?: number
+    throatLength?: number
+    outletRadius?: number
+    tunnelExit?: TrackVector
+    tunnelDirection?: TrackVector
+  }
+}
+
+export interface SplitterPieceDefinition extends TrackPieceBase, PhysicsSplitterPieceDefinition {
+  type: 'splitter'
+  center: TrackVector
+  capture: TrackVector
+  direction: TrackVector
+  surfaceAligned?: boolean
+  captureRadius: number
+  barLength: number
+  barHeight: number
+  barDepth: number
+  swingRadians: number
+  cycleSeconds: number
+  phaseIndex: number
+}
+
+export interface JumpPieceDefinition extends TrackPieceBase, PhysicsJumpPieceDefinition {
+  type: 'jump'
+  points: readonly TrackVector[]
+  width: number
+  wallHeight: number
+}
+
+export interface ConveyorPieceDefinition extends TrackPieceBase, PhysicsConveyorPieceDefinition {
+  type: 'conveyor'
+  bottom: TrackVector
+  top: TrackVector
+  direction: TrackVector
+  width: number
+  shelfDepth: number
+  shelfCount: number
+  speed: number
+  friction: number
+  shelfTiltRadians: number
+  releaseHeight: number
+  phaseIndex: number
+}
+
+export interface FlipperMountDefinition {
+  anchor: TrackVector
+  side: 'left' | 'right'
+  direction?: TrackVector
+}
+
+export interface FlipperBankPieceDefinition extends TrackPieceBase, PhysicsFlipperBankPieceDefinition {
+  type: 'flipper-bank'
+  direction: TrackVector
+  mounts: readonly FlipperMountDefinition[]
+  paddleLength: number
+  paddleWidth: number
+  paddleHeight: number
+  swingRadians: number
+  strikeSeconds: number
+  holdSeconds: number
+  returnSeconds: number
+  minimumIntervalSeconds: number
+  maximumIntervalSeconds: number
+}
+
+export interface TurntablePieceDefinition extends TrackPieceBase, PhysicsTurntablePieceDefinition {
+  type: 'turntable'
+  center: TrackVector
+  direction: TrackVector
+  radius: number
+  channelWidth: number
+  wallHeight: number
+  routeAngles: readonly number[]
+  rotationSeconds: number
+  settleSeconds: number
+  triggerRadius: number
+}
+
+export interface DipperPieceDefinition extends TrackPieceBase, PhysicsDipperPieceDefinition {
+  type: 'dipper'
+  hinge: TrackVector
+  direction: TrackVector
+  length: number
+  width: number
+  wallHeight: number
+  dropRadians: number
+  lowerSeconds: number
+  holdSeconds: number
+  resetSeconds: number
+  triggerRadius: number
+}
+
+export interface PegFieldPieceDefinition extends TrackPieceBase, PhysicsPegFieldPieceDefinition {
+  type: 'peg-field'
+  direction: TrackVector
+  pegs: readonly TrackVector[]
+  pegDirections?: readonly TrackVector[]
+  pegRadius: number
+  pegHeight: number
+  colliderShape?: 'cone' | 'cylinder'
+  friction?: number
+  restitution?: number
+}
+
+export interface ReboundMountDefinition {
+  anchor: TrackVector
+  angle: number
+  side: 'left' | 'right'
+}
+
+export interface ReboundPieceDefinition extends TrackPieceBase, PhysicsReboundPieceDefinition {
+  type: 'rebounds'
+  direction: TrackVector
+  mounts: readonly ReboundMountDefinition[]
+  reboundLength: number
+  reboundWidth: number
+  reboundHeight: number
+  friction: number
+  restitution: number
+  strikeDistance: number
+  strikeSeconds: number
+  holdSeconds: number
+  returnSeconds: number
+  cooldownSeconds: number
+}
+
+export interface RisingWallAnchorDefinition {
+  position: TrackVector
+  row: number
+  column: number
+}
+
+export interface RisingWallForestPieceDefinition extends TrackPieceBase, PhysicsRisingWallForestPieceDefinition {
+  type: 'rising-wall-forest'
+  direction: TrackVector
+  anchors: readonly RisingWallAnchorDefinition[]
+  rows: number
+  columns: number
+  density: 'sparse' | 'dense'
+  wallWidth: number
+  wallHeight: number
+  wallDepth: number
+  cycleSeconds: number
+}
+
+export interface PortalPieceDefinition extends TrackPieceBase, PhysicsPortalPieceDefinition {
+  type: 'portal'
+  entryVisualStyle?: PortalVisualStyle
+  exitVisualStyle?: PortalVisualStyle
+  color: string
+  entry: TrackVector
+  entryDirection?: TrackVector
+  exit: TrackVector
+  exitDirection: TrackVector
+  entryVisualCenter: TrackVector
+  entryVisualDirection: TrackVector
+  exitVisualCenter: TrackVector
+  exitVisualDirection: TrackVector
+  captureRadius?: number
+  captureHalfExtents?: TrackVector
+  releaseSpeed: number
+}
+
+export type PortalVisualStyle = 'live-window'
+
+export interface FinishPieceDefinition extends TrackPieceBase, PhysicsFinishPieceDefinition {
+  type: 'finish'
+  center: TrackVector
+  direction: TrackVector
+  width: number
+  channelEnd: TrackVector
+  rankingSlots: number
+  rankingSpacing: number
+}
+
+export type TrackPieceDefinition =
+  | RailPieceDefinition
+  | VortexPieceDefinition
+  | SplitterPieceDefinition
+  | JumpPieceDefinition
+  | ConveyorPieceDefinition
+  | FlipperBankPieceDefinition
+  | TurntablePieceDefinition
+  | DipperPieceDefinition
+  | PegFieldPieceDefinition
+  | ReboundPieceDefinition
+  | RisingWallForestPieceDefinition
+  | PortalPieceDefinition
+  | FinishPieceDefinition
+
+export interface TrackGuidePoint {
+  position: TrackVector
+  progress: number
+  pieceId: string
+}
+
+export interface TrackGuidePath {
+  id: string
+  points: readonly TrackGuidePoint[]
+}
+
+export interface TrackDefinition extends PhysicsTrackDefinition {
+  id: string
+  version: number
+  label: string
+  description: string
+  targetDurationSeconds: readonly [number, number]
+  spawnProgress: number
+  spawnWidth: number
+  themeId?: string
+  skin: TrackSkin
+  pieces: readonly TrackPieceDefinition[]
+  cameraPath: TrackGuidePath
+  projectionPaths: readonly TrackGuidePath[]
+  /**
+   * Authored source for the canonical Lab visual assembly. This is runtime
+   * context rather than simulation identity and is omitted by legacy tracks.
+   */
+  sourceDocument?: TrackDocument
+}
+
+export const NEUTRAL_STUDIO_SKIN: TrackSkin = {
+  id: 'neutral-studio',
+  label: 'Neutral Studio',
+  background: 0x080b10,
+  fog: 0x0b1016,
+  trackTop: 0xaeb9be,
+  trackEdge: 0x27313a,
+  rail: 0xe3eaeb,
+  structure: 0x35414a,
+  signal: 0xdfff65,
+  hazard: 0xff765f,
+}

package/src/pages/play/race/track-fence-architecture.ts

@@ -0,0 +1,33 @@
+/** Shared visual proportions for open timber fences, independent of theme materials. */
+export const WOODEN_FENCE_HEIGHT_RATIO = 0.65
+export const WOODEN_FENCE_POST_SPAN_RATIO = 1.82
+export const WOODEN_FENCE_MINIMUM_POST_GAP = 0.08
+/** Visual breathing room beyond the physical wall's outer face. */
+export const WOODEN_FENCE_EDGE_ALLOWANCE = 0.025
+
+export function woodenFenceHeight(wallHeight: number): number {
+  return Math.max(0, wallHeight) * WOODEN_FENCE_HEIGHT_RATIO
+}
+
+export function woodenFencePostCount(totalLength: number, fenceHeight: number): number {
+  if (totalLength <= 0 || fenceHeight <= 0) return 0
+  return Math.max(2, Math.ceil(totalLength / (fenceHeight * WOODEN_FENCE_POST_SPAN_RATIO)) + 1)
+}
+
+/**
+ * Spatial exclusion shared by path-following fence schedulers. Junctions can
+ * contain several boundary runs whose independent arc-length stations meet in
+ * world space; this keeps their post surfaces separated by a real gap.
+ */
+export function woodenFenceMinimumPostCenterDistance(maximumPostWidth: number): number {
+  return Math.max(0, maximumPostWidth) + WOODEN_FENCE_MINIMUM_POST_GAP
+}
+
+/**
+ * Canonical wall runs describe the middle of a physical wall. Fence members
+ * live just outside its exterior face, matching the placement used by normal
+ * ribbon lanes.
+ */
+export function woodenFenceOutwardPlacementOffset(wallThickness: number): number {
+  return Math.max(0, wallThickness) / 2 + WOODEN_FENCE_EDGE_ALLOWANCE
+}

package/src/pages/play/race/track-floor-material-rules.ts

@@ -0,0 +1,51 @@
+import type { ThemeMaterialRegistry } from '../../../three/theme-material-registry'
+import { TRACK_THEMES } from '../../../three/theme-catalog'
+import { resolvedFloorMaterialIdForTheme } from '../../../three/railroad-appearance'
+import type { MaterialRecipe, TrackThemeDefinition } from '../../../three/track-theme'
+import type { FloorSurfaceTreatment, TrackMaterials } from './track-mechanisms'
+
+function floorRecipeForTheme(theme: TrackThemeDefinition, floorMaterialId: string | undefined): MaterialRecipe {
+  const resolvedId = resolvedFloorMaterialIdForTheme(theme, floorMaterialId)
+  if (!resolvedId) return theme.materials['lane.surface']
+  return (
+    theme.detailMaterials?.[resolvedId] ??
+    theme.appearancePresets?.floor?.find(preset => preset.id === resolvedId)?.material ??
+    theme.materials['lane.surface']
+  )
+}
+
+export function resolveFloorSurfaceTreatment(
+  registry: ThemeMaterialRegistry,
+  floorMaterialId: string | undefined,
+): TrackMaterials['floorSurfaceTreatment'] {
+  const treatment = registry.getAppearanceRecipe(floorMaterialId, 'lane.surface').surfaceTreatment
+  return treatment
+    ? {
+        ...treatment,
+        material: registry.getAppearance(treatment.materialId, 'lane.edge'),
+        themeId: registry.activeTheme.id,
+      }
+    : undefined
+}
+
+export function resolveFloorSurfaceTreatments(
+  registry: ThemeMaterialRegistry,
+  floorMaterialId: string | undefined,
+): readonly FloorSurfaceTreatment[] {
+  const grouped = new Map<string, { treatment: NonNullable<MaterialRecipe['surfaceTreatment']>; themeIds: string[] }>()
+  for (const theme of TRACK_THEMES) {
+    const treatment = floorRecipeForTheme(theme, floorMaterialId).surfaceTreatment
+    if (!treatment) continue
+    const key = `${treatment.kind}:${treatment.materialId}:${treatment.bandWidth}:${treatment.featherWidth}:${treatment.normalOffset}`
+    const group = grouped.get(key) ?? { treatment, themeIds: [] }
+    group.themeIds.push(theme.id)
+    grouped.set(key, group)
+  }
+  return [...grouped.values()].map(({ treatment, themeIds }) => ({
+    ...treatment,
+    get material() {
+      return registry.getAppearance(treatment.materialId, 'lane.edge')
+    },
+    themeId: themeIds.length === 1 ? themeIds[0]! : themeIds,
+  }))
+}