@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/path-pattern-layout.ts

@@ -0,0 +1,142 @@
+import * as THREE from 'three'
+
+export interface PathPatternFrame {
+  point: THREE.Vector3
+  tangent: THREE.Vector3
+  distance: number
+}
+
+export interface PathPatternDomain {
+  frames: readonly PathPatternFrame[]
+  length: number
+  closed: boolean
+  includeStart?: boolean
+  includeEnd?: boolean
+}
+
+export interface PathPatternPolicy {
+  maximumSpacing: number
+  dedupeDistance?: number
+  dedupeSpace?: 'world' | 'horizontal'
+}
+
+export interface PathPatternPlacement {
+  domainIndex: number
+  distance: number
+  point: THREE.Vector3
+  tangent: THREE.Vector3
+  terminal: boolean
+}
+
+export interface LinearPatternPolicy {
+  targetPitch: number
+  gap: number
+  minimumElementSize?: number
+}
+
+export interface LinearPatternLayout {
+  count: number
+  pitch: number
+  elementSize: number
+  centers: number[]
+  terminalGap: number
+}
+
+const EPSILON = 0.000_001
+
+/**
+ * Keeps repeated elements on one fixed arc-length cadence. Any remainder is
+ * split symmetrically between the two terminals; refitting the pitch per
+ * piece makes plank courses visibly accelerate and breaks their module-locked
+ * rhythm at a connector.
+ */
+export function distributeLinearPattern(
+  length: number,
+  policy: LinearPatternPolicy,
+): LinearPatternLayout {
+  const safeLength = Math.max(EPSILON, length)
+  const targetPitch = Math.max(EPSILON, policy.targetPitch)
+  const gap = Math.max(0, policy.gap)
+  const minimumElementSize = Math.max(EPSILON, policy.minimumElementSize ?? EPSILON)
+  const count = Math.max(1, Math.floor(safeLength / targetPitch))
+  const pitch = safeLength < targetPitch ? safeLength : targetPitch
+  const usableElementSize = Math.max(EPSILON, Math.min(pitch, safeLength) - gap)
+  const elementSize = Math.min(safeLength, Math.max(minimumElementSize, usableElementSize))
+  const remainder = Math.max(0, safeLength - count * pitch)
+  const terminalRemainder = remainder / 2
+  return {
+    count,
+    pitch,
+    elementSize,
+    centers: Array.from({ length: count }, (_, index) => terminalRemainder + (index + 0.5) * pitch),
+    terminalGap: terminalRemainder + Math.min(gap, Math.max(0, pitch - minimumElementSize)) / 2,
+  }
+}
+
+/**
+ * Distributes repeated visual elements over canonical paths using the same
+ * rule as the Wild West stockade: spacing is a maximum gap, and the chosen
+ * number of intervals is re-phased evenly over the complete run.
+ *
+ * An open connected run normally owns its end and not its start. That gives a
+ * shared terminal exactly one owner when independently rendered track pieces
+ * meet, without any track-template-specific seam code.
+ */
+export function distributePathPattern(
+  domains: readonly PathPatternDomain[],
+  policy: PathPatternPolicy,
+): PathPatternPlacement[] {
+  const maximumSpacing = Math.max(0.001, policy.maximumSpacing)
+  const dedupeDistance = Math.max(0, policy.dedupeDistance ?? 0.025)
+  const placements: PathPatternPlacement[] = []
+
+  for (const [domainIndex, domain] of domains.entries()) {
+    if (domain.frames.length < 2 || domain.length <= EPSILON) continue
+    const intervalCount = domain.closed
+      ? Math.max(3, Math.ceil(domain.length / maximumSpacing))
+      : Math.max(1, Math.ceil(domain.length / maximumSpacing))
+    const stationCount = domain.closed ? intervalCount : intervalCount + 1
+    const stations = Array.from({ length: stationCount }, (_, index) => (index / intervalCount) * domain.length)
+
+    for (const distance of stations) {
+      if (!domain.closed && distance <= EPSILON && domain.includeStart === false) continue
+      if (!domain.closed && domain.length - distance <= EPSILON && domain.includeEnd === false) continue
+      const sample = samplePathPatternDomain(domain, distance)
+      const terminal = !domain.closed && (distance <= EPSILON || domain.length - distance <= EPSILON)
+      const duplicate = placements.find(placement => {
+        const dx = placement.point.x - sample.point.x
+        const dy = policy.dedupeSpace === 'horizontal' ? 0 : placement.point.y - sample.point.y
+        const dz = placement.point.z - sample.point.z
+        return dx * dx + dy * dy + dz * dz <= dedupeDistance * dedupeDistance
+      })
+      if (duplicate) {
+        duplicate.terminal ||= terminal
+        continue
+      }
+      placements.push({ domainIndex, distance, ...sample, terminal })
+    }
+  }
+
+  return placements
+}
+
+function samplePathPatternDomain(
+  domain: PathPatternDomain,
+  requestedDistance: number,
+): { point: THREE.Vector3; tangent: THREE.Vector3 } {
+  const distance = THREE.MathUtils.clamp(requestedDistance, 0, domain.length)
+  let segment = 0
+  while (segment < domain.frames.length - 2 && domain.frames[segment + 1]!.distance < distance) segment += 1
+  const start = domain.frames[segment]!
+  const end = domain.frames[segment + 1]!
+  const span = end.distance - start.distance
+  const progress = span <= EPSILON ? 0 : (distance - start.distance) / span
+  const tangent = start.tangent.clone().lerp(end.tangent, progress)
+  if (tangent.lengthSq() <= EPSILON) tangent.copy(end.point).sub(start.point)
+  if (tangent.lengthSq() <= EPSILON) tangent.set(0, 0, 1)
+  tangent.normalize()
+  return {
+    point: start.point.clone().lerp(end.point, progress),
+    tangent,
+  }
+}

