@inventure71/paddockjs 1.0.0 → 2.0.0

package/src/simulation/timing/lapTelemetry.js

@@ -0,0 +1,182 @@
+import { clamp } from '../simMath.js';
+import { TELEMETRY_SECTOR_COUNT } from './timingConstants.js';
+import {
+  createEmptySectorPerformance,
+  createEmptySectorTimes,
+  finiteOrNull,
+  serializeSectorPerformance,
+  serializeSectorTimes,
+} from './sectorPerformance.js';
+
+function getSectorLength(track) {
+  return track.length / TELEMETRY_SECTOR_COUNT;
+}
+
+function getLapTelemetryPosition(track, raceDistance, totalLaps = Infinity) {
+  const positiveDistance = Math.max(0, raceDistance ?? 0);
+  const lapIndex = Math.min(
+    Math.floor(positiveDistance / track.length),
+    Math.max(0, totalLaps - 1),
+  );
+  const lapProgress = positiveDistance >= track.length * totalLaps
+    ? track.length
+    : positiveDistance - lapIndex * track.length;
+  const sectorLength = getSectorLength(track);
+  const sectorIndex = Math.min(TELEMETRY_SECTOR_COUNT - 1, Math.floor(lapProgress / sectorLength));
+  const sectorStart = sectorIndex * sectorLength;
+
+  return {
+    completedLaps: Math.floor(positiveDistance / track.length),
+    currentLap: Math.max(1, lapIndex + 1),
+    currentSector: sectorIndex + 1,
+    currentSectorProgress: clamp((lapProgress - sectorStart) / sectorLength, 0, 1),
+  };
+}
+
+function createSectorProgress(position, currentSectors = null) {
+  const activeIndex = clamp((position.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
+  return createEmptySectorTimes().map((_, index) => {
+    if (index < activeIndex && Number.isFinite(currentSectors?.[index])) return 1;
+    if (index === activeIndex) return clamp(position.currentSectorProgress ?? 0, 0, 1);
+    return 0;
+  });
+}
+
+export function createLapTelemetry(track, currentTime = 0, raceDistance = 0, totalLaps = Infinity) {
+  const position = getLapTelemetryPosition(track, raceDistance, totalLaps);
+  return {
+    ...position,
+    currentLapStartedAt: currentTime,
+    currentSectorStartedAt: currentTime,
+    lastUpdatedAt: currentTime,
+    currentLapTime: 0,
+    currentSectorElapsed: 0,
+    currentSectors: createEmptySectorTimes(),
+    sectorProgress: createSectorProgress(position),
+    liveSectors: createEmptySectorTimes(),
+    lastLapTime: null,
+    bestLapTime: null,
+    lastSectors: createEmptySectorTimes(),
+    bestSectors: createEmptySectorTimes(),
+    sectorPerformance: createEmptySectorPerformance(),
+  };
+}
+
+export function resetLapTelemetry(car, currentTime, track, totalLaps) {
+  car.lapTelemetry = createLapTelemetry(track, currentTime, car.raceDistance, totalLaps);
+}
+
+export function serializeLapTelemetry(telemetry) {
+  return {
+    currentLap: telemetry.currentLap,
+    currentSector: telemetry.currentSector,
+    currentLapTime: finiteOrNull(telemetry.currentLapTime),
+    currentSectorElapsed: finiteOrNull(telemetry.currentSectorElapsed),
+    currentSectorProgress: finiteOrNull(telemetry.currentSectorProgress),
+    currentSectors: serializeSectorTimes(telemetry.currentSectors),
+    sectorProgress: serializeSectorTimes(telemetry.sectorProgress),
+    liveSectors: serializeSectorTimes(telemetry.liveSectors),
+    lastSectors: serializeSectorTimes(telemetry.lastSectors),
+    bestSectors: serializeSectorTimes(telemetry.bestSectors),
+    lastLapTime: finiteOrNull(telemetry.lastLapTime),
+    bestLapTime: finiteOrNull(telemetry.bestLapTime),
+    sectorPerformance: {
+      current: serializeSectorPerformance(telemetry.sectorPerformance?.current),
+      last: serializeSectorPerformance(telemetry.sectorPerformance?.last),
+      best: serializeSectorPerformance(telemetry.sectorPerformance?.best),
+    },
+    completedLaps: telemetry.completedLaps,
+  };
+}
+
+export function updateLapTelemetry(car, previousRaceDistance, currentTime, track, totalLaps) {
+  if (!car.lapTelemetry) resetLapTelemetry(car, currentTime, track, totalLaps);
+  const telemetry = car.lapTelemetry;
+  const currentRaceDistance = car.raceDistance ?? 0;
+  const previousDistance = Math.max(0, previousRaceDistance ?? currentRaceDistance);
+  const currentDistance = Math.max(0, currentRaceDistance);
+  const travelled = currentDistance - previousDistance;
+  const previousUpdateTime = Number.isFinite(telemetry.lastUpdatedAt) ? telemetry.lastUpdatedAt : currentTime;
+  const elapsedTime = Math.max(0, currentTime - previousUpdateTime);
+
+  if (!Number.isFinite(previousDistance) || !Number.isFinite(currentDistance) || travelled < -1e-3 || travelled > track.length / 2) {
+    resetLapTelemetry(car, currentTime, track, totalLaps);
+    return;
+  }
+
+  const sectorLength = getSectorLength(track);
+  if (travelled > 1e-6) {
+    const firstBoundary = Math.floor(previousDistance / sectorLength) + 1;
+    const lastBoundary = Math.floor(currentDistance / sectorLength);
+
+    for (let boundary = firstBoundary; boundary <= lastBoundary; boundary += 1) {
+      const boundaryDistance = boundary * sectorLength;
+      if (boundaryDistance <= previousDistance + 1e-3 || boundaryDistance > currentDistance + 1e-3) continue;
+
+      const boundaryRatio = clamp((boundaryDistance - previousDistance) / travelled, 0, 1);
+      const crossingTime = previousUpdateTime + boundaryRatio * elapsedTime;
+      const sectorIndex = (boundary - 1) % TELEMETRY_SECTOR_COUNT;
+      const sectorTime = Math.max(0, crossingTime - telemetry.currentSectorStartedAt);
+
+      telemetry.currentSectors[sectorIndex] = sectorTime;
+      updateBestSector(telemetry, sectorIndex, sectorTime);
+
+      if (sectorIndex === TELEMETRY_SECTOR_COUNT - 1) {
+        const lapTime = Math.max(0, crossingTime - telemetry.currentLapStartedAt);
+        telemetry.lastLapTime = lapTime;
+        telemetry.bestLapTime = Number.isFinite(telemetry.bestLapTime)
+          ? Math.min(telemetry.bestLapTime, lapTime)
+          : lapTime;
+        telemetry.lastSectors = serializeSectorTimes(telemetry.currentSectors);
+        telemetry.currentSectors = createEmptySectorTimes();
+        telemetry.currentLapStartedAt = crossingTime;
+        telemetry.completedLaps = Math.max(telemetry.completedLaps + 1, Math.min(Math.floor(boundaryDistance / track.length), totalLaps));
+      }
+
+      telemetry.currentSectorStartedAt = crossingTime;
+    }
+  }
+
+  syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps);
+  telemetry.lastUpdatedAt = currentTime;
+}
+
+function updateBestSector(telemetry, sectorIndex, sectorTime) {
+  const previousBest = telemetry.bestSectors[sectorIndex];
+  if (!Number.isFinite(previousBest) || sectorTime < previousBest) {
+    telemetry.bestSectors[sectorIndex] = sectorTime;
+  }
+}
+
+function clearFutureSectorTelemetry(telemetry) {
+  const activeIndex = clamp((telemetry.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
+  for (let index = activeIndex; index < TELEMETRY_SECTOR_COUNT; index += 1) {
+    telemetry.currentSectors[index] = null;
+  }
+}
+
+function syncLiveSectorTelemetry(telemetry) {
+  const activeIndex = clamp((telemetry.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
+
+  telemetry.liveSectors = createEmptySectorTimes();
+  telemetry.currentSectors.forEach((time, index) => {
+    if (index >= activeIndex) return;
+    if (!Number.isFinite(time)) return;
+    telemetry.liveSectors[index] = time;
+  });
+  telemetry.liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+}
+
+function syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps) {
+  const position = getLapTelemetryPosition(track, currentRaceDistance, totalLaps);
+  telemetry.completedLaps = position.completedLaps;
+  telemetry.currentLap = position.currentLap;
+  telemetry.currentSector = position.currentSector;
+  telemetry.currentSectorProgress = position.currentSectorProgress;
+  clearFutureSectorTelemetry(telemetry);
+  telemetry.sectorProgress = createSectorProgress(position, telemetry.currentSectors);
+  telemetry.completedLaps = Math.max(telemetry.completedLaps, Math.min(position.completedLaps, totalLaps));
+  telemetry.currentLapTime = Math.max(0, currentTime - telemetry.currentLapStartedAt);
+  telemetry.currentSectorElapsed = Math.max(0, currentTime - telemetry.currentSectorStartedAt);
+  syncLiveSectorTelemetry(telemetry);
+}

package/src/simulation/timing/raceTiming.js

@@ -0,0 +1,15 @@
+export {
+  createLapTelemetry,
+  resetLapTelemetry,
+  serializeLapTelemetry,
+  updateLapTelemetry,
+} from './lapTelemetry.js';
+export { estimateGapAheadSeconds, estimateTimingLineGapSeconds, wholeLapGap } from './gapEstimation.js';
+export { createEmptySectorPerformance, createEmptySectorTimes, updateSectorPerformance } from './sectorPerformance.js';
+export { recordTimingSample, resetTimingHistory, trimTimingHistory } from './timingHistory.js';
+export {
+  createTimingLines,
+  getTimingLineNumber,
+  recordTimingLineCrossings,
+  resetTimingLineCrossings,
+} from './timingLines.js';

package/src/simulation/timing/sectorPerformance.js

@@ -0,0 +1,60 @@
+import { TELEMETRY_SECTOR_COUNT } from './timingConstants.js';
+
+export function createEmptySectorTimes() {
+  return Array.from({ length: TELEMETRY_SECTOR_COUNT }, () => null);
+}
+
+export function createEmptySectorPerformance() {
+  return {
+    current: createEmptySectorTimes(),
+    last: createEmptySectorTimes(),
+    best: createEmptySectorTimes(),
+  };
+}
+
+export function serializeSectorTimes(values) {
+  return createEmptySectorTimes().map((_, index) => finiteOrNull(values?.[index]));
+}
+
+export function serializeSectorPerformance(values) {
+  return createEmptySectorTimes().map((_, index) => values?.[index] ?? null);
+}
+
+export function updateSectorPerformance(cars) {
+  const overallBestSectors = createEmptySectorTimes();
+  cars.forEach((car) => {
+    car.lapTelemetry?.bestSectors?.forEach((value, index) => {
+      if (!Number.isFinite(value)) return;
+      const previousBest = overallBestSectors[index];
+      if (!Number.isFinite(previousBest) || value < previousBest) overallBestSectors[index] = value;
+    });
+  });
+  cars.forEach((car) => {
+    const telemetry = car.lapTelemetry;
+    if (!telemetry) return;
+    telemetry.sectorPerformance = {
+      current: telemetry.currentSectors.map((value, index) => classifySectorPerformance(
+        value,
+        telemetry.bestSectors[index],
+        overallBestSectors[index],
+      )),
+      last: telemetry.lastSectors.map((value, index) => classifySectorPerformance(
+        value,
+        telemetry.bestSectors[index],
+        overallBestSectors[index],
+      )),
+      best: telemetry.bestSectors.map((value, index) => classifySectorPerformance(value, value, overallBestSectors[index])),
+    };
+  });
+}
+
+export function finiteOrNull(value) {
+  return Number.isFinite(value) ? value : null;
+}
+
+function classifySectorPerformance(value, personalBest, overallBest) {
+  if (!Number.isFinite(value)) return null;
+  if (Number.isFinite(overallBest) && Math.abs(value - overallBest) <= 1e-6) return 'overall-best';
+  if (Number.isFinite(personalBest) && Math.abs(value - personalBest) <= 1e-6) return 'personal-best';
+  return 'slower';
+}

package/src/simulation/timing/timingConstants.js

@@ -0,0 +1,5 @@
+export const TELEMETRY_SECTOR_COUNT = 3;
+export const TIMING_HISTORY_WINDOW_SECONDS = 18;
+export const TIMING_HISTORY_MAX_SAMPLES = 720;
+export const TIMING_LINE_TARGET_SPACING_METERS = 175;
+export const TIMING_LINE_HISTORY_LAPS = 3;

package/src/simulation/timing/timingHistory.js

@@ -0,0 +1,46 @@
+import { TIMING_HISTORY_MAX_SAMPLES, TIMING_HISTORY_WINDOW_SECONDS } from './timingConstants.js';
+
+export function trimTimingHistory(history, currentTime) {
+  const cutoff = currentTime - TIMING_HISTORY_WINDOW_SECONDS;
+  while (history.length > 2 && (history[0].time < cutoff || history.length > TIMING_HISTORY_MAX_SAMPLES)) {
+    history.shift();
+  }
+}
+
+export function resetTimingHistory(car, currentTime) {
+  car.timingHistory = [{ time: currentTime, raceDistance: car.raceDistance }];
+}
+
+export function recordTimingSample(car, currentTime) {
+  if (!Number.isFinite(car.raceDistance)) return;
+  if (!Array.isArray(car.timingHistory)) {
+    resetTimingHistory(car, currentTime);
+    return;
+  }
+
+  const previous = car.timingHistory[car.timingHistory.length - 1];
+  if (
+    previous &&
+    Math.abs(previous.time - currentTime) <= 1e-6 &&
+    Math.abs(previous.raceDistance - car.raceDistance) <= 1e-3
+  ) {
+    return;
+  }
+
+  car.timingHistory.push({ time: currentTime, raceDistance: car.raceDistance });
+  trimTimingHistory(car.timingHistory, currentTime);
+}
+
+export function interpolateTimeAtDistance(history, targetDistance) {
+  if (!Array.isArray(history) || history.length < 2) return null;
+  for (let index = history.length - 1; index > 0; index -= 1) {
+    const current = history[index];
+    const previous = history[index - 1];
+    if (targetDistance < previous.raceDistance || targetDistance > current.raceDistance) continue;
+    const coveredDistance = current.raceDistance - previous.raceDistance;
+    if (coveredDistance <= 1e-6) return current.time;
+    const ratio = (targetDistance - previous.raceDistance) / coveredDistance;
+    return previous.time + (current.time - previous.time) * ratio;
+  }
+  return null;
+}

package/src/simulation/timing/timingLines.js

@@ -0,0 +1,79 @@
+import { clamp } from '../simMath.js';
+import { metersToSimUnits, simUnitsToMeters } from '../units.js';
+import { pointAt } from '../track/trackModel.js';
+import { TIMING_LINE_HISTORY_LAPS, TIMING_LINE_TARGET_SPACING_METERS } from './timingConstants.js';
+
+export function createTimingLines(track) {
+  const targetSpacing = metersToSimUnits(TIMING_LINE_TARGET_SPACING_METERS);
+  const count = Math.max(1, Math.round(track.length / targetSpacing));
+  const spacing = track.length / count;
+  return {
+    spacing,
+    spacingMeters: simUnitsToMeters(spacing),
+    count,
+    lines: Array.from({ length: count }, (_, index) => {
+      const distance = index * spacing;
+      const point = pointAt(track, distance);
+      return {
+        index,
+        distance,
+        distanceMeters: simUnitsToMeters(distance),
+        x: point.x,
+        y: point.y,
+        heading: point.heading,
+      };
+    }),
+  };
+}
+
+export function getTimingLineNumber(track, raceDistance) {
+  const spacing = track.timingLines?.spacing;
+  if (!Number.isFinite(spacing) || spacing <= 0 || !Number.isFinite(raceDistance)) return null;
+  return Math.floor(Math.max(0, raceDistance) / spacing);
+}
+
+export function resetTimingLineCrossings(car, currentTime) {
+  car.timingLineCrossings = Object.create(null);
+  car.timingLineLastUpdatedAt = currentTime;
+  car.previousRaceDistanceForTiming = car.raceDistance;
+}
+
+export function recordTimingLineCrossings(car, previousRaceDistance, currentTime, track) {
+  const spacing = track.timingLines?.spacing;
+  if (!Number.isFinite(spacing) || spacing <= 0 || !Number.isFinite(car.raceDistance)) return;
+  if (!car.timingLineCrossings || typeof car.timingLineCrossings !== 'object') {
+    resetTimingLineCrossings(car, currentTime);
+    return;
+  }
+
+  const previousDistance = Number.isFinite(previousRaceDistance) ? previousRaceDistance : car.raceDistance;
+  const currentDistance = car.raceDistance;
+  const travelled = currentDistance - previousDistance;
+  const previousTime = Number.isFinite(car.timingLineLastUpdatedAt) ? car.timingLineLastUpdatedAt : currentTime;
+  const elapsed = Math.max(0, currentTime - previousTime);
+
+  if (travelled > 1e-6 && travelled < track.length / 2) {
+    const firstLine = Math.floor(Math.max(0, previousDistance) / spacing) + 1;
+    const lastLine = Math.floor(Math.max(0, currentDistance) / spacing);
+    for (let lineNumber = firstLine; lineNumber <= lastLine; lineNumber += 1) {
+      const lineDistance = lineNumber * spacing;
+      if (lineDistance <= previousDistance + 1e-6 || lineDistance > currentDistance + 1e-6) continue;
+      const ratio = clamp((lineDistance - previousDistance) / travelled, 0, 1);
+      car.timingLineCrossings[lineNumber] = previousTime + ratio * elapsed;
+    }
+  }
+
+  car.timingLineLastUpdatedAt = currentTime;
+  const latestLine = getTimingLineNumber(track, currentDistance);
+  if (latestLine != null) {
+    const cutoff = latestLine - (track.timingLines.count * TIMING_LINE_HISTORY_LAPS);
+    Object.keys(car.timingLineCrossings).forEach((key) => {
+      if (Number(key) < cutoff) delete car.timingLineCrossings[key];
+    });
+  }
+}
+
+export function getTimingLineCrossingTime(car, lineNumber) {
+  const value = car?.timingLineCrossings?.[lineNumber];
+  return Number.isFinite(value) ? value : null;
+}

package/src/simulation/track/centerlineSpline.js

@@ -0,0 +1,59 @@
+import { distance } from './trackMath.js';
+import { CENTERLINE_CONTROLS } from './trackConstants.js';
+
+export function uniformCatmullRom(p0, p1, p2, p3, t) {
+  const t2 = t * t;
+  const t3 = t2 * t;
+  return {
+    x: 0.5 * (
+      (2 * p1.x) +
+      (-p0.x + p2.x) * t +
+      (2 * p0.x - 5 * p1.x + 4 * p2.x - p3.x) * t2 +
+      (-p0.x + 3 * p1.x - 3 * p2.x + p3.x) * t3
+    ),
+    y: 0.5 * (
+      (2 * p1.y) +
+      (-p0.y + p2.y) * t +
+      (2 * p0.y - 5 * p1.y + 4 * p2.y - p3.y) * t2 +
+      (-p0.y + 3 * p1.y - 3 * p2.y + p3.y) * t3
+    ),
+  };
+}
+
+export function centripetalCatmullRom(p0, p1, p2, p3, t) {
+  const t0 = 0;
+  const t1 = t0 + Math.sqrt(Math.max(distance(p0, p1), 0.001));
+  const t2 = t1 + Math.sqrt(Math.max(distance(p1, p2), 0.001));
+  const t3 = t2 + Math.sqrt(Math.max(distance(p2, p3), 0.001));
+  const localT = t1 + (t2 - t1) * t;
+
+  const interpolate = (a, b, start, end) => {
+    const span = Math.max(end - start, 0.001);
+    const amount = (localT - start) / span;
+    return {
+      x: a.x + (b.x - a.x) * amount,
+      y: a.y + (b.y - a.y) * amount,
+    };
+  };
+
+  const a1 = interpolate(p0, p1, t0, t1);
+  const a2 = interpolate(p1, p2, t1, t2);
+  const a3 = interpolate(p2, p3, t2, t3);
+  const b1 = interpolate(a1, a2, t0, t2);
+  const b2 = interpolate(a2, a3, t1, t3);
+  return interpolate(b1, b2, t1, t2);
+}
+
+export function rawCenterPoint(ratio, controls = CENTERLINE_CONTROLS, interpolation = 'uniform') {
+  const count = controls.length;
+  const scaled = ratio * count;
+  const index = Math.floor(scaled) % count;
+  const localT = scaled - Math.floor(scaled);
+  const p0 = controls[(index - 1 + count) % count];
+  const p1 = controls[index];
+  const p2 = controls[(index + 1) % count];
+  const p3 = controls[(index + 2) % count];
+  return interpolation === 'centripetal'
+    ? centripetalCatmullRom(p0, p1, p2, p3, localT)
+    : uniformCatmullRom(p0, p1, p2, p3, localT);
+}

package/src/simulation/track/drsZones.js

@@ -0,0 +1,67 @@
+import { wrapDistance } from '../simMath.js';
+
+export function normalizeDrsZone(zone, totalLength) {
+  if (Number.isFinite(zone.start) && Number.isFinite(zone.end)) return zone;
+  const start = zone.startRatio * totalLength;
+  const rawEnd = zone.endRatio * totalLength;
+  return {
+    ...zone,
+    start,
+    end: rawEnd >= start ? rawEnd : rawEnd + totalLength,
+  };
+}
+
+export function scoreStraightWindow(samples, startIndex, windowSize) {
+  let curvature = 0;
+  for (let offset = 0; offset < windowSize; offset += 1) {
+    curvature += samples[(startIndex + offset) % (samples.length - 1)].curvature;
+  }
+  return curvature / windowSize;
+}
+
+export function deriveDrsZones(samples, totalLength) {
+  const usableSampleCount = samples.length - 1;
+  const windowSize = Math.max(96, Math.floor(usableSampleCount * 0.07));
+  const candidates = [];
+
+  for (let index = 0; index < usableSampleCount; index += Math.floor(windowSize / 2)) {
+    const start = samples[index];
+    const end = samples[(index + windowSize) % usableSampleCount];
+    const distance = end.distance >= start.distance
+      ? end.distance - start.distance
+      : totalLength - start.distance + end.distance;
+    if (distance < 360) continue;
+    candidates.push({
+      startRatio: start.distance / totalLength,
+      endRatio: (start.distance + Math.min(distance, totalLength * 0.16)) / totalLength,
+      score: scoreStraightWindow(samples, index, windowSize),
+    });
+  }
+
+  return candidates
+    .sort((a, b) => a.score - b.score)
+    .reduce((zones, candidate) => {
+      const farEnough = zones.every((zone) => Math.abs(zone.startRatio - candidate.startRatio) > 0.18);
+      if (farEnough && zones.length < 3) {
+        zones.push({
+          id: `generated-drs-${zones.length + 1}`,
+          startRatio: candidate.startRatio % 1,
+          endRatio: candidate.endRatio % 1,
+        });
+      }
+      return zones;
+    }, [])
+    .sort((a, b) => a.startRatio - b.startRatio);
+}
+
+export function isInDrsZone(track, progress) {
+  const wrapped = wrapDistance(progress, track.length);
+  return track.drsZones.some((zone) => {
+    const start = wrapDistance(zone.start, track.length);
+    const end = wrapDistance(zone.end, track.length);
+    if (zone.end - zone.start >= track.length) return true;
+    return end >= start
+      ? wrapped >= start && wrapped <= end
+      : wrapped >= start || wrapped <= end;
+  });
+}

package/src/simulation/track/pitLaneAccess.js

@@ -0,0 +1,103 @@
+import { clamp, wrapDistance } from '../simMath.js';
+import { PIT_ACCESS_MAX_LENGTH, PIT_ACCESS_SAMPLE_STEPS, PIT_ACCESS_SEARCH_STEP, PIT_ACCESS_TRACK_OVERLAP, PIT_LANE_WIDTH } from './trackConstants.js';
+import { angleBetweenVectors, headingVector, normalizeVector, sampleCubicBezier, signedLateralOffsetToPoint } from './trackMath.js';
+import { offsetTrackPoint, pointAt } from './spatialQueries.js';
+
+export function createPitAccessRoadCenterline(start, end, startForward, endForward, tangentLength) {
+  return sampleCubicBezier(
+    start,
+    {
+      x: start.x + startForward.x * tangentLength,
+      y: start.y + startForward.y * tangentLength,
+    },
+    {
+      x: end.x - endForward.x * tangentLength,
+      y: end.y - endForward.y * tangentLength,
+    },
+    end,
+    PIT_ACCESS_SAMPLE_STEPS,
+  );
+}
+
+export function createLaneFacingTrackConnection(track, distanceFromStart, lanePoint) {
+  const trackPoint = pointAt(track, distanceFromStart);
+  const laneSide = signedLateralOffsetToPoint(trackPoint, lanePoint) >= 0 ? 1 : -1;
+  const edgePoint = offsetTrackPoint(trackPoint, laneSide * (track.width / 2));
+  const trackConnectPoint = offsetTrackPoint(
+    trackPoint,
+    laneSide * Math.max(0, track.width / 2 - PIT_ACCESS_TRACK_OVERLAP),
+  );
+
+  return {
+    distanceFromStart,
+    trackDistance: wrapDistance(trackPoint.distance, track.length),
+    trackPoint,
+    edgePoint,
+    trackConnectPoint,
+    laneSide,
+  };
+}
+
+export function scorePitAccessConnection(track, connection, lanePoint, laneForward, direction) {
+  const roadVector = direction === 'entry'
+    ? normalizeVector({
+      x: lanePoint.x - connection.trackConnectPoint.x,
+      y: lanePoint.y - connection.trackConnectPoint.y,
+    })
+    : normalizeVector({
+      x: connection.trackConnectPoint.x - lanePoint.x,
+      y: connection.trackConnectPoint.y - lanePoint.y,
+    });
+  const trackForward = headingVector(connection.trackPoint.heading);
+  const trackAngle = angleBetweenVectors(roadVector, trackForward);
+  const laneAngle = angleBetweenVectors(roadVector, laneForward);
+  const laneFacingClearance = Math.abs(signedLateralOffsetToPoint(connection.trackPoint, lanePoint)) - track.width / 2;
+
+  return {
+    ...connection,
+    roadVector,
+    trackAngle,
+    laneAngle,
+    pathLength: roadVector.length,
+    score:
+      trackAngle * 1100 +
+      laneAngle * 900 +
+      roadVector.length * 0.32 -
+      Math.max(0, laneFacingClearance) * 0.18,
+  };
+}
+
+export function findPitAccessConnection(track, lanePoint, laneForward, {
+  direction,
+  startDistance,
+  endDistance,
+  fallbackDistance,
+}) {
+  const start = Math.min(startDistance, endDistance);
+  const end = Math.max(startDistance, endDistance);
+  let best = null;
+  let fallback = null;
+
+  for (let distanceFromStart = start; distanceFromStart <= end; distanceFromStart += PIT_ACCESS_SEARCH_STEP) {
+    const connection = scorePitAccessConnection(
+      track,
+      createLaneFacingTrackConnection(track, distanceFromStart, lanePoint),
+      lanePoint,
+      laneForward,
+      direction,
+    );
+    fallback = !fallback || connection.score < fallback.score ? connection : fallback;
+    if (connection.trackAngle > 1.15 || connection.laneAngle > 1.15) continue;
+    best = !best || connection.score < best.score ? connection : best;
+  }
+
+  if (best) return best;
+
+  return fallback ?? scorePitAccessConnection(
+    track,
+    createLaneFacingTrackConnection(track, fallbackDistance, lanePoint),
+    lanePoint,
+    laneForward,
+    direction,
+  );
+}