@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/race-camera-director.ts

@@ -0,0 +1,586 @@
+import * as THREE from 'three'
+
+export type RaceCameraDirectorState = 'tour' | 'start-line' | 'follow'
+
+export interface CameraMotionLimits {
+  deadZone: number
+  response: number
+  maximumSpeed: number
+  maximumAcceleration: number
+}
+
+export interface CameraDirectorDiagnostics {
+  state: RaceCameraDirectorState
+  stateSeconds: number
+  linearSpeed: number
+  targetSpeed: number
+}
+
+export const CAMERA_POSITION_LIMITS: CameraMotionLimits = {
+  deadZone: 0.14,
+  response: 3,
+  // At the minimum Race-view boom length this stays below the angular
+  // comfort limit, so the camera cannot orbit its target faster than it can
+  // turn to keep that target framed.
+  maximumSpeed: 18,
+  maximumAcceleration: 44,
+}
+
+export const CAMERA_TARGET_LIMITS: CameraMotionLimits = {
+  deadZone: 0.3,
+  response: 3.1,
+  maximumSpeed: 18,
+  maximumAcceleration: 40,
+}
+
+export const CAMERA_MAXIMUM_ANGULAR_SPEED = THREE.MathUtils.degToRad(75)
+
+/** Quintic easing gives the authored intro zero velocity and acceleration at both ends. */
+export function smoothCameraTourProgress(value: number): number {
+  const clamped = THREE.MathUtils.clamp(value, 0, 1)
+  return clamped * clamped * clamped * (clamped * (clamped * 6 - 15) + 10)
+}
+
+export function retainCameraLeader(currentProgress: number, bestProgress: number, switchGap = 1.4): boolean {
+  return bestProgress - currentProgress <= switchGap
+}
+
+export function advanceCameraOrientation(
+  current: THREE.Quaternion,
+  desired: THREE.Quaternion,
+  deltaSeconds: number,
+): void {
+  current.rotateTowards(desired, CAMERA_MAXIMUM_ANGULAR_SPEED * THREE.MathUtils.clamp(deltaSeconds, 0, 0.1))
+}
+
+/**
+ * Resolves a stable course-facing direction. Long guide chords are useful on
+ * gentle track, but on consecutive curves they can cut across the inside of
+ * the bend or even point backward. The local tangent remains authoritative in
+ * those cases.
+ */
+export function writeStableCameraGuideDirection(
+  localTangent: THREE.Vector3,
+  guideChord: THREE.Vector3,
+  output: THREE.Vector3,
+): THREE.Vector3 {
+  output.copy(localTangent)
+  if (output.lengthSq() < 0.000_001) output.set(0, 0, 1)
+  else output.normalize()
+
+  const chordLengthSquared = guideChord.lengthSq()
+  if (chordLengthSquared < 4) return output
+  const inverseChordLength = 1 / Math.sqrt(chordLengthSquared)
+  const alignment = output.dot(guideChord) * inverseChordLength
+  if (alignment < 0.45) return output
+
+  output.x = output.x * 0.65 + guideChord.x * inverseChordLength * 0.35
+  output.y = output.y * 0.65 + guideChord.y * inverseChordLength * 0.35
+  output.z = output.z * 0.65 + guideChord.z * inverseChordLength * 0.35
+  return output.normalize()
+}
+
+export function cameraPoseWithinTolerance(
+  position: THREE.Vector3,
+  desiredPosition: THREE.Vector3,
+  target: THREE.Vector3,
+  desiredTarget: THREE.Vector3,
+  orientation: THREE.Quaternion,
+  desiredOrientation: THREE.Quaternion,
+  positionTolerance: number,
+  targetTolerance: number,
+  angleTolerance: number,
+): boolean {
+  return (
+    position.distanceToSquared(desiredPosition) <= positionTolerance * positionTolerance &&
+    target.distanceToSquared(desiredTarget) <= targetTolerance * targetTolerance &&
+    orientation.angleTo(desiredOrientation) <= angleTolerance
+  )
+}
+
+function moveVectorTowards(current: THREE.Vector3, target: THREE.Vector3, maximumDelta: number): void {
+  const deltaX = target.x - current.x
+  const deltaY = target.y - current.y
+  const deltaZ = target.z - current.z
+  const distance = Math.hypot(deltaX, deltaY, deltaZ)
+  if (distance <= maximumDelta || distance < 0.000_001) {
+    current.copy(target)
+    return
+  }
+  const scale = maximumDelta / distance
+  current.x += deltaX * scale
+  current.y += deltaY * scale
+  current.z += deltaZ * scale
+}
+
+/**
+ * Advances a camera value with bounded velocity and acceleration. The function
+ * mutates supplied vectors so the rendered hot path does not allocate.
+ */
+export function advanceCameraVector(
+  current: THREE.Vector3,
+  velocity: THREE.Vector3,
+  goal: THREE.Vector3,
+  deltaSeconds: number,
+  limits: CameraMotionLimits,
+  desiredVelocity: THREE.Vector3,
+): void {
+  const safeDelta = THREE.MathUtils.clamp(deltaSeconds, 0, 0.1)
+  if (safeDelta <= 0) return
+
+  desiredVelocity.subVectors(goal, current)
+  const remainingDistance = desiredVelocity.length()
+  if (remainingDistance <= limits.deadZone && velocity.lengthSq() <= 0.04) {
+    velocity.set(0, 0, 0)
+    return
+  }
+
+  desiredVelocity.multiplyScalar(limits.response)
+  if (desiredVelocity.lengthSq() > limits.maximumSpeed ** 2) {
+    desiredVelocity.setLength(limits.maximumSpeed)
+  }
+  moveVectorTowards(velocity, desiredVelocity, limits.maximumAcceleration * safeDelta)
+
+  const stepDistance = velocity.length() * safeDelta
+  if (remainingDistance <= stepDistance && remainingDistance > limits.deadZone) {
+    current.copy(goal)
+    velocity.set(0, 0, 0)
+    return
+  }
+  current.addScaledVector(velocity, safeDelta)
+}
+
+export class RaceCameraDirector {
+  private readonly positionVelocity = new THREE.Vector3()
+  private readonly targetVelocity = new THREE.Vector3()
+  private readonly desiredPositionVelocity = new THREE.Vector3()
+  private readonly desiredTargetVelocity = new THREE.Vector3()
+  private state: RaceCameraDirectorState = 'follow'
+  private stateSeconds = 0
+  private initialized = false
+
+  initialize(position: THREE.Vector3, target: THREE.Vector3): void {
+    this.positionVelocity.set(0, 0, 0)
+    this.targetVelocity.set(0, 0, 0)
+    this.initialized = true
+    // The caller owns the actual position and target. Initialization only
+    // clears motion history so the first presented frame may be composed.
+    void position
+    void target
+  }
+
+  isInitialized(): boolean {
+    return this.initialized
+  }
+
+  setState(state: RaceCameraDirectorState): void {
+    if (this.state === state) return
+    this.state = state
+    this.stateSeconds = 0
+  }
+
+  update(
+    position: THREE.Vector3,
+    target: THREE.Vector3,
+    desiredPosition: THREE.Vector3,
+    desiredTarget: THREE.Vector3,
+    deltaSeconds: number,
+    lockTarget = false,
+    positionLimits = CAMERA_POSITION_LIMITS,
+    targetLimits = CAMERA_TARGET_LIMITS,
+  ): void {
+    if (!this.initialized) this.initialize(position, target)
+    this.stateSeconds += THREE.MathUtils.clamp(deltaSeconds, 0, 0.1)
+    advanceCameraVector(
+      position,
+      this.positionVelocity,
+      desiredPosition,
+      deltaSeconds,
+      positionLimits,
+      this.desiredPositionVelocity,
+    )
+    if (lockTarget) {
+      target.copy(desiredTarget)
+      this.targetVelocity.set(0, 0, 0)
+      this.desiredTargetVelocity.set(0, 0, 0)
+    } else {
+      advanceCameraVector(
+        target,
+        this.targetVelocity,
+        desiredTarget,
+        deltaSeconds,
+        targetLimits,
+        this.desiredTargetVelocity,
+      )
+    }
+  }
+
+  /** Advances only a free-orbit pivot; the caller retains ownership of orbit rotation and radius. */
+  updateTarget(target: THREE.Vector3, desiredTarget: THREE.Vector3, deltaSeconds: number): void {
+    if (!this.initialized) this.initialize(target, target)
+    this.stateSeconds += THREE.MathUtils.clamp(deltaSeconds, 0, 0.1)
+    advanceCameraVector(
+      target,
+      this.targetVelocity,
+      desiredTarget,
+      deltaSeconds,
+      CAMERA_TARGET_LIMITS,
+      this.desiredTargetVelocity,
+    )
+  }
+
+  synchronize(position: THREE.Vector3, target: THREE.Vector3): void {
+    this.initialize(position, target)
+  }
+
+  diagnostics(): CameraDirectorDiagnostics {
+    return {
+      state: this.state,
+      stateSeconds: this.stateSeconds,
+      linearSpeed: this.positionVelocity.length(),
+      targetSpeed: this.targetVelocity.length(),
+    }
+  }
+}
+
+export interface LeadingPackCandidate {
+  bestProgress: number
+  progress?: number
+  visual: { position: { x: number; y: number; z: number } }
+}
+
+export interface LeadingPackFrame {
+  center: THREE.Vector3
+  count: number
+  progress: number
+  radius: number
+}
+
+const RACE_PACK_SWITCH_HOLD_SECONDS = 0.65
+const RACE_PACK_DECISIVE_SWITCH_HOLD_SECONDS = 0.18
+
+function resetLeadingPackFrame(output: LeadingPackFrame): void {
+  output.center.set(0, 0, 0)
+  output.count = 0
+  output.progress = 0
+  output.radius = 0
+}
+
+function selectLeadingPackLeader(
+  candidates: readonly LeadingPackCandidate[],
+  maxProgressGap: number,
+  maxSpatialGap: number,
+  preferredCenter?: THREE.Vector3,
+): LeadingPackCandidate | undefined {
+  const maximumSpatialGapSquared = maxSpatialGap * maxSpatialGap
+  let packLeader: LeadingPackCandidate | undefined
+  let packCount = 0
+  let packProgress = Number.NEGATIVE_INFINITY
+  let packCenterDistanceSquared = Number.POSITIVE_INFINITY
+
+  for (const candidateLeader of candidates) {
+    const leaderPosition = candidateLeader.visual.position
+    let candidateCount = 0
+    let candidateProgress = 0
+    let candidateCenterX = 0
+    let candidateCenterY = 0
+    let candidateCenterZ = 0
+    for (const candidate of candidates) {
+      const progressGap = candidateLeader.bestProgress - candidate.bestProgress
+      if (progressGap < 0 || progressGap > maxProgressGap) continue
+      const position = candidate.visual.position
+      const deltaX = position.x - leaderPosition.x
+      const deltaY = position.y - leaderPosition.y
+      const deltaZ = position.z - leaderPosition.z
+      if (deltaX * deltaX + deltaY * deltaY + deltaZ * deltaZ > maximumSpatialGapSquared) continue
+      candidateCount += 1
+      candidateProgress += candidate.bestProgress
+      candidateCenterX += position.x
+      candidateCenterY += position.y
+      candidateCenterZ += position.z
+    }
+    const averageProgress = candidateCount > 0 ? candidateProgress / candidateCount : Number.NEGATIVE_INFINITY
+    const inverseCount = candidateCount > 0 ? 1 / candidateCount : 0
+    const centerDeltaX = candidateCenterX * inverseCount - (preferredCenter?.x ?? 0)
+    const centerDeltaY = candidateCenterY * inverseCount - (preferredCenter?.y ?? 0)
+    const centerDeltaZ = candidateCenterZ * inverseCount - (preferredCenter?.z ?? 0)
+    const centerDistanceSquared = preferredCenter
+      ? centerDeltaX * centerDeltaX + centerDeltaY * centerDeltaY + centerDeltaZ * centerDeltaZ
+      : Number.POSITIVE_INFINITY
+    const closerToRetainedCenter =
+      preferredCenter !== undefined &&
+      candidateCount === packCount &&
+      centerDistanceSquared < packCenterDistanceSquared - 0.000_001
+    const equallyCloseToRetainedCenter =
+      preferredCenter === undefined || Math.abs(centerDistanceSquared - packCenterDistanceSquared) <= 0.000_001
+    if (
+      candidateCount > packCount ||
+      closerToRetainedCenter ||
+      (candidateCount === packCount && equallyCloseToRetainedCenter && averageProgress > packProgress)
+    ) {
+      packLeader = candidateLeader
+      packCount = candidateCount
+      packProgress = averageProgress
+      packCenterDistanceSquared = centerDistanceSquared
+    }
+  }
+
+  return packLeader
+}
+
+function writePackFrameForLeader(
+  candidates: readonly LeadingPackCandidate[],
+  packLeader: LeadingPackCandidate,
+  output: LeadingPackFrame,
+  maxProgressGap: number,
+  maxSpatialGap: number,
+  members?: LeadingPackCandidate[],
+): number {
+  resetLeadingPackFrame(output)
+  if (members) members.length = 0
+
+  const leaderPosition = packLeader.visual.position
+  const maximumSpatialGapSquared = maxSpatialGap * maxSpatialGap
+  for (const candidate of candidates) {
+    const progressGap = packLeader.bestProgress - candidate.bestProgress
+    if (progressGap < 0 || progressGap > maxProgressGap) continue
+    const position = candidate.visual.position
+    const deltaX = position.x - leaderPosition.x
+    const deltaY = position.y - leaderPosition.y
+    const deltaZ = position.z - leaderPosition.z
+    if (deltaX * deltaX + deltaY * deltaY + deltaZ * deltaZ > maximumSpatialGapSquared) continue
+    output.center.x += position.x
+    output.center.y += position.y
+    output.center.z += position.z
+    output.progress += candidate.progress ?? candidate.bestProgress
+    output.count += 1
+    members?.push(candidate)
+  }
+  if (output.count === 0) return 0
+  output.center.multiplyScalar(1 / output.count)
+  output.progress /= output.count
+
+  const packMembers = members ?? candidates
+  for (const candidate of packMembers) {
+    if (!members) {
+      const progressGap = packLeader.bestProgress - candidate.bestProgress
+      if (progressGap < 0 || progressGap > maxProgressGap) continue
+      const position = candidate.visual.position
+      const leaderDeltaX = position.x - leaderPosition.x
+      const leaderDeltaY = position.y - leaderPosition.y
+      const leaderDeltaZ = position.z - leaderPosition.z
+      if (
+        leaderDeltaX * leaderDeltaX + leaderDeltaY * leaderDeltaY + leaderDeltaZ * leaderDeltaZ >
+        maximumSpatialGapSquared
+      ) {
+        continue
+      }
+    }
+    const position = candidate.visual.position
+    const deltaX = position.x - output.center.x
+    const deltaY = position.y - output.center.y
+    const deltaZ = position.z - output.center.z
+    output.radius = Math.max(output.radius, Math.hypot(deltaX, deltaY, deltaZ))
+  }
+  return output.count
+}
+
+function copyLeadingPackFrame(source: LeadingPackFrame, output: LeadingPackFrame): void {
+  output.center.copy(source.center)
+  output.count = source.count
+  output.progress = source.progress
+  output.radius = source.radius
+}
+
+/**
+ * Retains one broadcast pack across frames. Normal membership changes that
+ * still overlap the retained pack are accepted immediately, while a disjoint
+ * group must remain the better choice before the camera is allowed to switch.
+ */
+export class RaceCameraPackTracker {
+  private readonly selectedMembers: LeadingPackCandidate[] = []
+  private readonly bestMembers: LeadingPackCandidate[] = []
+  private readonly retainedMembers: LeadingPackCandidate[] = []
+  private readonly challengerMembers: LeadingPackCandidate[] = []
+  private readonly bestFrame: LeadingPackFrame = {
+    center: new THREE.Vector3(),
+    count: 0,
+    progress: 0,
+    radius: 0,
+  }
+  private readonly retainedFrame: LeadingPackFrame = {
+    center: new THREE.Vector3(),
+    count: 0,
+    progress: 0,
+    radius: 0,
+  }
+  private readonly lastCenter = new THREE.Vector3()
+  private readonly pendingDiscontinuity = new THREE.Vector3()
+  private hasLastCenter = false
+  private challengerSeconds = 0
+
+  reset(): void {
+    this.selectedMembers.length = 0
+    this.bestMembers.length = 0
+    this.retainedMembers.length = 0
+    this.challengerMembers.length = 0
+    this.lastCenter.set(0, 0, 0)
+    this.pendingDiscontinuity.set(0, 0, 0)
+    this.hasLastCenter = false
+    this.challengerSeconds = 0
+  }
+
+  update(
+    candidates: readonly LeadingPackCandidate[],
+    output: LeadingPackFrame,
+    deltaSeconds: number,
+    maxProgressGap = 7,
+    maxSpatialGap = 14,
+  ): number {
+    this.pendingDiscontinuity.set(0, 0, 0)
+    const bestLeader = selectLeadingPackLeader(candidates, maxProgressGap, maxSpatialGap)
+    if (!bestLeader) {
+      this.reset()
+      resetLeadingPackFrame(output)
+      return 0
+    }
+    writePackFrameForLeader(
+      candidates,
+      bestLeader,
+      this.bestFrame,
+      maxProgressGap,
+      maxSpatialGap,
+      this.bestMembers,
+    )
+
+    if (this.selectedMembers.length === 0) {
+      this.adoptBest(output, maxSpatialGap, false)
+      return output.count
+    }
+
+    const retainedLeader = selectLeadingPackLeader(
+      this.selectedMembers,
+      maxProgressGap,
+      maxSpatialGap,
+      this.hasLastCenter ? this.lastCenter : undefined,
+    )
+    if (retainedLeader) {
+      writePackFrameForLeader(
+        this.selectedMembers,
+        retainedLeader,
+        this.retainedFrame,
+        maxProgressGap,
+        maxSpatialGap,
+        this.retainedMembers,
+      )
+    } else {
+      resetLeadingPackFrame(this.retainedFrame)
+      this.retainedMembers.length = 0
+    }
+
+    let overlap = 0
+    for (const candidate of this.bestMembers) {
+      if (this.selectedMembers.includes(candidate)) overlap += 1
+    }
+    const samePack = overlap * 2 > Math.max(this.selectedMembers.length, this.bestMembers.length)
+    if (samePack) {
+      this.adoptBest(output, maxSpatialGap, true)
+      return output.count
+    }
+
+    if (this.retainedFrame.count === 0) {
+      this.adoptBest(output, maxSpatialGap, false)
+      return output.count
+    }
+
+    let challengerOverlap = 0
+    for (const candidate of this.bestMembers) {
+      if (this.challengerMembers.includes(candidate)) challengerOverlap += 1
+    }
+    const sameChallenger =
+      this.challengerMembers.length > 0 &&
+      challengerOverlap * 2 > Math.max(this.challengerMembers.length, this.bestMembers.length)
+    if (!sameChallenger) {
+      this.challengerMembers.length = 0
+      this.challengerMembers.push(...this.bestMembers)
+      this.challengerSeconds = 0
+    } else {
+      this.challengerSeconds += THREE.MathUtils.clamp(deltaSeconds, 0, 0.1)
+    }
+    const decisiveSwitch = this.retainedFrame.count === 1 && this.bestFrame.count >= 3
+    const switchHoldSeconds = decisiveSwitch
+      ? RACE_PACK_DECISIVE_SWITCH_HOLD_SECONDS
+      : RACE_PACK_SWITCH_HOLD_SECONDS
+    if (this.challengerSeconds >= switchHoldSeconds) {
+      this.adoptBest(output, maxSpatialGap, false)
+      return output.count
+    }
+
+    this.publish(this.retainedFrame, output, maxSpatialGap, true)
+    return output.count
+  }
+
+  consumeDiscontinuity(output: THREE.Vector3): boolean {
+    if (this.pendingDiscontinuity.lengthSq() < 0.000_001) return false
+    output.copy(this.pendingDiscontinuity)
+    this.pendingDiscontinuity.set(0, 0, 0)
+    return true
+  }
+
+  private adoptBest(output: LeadingPackFrame, maxSpatialGap: number, preserveIdentity: boolean): void {
+    this.selectedMembers.length = 0
+    this.selectedMembers.push(...this.bestMembers)
+    this.challengerMembers.length = 0
+    this.challengerSeconds = 0
+    this.publish(this.bestFrame, output, maxSpatialGap, preserveIdentity)
+  }
+
+  private publish(
+    frame: LeadingPackFrame,
+    output: LeadingPackFrame,
+    maxSpatialGap: number,
+    preserveIdentity: boolean,
+  ): void {
+    if (
+      preserveIdentity &&
+      this.hasLastCenter &&
+      this.lastCenter.distanceToSquared(frame.center) > (maxSpatialGap * 1.5) ** 2
+    ) {
+      this.pendingDiscontinuity.subVectors(frame.center, this.lastCenter)
+    }
+    this.lastCenter.copy(frame.center)
+    this.hasLastCenter = frame.count > 0
+    copyLeadingPackFrame(frame, output)
+  }
+}
+
+/**
+ * Frames the largest progress-close and spatially coherent group, preferring
+ * the front-most group when two packs contain the same number of racers. This
+ * keeps a breakaway marble from turning Race View into a leader-follow camera.
+ * The spatial gate also prevents portal-separated or tightly folded track
+ * sections from producing a centroid in empty space.
+ */
+export function writeLeadingPackFrame(
+  candidates: readonly LeadingPackCandidate[],
+  output: LeadingPackFrame,
+  maxProgressGap = 14,
+  maxSpatialGap = 20,
+): number {
+  const packLeader = selectLeadingPackLeader(candidates, maxProgressGap, maxSpatialGap)
+  if (!packLeader) {
+    resetLeadingPackFrame(output)
+    return 0
+  }
+  return writePackFrameForLeader(candidates, packLeader, output, maxProgressGap, maxSpatialGap)
+}
+
+/** Writes the centroid of the largest progress-coherent pack. */
+export function writeLeadingPackCentroid(
+  candidates: readonly LeadingPackCandidate[],
+  output: THREE.Vector3,
+  maxProgressGap = 14,
+): number {
+  const frame: LeadingPackFrame = { center: output, count: 0, progress: 0, radius: 0 }
+  return writeLeadingPackFrame(candidates, frame, maxProgressGap, Number.POSITIVE_INFINITY)
+}

