@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/race-camera-tour-planner.ts

@@ -0,0 +1,274 @@
+import * as THREE from 'three'
+
+import type { TrackDefinition } from './track-definition'
+
+const COMPACT_MIN_DURATION_SECONDS = 2.75
+const SHOWCASE_MIN_DURATION_SECONDS = 5
+const MAX_DURATION_SECONDS = 9
+const TOUR_SAMPLE_COUNT = 241
+const MAX_EXTRA_CORKSCREW_TURNS = 1.15
+const COMPACT_TRACK_SPAN = 16
+const FULL_CORKSCREW_TRACK_SPAN = 64
+
+export type CameraTourRouteDirection = 'corkscrew'
+
+export interface CameraTourPose {
+  readonly position: readonly [number, number, number]
+  readonly target: readonly [number, number, number]
+  readonly fov: number
+}
+
+export interface CameraTourDiagnostics {
+  readonly footprintWidth: number
+  readonly footprintDepth: number
+  readonly occupiedCells: number
+  readonly routeDirection: CameraTourRouteDirection
+  readonly routeLength: number
+  readonly minimumClearance: number
+  readonly validationAttempts: number
+  readonly cruiseAltitude: number
+  readonly pitchChanges: number
+  readonly fallbackReason?: string
+}
+
+export interface CameraTourPlan {
+  readonly durationSeconds: number
+  readonly sampleCount: number
+  readonly positions: Float64Array
+  readonly targets: Float64Array
+  readonly fovs: Float32Array
+  readonly startPose: CameraTourPose
+  readonly diagnostics: CameraTourDiagnostics
+}
+
+export interface CameraTourPlannerInput {
+  readonly track: TrackDefinition
+  readonly finishPose: CameraTourPose
+  readonly startPose: CameraTourPose
+  readonly startForward: THREE.Vector3
+  readonly durationSeconds?: number
+}
+
+export interface CameraTourSampleOutput {
+  readonly position: THREE.Vector3
+  readonly target: THREE.Vector3
+}
+
+interface Point2 {
+  x: number
+  y: number
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value))
+}
+
+function smootherstep(value: number): number {
+  const t = clamp01(value)
+  return t * t * t * (t * (t * 6 - 15) + 10)
+}
+
+function cross(origin: Point2, left: Point2, right: Point2): number {
+  return (left.x - origin.x) * (right.y - origin.y) - (left.y - origin.y) * (right.x - origin.x)
+}
+
+export function convexHull2D(points: readonly Point2[]): Point2[] {
+  const finitePoints = points.filter(point => Number.isFinite(point.x) && Number.isFinite(point.y))
+  if (finitePoints.length <= 1) return finitePoints.map(point => ({ ...point }))
+  const sorted = [...finitePoints].sort((left, right) => left.x - right.x || left.y - right.y)
+  const unique = sorted.filter(
+    (point, index) => index === 0 || point.x !== sorted[index - 1]!.x || point.y !== sorted[index - 1]!.y,
+  )
+  if (unique.length <= 2) return unique.map(point => ({ ...point }))
+  const lower: Point2[] = []
+  for (const point of unique) {
+    while (lower.length >= 2 && cross(lower.at(-2)!, lower.at(-1)!, point) <= 0) lower.pop()
+    lower.push(point)
+  }
+  const upper: Point2[] = []
+  for (let index = unique.length - 1; index >= 0; index -= 1) {
+    const point = unique[index]!
+    while (upper.length >= 2 && cross(upper.at(-2)!, upper.at(-1)!, point) <= 0) upper.pop()
+    upper.push(point)
+  }
+  lower.pop()
+  upper.pop()
+  return [...lower, ...upper]
+}
+
+function trackBounds(track: TrackDefinition): { bounds: THREE.Box3; pointCount: number } {
+  const bounds = new THREE.Box3()
+  let pointCount = 0
+  for (const path of [track.cameraPath, ...track.projectionPaths]) {
+    for (const point of path.points) {
+      const position = new THREE.Vector3().fromArray(point.position)
+      if (![position.x, position.y, position.z].every(Number.isFinite)) continue
+      bounds.expandByPoint(position)
+      pointCount += 1
+    }
+  }
+  if (bounds.isEmpty()) bounds.setFromCenterAndSize(new THREE.Vector3(), new THREE.Vector3(1, 1, 1))
+  return { bounds, pointCount }
+}
+
+function shortestSignedAngle(from: number, to: number): number {
+  return Math.atan2(Math.sin(to - from), Math.cos(to - from))
+}
+
+function countPitchChanges(positions: Float64Array, targets: Float64Array): number {
+  let changes = 0
+  let previousPitch: number | undefined
+  let previousDirection = 0
+  for (let sample = 0; sample < TOUR_SAMPLE_COUNT; sample += 1) {
+    const offset = sample * 3
+    const horizontal = Math.hypot(targets[offset]! - positions[offset]!, targets[offset + 2]! - positions[offset + 2]!)
+    const pitch = Math.atan2(targets[offset + 1]! - positions[offset + 1]!, Math.max(horizontal, 0.000_001))
+    if (previousPitch !== undefined) {
+      const direction = Math.sign(pitch - previousPitch)
+      if (direction !== 0 && previousDirection !== 0 && direction !== previousDirection) changes += 1
+      if (direction !== 0) previousDirection = direction
+    }
+    previousPitch = pitch
+  }
+  return changes
+}
+
+/**
+ * Creates the authored finish-to-start corkscrew with geometry alone.
+ *
+ * Runtime camera motion is presentation, not physics. It must never block a
+ * race while exhaustively querying every Rapier collider. The conservative
+ * ellipse is derived from the track guides, rises above their highest point,
+ * and hands off exactly to the existing start-line composition.
+ */
+export function createCameraTourPlan(input: CameraTourPlannerInput): CameraTourPlan {
+  const { bounds, pointCount } = trackBounds(input.track)
+  const center = bounds.getCenter(new THREE.Vector3())
+  const size = bounds.getSize(new THREE.Vector3())
+  const finishPosition = new THREE.Vector3().fromArray(input.finishPose.position)
+  const finishTarget = new THREE.Vector3().fromArray(input.finishPose.target)
+  const startPosition = new THREE.Vector3().fromArray(input.startPose.position)
+  const authoredStartTarget = new THREE.Vector3().fromArray(input.startPose.target)
+  const startLookOffset = input.startForward.clone()
+  if (startLookOffset.lengthSq() < 0.000_001) startLookOffset.subVectors(authoredStartTarget, startPosition)
+  const startLookDistance = Math.max(1, authoredStartTarget.distanceTo(startPosition))
+  startLookOffset.normalize().multiplyScalar(startLookDistance)
+  const startTarget = startPosition.clone().add(startLookOffset)
+  const resolvedStartPose: CameraTourPose = {
+    position: input.startPose.position,
+    target: [startTarget.x, startTarget.y, startTarget.z],
+    fov: input.startPose.fov,
+  }
+
+  const radiusX = THREE.MathUtils.clamp(size.x * 0.58 + 7, 11, 52)
+  const radiusZ = THREE.MathUtils.clamp(size.z * 0.58 + 7, 11, 52)
+  const finishAngle = Math.atan2(finishPosition.z - center.z, finishPosition.x - center.x)
+  const startAngle = Math.atan2(startPosition.z - center.z, startPosition.x - center.x)
+  const footprintSpan = Math.hypot(size.x, size.z)
+  const showcaseWeight = smootherstep(
+    (footprintSpan - COMPACT_TRACK_SPAN) / (FULL_CORKSCREW_TRACK_SPAN - COMPACT_TRACK_SPAN),
+  )
+  const shortestArc = shortestSignedAngle(finishAngle, startAngle)
+  const orbitDirection = Math.sign(shortestArc) || 1
+  const angularTravel = shortestArc + orbitDirection * Math.PI * 2 * MAX_EXTRA_CORKSCREW_TURNS * showcaseWeight
+  const cruiseAltitude = Math.max(
+    finishPosition.y + 4,
+    startPosition.y + 4,
+    bounds.max.y + THREE.MathUtils.clamp(Math.max(size.x, size.z) * 0.12, 8, 18),
+  )
+  const positions = new Float64Array(TOUR_SAMPLE_COUNT * 3)
+  const targets = new Float64Array(TOUR_SAMPLE_COUNT * 3)
+  const fovs = new Float32Array(TOUR_SAMPLE_COUNT)
+  const position = new THREE.Vector3()
+  const target = new THREE.Vector3()
+  const orbit = new THREE.Vector3()
+  const orbitTarget = new THREE.Vector3()
+  const finalLookTarget = new THREE.Vector3()
+  const previousPosition = new THREE.Vector3()
+  let routeLength = 0
+
+  for (let sample = 0; sample < TOUR_SAMPLE_COUNT; sample += 1) {
+    const fraction = sample / (TOUR_SAMPLE_COUNT - 1)
+    const eased = smootherstep(fraction)
+    const angle = finishAngle + angularTravel * fraction
+    const rise = Math.sin(Math.PI * fraction)
+    orbit.set(
+      center.x + Math.cos(angle) * radiusX,
+      THREE.MathUtils.lerp(finishPosition.y, startPosition.y, eased) +
+        rise * (cruiseAltitude - THREE.MathUtils.lerp(finishPosition.y, startPosition.y, eased)),
+      center.z + Math.sin(angle) * radiusZ,
+    )
+    orbitTarget.copy(center)
+
+    const finishBlend = smootherstep(fraction / 0.12)
+    const startBlend = smootherstep((fraction - 0.8) / 0.2)
+    const finalPitchBlend = smootherstep((fraction - 0.55) / 0.3)
+    position.copy(finishPosition).lerp(orbit, finishBlend).lerp(startPosition, startBlend)
+    finalLookTarget.copy(position).add(startLookOffset)
+    target.copy(finishTarget).lerp(orbitTarget, finishBlend).lerp(finalLookTarget, finalPitchBlend)
+
+    if (sample === 0) {
+      position.copy(finishPosition)
+      target.copy(finishTarget)
+    } else {
+      routeLength += position.distanceTo(previousPosition)
+    }
+    if (sample === TOUR_SAMPLE_COUNT - 1) {
+      routeLength += position.distanceTo(startPosition)
+      position.copy(startPosition)
+      target.copy(startTarget)
+    }
+    previousPosition.copy(position)
+    const offset = sample * 3
+    position.toArray(positions, offset)
+    target.toArray(targets, offset)
+    fovs[sample] = THREE.MathUtils.lerp(input.finishPose.fov, input.startPose.fov, eased)
+  }
+
+  return Object.freeze({
+    durationSeconds:
+      input.durationSeconds !== undefined && Number.isFinite(input.durationSeconds) && input.durationSeconds > 0
+        ? input.durationSeconds
+        : THREE.MathUtils.clamp(
+            routeLength / 32,
+            THREE.MathUtils.lerp(COMPACT_MIN_DURATION_SECONDS, SHOWCASE_MIN_DURATION_SECONDS, showcaseWeight),
+            MAX_DURATION_SECONDS,
+          ),
+    sampleCount: TOUR_SAMPLE_COUNT,
+    positions,
+    targets,
+    fovs,
+    startPose: resolvedStartPose,
+    diagnostics: Object.freeze({
+      footprintWidth: size.x,
+      footprintDepth: size.z,
+      occupiedCells: pointCount,
+      routeDirection: 'corkscrew' as const,
+      routeLength,
+      minimumClearance: 0,
+      validationAttempts: 0,
+      cruiseAltitude,
+      pitchChanges: countPitchChanges(positions, targets),
+    }),
+  })
+}
+
+export function sampleCameraTourPlan(plan: CameraTourPlan, progress: number, output: CameraTourSampleOutput): number {
+  const scaled = clamp01(progress) * (plan.sampleCount - 1)
+  const left = Math.floor(scaled)
+  const right = Math.min(plan.sampleCount - 1, left + 1)
+  const alpha = scaled - left
+  const leftOffset = left * 3
+  const rightOffset = right * 3
+  output.position.set(
+    THREE.MathUtils.lerp(plan.positions[leftOffset]!, plan.positions[rightOffset]!, alpha),
+    THREE.MathUtils.lerp(plan.positions[leftOffset + 1]!, plan.positions[rightOffset + 1]!, alpha),
+    THREE.MathUtils.lerp(plan.positions[leftOffset + 2]!, plan.positions[rightOffset + 2]!, alpha),
+  )
+  output.target.set(
+    THREE.MathUtils.lerp(plan.targets[leftOffset]!, plan.targets[rightOffset]!, alpha),
+    THREE.MathUtils.lerp(plan.targets[leftOffset + 1]!, plan.targets[rightOffset + 1]!, alpha),
+    THREE.MathUtils.lerp(plan.targets[leftOffset + 2]!, plan.targets[rightOffset + 2]!, alpha),
+  )
+  return THREE.MathUtils.lerp(plan.fovs[left]!, plan.fovs[right]!, alpha)
+}

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

