@inventure71/paddockjs 3.0.0 → 4.1.0

package/src/simulation/track/trackQueryPitIndex.js

@@ -1,6 +1,9 @@
 import { createSpatialGrid, insertIdIntoGridBounds, candidateIdsFromGrid } from './trackQueryGrid.js';
 import { recordFallback, recordStat } from './trackQueryStats.js';
 
+const PIT_ROAD_GRID_NEIGHBOR_LIMIT = 1;
+const PIT_ROAD_ENDPOINT_SEGMENT_COUNT = 4;
+
 export function createPitQueryIndex(track, cellSize) {
   const pitLane = track.pitLane;
   if (!pitLane?.enabled) return null;
@@ -21,7 +24,11 @@ export function createPitQueryIndex(track, cellSize) {
     ['working', pitLane.workingLane?.points],
     ['exit', pitLane.exit?.roadCenterline],
   ].forEach(([routeId, points]) => {
-    routes[routeId] = { start: roadSegments.length };
+    routes[routeId] = {
+      start: roadSegments.length,
+      cumulativeDistances: createRouteCumulativeDistances(points),
+      ...createRouteEndpointSegmentWindows(points),
+    };
     indexPitRoute(roadGrid, roadSegments, routeId, points, cellSize);
     routes[routeId].end = roadSegments.length;
   });
@@ -50,7 +57,7 @@ export function createPitQueryIndex(track, cellSize) {
   };
 }
 