package/src/pages/play/race/peg-obstacle-visual.ts

@@ -0,0 +1,171 @@
+import * as THREE from 'three'
+
+import { VisualSphereGeometry, VisualTorusGeometry } from '../../../three/visual-geometry'
+import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+
+export interface PegObstacleVisualFactoryOptions {
+  radius: number
+  height: number
+  colliderShape?: 'cone' | 'cylinder'
+  bodyMaterial: THREE.Material
+  trimMaterial: THREE.Material
+}
+
+export interface PegObstacleVisual {
+  group: THREE.Group
+}
+
+interface RevolvedProfilePoint {
+  radius: number
+  y: number
+}
+
+/** Builds the one shared high-quality peg/deflector visual used by every theme. */
+export function createPegObstacleVisualFactory(
+  options: PegObstacleVisualFactoryOptions,
+): (seed: string) => PegObstacleVisual {
+  const isPost = options.colliderShape === 'cylinder'
+  const profile = isPost
+    ? createRoundedPostProfile(options.radius, options.height)
+    : createTaperedDeflectorProfile(options.radius, options.height)
+  const bodyGeometry = createClosedRevolvedGeometry(
+    profile,
+    8,
+    isPost ? 'rounded-peg-body-geometry' : 'tapered-deflector-body-geometry',
+  )
+  const trimGeometry = createDeflectorTrimGeometry(options.radius, options.height, isPost)
+  const style = isPost ? 'rounded-peg' : 'tapered-deflector'
+
+  return () => {
+    const group = new THREE.Group()
+    group.userData.obstacleVisualStyle = style
+
+    const body = new THREE.Mesh(bodyGeometry, options.bodyMaterial)
+    body.name = 'deflector-body'
+    body.castShadow = true
+    body.receiveShadow = true
+    group.add(body)
+
+    const trim = new THREE.Mesh(trimGeometry, options.trimMaterial)
+    trim.name = 'deflector-ribs-and-bolts'
+    trim.userData.decorative = true
+    trim.castShadow = true
+    trim.receiveShadow = true
+    group.add(trim)
+    return { group }
+  }
+}
+
+function createTaperedDeflectorProfile(radius: number, height: number): RevolvedProfilePoint[] {
+  const halfHeight = height / 2
+  return [
+    { radius: radius * 0.72, y: -halfHeight },
+    { radius: radius * 0.94, y: -halfHeight + height * 0.045 },
+    { radius, y: -halfHeight + height * 0.12 },
+    { radius: radius * 0.96, y: -halfHeight + height * 0.2 },
+    { radius: radius * 0.72, y: -halfHeight + height * 0.28 },
+    { radius: radius * 0.59, y: -halfHeight + height * 0.58 },
+    { radius: radius * 0.43, y: -halfHeight + height * 0.82 },
+    { radius: radius * 0.25, y: halfHeight - height * 0.055 },
+  ]
+}
+
+function createRoundedPostProfile(radius: number, height: number): RevolvedProfilePoint[] {
+  const halfHeight = height / 2
+  return [
+    { radius: radius * 0.72, y: -halfHeight },
+    { radius: radius * 0.94, y: -halfHeight + height * 0.055 },
+    { radius, y: -halfHeight + height * 0.14 },
+    { radius: radius * 0.96, y: halfHeight - height * 0.22 },
+    { radius: radius * 0.78, y: halfHeight - height * 0.08 },
+    { radius: radius * 0.38, y: halfHeight - height * 0.018 },
+  ]
+}
+
+function createClosedRevolvedGeometry(
+  profile: readonly RevolvedProfilePoint[],
+  segments: number,
+  name: string,
+): THREE.BufferGeometry {
+  const positions: number[] = []
+  const uvs: number[] = []
+  const indices: number[] = []
+  for (const point of profile) {
+    for (let segment = 0; segment < segments; segment += 1) {
+      const angle = (segment / segments) * Math.PI * 2
+      const x = Math.cos(angle) * point.radius
+      const z = Math.sin(angle) * point.radius
+      positions.push(x, point.y, z)
+      // Theme materials use metric triplanar projection; this planar UV is a
+      // harmless fallback for non-patterned materials without adding a seam.
+      uvs.push(x, point.y)
+    }
+  }
+
+  for (let ring = 0; ring < profile.length - 1; ring += 1) {
+    for (let segment = 0; segment < segments; segment += 1) {
+      const next = (segment + 1) % segments
+      const lower = ring * segments + segment
+      const lowerNext = ring * segments + next
+      const upper = (ring + 1) * segments + segment
+      const upperNext = (ring + 1) * segments + next
+      indices.push(lower, upper, lowerNext, lowerNext, upper, upperNext)
+    }
+  }
+
+  const bottomCenter = positions.length / 3
+  positions.push(0, profile[0]!.y, 0)
+  uvs.push(0, profile[0]!.y)
+  const topCenter = positions.length / 3
+  positions.push(0, profile.at(-1)!.y + Math.abs(profile.at(-1)!.radius) * 0.24, 0)
+  uvs.push(0, profile.at(-1)!.y)
+  const topRingOffset = (profile.length - 1) * segments
+  for (let segment = 0; segment < segments; segment += 1) {
+    const next = (segment + 1) % segments
+    indices.push(bottomCenter, segment, next)
+    indices.push(topCenter, topRingOffset + next, topRingOffset + segment)
+  }
+
+  const geometry = new THREE.BufferGeometry()
+  geometry.name = name
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  geometry.userData.closedSurface = true
+  geometry.userData.visualOnly = true
+  return geometry
+}
+
+function createDeflectorTrimGeometry(radius: number, height: number, isPost: boolean): THREE.BufferGeometry {
+  const pieces: THREE.BufferGeometry[] = []
+  const ringLevels = isPost ? [-0.3, 0.22] : [-0.31, -0.18]
+  for (const level of ringLevels) {
+    const progress = level + 0.5
+    const ringRadius = isPost ? radius * 0.985 : radius * THREE.MathUtils.lerp(0.98, 0.46, progress)
+    const ring = new VisualTorusGeometry(ringRadius, radius * 0.045, 6, 24)
+    ring.rotateX(Math.PI / 2)
+    ring.translate(0, level * height, 0)
+    pieces.push(ring)
+  }
+
+  const boltRadius = Math.max(0.025, radius * 0.075)
+  const boltY = -height * 0.38
+  for (let bolt = 0; bolt < 8; bolt += 1) {
+    const angle = (bolt / 8) * Math.PI * 2
+    const boltGeometry = new VisualSphereGeometry(boltRadius, 7, 5)
+    boltGeometry.translate(Math.cos(angle) * radius * 0.965, boltY, Math.sin(angle) * radius * 0.965)
+    pieces.push(boltGeometry)
+  }
+
+  const geometry = mergeGeometries(pieces, false)
+  pieces.forEach(piece => piece.dispose())
+  if (!geometry) throw new Error('Unable to create deflector trim geometry.')
+  geometry.name = 'deflector-rings-and-bolts-geometry'
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  geometry.userData.visualOnly = true
+  return geometry
+}