@@ -0,0 +1,206 @@
+import * as THREE from 'three'
+
+/** The race camera has exactly two authored views. */
+export const RACE_CAMERA_VIEWS = ['race', 'focus'] as const
+
+export type RaceCameraView = (typeof RACE_CAMERA_VIEWS)[number]
+
+/** Zooming out releases a view; Race orbit also releases while Focus orbit retains its subject lock. */
+export const RACE_CAMERA_CONTROLS = ['locked', 'free'] as const
+
+export type RaceCameraControl = (typeof RACE_CAMERA_CONTROLS)[number]
+
+export const RACE_CAMERA_STATES = ['race-locked', 'race-free', 'focus-locked', 'focus-free'] as const
+
+export type RaceCameraState = (typeof RACE_CAMERA_STATES)[number]
+
+export interface RaceCameraSnapshot {
+  view: RaceCameraView
+  control: RaceCameraControl
+  targetSlotId?: string
+}
+
+export function raceCameraState(view: RaceCameraView, control: RaceCameraControl): RaceCameraState {
+  return `${view}-${control}`
+}
+
+const CAMERA_ZOOM_DIRECTION_EPSILON = 0.000_1
+const CAMERA_RETURN_PROGRESS_PER_SECOND = 2.4
+const CAMERA_ORBIT_RETURN_INPUT_RATIO = 0.3
+
+/** Close-enough boundary where the remaining curve is consumed into the authored pose. */
+export const CAMERA_ZOOM_LOCK_DISTANCE_RATIO = 1.03
+
+export function cameraZoomIsInward(previousDistance: number, requestedDistance: number): boolean {
+  return (
+    Number.isFinite(previousDistance) &&
+    Number.isFinite(requestedDistance) &&
+    requestedDistance < previousDistance - CAMERA_ZOOM_DIRECTION_EPSILON
+  )
+}
+
+export function cameraZoomIsOutward(previousDistance: number, requestedDistance: number): boolean {
+  return (
+    Number.isFinite(previousDistance) &&
+    Number.isFinite(requestedDistance) &&
+    requestedDistance > previousDistance + CAMERA_ZOOM_DIRECTION_EPSILON
+  )
+}
+
+export function cameraReturnProgress(startDistance: number, requestedDistance: number, lockedDistance: number): number {
+  if (
+    !Number.isFinite(startDistance) ||
+    !Number.isFinite(requestedDistance) ||
+    !Number.isFinite(lockedDistance) ||
+    lockedDistance <= 0
+  ) {
+    return 0
+  }
+  if (requestedDistance <= lockedDistance * CAMERA_ZOOM_LOCK_DISTANCE_RATIO) return 1
+  if (startDistance <= lockedDistance + CAMERA_ZOOM_DIRECTION_EPSILON) return 0
+  return THREE.MathUtils.clamp((startDistance - requestedDistance) / (startDistance - lockedDistance), 0, 1)
+}
+
+/** Moves a free orbit with its subject without changing the user-authored orbit vector. */
+export function translateFreeCameraRig(
+  position: THREE.Vector3,
+  target: THREE.Vector3,
+  anchor: THREE.Vector3,
+  nextAnchor: THREE.Vector3,
+  translation: THREE.Vector3,
+): void {
+  translation.subVectors(nextAnchor, anchor)
+  anchor.copy(nextAnchor)
+  position.add(translation)
+  target.add(translation)
+}
+
+/**
+ * Allocation-free curve from a user-authored orbit back to the live authored
+ * race/focus pose. Target, radius, direction, and FOV bend together, while
+ * `translate` carries the captured free pose with the moving race subject.
+ */
+export class RaceCameraReturnCurve {
+  private readonly startPosition = new THREE.Vector3()
+  private readonly startTarget = new THREE.Vector3()
+  private readonly startOffset = new THREE.Vector3()
+  private readonly lockedOffset = new THREE.Vector3()
+  private readonly startDirection = new THREE.Vector3()
+  private readonly lockedDirection = new THREE.Vector3()
+  private readonly interpolatedDirection = new THREE.Vector3()
+  private readonly shortestRotation = new THREE.Quaternion()
+  private readonly interpolatedRotation = new THREE.Quaternion()
+  private startFov = 52
+  private startDistance = 0
+  private requestedDistance = 0
+  private requestedInputProgress = 0
+  private progress = 0
+  private active = false
+  private inputDriven = false
+
+  begin(position: THREE.Vector3, target: THREE.Vector3, fov: number, distance: number): void {
+    this.startPosition.copy(position)
+    this.startTarget.copy(target)
+    this.startFov = fov
+    this.startDistance = Math.max(0, distance)
+    this.requestedDistance = this.startDistance
+    this.requestedInputProgress = 0
+    this.progress = 0
+    this.active = true
+    this.inputDriven = false
+  }
+
+  cancel(): void {
+    this.active = false
+    this.progress = 0
+    this.requestedInputProgress = 0
+    this.inputDriven = false
+  }
+
+  isActive(): boolean {
+    return this.active
+  }
+
+  isComplete(): boolean {
+    return this.active && this.progress >= 1
+  }
+
+  setRequestedDistance(distance: number, inputDriven = false): void {
+    if (!Number.isFinite(distance)) return
+    this.requestedDistance = Math.max(0, distance)
+    this.inputDriven = inputDriven
+  }
+
+  addInwardInput(previousDistance: number, requestedDistance: number, lockedDistance: number): void {
+    if (
+      !this.active ||
+      !Number.isFinite(previousDistance) ||
+      !Number.isFinite(requestedDistance) ||
+      !Number.isFinite(lockedDistance) ||
+      lockedDistance <= 0
+    ) {
+      return
+    }
+    const inwardDistance = Math.max(0, previousDistance - requestedDistance)
+    const returnInputDistance = Math.max(
+      this.startDistance - lockedDistance,
+      lockedDistance * CAMERA_ORBIT_RETURN_INPUT_RATIO,
+      CAMERA_ZOOM_DIRECTION_EPSILON,
+    )
+    this.requestedInputProgress = THREE.MathUtils.clamp(
+      this.requestedInputProgress + inwardDistance / returnInputDistance,
+      0,
+      1,
+    )
+    this.inputDriven = true
+  }
+
+  translate(delta: THREE.Vector3): void {
+    if (!this.active) return
+    this.startPosition.add(delta)
+    this.startTarget.add(delta)
+  }
+
+  writePose(
+    lockedPosition: THREE.Vector3,
+    lockedTarget: THREE.Vector3,
+    lockedFov: number,
+    outputPosition: THREE.Vector3,
+    outputTarget: THREE.Vector3,
+    deltaSeconds: number,
+  ): number {
+    if (!this.active) return lockedFov
+
+    this.startOffset.subVectors(this.startPosition, this.startTarget)
+    this.lockedOffset.subVectors(lockedPosition, lockedTarget)
+    const lockedDistance = this.lockedOffset.length()
+    const requestedProgress = Math.max(
+      this.progress,
+      this.inputDriven
+        ? this.requestedInputProgress
+        : cameraReturnProgress(this.startDistance, this.requestedDistance, lockedDistance),
+    )
+    this.progress = this.inputDriven
+      ? requestedProgress
+      : Math.min(
+          requestedProgress,
+          this.progress + CAMERA_RETURN_PROGRESS_PER_SECOND * THREE.MathUtils.clamp(deltaSeconds, 0, 0.1),
+        )
+    const curvedProgress = THREE.MathUtils.smootherstep(this.progress, 0, 1)
+
+    outputTarget.lerpVectors(this.startTarget, lockedTarget, curvedProgress)
+    if (this.startOffset.lengthSq() < 0.000_001 || this.lockedOffset.lengthSq() < 0.000_001) {
+      outputPosition.lerpVectors(this.startPosition, lockedPosition, curvedProgress)
+      return THREE.MathUtils.lerp(this.startFov, lockedFov, curvedProgress)
+    }
+
+    this.startDirection.copy(this.startOffset).normalize()
+    this.lockedDirection.copy(this.lockedOffset).normalize()
+    this.shortestRotation.setFromUnitVectors(this.startDirection, this.lockedDirection)
+    this.interpolatedRotation.identity().slerp(this.shortestRotation, curvedProgress)
+    this.interpolatedDirection.copy(this.startDirection).applyQuaternion(this.interpolatedRotation).normalize()
+    const radius = THREE.MathUtils.lerp(this.startDistance, lockedDistance, this.progress)
+    outputPosition.copy(outputTarget).addScaledVector(this.interpolatedDirection, radius)
+    return THREE.MathUtils.lerp(this.startFov, lockedFov, curvedProgress)
+  }
+}

