@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-surface-basis.ts

@@ -0,0 +1 @@
+export { trackSurfaceBasis, type TrackSurfaceBasis } from '@marble.fun/physics-engine'

package/src/pages/play/race/track-surface-topology.ts

@@ -0,0 +1,326 @@
+import * as THREE from 'three'
+
+export type TrackWallBoundaryRole = 'outer' | 'junction' | 'divider'
+export type TrackBoundaryOwnership = 'exposed' | 'connected' | 'closed-loop'
+
+export const TRACK_SURFACE_BOUNDARY_INTERIOR = 0
+export const TRACK_SURFACE_BOUNDARY_EXPOSED = 1
+export const TRACK_SURFACE_BOUNDARY_CONNECTED = 2
+
+export interface CanonicalWallFrame {
+  base: THREE.Vector3
+  tangent: THREE.Vector3
+  up: THREE.Vector3
+  outward: THREE.Vector3
+  distance: number
+}
+
+export interface CanonicalWallRun {
+  frames: readonly CanonicalWallFrame[]
+  role: TrackWallBoundaryRole
+  capStart: boolean
+  capEnd: boolean
+  startOwnership: TrackBoundaryOwnership
+  endOwnership: TrackBoundaryOwnership
+  closed: boolean
+  length: number
+}
+
+export interface RawWallFrame {
+  base: THREE.Vector3
+  tangent: THREE.Vector3
+  up: THREE.Vector3
+  outward: THREE.Vector3
+}
+
+export type CanonicalWallTerminal = 'start' | 'end'
+
+/**
+ * Finds convergent terminals that are open only because two runs inside the
+ * same visual assembly meet there. Ordinary end-to-start track connectors
+ * remain neighbor-owned and open; two starts or two ends at one point need a
+ * single local visual closure so modular facades cannot expose a slit.
+ */
+export function canonicalConvergentConnectedTerminalClosures(
+  runs: readonly CanonicalWallRun[],
+): ReadonlySet<string> {
+  const groups = new Map<string, Array<{ runIndex: number; terminal: CanonicalWallTerminal }>>()
+  runs.forEach((run, runIndex) => {
+    if (run.closed || run.frames.length < 2) return
+    for (const [terminal, ownership] of [
+      ['start', run.startOwnership],
+      ['end', run.endOwnership],
+    ] as const) {
+      if (ownership !== 'connected') continue
+      const frame = terminal === 'start' ? run.frames[0]! : run.frames.at(-1)!
+      const key = frame.base.toArray().map(value => value.toFixed(5)).join(':')
+      const entries = groups.get(key) ?? []
+      entries.push({ runIndex, terminal })
+      groups.set(key, entries)
+    }
+  })
+  const owners = new Set<string>()
+  for (const entries of groups.values()) {
+    if (entries.length < 2 || !entries.every(entry => entry.terminal === entries[0]!.terminal)) continue
+    const owner = entries[0]!
+    owners.add(`${owner.runIndex}:${owner.terminal}`)
+  }
+  return owners
+}
+
+const EPSILON = 0.000_001
+
+function finiteVector(vector: THREE.Vector3): boolean {
+  return Number.isFinite(vector.x) && Number.isFinite(vector.y) && Number.isFinite(vector.z)
+}
+
+function segmentsIntersect(
+  a: THREE.Vector3,
+  b: THREE.Vector3,
+  c: THREE.Vector3,
+  d: THREE.Vector3,
+): boolean {
+  const first = b.clone().sub(a)
+  const second = d.clone().sub(c)
+  const between = a.clone().sub(c)
+  const firstLength = first.dot(first)
+  const crossLength = first.dot(second)
+  const secondLength = second.dot(second)
+  const firstOffset = first.dot(between)
+  const secondOffset = second.dot(between)
+  const determinant = firstLength * secondLength - crossLength * crossLength
+  let firstNumerator: number
+  let firstDenominator = determinant
+  let secondNumerator: number
+  let secondDenominator: number
+
+  if (determinant <= EPSILON) {
+    firstNumerator = 0
+    firstDenominator = 1
+    secondNumerator = secondOffset
+    secondDenominator = secondLength
+  } else {
+    secondDenominator = determinant
+    firstNumerator = crossLength * secondOffset - secondLength * firstOffset
+    secondNumerator = firstLength * secondOffset - crossLength * firstOffset
+    if (firstNumerator < 0) {
+      firstNumerator = 0
+      secondNumerator = secondOffset
+      secondDenominator = secondLength
+    } else if (firstNumerator > firstDenominator) {
+      firstNumerator = firstDenominator
+      secondNumerator = secondOffset + crossLength
+      secondDenominator = secondLength
+    }
+  }
+
+  if (secondNumerator < 0) {
+    secondNumerator = 0
+    if (-firstOffset < 0) firstNumerator = 0
+    else if (-firstOffset > firstLength) firstNumerator = firstDenominator
+    else {
+      firstNumerator = -firstOffset
+      firstDenominator = firstLength
+    }
+  } else if (secondNumerator > secondDenominator) {
+    secondNumerator = secondDenominator
+    const terminalOffset = -firstOffset + crossLength
+    if (terminalOffset < 0) firstNumerator = 0
+    else if (terminalOffset > firstLength) firstNumerator = firstDenominator
+    else {
+      firstNumerator = terminalOffset
+      firstDenominator = firstLength
+    }
+  }
+
+  const firstProgress = Math.abs(firstNumerator) <= EPSILON ? 0 : firstNumerator / firstDenominator
+  const secondProgress = Math.abs(secondNumerator) <= EPSILON ? 0 : secondNumerator / secondDenominator
+  return between.addScaledVector(first, firstProgress).addScaledVector(second, -secondProgress).lengthSq() <= EPSILON * EPSILON
+}
+
+function assertSimplePath(points: readonly THREE.Vector3[], closed: boolean): void {
+  const segmentCount = points.length - 1
+  for (let left = 0; left < segmentCount; left += 1) {
+    for (let right = left + 1; right < segmentCount; right += 1) {
+      if (right === left + 1) continue
+      if (closed && left === 0 && right === segmentCount - 1) continue
+      if (segmentsIntersect(points[left]!, points[left + 1]!, points[right]!, points[right + 1]!)) {
+        throw new Error(
+          `Wall boundary self-intersects between segments ${left} and ${right}: ${JSON.stringify([
+            points[left]!.toArray(),
+            points[left + 1]!.toArray(),
+            points[right]!.toArray(),
+            points[right + 1]!.toArray(),
+          ])}`,
+        )
+      }
+    }
+  }
+}
+
+/**
+ * Converts one source boundary into the only frame contract themed walls may
+ * consume. Path positions own the tangent; authored axes are orientation hints
+ * only. Invalid topology fails here instead of exploding inside a theme.
+ */
+export function createCanonicalWallRun(
+  source: readonly RawWallFrame[],
+  options: {
+    role: TrackWallBoundaryRole
+    capStart?: boolean
+    capEnd?: boolean
+    /** Width-changing lanes must derive orientation from their moving boundary. */
+    tangentSource?: 'authored' | 'boundary'
+  },
+): CanonicalWallRun | undefined {
+  const points: RawWallFrame[] = []
+  for (const frame of source) {
+    if (![frame.base, frame.tangent, frame.up, frame.outward].every(finiteVector)) {
+      throw new Error('Wall boundary contains a non-finite frame')
+    }
+    const previous = points.at(-1)
+    if (previous && previous.base.distanceToSquared(frame.base) <= EPSILON * EPSILON) continue
+    points.push({
+      base: frame.base.clone(),
+      tangent: frame.tangent.clone(),
+      up: frame.up.clone(),
+      outward: frame.outward.clone(),
+    })
+  }
+  if (points.length < 2) return undefined
+
+  const closed = points[0]!.base.distanceToSquared(points.at(-1)!.base) <= 0.001 * 0.001
+  if (closed && points.length < 4) return undefined
+  assertSimplePath(points.map(frame => frame.base), closed)
+  const uniqueCount = closed ? points.length - 1 : points.length
+  const frames: CanonicalWallFrame[] = []
+  let distance = 0
+
+  for (let index = 0; index < uniqueCount; index += 1) {
+    const sourceFrame = points[index]!
+    const previous = points[closed ? (index - 1 + uniqueCount) % uniqueCount : Math.max(0, index - 1)]!
+    const next = points[closed ? (index + 1) % uniqueCount : Math.min(uniqueCount - 1, index + 1)]!
+    // Walls follow the boundary's elevation, but their construction frame is
+    // always vertical. Including grade in the frame tangent forces `up` to
+    // lean backwards on slopes and makes every themed wall/roof inherit that
+    // piece-specific skew.
+    const worldUp = new THREE.Vector3(0, 1, 0)
+    const pathTangent = next.base.clone().sub(previous.base)
+    pathTangent.y = 0
+    if (pathTangent.lengthSq() <= EPSILON) {
+      pathTangent.copy(sourceFrame.tangent)
+      pathTangent.y = 0
+    }
+    if (pathTangent.lengthSq() <= EPSILON) return undefined
+    pathTangent.normalize()
+    if (pathTangent.dot(sourceFrame.tangent) < 0) pathTangent.negate()
+    const authoredTangent = sourceFrame.tangent.clone()
+    authoredTangent.y = 0
+    if (authoredTangent.lengthSq() > EPSILON) authoredTangent.normalize()
+    // Authored derivatives preserve smooth curve/grade continuity. The path
+    // chord takes ownership only when they materially disagree (normally a
+    // width transition or malformed producer), using one global threshold.
+    const openTerminal = !closed && (index === 0 || index === uniqueCount - 1)
+    const tangent =
+      openTerminal && authoredTangent.lengthSq() > EPSILON
+        ? authoredTangent
+        : options.tangentSource === 'boundary'
+        ? pathTangent
+        : uniqueCount > 2 &&
+            authoredTangent.lengthSq() > EPSILON &&
+            pathTangent.dot(authoredTangent) >= Math.cos(THREE.MathUtils.degToRad(20))
+          ? authoredTangent
+          : pathTangent
+
+    const up = worldUp.clone()
+    const outward = new THREE.Vector3().crossVectors(tangent, up)
+    if (outward.lengthSq() <= EPSILON) return undefined
+    outward.normalize()
+    // A mirrored lane reverses the path-local tangent, not world up. Flipping
+    // up to satisfy the outward hint turns roofs upside-down; flipping tangent
+    // preserves the physical boundary order while keeping the frame proper.
+    if (outward.dot(sourceFrame.outward) < 0) {
+      tangent.negate()
+      outward.crossVectors(tangent, up).normalize()
+    }
+    if (frames.length > 0) distance += sourceFrame.base.distanceTo(frames.at(-1)!.base)
+    frames.push({ base: sourceFrame.base.clone(), tangent, up, outward, distance })
+  }
+
+  if (closed) {
+    distance += frames.at(-1)!.base.distanceTo(frames[0]!.base)
+    frames.push({
+      base: frames[0]!.base.clone(),
+      tangent: frames[0]!.tangent.clone(),
+      up: frames[0]!.up.clone(),
+      outward: frames[0]!.outward.clone(),
+      distance,
+    })
+  }
+  const capStart = !closed && options.capStart !== false
+  const capEnd = !closed && options.capEnd !== false
+  return {
+    frames,
+    role: options.role,
+    capStart,
+    capEnd,
+    startOwnership: closed ? 'closed-loop' : capStart ? 'exposed' : 'connected',
+    endOwnership: closed ? 'closed-loop' : capEnd ? 'exposed' : 'connected',
+    closed,
+    length: distance,
+  }
+}
+
+export function canonicalWallFrameAt(run: CanonicalWallRun, targetDistance: number): CanonicalWallFrame {
+  const target = THREE.MathUtils.clamp(targetDistance, 0, run.length)
+  let low = 1
+  let high = run.frames.length - 1
+  while (low < high) {
+    const middle = (low + high) >>> 1
+    if (run.frames[middle]!.distance < target) low = middle + 1
+    else high = middle
+  }
+  const segment = Math.max(0, low - 1)
+  const start = run.frames[segment]!
+  const end = run.frames[segment + 1]!
+  const span = end.distance - start.distance
+  const progress = span <= EPSILON ? 0 : (target - start.distance) / span
+  const tangent = start.tangent.clone().lerp(end.tangent, progress).normalize()
+  const up = start.up.clone().lerp(end.up, progress)
+  up.addScaledVector(tangent, -up.dot(tangent)).normalize()
+  const outward = new THREE.Vector3().crossVectors(tangent, up).normalize()
+  if (outward.dot(start.outward.clone().lerp(end.outward, progress)) < 0) outward.negate()
+  up.crossVectors(outward, tangent).normalize()
+  return {
+    base: start.base.clone().lerp(end.base, progress),
+    tangent,
+    up,
+    outward,
+    distance: target,
+  }
+}
+
+export function resampleCanonicalWallRun(run: CanonicalWallRun, spacing: number): CanonicalWallRun {
+  const safeSpacing = Math.max(0.01, spacing)
+  const count = Math.max(2, Math.ceil(run.length / safeSpacing) + 1)
+  const cornerCosine = Math.cos(THREE.MathUtils.degToRad(12))
+  // Source curves may contain dozens of tessellation frames. Retaining every
+  // one defeats metric resampling and compresses decorative seams on the
+  // shorter side of a bend. Preserve only genuine authored corners.
+  const cornerDistances = run.frames.flatMap((frame, index) => {
+    if (index === 0 || index >= run.frames.length - 1) return []
+    const incoming = frame.base.clone().sub(run.frames[index - 1]!.base)
+    const outgoing = run.frames[index + 1]!.base.clone().sub(frame.base)
+    if (incoming.lengthSq() <= EPSILON || outgoing.lengthSq() <= EPSILON) return []
+    return incoming.normalize().dot(outgoing.normalize()) < cornerCosine ? [frame.distance] : []
+  })
+  const targets = [
+    0,
+    ...cornerDistances,
+    run.length,
+    ...Array.from({ length: count }, (_, index) => (index / (count - 1)) * run.length),
+  ]
+    .sort((left, right) => left - right)
+    .filter((distance, index, values) => index === 0 || distance - values[index - 1]! > EPSILON)
+  return { ...run, frames: targets.map(distance => canonicalWallFrameAt(run, distance)) }
+}