-export function queryPitBoxCandidates(track, position) {
+export function queryPitBoxCandidates(track, position, scratch = null) {
   const index = track?.queryIndex;
   const pit = index?.pit;
   if (!pit?.boxGrid) {
@@ -65,18 +72,36 @@ export function queryPitBoxCandidates(track, position) {
   const ids = candidateIdsFromGrid(index, pit.boxGrid, position, 1);
   if (!ids.length) {
     recordStat(index, 'pitPaths', 'box-grid-miss');
+    if (scratch) {
+      const empty = scratch.pitBoxCandidates ?? [];
+      scratch.pitBoxCandidates = empty;
+      empty.length = 0;
+      return empty;
+    }
     return [];
   }
   recordStat(index, 'pitPaths', 'box-grid-hit');
-  return ids.map((id) => pit.boxCandidates[id]).filter(Boolean);
+  const candidates = scratch ? (scratch.pitBoxCandidates ??= []) : [];
+  candidates.length = 0;
+  ids.forEach((id) => {
+    const candidate = pit.boxCandidates[id];
+    if (candidate) candidates.push(candidate);
+  });
+  return scratch ? candidates : [...candidates];
 }
 
-export function queryPitRoadSegmentCandidates(track, routeId, position) {
-  const candidatesByRoute = queryPitRoadSegmentCandidatesByRoute(track, position);
+export function queryPitRoadSegmentCandidates(track, routeId, position, scratch = null) {
+  const candidatesByRoute = queryPitRoadSegmentCandidatesByRoute(track, position, null, scratch);
   return candidatesByRoute?.[routeId] ?? candidatesByRoute;
 }
 
-export function queryPitRoadSegmentCandidatesByRoute(track, position) {
+export function queryPitRoadSegmentCandidatesByRoute(
+  track,
+  position,
+  progressHintOrScratch = null,
+  scratchArg = null,
+  options = {},
+) {
   const index = track?.queryIndex;
   const pit = index?.pit;
   if (!pit?.roadGrid) {
@@ -87,22 +112,87 @@ export function queryPitRoadSegmentCandidatesByRoute(track, position) {
     recordFallback(index, 'pitFallbackReasons', 'invalid-position');
     return null;
   }
-  index.stats.pitQueries += 1;
-  const ids = candidateIdsFromGrid(index, pit.roadGrid, position, 1);
-  if (!ids.length) {
-    recordStat(index, 'pitPaths', 'road-grid-miss');
-    return null;
-  }
-  const candidatesByRoute = { entry: [], main: [], working: [], exit: [] };
+  const progressHint = Number.isFinite(progressHintOrScratch)
+    ? progressHintOrScratch
+    : null;
+  const scratch = progressHint === null && scratchArg == null && progressHintOrScratch && typeof progressHintOrScratch === 'object'
+    ? progressHintOrScratch
+    : scratchArg;
+  if (options.countQuery !== false) index.stats.pitQueries += 1;
+  const ids = candidateIdsFromGrid(index, pit.roadGrid, position, PIT_ROAD_GRID_NEIGHBOR_LIMIT);
+  const candidatesByRoute = scratch
+    ? (scratch.pitRouteCandidates ??= { entry: [], main: [], working: [], exit: [] })
+    : { entry: [], main: [], working: [], exit: [] };
+  candidatesByRoute.entry.length = 0;
+  candidatesByRoute.main.length = 0;
+  candidatesByRoute.working.length = 0;
+  candidatesByRoute.exit.length = 0;
   ids.forEach((id) => {
     const segment = pit.roadSegments[id];
     if (!segment || !candidatesByRoute[segment.routeId]) return;
     candidatesByRoute[segment.routeId].push(segment.segmentIndex);
   });
-  recordStat(index, 'pitPaths', 'road-grid-hit');
+  const recordPathStats = options.recordPathStats !== false;
+  const endpointAugmented = appendEndpointSegmentsForProgress(track, candidatesByRoute, progressHint);
+  const hasAnyCandidates = (
+    candidatesByRoute.entry.length +
+    candidatesByRoute.main.length +
+    candidatesByRoute.working.length +
+    candidatesByRoute.exit.length
+  ) > 0;
+  if (!hasAnyCandidates) {
+    if (recordPathStats) recordStat(index, 'pitPaths', 'road-grid-miss');
+    return null;
+  }
+  if (recordPathStats) recordStat(index, 'pitPaths', ids.length ? 'road-grid-hit' : 'road-grid-endpoint-hit');
+  if (recordPathStats && endpointAugmented) {
+    recordStat(index, 'pitPaths', 'road-endpoint-window-hit');
+  }
   return candidatesByRoute;
 }
 
+function appendEndpointSegmentsForProgress(track, candidatesByRoute, progressHint) {
+  if (!Number.isFinite(progressHint)) return false;
+  const pit = track?.queryIndex?.pit;
+  const pitLane = track?.pitLane;
+  if (!pit?.routes || !pitLane?.enabled) return false;
+  let augmented = false;
+  if (progressHint >= pitLane.entry.trackDistance) {
+    augmented = appendRouteEndpointSegments(
+      candidatesByRoute.entry,
+      pit.routes.entry,
+      'start',
+    ) || augmented;
+  }
+  if (progressHint <= pitLane.exit.trackDistance) {
+    augmented = appendRouteEndpointSegments(
+      candidatesByRoute.exit,
+      pit.routes.exit,
+      'end',
+    ) || augmented;
+  }
+  return augmented;
+}
+
+function appendRouteEndpointSegments(target, route, edge) {
+  if (!Array.isArray(target) || !route) return false;
+  const beforeLength = target.length;
+  if (edge === 'start') {
+    const limit = Math.min(route.end, route.start + PIT_ROAD_ENDPOINT_SEGMENT_COUNT);
+    for (let id = route.start; id < limit; id += 1) {
+      const segmentIndex = id - route.start;
+      if (!target.includes(segmentIndex)) target.push(segmentIndex);
+    }
+  } else {
+    const limit = Math.max(route.start, route.end - PIT_ROAD_ENDPOINT_SEGMENT_COUNT);
+    for (let id = limit; id < route.end; id += 1) {
+      const segmentIndex = id - route.start;
+      if (!target.includes(segmentIndex)) target.push(segmentIndex);
+    }
+  }
+  return target.length > beforeLength;
+}
+
 function indexPitRoute(grid, roadSegments, routeId, points, expansion) {
   if (!Array.isArray(points) || points.length < 2) return;
   for (let index = 0; index < points.length - 1; index += 1) {
@@ -120,6 +210,40 @@ function indexPitRoute(grid, roadSegments, routeId, points, expansion) {
   }
 }
 
+function createRouteCumulativeDistances(points) {
+  if (!Array.isArray(points) || points.length === 0) return null;
+  const distances = new Array(points.length);
+  distances[0] = 0;
+  for (let index = 1; index < points.length; index += 1) {
+    const previous = points[index - 1];
+    const current = points[index];
+    distances[index] = distances[index - 1] + Math.hypot(current.x - previous.x, current.y - previous.y);
+  }
+  return distances;
+}
+
+function createRouteEndpointSegmentWindows(points) {
+  const segmentCount = Array.isArray(points) ? Math.max(0, points.length - 1) : 0;
+  const startSegmentWindow = [];
+  const endSegmentWindow = [];
+  const endpointSegmentWindow = [];
+  const startLimit = Math.min(segmentCount, PIT_ROAD_ENDPOINT_SEGMENT_COUNT);
+  const endStart = Math.max(0, segmentCount - PIT_ROAD_ENDPOINT_SEGMENT_COUNT);
+  for (let index = 0; index < startLimit; index += 1) {
+    startSegmentWindow.push(index);
+    endpointSegmentWindow.push(index);
+  }
+  for (let index = endStart; index < segmentCount; index += 1) {
+    endSegmentWindow.push(index);
+    if (!endpointSegmentWindow.includes(index)) endpointSegmentWindow.push(index);
+  }
+  return {
+    startSegmentWindow,
+    endSegmentWindow,
+    endpointSegmentWindow,
+  };
+}
+
 function polygonBounds(polygon, expansion) {
   const bounds = polygon.reduce((current, point) => ({
     minX: Math.min(current.minX, point.x),

package/src/simulation/track/trackQueryScratch.js

@@ -18,7 +18,14 @@ export function createQueryScratch(index) {
     rayCellEpoch: 1,
     raySegmentIds: [],
     rayVisitedCells: [],
+    rayTracePoint: { x: 0, y: 0 },
     rayTraceCache: new Map(),
+    hintDistanceCacheDistance: Number.NaN,
+    hintDistanceCacheWrappedDistance: Number.NaN,
+    hintDistanceCacheSegmentId: -1,
+    hintDistanceCachePointX: Number.NaN,
+    hintDistanceCachePointY: Number.NaN,
+    segmentNeighborhoodProjection: {},
   };
 }
 

package/src/simulation/track/trackQueryStats.js

@@ -2,12 +2,37 @@ export function createQueryStats() {
   return {
     nearestQueries: 0,
     nearestFallbacks: 0,
+    hintDistanceCacheHits: 0,
+    precomputedSegmentNeighborhoodHits: 0,
+    nearestEmptyCellSkippedRings: 0,
+    nearestIsolatedHintQueries: 0,
+    nearestLowDensityHintQueries: 0,
+    nearestLowDensityCellExactQueries: 0,
+    nearestLowDensityCellDirectQueries: 0,
+    nearestSparseGridExactQueries: 0,
+    nearestRing2NeighborhoodExactQueries: 0,
+    arcBucketRadius2PrecomputedQueries: 0,
     nearestPaths: {},
     nearestFallbackReasons: {
       'spatial-grid-no-candidates': 0,
     },
+    hintedArcQueries: 0,
+    hintedSegmentFastPathQueries: 0,
+    hintedSegmentWideRadiusQueries: 0,
+    hintedSegmentWideRadiusHits: 0,
+    candidateProjectionObjectAllocations: 0,
+    raySegmentObjectAllocations: 0,
+    rayTraceCacheEntryAllocations: 0,
+    hintedArcPaths: {},
+    segmentNeighborhoodQueries: 0,
+    segmentNeighborhoodBatchCalls: 0,
+    segmentNeighborhoodPaths: {},
+    runoffRadius1Queries: 0,
+    runoffRadius2Queries: 0,
     pitQueries: 0,
     pitFallbacks: 0,
+    pitConnectorEndpointWindowProjectionCalls: 0,
+    pitConnectorFullRouteProjectionScans: 0,
     pitPaths: {},
     pitFallbackReasons: {},
   };

package/src/simulation/track/trackSnapshotJson.js

@@ -0,0 +1,139 @@
+const TRACK_JSON_CACHE = new WeakMap();
+const MAX_JSON_SAMPLES = 320;
+const TRACK_SAMPLE_SCHEMA = Object.freeze([
+  'x',
+  'y',
+  'distance',
+  'heading',
+  'normalX',
+  'normalY',
+  'curvature',
+]);
+
+const OMIT_JSON_KEYS = new Set([
+  'bounds',
+  'boxBounds',
+  'connectorBounds',
+  'pitCrew',
+]);
+
+const HIGH_PRECISION_JSON_KEYS = new Set([
+  'heading',
+  'normalX',
+  'normalY',
+  'curvature',
+  'startRatio',
+  'endRatio',
+]);
+
+export function attachTrackSnapshotJsonSerializer(track) {
+  if (!track || typeof track !== 'object') return track;
+  Object.defineProperty(track, 'toJSON', {
+    configurable: true,
+    enumerable: false,
+    value: trackSnapshotToJson,
+    writable: false,
+  });
+  return track;
+}
+
+export function serializeTrackSnapshotJson(track) {
+  if (!track || typeof track !== 'object') return track;
+  const cached = TRACK_JSON_CACHE.get(track);
+  if (cached) return cached;
+  const serialized = cloneTrackJsonValue(track);
+  TRACK_JSON_CACHE.set(track, serialized);
+  return serialized;
+}
+
+function trackSnapshotToJson() {
+  return serializeTrackSnapshotJson(this);
+}
+
+function cloneTrackJsonValue(value, key = null) {
+  if (typeof value === 'number') return roundTrackJsonNumber(key, value);
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) {
+    if (key === 'samples') return cloneTrackSamples(value);
+    return value.map((entry) => cloneTrackJsonValue(entry));
+  }
+  if (key === 'pitLane') return clonePitLaneJson(value);
+
+  const clone = {};
+  Object.entries(value).forEach(([childKey, childValue]) => {
+    if (OMIT_JSON_KEYS.has(childKey)) return;
+    clone[childKey] = cloneTrackJsonValue(childValue, childKey);
+  });
+  if (key == null && Array.isArray(clone.samples)) clone.sampleSchema = TRACK_SAMPLE_SCHEMA;
+  return clone;
+}
+
+function cloneTrackSamples(samples) {
+  if (samples.length <= MAX_JSON_SAMPLES) {
+    return samples.map((entry) => serializeTrackSample(entry));
+  }
+  const lastIndex = samples.length - 1;
+  const stride = Math.max(1, Math.ceil(lastIndex / (MAX_JSON_SAMPLES - 1)));
+  const decimated = [];
+  for (let index = 0; index < lastIndex; index += stride) {
+    decimated.push(serializeTrackSample(samples[index]));
+  }
+  const lastSample = serializeTrackSample(samples[lastIndex]);
+  if (!decimated.length || decimated[decimated.length - 1]?.[2] !== lastSample?.[2]) {
+    decimated.push(lastSample);
+  }
+  return decimated;
+}
+
+function serializeTrackSample(sample) {
+  return [
+    roundTrackJsonNumber('x', sample?.x),
+    roundTrackJsonNumber('y', sample?.y),
+    roundTrackJsonNumber('distance', sample?.distance),
+    roundTrackJsonNumber('heading', sample?.heading),
+    roundTrackJsonNumber('normalX', sample?.normalX),
+    roundTrackJsonNumber('normalY', sample?.normalY),
+    roundTrackJsonNumber('curvature', sample?.curvature),
+  ];
+}
+
+function clonePitLaneJson(pitLane) {
+  const clone = {};
+  Object.entries(pitLane).forEach(([childKey, childValue]) => {
+    if (OMIT_JSON_KEYS.has(childKey)) return;
+    if (childKey === 'boxes') {
+      clone.boxes = childValue.map(clonePitBoxJson);
+      return;
+    }
+    if (childKey === 'serviceAreas') {
+      clone.serviceAreas = childValue.map(clonePitServiceAreaJson);
+      return;
+    }
+    clone[childKey] = cloneTrackJsonValue(childValue, childKey);
+  });
+  return clone;
+}
+
+function clonePitBoxJson(box) {
+  const clone = {};
+  Object.entries(box).forEach(([childKey, childValue]) => {
+    if (childKey === 'teamId' || childKey === 'teamName' || childKey === 'teamColor') return;
+    clone[childKey] = cloneTrackJsonValue(childValue, childKey);
+  });
+  return clone;
+}
+
+function clonePitServiceAreaJson(area) {
+  const clone = {};
+  Object.entries(area).forEach(([childKey, childValue]) => {
+    if (childKey === 'teamId' || childKey === 'teamName' || childKey === 'teamColor') return;
+    clone[childKey] = cloneTrackJsonValue(childValue, childKey);
+  });
+  return clone;
+}
+
+function roundTrackJsonNumber(key, value) {
+  if (!Number.isFinite(value)) return value;
+  const precision = HIGH_PRECISION_JSON_KEYS.has(key) ? 1_000_000 : 1_000;
+  return Math.round(value * precision) / precision;
+}

package/src/simulation/track/trackStatePolicy.js

@@ -1,4 +1,18 @@
-import { nearestTrackState } from './trackModel.js';
+import { metersToSimUnits } from '../units.js';
+import { pointInsideBounds } from './trackMath.js';
+import { nearestTrackState, resolveTrackStatePitOverride, writeTrackState } from './spatialQueries.js';
+import { nearestPitLaneState } from './pitLaneState.js';
+import {
+  queryHintedTrackProjection,
+  querySegmentNeighborhoodProjection,
+  querySegmentNeighborhoodProjections,
+} from './trackQueryIndex.js';
+
+const LOCAL_SEGMENT_RADIUS = 3;
+const RUNOFF_FAST_PATH_LOCAL_SEGMENT_RADIUS = 2;
+const RUNOFF_FAST_PATH_SMALL_MOTION_RADIUS = 1;
+const RUNOFF_FAST_PATH_SMALL_MOTION_LIMIT = metersToSimUnits(1.1);
+const RUNOFF_FAST_PATH_TELEPORT_LIMIT = metersToSimUnits(80);
 
 export function pitOverrideAllowedForCar(car) {
   if (!car?.environmentControlled) return true;
@@ -21,3 +35,237 @@ export function nearestTrackStateForCar(
     allowPitOverride: resolvedAllowPitOverride,
   });
 }
+
+export function queryHintedTrackStateForCar(
+  track,
+  car,
+  position = car,
+  progressHint = car?.progress ?? null,
+  options = {},
+) {
+  const resolvedAllowPitOverride = options.allowPitOverride ?? pitOverrideAllowedForCar(car);
+  const projection = queryHintedTrackProjection(track, position, progressHint, {
+    radius: options.radius ?? 2,
+  });
+  if (!projection) {
+    return nearestTrackState(track, position, progressHint, {
+      ...options,
+      allowPitOverride: resolvedAllowPitOverride,
+    });
+  }
+  const trackState = writeTrackState(options.target ?? {}, track, position, projection);
+  if (!resolvedAllowPitOverride) return trackState;
+  return resolveTrackStatePitOverride(track, trackState, nearestPitLaneState(track, position, progressHint));
+}
+
+export function queryLocalSegmentTrackStateForCar(
+  track,
+  car,
+  position = car,
+  baseSegmentId = car?.trackState?.segmentId ?? null,
+  progressHint = car?.progress ?? null,
+  options = {},
+) {
+  const resolvedAllowPitOverride = options.allowPitOverride ?? pitOverrideAllowedForCar(car);
+  const indexScratch = track?.queryIndex?.queryScratch;
+  const projectionTarget = options.targetProjection ?? (
+    indexScratch
+      ? (indexScratch.segmentNeighborhoodProjection ??= {})
+      : {}
+  );
+  const projection = querySegmentNeighborhoodProjection(track, position, baseSegmentId, {
+    radius: options.radius ?? LOCAL_SEGMENT_RADIUS,
+    preferredDistance: progressHint,
+    target: projectionTarget,
+  });
+  if (!projection) {
+    return queryHintedTrackStateForCar(track, car, position, progressHint, options);
+  }
+  const trackState = writeTrackState(options.target ?? {}, track, position, projection);
+  return finalizeTrackState(track, position, progressHint, trackState, resolvedAllowPitOverride, options);
+}
+
+export function queryLocalSegmentTrackStatesForCar(
+  track,
+  car,
+  positions,
+  baseSegmentId = car?.trackState?.segmentId ?? null,
+  progressHint = car?.progress ?? null,
+  options = {},
+) {
+  const resolvedAllowPitOverride = options.allowPitOverride ?? pitOverrideAllowedForCar(car);
+  const targets = Array.isArray(options.target) ? options.target : new Array(positions.length);
+  const projections = queryLocalSegmentTrackProjectionsForCar(
+    track,
+    car,
+    positions,
+    baseSegmentId,
+    progressHint,
+    options,
+  );
+  if (!projections) {
+    for (let index = 0; index < positions.length; index += 1) {
+      targets[index] = queryHintedTrackStateForCar(track, car, positions[index], progressHint, options);
+    }
+    return targets;
+  }
+  return writeLocalSegmentTrackStatesFromProjections(
+    track,
+    positions,
+    progressHint,
+    projections,
+    {
+      ...options,
+      allowPitOverride: resolvedAllowPitOverride,
+      target: targets,
+    },
+  );
+}
+
+export function queryLocalSegmentTrackProjectionsForCar(
+  track,
+  car,
+  positions,
+  baseSegmentId = car?.trackState?.segmentId ?? null,
+  progressHint = car?.progress ?? null,
+  options = {},
+) {
+  if (!Number.isInteger(baseSegmentId)) return null;
+  return querySegmentNeighborhoodProjections(track, positions, baseSegmentId, {
+    radius: options.radius ?? LOCAL_SEGMENT_RADIUS,
+    preferredDistance: progressHint,
+    target: options.projections,
+  });
+}
+
+export function writeLocalSegmentTrackStatesFromProjections(
+  track,
+  positions,
+  progressHint,
+  projections,
+  options = {},
+) {
+  if (!Array.isArray(projections)) return null;
+  const allowPitOverride = options.allowPitOverride !== false;
+  const targets = Array.isArray(options.target) ? options.target : new Array(positions.length);
+  for (let index = 0; index < positions.length; index += 1) {
+    const projection = projections[index];
+    if (!projection) {
+      targets[index] = null;
+      continue;
+    }
+    const trackState = writeTrackState(targets[index] ?? {}, track, positions[index], projection);
+    targets[index] = finalizeTrackState(track, positions[index], progressHint, trackState, allowPitOverride, options);
+  }
+  return targets;
+}
+
+export function queryRunoffTrackStateForCar(track, car, position = car) {
+  const allowPitOverride = pitOverrideAllowedForCar(car);
+  const previousState = car?.trackState;
+  const progressHint = car?.progress ?? previousState?.distance ?? null;
+  const scratch = car?.runoffTrackStateScratch ?? {
+    mainTrackState: {},
+    result: {
+      state: null,
+      mainTrackState: null,
+      usedFastPathProjection: false,
+    },
+  };
+  if (car && car.runoffTrackStateScratch == null) car.runoffTrackStateScratch = scratch;
+  const canUseHintedMainTrack = Number.isFinite(previousState?.distance) &&
+    !previousState?.inPitLane &&
+    !runoffMotionLooksLikeTeleport(car) &&
+    !runoffProgressJumpLooksLikeTeleport(track, previousState, progressHint) &&
+    (!allowPitOverride || !pitOverrideMayApply(track, position, previousState));
+
+  if (canUseHintedMainTrack) {
+    const localRadius = runoffFastPathLocalSegmentRadius(car);
+    const mainTrackState = queryLocalSegmentTrackStateForCar(track, car, position, previousState.segmentId, previousState.distance, {
+      allowPitOverride: false,
+      radius: localRadius,
+      target: scratch.mainTrackState,
+    });
+    recordRunoffRadiusUsage(track, localRadius);
+    scratch.result.state = mainTrackState;
+    scratch.result.mainTrackState = mainTrackState;
+    scratch.result.usedFastPathProjection = true;
+    return scratch.result;
+  }
+
+  const state = nearestTrackState(track, position, progressHint, { allowPitOverride });
+  const mainTrackState = state.inPitLane
+    ? nearestTrackState(track, position, progressHint, { allowPitOverride: false })
+    : state;
+  scratch.result.state = state;
+  scratch.result.mainTrackState = mainTrackState;
+  scratch.result.usedFastPathProjection = false;
+  return scratch.result;
+}
+
+function pitOverrideMayApply(track, position, previousState) {
+  const pitLane = track?.pitLane;
+  if (!pitLane || !previousState) return false;
+  const signedOffset = previousState.signedOffset ?? 0;
+  const mainRoadEdge = track.width / 2 + (track.kerbWidth ?? 0);
+  if (Math.abs(signedOffset) <= mainRoadEdge) return false;
+  if (signedOffset * pitLane.side <= 0) return false;
+  const connectorBounds = pitLane.connectorBounds;
+  return Boolean(
+    connectorBounds && (
+      (connectorBounds.entry && pointInsideBounds(position, connectorBounds.entry)) ||
+      (connectorBounds.exit && pointInsideBounds(position, connectorBounds.exit))
+    ),
+  );
+}
+
+function runoffMotionLooksLikeTeleport(car) {
+  return runoffMotionDistance(car) > RUNOFF_FAST_PATH_TELEPORT_LIMIT;
+}
+
+function runoffProgressJumpLooksLikeTeleport(track, previousState, progressHint) {
+  if (!Number.isFinite(previousState?.distance) || !Number.isFinite(progressHint)) return true;
+  const trackLength = track?.length;
+  if (!Number.isFinite(trackLength) || trackLength <= 0) {
+    return Math.abs(progressHint - previousState.distance) > RUNOFF_FAST_PATH_TELEPORT_LIMIT;
+  }
+  const delta = Math.abs(progressHint - previousState.distance);
+  return Math.min(delta, trackLength - delta) > RUNOFF_FAST_PATH_TELEPORT_LIMIT;
+}
+
+function runoffFastPathLocalSegmentRadius(car) {
+  return runoffMotionDistance(car) <= RUNOFF_FAST_PATH_SMALL_MOTION_LIMIT
+    ? RUNOFF_FAST_PATH_SMALL_MOTION_RADIUS
+    : RUNOFF_FAST_PATH_LOCAL_SEGMENT_RADIUS;
+}
+
+function recordRunoffRadiusUsage(track, radius) {
+  const stats = track?.queryIndex?.stats;
+  if (!stats) return;
+  if (radius <= RUNOFF_FAST_PATH_SMALL_MOTION_RADIUS) {
+    stats.runoffRadius1Queries = (stats.runoffRadius1Queries ?? 0) + 1;
+    return;
+  }
+  stats.runoffRadius2Queries = (stats.runoffRadius2Queries ?? 0) + 1;
+}
+
+function finalizeTrackState(track, position, progressHint, trackState, allowPitOverride, options) {
+  if (!allowPitOverride) return trackState;
+  if (options.skipPitOverrideInsideMainRoad) {
+    const mainRoadEdge = track.width / 2 + (track.kerbWidth ?? 0);
+    if (trackState.crossTrackError <= mainRoadEdge) return trackState;
+  }
+  return resolveTrackStatePitOverride(track, trackState, nearestPitLaneState(track, position, progressHint));
+}
+
+function runoffMotionDistance(car) {
+  if (
+    !Number.isFinite(car?.previousX) ||
+    !Number.isFinite(car?.previousY) ||
+    !Number.isFinite(car?.x) ||
+    !Number.isFinite(car?.y)
+  ) return 0;
+  const dx = car.x - car.previousX;
+  const dy = car.y - car.previousY;
+  return Math.hypot(dx, dy);
+}