package/src/pages/play/race/race-completion.ts

@@ -0,0 +1,5 @@
+export {
+  RACE_FINISH_COAST_SECONDS as FINISH_COAST_SECONDS,
+  RACE_FINISH_COAST_TICKS as FINISH_COAST_TICKS,
+  hasRaceFinishCoastElapsed as hasFinishCoastElapsed,
+} from '@marble.fun/physics-engine'

package/src/pages/play/race/race-configuration.ts

@@ -0,0 +1,57 @@
+import {
+  createRaceConfiguration as createCoreRaceConfiguration,
+  createRaceTuning as createCoreRaceTuning,
+  raceConfigurationKey,
+  RACE_MARBLE_RADIUS,
+} from '@marble.fun/physics-engine'
+
+import { MAX_MARBLES, MIN_MARBLES, type MarbleAssignment, type RaceConfiguration, type RaceTuning } from './race-types'
+import { STOCK_MARBLES } from '../../lobby/lobby-types'
+import { normalizeSeed } from './seeded-random'
+import type { TrackDefinition } from './track-definition'
+
+export const STOCK_PRESETS = [
+  ...STOCK_MARBLES.map(stock => ({ label: stock.id, color: stock.color })),
+  { label: 'DEMO 5', color: '#fd9d55' },
+  { label: 'DEMO 6', color: '#8d7cff' },
+] as const
+
+export const MARBLE_RADIUS = RACE_MARBLE_RADIUS
+
+export function createAssignments(marbleCount: number): MarbleAssignment[] {
+  return STOCK_PRESETS.slice(0, marbleCount).map((preset, index) => ({
+    slotId: `M${index + 1}`,
+    label: preset.label,
+    color: preset.color,
+  }))
+}
+
+export function createRaceConfiguration(
+  seed: string,
+  marbleCount: number,
+  track: Pick<TrackDefinition, 'id' | 'version'>,
+): RaceConfiguration {
+  const safeCount = Math.min(MAX_MARBLES, Math.max(MIN_MARBLES, Math.round(marbleCount)))
+  return createCoreRaceConfiguration(normalizeSeed(seed), safeCount, track, createAssignments(safeCount))
+}
+
+export function createLabTestRunConfiguration(
+  seed: string,
+  marbleCount: number,
+  track: Pick<TrackDefinition, 'id' | 'version'>,
+): RaceConfiguration {
+  const configuration = createRaceConfiguration(seed, marbleCount, track)
+  return {
+    ...configuration,
+    assignments: configuration.assignments.map(assignment => ({
+      ...assignment,
+      label: assignment.slotId,
+    })),
+  }
+}
+
+export function createRaceTuning(configuration: RaceConfiguration, track: TrackDefinition): RaceTuning {
+  return createCoreRaceTuning(configuration, track)
+}
+
+export { raceConfigurationKey }