package/src/pages/play/race/physics-debug.ts

@@ -0,0 +1 @@
+export * from '@marble.fun/physics-engine'

package/src/pages/play/race/physics-dry-run.ts

@@ -0,0 +1,90 @@
+import {
+  CURRENT_RACE_ENGINE_VERSION,
+  createPreparedRaceSimulation,
+  createRaceTuning,
+  preparePhysicsTrack,
+  type PhysicsDebugReport,
+  type PhysicsMechanismDiagnostics,
+  type PhysicsSimulationCheckpoint,
+} from '@marble.fun/physics-engine'
+
+import type { RaceConfiguration, RaceWinner } from './race-types'
+import type { TrackDefinition } from './track-definition'
+import type { ThemeMaterialRegistry } from '../../../three/theme-material-registry'
+import type { CanonicalTrackAssembly } from '../../track-lab/engine/canonical-track-assembly'
+
+export interface PhysicsDryRunResult {
+  simulationKey: string
+  simulationTick: number
+  elapsedMs: number
+  replayFingerprint: string
+  winner: RaceWinner
+  debug: PhysicsDebugReport
+  mechanisms: PhysicsMechanismDiagnostics[]
+  finishOrder: Array<{
+    rank: number
+    slotId: string
+    label: string
+    finishTimeMs: number
+  }>
+  checkpoints: PhysicsDryRunCheckpoint[]
+}
+
+export type PhysicsDryRunCheckpoint = PhysicsSimulationCheckpoint
+
+export interface PhysicsDryRunOptions {
+  canonicalAssembly?: CanonicalTrackAssembly
+  checkpointIntervalTicks?: number
+  materialRegistry?: ThemeMaterialRegistry
+  track?: TrackDefinition
+}
+
+export async function runPhysicsDryRun(
+  configuration: RaceConfiguration,
+  options: PhysicsDryRunOptions = {},
+): Promise<PhysicsDryRunResult> {
+  const track = options.track
+  if (!track) throw new Error('A compiled catalog track is required for deterministic simulation')
+  const tuning = createRaceTuning(configuration, track)
+  const simulation = await createPreparedRaceSimulation(
+    {
+      engineVersion: CURRENT_RACE_ENGINE_VERSION,
+      seed: configuration.seed,
+      trackId: track.id,
+      trackJson: track.sourceDocument ? JSON.stringify(track.sourceDocument) : '{}',
+      entrants: configuration.assignments,
+    },
+    preparePhysicsTrack(track),
+    undefined,
+    {
+      enabled: true,
+      checkpointIntervalTicks: options.checkpointIntervalTicks,
+    },
+  )
+  try {
+    while (!simulation.complete) {
+      simulation.advance()
+      simulation.drainEvents()
+    }
+    const result = simulation.result()!
+    const assignments = new Map(configuration.assignments.map(assignment => [assignment.slotId, assignment]))
+    return {
+      simulationKey: tuning.simulationKey,
+      simulationTick: result.simulationTicks,
+      elapsedMs: result.durationMs,
+      replayFingerprint: result.replayFingerprint,
+      winner: result.winner,
+      debug: simulation.debugReport()!,
+      mechanisms: simulation.mechanismDiagnostics(),
+      finishOrder: result.finishOrder.map(finisher => ({
+        rank: finisher.rank,
+        slotId: finisher.slotId,
+        label: assignments.get(finisher.slotId)?.label ?? finisher.slotId,
+        finishTimeMs: finisher.finishTimeMs,
+      })),
+      checkpoints: [...simulation.diagnosticCheckpoints()],
+    }
+  } finally {
+    simulation.dispose()
+  }
+}