package/src/pages/play/race/race-camera-obstruction.ts

@@ -0,0 +1,37 @@
+export const CAMERA_OBSTRUCTION_CLEARANCE = 0.75
+export const CAMERA_MIN_TARGET_DISTANCE = 0.35
+export const CAMERA_OBSTRUCTION_TARGET_OFFSET = 1.25
+
+/** Starts the sightline beyond the subject's immediate track contact patch. */
+export function cameraObstructionProbeOffset(desiredDistance: number): number {
+  return Math.max(0, Math.min(CAMERA_OBSTRUCTION_TARGET_OFFSET, desiredDistance - CAMERA_MIN_TARGET_DISTANCE))
+}
+
+/** Compresses the boom along its existing sightline; it never selects another side. */
+export function resolveCameraObstructionDistance(
+  desiredDistance: number,
+  firstHitDistance?: number,
+  probeOffset = 0,
+): number {
+  if (firstHitDistance === undefined) return desiredDistance
+  const absoluteHitDistance = probeOffset + firstHitDistance
+  if (absoluteHitDistance >= desiredDistance) return desiredDistance
+  return Math.min(
+    desiredDistance,
+    Math.max(CAMERA_MIN_TARGET_DISTANCE, absoluteHitDistance - CAMERA_OBSTRUCTION_CLEARANCE),
+  )
+}
+
+/** Expands slowly after an obstruction clears, but contracts immediately to remain in front of it. */
+export function advanceCameraObstructionDistance(
+  currentDistance: number,
+  allowedDistance: number,
+  deltaSeconds: number,
+  releaseResponse = 4,
+): number {
+  if (!Number.isFinite(currentDistance) || currentDistance <= 0 || allowedDistance <= currentDistance) {
+    return allowedDistance
+  }
+  const alpha = 1 - Math.exp(-releaseResponse * Math.max(0, deltaSeconds))
+  return currentDistance + (allowedDistance - currentDistance) * alpha
+}