package/src/pages/play/race/race-marble-focus-renderer.ts

@@ -0,0 +1,134 @@
+import * as THREE from 'three'
+import { FullScreenQuad } from 'three/addons/postprocessing/Pass.js'
+
+const vertexShader = /* glsl */ `
+  varying vec2 vUv;
+
+  void main() {
+    vUv = uv;
+    gl_Position = vec4(position.xy, 0.0, 1.0);
+  }
+`
+
+const fragmentShader = /* glsl */ `
+  uniform sampler2D tColor;
+  uniform vec2 texelSize;
+  uniform vec2 focusUv;
+  uniform float aspect;
+  uniform float focusRadius;
+  uniform float focusFeather;
+  uniform float maxBlurPixels;
+
+  varying vec2 vUv;
+
+  void main() {
+    vec4 centerColor = texture2D(tColor, vUv);
+    vec2 focusDelta = (vUv - focusUv) * vec2(aspect, 1.0);
+    float blur = smoothstep(focusRadius, focusRadius + focusFeather, length(focusDelta));
+
+    if (blur <= 0.001) {
+      gl_FragColor = centerColor;
+      return;
+    }
+
+    vec2 radius = texelSize * maxBlurPixels * blur;
+    vec4 blurredColor = centerColor * 0.2;
+    for (int index = 0; index < 8; index++) {
+      float angle = float(index) * 0.7853981634;
+      vec2 tap = vec2(cos(angle), sin(angle));
+      vec2 sampleUv = clamp(vUv + tap * radius, vec2(0.0), vec2(1.0));
+      blurredColor += texture2D(tColor, sampleUv) * 0.1;
+    }
+
+    // The framebuffer copy already contains final display pixels. Interpolate
+    // those raw values only; never tone-map, expose, or encode them again.
+    gl_FragColor = mix(centerColor, blurredColor, blur);
+  }
+`
+
+/** Keeps the ball and nearby track sharp, then gradually softens the surrounding frame. */
+export class RaceMarbleFocusRenderer {
+  private colorTexture = this.createColorTexture(1, 1)
+  private readonly material: THREE.ShaderMaterial
+  private readonly quad: FullScreenQuad
+  private readonly drawingBufferSize = new THREE.Vector2()
+  private readonly projectedFocus = new THREE.Vector3()
+  private width = 0
+  private height = 0
+
+  constructor() {
+    this.material = new THREE.ShaderMaterial({
+      depthTest: false,
+      depthWrite: false,
+      toneMapped: false,
+      transparent: false,
+      uniforms: {
+        tColor: { value: this.colorTexture },
+        texelSize: { value: new THREE.Vector2(1, 1) },
+        focusUv: { value: new THREE.Vector2(0.5, 0.5) },
+        aspect: { value: 1 },
+        // Screen-height-relative radii after aspect correction: a broad sharp
+        // neighborhood around the marble followed by a long, gentle falloff.
+        focusRadius: { value: 0.14 },
+        focusFeather: { value: 0.22 },
+        maxBlurPixels: { value: 4 },
+      },
+      vertexShader,
+      fragmentShader,
+    })
+    this.quad = new FullScreenQuad(this.material)
+  }
+
+  render(
+    renderer: THREE.WebGLRenderer,
+    scene: THREE.Scene,
+    camera: THREE.PerspectiveCamera,
+    focusWorldPosition: THREE.Vector3,
+  ): void {
+    this.syncSize(renderer)
+
+    // Establish the authoritative color first through the ordinary renderer.
+    // Copying it avoids a second scene render and guarantees identical grading.
+    renderer.render(scene, camera)
+    renderer.copyFramebufferToTexture(this.colorTexture)
+
+    this.projectedFocus.copy(focusWorldPosition).project(camera)
+    ;(this.material.uniforms.focusUv!.value as THREE.Vector2).set(
+      this.projectedFocus.x * 0.5 + 0.5,
+      this.projectedFocus.y * 0.5 + 0.5,
+    )
+    this.quad.render(renderer)
+  }
+
+  dispose(): void {
+    this.quad.dispose()
+    this.material.dispose()
+    this.colorTexture.dispose()
+  }
+
+  private createColorTexture(width: number, height: number): THREE.FramebufferTexture {
+    const texture = new THREE.FramebufferTexture(width, height)
+    texture.name = 'race-marble-focus-screen-copy'
+    // The copy contains already encoded display values. Treat them as raw data
+    // so the focus shader cannot alter exposure or color-space transforms.
+    texture.colorSpace = THREE.NoColorSpace
+    texture.magFilter = THREE.LinearFilter
+    texture.minFilter = THREE.LinearFilter
+    return texture
+  }
+
+  private syncSize(renderer: THREE.WebGLRenderer): void {
+    renderer.getDrawingBufferSize(this.drawingBufferSize)
+    const width = Math.max(1, Math.round(this.drawingBufferSize.x))
+    const height = Math.max(1, Math.round(this.drawingBufferSize.y))
+    if (width === this.width && height === this.height) return
+
+    this.width = width
+    this.height = height
+    this.colorTexture.dispose()
+    this.colorTexture = this.createColorTexture(width, height)
+    this.material.uniforms.tColor!.value = this.colorTexture
+    ;(this.material.uniforms.texelSize!.value as THREE.Vector2).set(1 / width, 1 / height)
+    this.material.uniforms.aspect!.value = width / height
+  }
+}

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

@@ -0,0 +1,7 @@
+export {
+  fastRaceDuration,
+  fastRaceElapsedSeconds,
+  fastRaceSpeed,
+  RACE_PACE,
+  RACE_PHYSICS as FAST_RACE_PHYSICS,
+} from '@marble.fun/physics-engine'