@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-appearance-wall-terminal.ts

@@ -0,0 +1,167 @@
+import * as THREE from 'three'
+
+import { TRACK_RAIL_WALL_THICKNESS } from './track-definition'
+import {
+  canonicalConvergentConnectedTerminalClosures,
+  type CanonicalWallRun,
+} from './track-surface-topology'
+
+export interface CanonicalWallTerminalSkinOptions {
+  material: THREE.Material
+  wallThickness?: number
+  facadeOverlap?: number
+  projection?: number
+  inset?: number
+  /** Vertical offset above the canonical wall base for layered terminal finishes. */
+  verticalOffset?: number
+}
+
+/**
+ * Covers exposed canonical wall terminals with the material selected by the
+ * appearance applier. Connected and closed-loop boundaries produce no skin.
+ * The short wrapped return hides backing and facade end faces without changing
+ * the canonical wall or its Rapier collider.
+ */
+export function addCanonicalWallTerminalSkins(
+  root: THREE.Group,
+  id: string,
+  runs: readonly CanonicalWallRun[],
+  wallHeight: number,
+  options: CanonicalWallTerminalSkinOptions,
+): THREE.Mesh | undefined {
+  if (wallHeight <= 0.001) return undefined
+  const wallThickness = options.wallThickness ?? TRACK_RAIL_WALL_THICKNESS
+  const facadeOverlap = options.facadeOverlap ?? 0.014
+  const projection = options.projection ?? 0.062
+  const inset = options.inset ?? 0.006
+  const verticalOffset = options.verticalOffset ?? 0
+  const positions: number[] = []
+  const uvs: number[] = []
+  const metricUvs: number[] = []
+  const indices: number[] = []
+  let terminalCount = 0
+  let sharedConnectedClosureCount = 0
+  const sharedConnectedClosures = canonicalConvergentConnectedTerminalClosures(runs)
+
+  const appendVertex = (point: THREE.Vector3, u: number, v: number, extent: number): number => {
+    const index = positions.length / 3
+    positions.push(point.x, point.y, point.z)
+    uvs.push(u, v)
+    metricUvs.push(u, v, 1, extent)
+    return index
+  }
+  const appendQuad = (
+    a: THREE.Vector3,
+    b: THREE.Vector3,
+    c: THREE.Vector3,
+    d: THREE.Vector3,
+    expectedNormal: THREE.Vector3,
+    width: number,
+    height: number,
+  ): void => {
+    const extent = Math.max(0.001, width, height)
+    const offset = positions.length / 3
+    appendVertex(a, 0, 0, extent)
+    appendVertex(b, width, 0, extent)
+    appendVertex(c, 0, height, extent)
+    appendVertex(d, width, height, extent)
+    const normal = b.clone().sub(a).cross(c.clone().sub(a))
+    if (normal.dot(expectedNormal) >= 0) {
+      indices.push(offset, offset + 1, offset + 2, offset + 2, offset + 1, offset + 3)
+    } else {
+      indices.push(offset, offset + 2, offset + 1, offset + 2, offset + 3, offset + 1)
+    }
+  }
+
+  for (const [runIndex, run] of runs.entries()) {
+    if (run.frames.length < 2 || run.closed) continue
+    for (const [terminal, ownership] of [
+      ['start', run.startOwnership],
+      ['end', run.endOwnership],
+    ] as const) {
+      const ownsSharedConnectedClosure = sharedConnectedClosures.has(`${runIndex}:${terminal}`)
+      if (ownership !== 'exposed' && !ownsSharedConnectedClosure) continue
+      const frame = terminal === 'start' ? run.frames[0]! : run.frames.at(-1)!
+      // Terminal projection follows the actual run endpoint chord. A
+      // canonical frame may reverse its tangent to preserve a physical
+      // outward side on mirrored or side-owned paths; using that orientation
+      // here can project the finish back into the traversable surface.
+      const adjacent = terminal === 'start' ? run.frames[1]! : run.frames.at(-2)!
+      const terminalNormal = frame.base.clone().sub(adjacent.base).setY(0)
+      if (terminalNormal.lengthSq() <= 0.000_001) {
+        terminalNormal.copy(frame.tangent).multiplyScalar(terminal === 'start' ? -1 : 1).setY(0)
+      }
+      terminalNormal.normalize()
+      const up = frame.up.clone().normalize()
+      const across = frame.outward.clone().normalize()
+      const halfWidth = wallThickness / 2 + facadeOverlap
+      const bottomCenter = frame.base.clone().addScaledVector(up, verticalOffset - 0.03)
+      // A convergent internal seam needs only a thin two-sided plug at the
+      // shared plane. The longer wrapped return remains exclusive to a truly
+      // exposed terminal so nothing protrudes through the neighboring run.
+      const terminalProjection = ownsSharedConnectedClosure ? inset : projection
+      const frontCenter = bottomCenter.clone().addScaledVector(terminalNormal, terminalProjection)
+      const backCenter = bottomCenter.clone().addScaledVector(terminalNormal, -inset)
+      const frontNegative = frontCenter.clone().addScaledVector(across, -halfWidth)
+      const frontPositive = frontCenter.clone().addScaledVector(across, halfWidth)
+      const backNegative = backCenter.clone().addScaledVector(across, -halfWidth)
+      const backPositive = backCenter.clone().addScaledVector(across, halfWidth)
+      const frontNegativeTop = frontNegative.clone().addScaledVector(up, wallHeight)
+      const frontPositiveTop = frontPositive.clone().addScaledVector(up, wallHeight)
+      const backNegativeTop = backNegative.clone().addScaledVector(up, wallHeight)
+      const backPositiveTop = backPositive.clone().addScaledVector(up, wallHeight)
+      const width = halfWidth * 2
+      const depth = terminalProjection + inset
+
+      appendQuad(frontNegative, frontPositive, frontNegativeTop, frontPositiveTop, terminalNormal, width, wallHeight)
+      appendQuad(
+        backPositive,
+        backNegative,
+        backPositiveTop,
+        backNegativeTop,
+        terminalNormal.clone().negate(),
+        width,
+        wallHeight,
+      )
+      appendQuad(
+        backNegative,
+        frontNegative,
+        backNegativeTop,
+        frontNegativeTop,
+        across.clone().negate(),
+        depth,
+        wallHeight,
+      )
+      appendQuad(frontPositive, backPositive, frontPositiveTop, backPositiveTop, across, depth, wallHeight)
+      appendQuad(frontNegativeTop, frontPositiveTop, backNegativeTop, backPositiveTop, up, width, depth)
+      appendQuad(backNegative, backPositive, frontNegative, frontPositive, up.clone().negate(), width, depth)
+      terminalCount += 1
+      if (ownsSharedConnectedClosure) sharedConnectedClosureCount += 1
+    }
+  }
+
+  if (terminalCount === 0) return undefined
+  const geometry = new THREE.BufferGeometry()
+  geometry.name = 'canonical-wall-terminal-skin-geometry'
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setAttribute('themeNetUv', new THREE.Float32BufferAttribute(metricUvs, 4))
+  geometry.setIndex(indices)
+  geometry.computeVertexNormals()
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  geometry.userData.terminalCount = terminalCount
+  geometry.userData.sharedConnectedClosureCount = sharedConnectedClosureCount
+  geometry.userData.boundaryOwnershipSource = 'canonical-wall-run'
+
+  const mesh = new THREE.Mesh(geometry, options.material)
+  mesh.name = `${id}-wall-terminal-skins`
+  mesh.castShadow = true
+  mesh.receiveShadow = true
+  mesh.userData.decorative = true
+  mesh.userData.visualOnly = true
+  mesh.userData.boundaryOwnershipSource = 'canonical-wall-run'
+  mesh.userData.sharedConnectedClosureCount = sharedConnectedClosureCount
+  root.add(mesh)
+  return mesh
+}

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

@@ -0,0 +1,271 @@
+import * as THREE from 'three'
+
+import type { TrackDefinition, TrackGuidePath } from './track-definition'
+
+export interface TrackSample {
+  guideId: string
+  pieceId: string
+  startDistance: number
+  endDistance: number
+  physicalLength: number
+  start: THREE.Vector3
+  end: THREE.Vector3
+  center: THREE.Vector3
+  tangent: THREE.Vector3
+  right: THREE.Vector3
+  up: THREE.Vector3
+  quaternion: THREE.Quaternion
+}
+
+export interface TrackPose {
+  sampleIndex: number
+  distance: number
+  position: THREE.Vector3
+  tangent: THREE.Vector3
+  right: THREE.Vector3
+  up: THREE.Vector3
+  quaternion: THREE.Quaternion
+}
+
+export interface TrackProjection {
+  sampleIndex: number
+  distance: number
+  lateralDistance: number
+  verticalDistance: number
+}
+
+export interface TrackDistanceSample {
+  endDistance: number
+}
+
+/** Finds the first guide sample ending at or after the requested distance. */
+export function findTrackSampleIndexAtDistance(
+  samples: readonly TrackDistanceSample[],
+  distance: number,
+  hintIndex = 0,
+): number {
+  if (samples.length === 0) return -1
+  const hint = Math.min(samples.length - 1, Math.max(0, hintIndex))
+  if (
+    distance <= samples[hint]!.endDistance &&
+    (hint === 0 || distance > samples[hint - 1]!.endDistance)
+  ) {
+    return hint
+  }
+
+  let low = 0
+  let high = samples.length - 1
+  while (low < high) {
+    const middle = (low + high) >>> 1
+    if (distance <= samples[middle]!.endDistance) high = middle
+    else low = middle + 1
+  }
+  return low
+}
+
+function vectorFromTuple(tuple: readonly [number, number, number]): THREE.Vector3 {
+  return new THREE.Vector3(tuple[0], tuple[1], tuple[2])
+}
+
+function createSampleQuaternion(tangent: THREE.Vector3, right: THREE.Vector3, up: THREE.Vector3): THREE.Quaternion {
+  const basis = new THREE.Matrix4().makeBasis(right, up, tangent)
+  return new THREE.Quaternion().setFromRotationMatrix(basis)
+}
+
+function buildSamples(path: TrackGuidePath): TrackSample[] {
+  return path.points.slice(0, -1).map((point, index) => {
+    const next = path.points[index + 1]!
+    const start = vectorFromTuple(point.position)
+    const end = vectorFromTuple(next.position)
+    const tangent = end.clone().sub(start).normalize()
+    const right = new THREE.Vector3(tangent.z, 0, -tangent.x).normalize()
+    const up = new THREE.Vector3().crossVectors(tangent, right).normalize()
+
+    return {
+      guideId: path.id,
+      pieceId: next.pieceId || point.pieceId,
+      startDistance: point.progress,
+      endDistance: next.progress,
+      physicalLength: start.distanceTo(end),
+      start,
+      end,
+      center: start.clone().add(end).multiplyScalar(0.5),
+      tangent,
+      right,
+      up,
+      quaternion: createSampleQuaternion(tangent, right, up),
+    }
+  })
+}
+
+function samplesAreContinuous(left: TrackSample | undefined, right: TrackSample | undefined): boolean {
+  if (!left || !right) return false
+  return (
+    left.guideId === right.guideId &&
+    Math.abs(left.endDistance - right.startDistance) <= 0.01 &&
+    left.end.distanceToSquared(right.start) <= 0.04
+  )
+}
+
+function writeBlendedUnitVector(
+  left: THREE.Vector3,
+  right: THREE.Vector3,
+  interpolation: number,
+  output: THREE.Vector3,
+): void {
+  output.set(
+    THREE.MathUtils.lerp(left.x, right.x, interpolation),
+    THREE.MathUtils.lerp(left.y, right.y, interpolation),
+    THREE.MathUtils.lerp(left.z, right.z, interpolation),
+  )
+  if (output.lengthSq() < 0.000_001) output.copy(left)
+  output.normalize()
+}
+
+export class TrackCourse {
+  readonly samples: TrackSample[]
+  readonly projectionSamples: TrackSample[]
+  readonly totalLength: number
+
+  constructor(readonly definition: TrackDefinition) {
+    this.samples = buildSamples(definition.cameraPath)
+    this.projectionSamples = definition.projectionPaths.flatMap(buildSamples)
+    this.totalLength = definition.cameraPath.points.at(-1)?.progress ?? 0
+
+    if (this.samples.length === 0 || this.projectionSamples.length === 0 || this.totalLength <= 0) {
+      throw new Error(`Track ${definition.id}@${definition.version} has an invalid progress guide`)
+    }
+  }
+
+  createPose(): TrackPose {
+    return {
+      sampleIndex: 0,
+      distance: 0,
+      position: new THREE.Vector3(),
+      tangent: new THREE.Vector3(),
+      right: new THREE.Vector3(),
+      up: new THREE.Vector3(),
+      quaternion: new THREE.Quaternion(),
+    }
+  }
+
+  writePoseAtDistance(distance: number, pose: TrackPose): TrackPose {
+    const clampedDistance = THREE.MathUtils.clamp(distance, 0, this.totalLength)
+    const sampleIndex = findTrackSampleIndexAtDistance(this.samples, clampedDistance, pose.sampleIndex)
+    const sample = this.samples[sampleIndex]!
+    const progressLength = Math.max(0.0001, sample.endDistance - sample.startDistance)
+    const interpolation = THREE.MathUtils.clamp((clampedDistance - sample.startDistance) / progressLength, 0, 1)
+
+    pose.sampleIndex = sampleIndex
+    pose.distance = clampedDistance
+    pose.position.copy(sample.start).lerp(sample.end, interpolation)
+    pose.tangent.copy(sample.tangent)
+    pose.right.copy(sample.right)
+    pose.up.copy(sample.up)
+    pose.quaternion.copy(sample.quaternion)
+
+    return pose
+  }
+
+  /**
+   * Writes a continuous frame along the marble's selected projection branch.
+   * Projection samples are straight segments, so copying a sample tangent
+   * makes the camera rotate in visible steps at every boundary. Blending the
+   * shared boundary frames makes consecutive curves one continuous turn while
+   * retaining the exact branch selected by physics projection.
+   */
+  writeProjectionFrameAtDistance(
+    projectionSampleIndex: number,
+    distance: number,
+    tangent: THREE.Vector3,
+    right: THREE.Vector3,
+    up: THREE.Vector3,
+  ): void {
+    const sampleIndex = THREE.MathUtils.clamp(projectionSampleIndex, 0, this.projectionSamples.length - 1)
+    const sample = this.projectionSamples[sampleIndex]!
+    const previous = this.projectionSamples[sampleIndex - 1]
+    const next = this.projectionSamples[sampleIndex + 1]
+    const continuousPrevious = samplesAreContinuous(previous, sample) ? previous : undefined
+    const continuousNext = samplesAreContinuous(sample, next) ? next : undefined
+    const progressLength = Math.max(0.0001, sample.endDistance - sample.startDistance)
+    const interpolation = THREE.MathUtils.clamp((distance - sample.startDistance) / progressLength, 0, 1)
+
+    const startTangent = continuousPrevious?.tangent ?? sample.tangent
+    const endTangent = continuousNext?.tangent ?? sample.tangent
+    tangent.set(
+      sample.tangent.x + startTangent.x,
+      sample.tangent.y + startTangent.y,
+      sample.tangent.z + startTangent.z,
+    )
+    right.set(
+      sample.tangent.x + endTangent.x,
+      sample.tangent.y + endTangent.y,
+      sample.tangent.z + endTangent.z,
+    )
+    writeBlendedUnitVector(tangent, right, interpolation, tangent)
+
+    const startUp = continuousPrevious?.up ?? sample.up
+    const endUp = continuousNext?.up ?? sample.up
+    up.set(sample.up.x + startUp.x, sample.up.y + startUp.y, sample.up.z + startUp.z).normalize()
+    right.set(sample.up.x + endUp.x, sample.up.y + endUp.y, sample.up.z + endUp.z).normalize()
+    writeBlendedUnitVector(up, right, interpolation, up)
+
+    right.crossVectors(up, tangent)
+    if (right.lengthSq() < 0.000_001) right.copy(sample.right)
+    else right.normalize()
+    up.crossVectors(tangent, right).normalize()
+  }
+
+  projectPoint(
+    point: { x: number; y: number; z: number },
+    _hintIndex: number,
+    projection: TrackProjection,
+    allowForwardJump = false,
+  ): TrackProjection {
+    let bestSquaredDistance = Number.POSITIVE_INFINITY
+    const previousProgress = projection.distance
+
+    for (let index = 0; index < this.projectionSamples.length; index += 1) {
+      const sample = this.projectionSamples[index]!
+      // Nearby spatially-overlapping devices may represent very different stages.
+      if (
+        sample.endDistance < previousProgress - 8 ||
+        (!allowForwardJump && sample.startDistance > previousProgress + 22)
+      ) {
+        continue
+      }
+      const offsetX = point.x - sample.start.x
+      const offsetY = point.y - sample.start.y
+      const offsetZ = point.z - sample.start.z
+      const physicalAlong = THREE.MathUtils.clamp(
+        offsetX * sample.tangent.x + offsetY * sample.tangent.y + offsetZ * sample.tangent.z,
+        0,
+        sample.physicalLength,
+      )
+      const closestX = sample.start.x + sample.tangent.x * physicalAlong
+      const closestY = sample.start.y + sample.tangent.y * physicalAlong
+      const closestZ = sample.start.z + sample.tangent.z * physicalAlong
+      const deltaX = point.x - closestX
+      const deltaY = point.y - closestY
+      const deltaZ = point.z - closestZ
+      const squaredDistance = deltaX * deltaX + deltaY * deltaY + deltaZ * deltaZ
+
+      if (squaredDistance >= bestSquaredDistance) {
+        continue
+      }
+
+      const fraction = sample.physicalLength > 0 ? physicalAlong / sample.physicalLength : 0
+      bestSquaredDistance = squaredDistance
+      projection.sampleIndex = index
+      projection.distance = THREE.MathUtils.lerp(sample.startDistance, sample.endDistance, fraction)
+      projection.lateralDistance = deltaX * sample.right.x + deltaY * sample.right.y + deltaZ * sample.right.z
+      projection.verticalDistance = deltaX * sample.up.x + deltaY * sample.up.y + deltaZ * sample.up.z
+    }
+
+    return projection
+  }
+
+  getPieceId(projectionSampleIndex: number): string {
+    return this.projectionSamples[projectionSampleIndex]?.pieceId ?? 'unknown'
+  }
+}