@inventure71/paddockjs 2.0.0 → 3.0.0

package/src/environment/scenarios.js

@@ -182,7 +182,9 @@ export function applyEnvironmentPlacements(sim, track, carsById, placements = {}
   Object.entries(placements).forEach(([driverId, placement]) => {
     const currentCar = carsById.get(driverId);
     if (!currentCar) return;
-    states[driverId] = placementToCarState(track, currentCar, placement);
+    states[driverId] = placementToCarState(track, currentCar, placement, {
+      physicsMode: sim.physicsMode,
+    });
   });
   if (typeof sim.setCarStates === 'function') {
     sim.setCarStates(states);
@@ -193,13 +195,14 @@ export function applyEnvironmentPlacements(sim, track, carsById, placements = {}
   });
 }
 
-function placementToCarState(track, currentCar, placement) {
+function placementToCarState(track, currentCar, placement, { physicsMode = 'arcade' } = {}) {
   const currentDistanceMeters = currentCar.distanceMeters ?? simUnitsToMeters(currentCar.raceDistance ?? currentCar.progress ?? 0);
   const raceDistance = metersToSimUnits(Math.max(0, placement.distanceMeters ?? currentDistanceMeters));
   const offset = metersToSimUnits(placement.offsetMeters ?? 0);
   const base = pointAt(track, raceDistance);
   const position = offsetTrackPoint(base, offset);
   const heading = normalizeAngle(base.heading + (placement.headingErrorRadians ?? 0));
+  const speed = placement.speedKph == null ? null : kphToSimSpeed(placement.speedKph);
   const partial = {
     x: position.x,
     y: position.y,
@@ -217,11 +220,27 @@ function placementToCarState(track, currentCar, placement) {
     canAttack: true,
     throttle: 0,
     brake: 0,
+    longitudinalAcceleration: 0,
+    lateralAcceleration: 0,
+    lateralG: 0,
+    longitudinalG: 0,
+    gripUsage: 0,
+    slipAngleRadians: 0,
+    tractionLimited: false,
     steeringAngle: 0,
     yawRate: 0,
     stabilityState: 'stable',
   };
-  if (placement.speedKph != null) partial.speed = kphToSimSpeed(placement.speedKph);
+  if (speed != null) {
+    partial.speed = speed;
+    if (physicsMode === 'advanced') {
+      partial.velocityX = Math.cos(heading) * speed;
+      partial.velocityY = Math.sin(heading) * speed;
+    } else {
+      partial.velocityX = null;
+      partial.velocityY = null;
+    }
+  }
   return partial;
 }
 

package/src/environment/sensors/index.js

@@ -1,7 +1,7 @@
 import { createCarRayMiss, estimateCarHit } from './carRays.js';
 import { normalizeRayOptions } from './rayConfig.js';
 import { degreesToRadians, getCarRayOrigin } from './rayGeometry.js';
-import { rayDetectableTargetsForSnapshot } from './sensorTargets.js';
+import { isSelfCarTarget, rayDetectableTargetsForSnapshot } from './sensorTargets.js';
 import { createTrackMiss, createTrackRayContext, estimateTrackHit } from './trackRays.js';
 import { createSurfaceMiss, estimateSurfaceHits, requestedSurfaceChannels } from './surfaceRays.js';
 import { canUseBatchTrainingRayApproximation } from './rayGuards.js';
@@ -28,9 +28,9 @@ export function buildRaySensors(car, snapshot, rayOptions = {}, batchContext = n
     requestedSurfaceChannels(normalized.channels).length > 0;
   const trackContext = !usesTrackContext
     ? null
-    : createTrackRayContext(car, snapshot, origin);
+    : createTrackRayContext(car, snapshot, origin, normalized.precision);
   const carTargets = normalized.channels.includes('car')
-    ? (batchContext?.rayTargets ?? rayDetectableTargetsForSnapshot(snapshot)).filter((target) => target.id !== car.id)
+    ? (batchContext?.rayTargets ?? rayDetectableTargetsForSnapshot(snapshot)).filter((target) => !isSelfCarTarget(car, target))
     : [];
 
   if (canUseFastBatchTrainingRays(car, snapshot, trackContext)) {

package/src/environment/sensors/opponentRadar.js

@@ -3,12 +3,12 @@ import { VEHICLE_GEOMETRY } from '../../simulation/vehicle/vehicleGeometry.js';
 
 export function enrichOpponentRadar(car, nearbyCars, snapshot) {
   const targetsById = new Map([
-    ...(snapshot.cars ?? []).map((entry) => [entry.id, entry]),
-    ...(snapshot.replayGhosts ?? []).map((entry) => [entry.id, entry]),
+    ...(snapshot.cars ?? []).map((entry) => [targetKey('car', entry.id), entry]),
+    ...(snapshot.replayGhosts ?? []).map((entry) => [targetKey('replayGhost', entry.id), entry]),
   ]);
 
   return nearbyCars.map((nearby) => {
-    const target = targetsById.get(nearby.id);
+    const target = targetsById.get(targetKey(nearby.entityType ?? 'car', nearby.id));
     const derived = target ? deriveRadarFields(car, target, nearby) : fallbackRadarFields(nearby);
     return {
       ...nearby,
@@ -17,6 +17,10 @@ export function enrichOpponentRadar(car, nearbyCars, snapshot) {
   });
 }
 
+function targetKey(entityType, id) {
+  return `${entityType}:${id}`;
+}
+
 function deriveRadarFields(car, target, nearby) {
   const dx = (target.x ?? 0) - (car.x ?? 0);
   const dy = (target.y ?? 0) - (car.y ?? 0);
@@ -56,6 +60,12 @@ function fallbackRadarFields(nearby) {
 }
 
 function velocity(car) {
+  if (Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)) {
+    return {
+      x: car.velocityX,
+      y: car.velocityY,
+    };
+  }
   const speed = Number.isFinite(car.speed) ? car.speed : kphToSimSpeed(car.speedKph ?? 0);
   const heading = car.heading ?? car.headingRadians ?? 0;
   return {

package/src/environment/sensors/sensorTargets.js

@@ -7,11 +7,11 @@ export const SENSOR_TARGET_CAR = 'car';
 export const SENSOR_TARGET_REPLAY_GHOST = 'replayGhost';
 
 export function rayDetectableTargets(self, snapshot) {
-  return rayDetectableTargetsForSnapshot(snapshot).filter((target) => target.id !== self.id);
+  return rayDetectableTargetsForSnapshot(snapshot).filter((target) => !isSelfCarTarget(self, target));
 }
 
 export function nearbyDetectableTargets(self, snapshot) {
-  return nearbyDetectableTargetsForSnapshot(snapshot).filter((target) => target.id !== self.id);
+  return nearbyDetectableTargetsForSnapshot(snapshot).filter((target) => !isSelfCarTarget(self, target));
 }
 
 export function rayDetectableTargetsForSnapshot(snapshot) {
@@ -37,6 +37,8 @@ function detectableCars(snapshot, predicate) {
       x: car.x,
       y: car.y,
       heading: car.heading,
+      velocityX: car.velocityX,
+      velocityY: car.velocityY,
       speedKph: car.speedKph ?? 0,
       lap: car.lap,
       order,
@@ -58,3 +60,7 @@ function detectableReplayGhosts(snapshot, sensorFlag) {
       order: carCount + index,
     }));
 }
+
+export function isSelfCarTarget(self, target) {
+  return target.entityType === SENSOR_TARGET_CAR && target.id === self.id;
+}

package/src/environment/sensors/surfaceRays.js

@@ -43,7 +43,10 @@ export function estimateSurfaceHits(
     return misses;
   }
 
-  const originState = context?.originState ?? nearestRayTrackState(snapshot.track, car, origin, car.progress);
+  const originState = context?.precision === precision
+    ? context.originState
+    : nearestRayTrackState(snapshot.track, car, origin, car.progress, precision);
+  const originHits = surfaceHitsAtOrigin(requested, originState);
   const indexedHits = estimateIndexedSurfaceHits({
     car,
     track: snapshot.track,
@@ -52,9 +55,10 @@ export function estimateSurfaceHits(
     vector,
     requested,
     originState,
+    precision,
     sharedRayQuery,
   });
-  if (indexedHits) return { ...misses, ...indexedHits };
+  if (indexedHits) return { ...misses, ...indexedHits, ...originHits };
   const analyticHits = estimateAnalyticSurfaceHits({
     car,
     track: snapshot.track,
@@ -63,16 +67,21 @@ export function estimateSurfaceHits(
     requested,
     originState,
   });
-  if (analyticHits) return { ...misses, ...analyticHits };
+  if (analyticHits) return { ...misses, ...analyticHits, ...originHits };
 
   const pending = new Set(requested);
+  Object.keys(originHits).forEach((channel) => {
+    misses[channel] = originHits[channel];
+    pending.delete(channel);
+  });
+  if (pending.size === 0) return misses;
   const maxDistance = metersToSimUnits(ray.lengthMeters);
   const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
   let previousDistance = 0;
   let previousState = null;
 
   for (let distance = 0; distance <= maxDistance; distance += step) {
-    const state = nearestRayTrackState(snapshot.track, car, pointOnRay(origin, vector, distance), car.progress);
+    const state = nearestRayTrackState(snapshot.track, car, pointOnRay(origin, vector, distance), car.progress, precision);
     for (const channel of [...pending]) {
       if (!matchesSurfaceChannel(channel, state)) continue;
       const hitDistance = previousState
@@ -93,6 +102,19 @@ export function estimateSurfaceHits(
   return misses;
 }
 
+function surfaceHitsAtOrigin(requested, originState) {
+  const hits = {};
+  requested.forEach((channel) => {
+    if (!matchesSurfaceChannel(channel, originState)) return;
+    hits[channel] = {
+      hit: true,
+      distanceMeters: 0,
+      surface: originState.surface ?? null,
+    };
+  });
+  return hits;
+}
+
 function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, originState }) {
   if (!originState || car.inPitLane || originState.inPitLane) return null;
   if (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState)) return null;
@@ -138,10 +160,9 @@ function estimateAnalyticSurfaceHits({ car, track, ray, vector, requested, origi
   return hits;
 }
 
-function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested, originState, sharedRayQuery }) {
+function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested, originState, precision, sharedRayQuery }) {
   if (!originState || car.inPitLane || originState.inPitLane) return null;
   if (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState)) return null;
-  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return null;
 
   const trackHalfWidth = track.width / 2;
   const kerbOuter = trackHalfWidth + (track.kerbWidth ?? 0);
@@ -167,10 +188,32 @@ function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested
     const boundaryDistance = channel === 'kerb'
       ? minFinite(boundaries.trackEdgeDistance, boundaries.kerbOuterDistance)
       : boundaries.kerbOuterDistance;
-    if (boundaryDistance == null) return null;
+    if (boundaryDistance == null) {
+      if (usesMainTrackOnlyRays(car) && channel === 'illegalSurface') {
+        hits[channel] = createSurfaceMiss(ray.lengthMeters);
+        continue;
+      }
+      if (canSampleRecoverySurface(track, originState, vector)) return null;
+      hits[channel] = createSurfaceMiss(ray.lengthMeters);
+      continue;
+    }
+    const hitDistance = usesMainTrackOnlyRays(car) || refineStepsForPrecision(precision) <= 0 || precision === 'debug'
+      ? boundaryDistance
+      : sampledIndexedSurfaceDistance({
+        track,
+        car,
+        origin,
+        vector,
+        progressHint: car.progress,
+        distance: boundaryDistance,
+        maxDistance: metersToSimUnits(ray.lengthMeters),
+        channel,
+        precision,
+      });
+    if (hitDistance == null) return null;
     hits[channel] = {
       hit: true,
-      distanceMeters: simUnitsToMeters(boundaryDistance),
+      distanceMeters: simUnitsToMeters(hitDistance),
       surface: channel === 'kerb'
         ? 'kerb'
         : surfaceBeyondKerb(track, originState.signedOffset ?? 0, lateral, metersToSimUnits(ray.lengthMeters)),
@@ -180,6 +223,28 @@ function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested
   return hits;
 }
 
+function sampledIndexedSurfaceDistance({
+  track,
+  car,
+  origin,
+  vector,
+  progressHint,
+  distance,
+  maxDistance,
+  channel,
+  precision,
+}) {
+  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
+  const firstIndex = Math.max(0, Math.floor(Math.max(0, distance - step * 1.5) / step));
+  const lastIndex = Math.ceil(Math.min(maxDistance, distance + step * 8) / step);
+  for (let index = firstIndex; index <= lastIndex; index += 1) {
+    const sampleDistance = Math.min(maxDistance, index * step);
+    const state = nearestRayTrackState(track, car, pointOnRay(origin, vector, sampleDistance), progressHint, precision);
+    if (matchesSurfaceChannel(channel, state)) return sampleDistance;
+  }
+  return null;
+}
+
 function usesMainTrackOnlyRays(car) {
   return car?.interaction?.profile === 'batch-training';
 }
@@ -281,12 +346,19 @@ function matchesSurfaceChannel(channel, state) {
   return false;
 }
 
-function nearestRayTrackState(track, car, point, progressHint) {
-  const useBatchTrainingIndexMode = usesMainTrackOnlyRays(car);
+function canSampleRecoverySurface(track, originState, vector) {
+  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return false;
+  const kerbOuter = track.width / 2 + (track.kerbWidth ?? 0);
+  const offset = originState.signedOffset ?? 0;
+  if (Math.abs(offset) <= kerbOuter) return false;
+  const lateral = vector.x * originState.normalX + vector.y * originState.normalY;
+  if (Math.abs(lateral) < 0.05) return false;
+  return offset > 0 ? lateral < 0 : lateral > 0;
+}
+
+function nearestRayTrackState(track, car, point, progressHint, precision = 'debug') {
   return nearestTrackState(track, point, progressHint, {
     allowPitOverride: pitOverrideAllowedForCar(car),
-    indexMode: useBatchTrainingIndexMode ? 'sample' : undefined,
-    hintMaxDistance: useBatchTrainingIndexMode ? Infinity : undefined,
   });
 }
 

package/src/environment/sensors/trackRays.js

@@ -12,13 +12,14 @@ import { canUseIndexedRecoveryRayApproximation } from './rayGuards.js';
 import { degreesToRadians, getCarRayOrigin, getCarRayVector, pointOnRay } from './rayGeometry.js';
 import { findIndexedTrackBandBoundaries } from './indexedRayBands.js';
 
-export function createTrackRayContext(car, snapshot, origin) {
+export function createTrackRayContext(car, snapshot, origin, precision = 'debug') {
   if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
-    return { origin, originState: null };
+    return { origin, originState: null, precision };
   }
   return {
     origin,
-    originState: nearestRayTrackState(snapshot.track, car, origin, car.progress),
+    originState: nearestRayTrackState(snapshot.track, car, origin, car.progress, precision),
+    precision,
   };
 }
 
@@ -38,7 +39,9 @@ export function estimateTrackHit(
   const ray = getCarRayVector(car, angleDegrees);
   const maxDistance = metersToSimUnits(lengthMeters);
   const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
-  const originState = context?.originState ?? nearestRayTrackState(snapshot.track, car, origin, car.progress);
+  const originState = context?.precision === precision
+    ? context.originState
+    : nearestRayTrackState(snapshot.track, car, origin, car.progress, precision);
   const includePitLane = Boolean(car.inPitLane || car.pitLanePart || originState.inPitLane);
   const indexedHit = estimateIndexedTrackHit({
     car,
@@ -48,9 +51,22 @@ export function estimateTrackHit(
     ray,
     lengthMeters,
     includePitLane,
+    precision,
     sharedRayQuery,
   });
   if (indexedHit) return indexedHit;
+  const directionalAnalyticHit = canUseDirectionalAnalyticTrackHit({ car, track: snapshot.track, originState, ray, includePitLane })
+    ? estimateAnalyticMainTrackHit({
+      car,
+      track: snapshot.track,
+      origin,
+      originState,
+      ray,
+      lengthMeters,
+      includePitLane,
+    })
+    : null;
+  if (directionalAnalyticHit) return directionalAnalyticHit;
   const analyticHit = estimateAnalyticMainTrackHit({
     car,
     track: snapshot.track,
@@ -65,7 +81,7 @@ export function estimateTrackHit(
   let previousInside = null;
 
   for (let distance = 0; distance <= maxDistance; distance += step) {
-    const state = nearestRayTrackState(snapshot.track, car, pointOnRay(origin, ray, distance), car.progress);
+    const state = nearestRayTrackState(snapshot.track, car, pointOnRay(origin, ray, distance), car.progress, precision);
     const inside = isInsideTrackBorder(state, snapshot.track, includePitLane);
     if (previousInside == null) {
       previousInside = inside;
@@ -86,6 +102,7 @@ export function estimateTrackHit(
         kind,
         includePitLane,
         refineStepsForPrecision(precision),
+        precision,
       );
       return {
         hit: true,
@@ -138,9 +155,17 @@ function estimateAnalyticMainTrackHit({ car, track, origin, originState, ray, le
   };
 }
 
-function estimateIndexedTrackHit({ car, track, origin, originState, ray, lengthMeters, includePitLane, sharedRayQuery }) {
+function canUseDirectionalAnalyticTrackHit({ car, track, originState, ray, includePitLane }) {
+  if (includePitLane || (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState))) return false;
+  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return false;
+  if (Math.abs(originState.curvature ?? 0) > ANALYTIC_TRACK_RAY_MAX_CURVATURE) return false;
+
+  const lateral = ray.x * originState.normalX + ray.y * originState.normalY;
+  return Math.abs(lateral) >= 0.08;
+}
+
+function estimateIndexedTrackHit({ car, track, origin, originState, ray, lengthMeters, includePitLane, precision, sharedRayQuery }) {
   if (includePitLane || (!usesMainTrackOnlyRays(car) && isNearPitConnector(track, originState))) return null;
-  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return null;
   const trackHalfWidth = track.width / 2;
   const inside = Math.abs(originState.signedOffset ?? 0) <= trackHalfWidth;
   const boundaries = findIndexedTrackBandBoundaries(
@@ -153,11 +178,33 @@ function estimateIndexedTrackHit({ car, track, origin, originState, ray, lengthM
     sharedRayQuery,
   );
   if (!boundaries.available) return null;
-  if (boundaries.trackEdgeDistance == null) return null;
+  if (boundaries.trackEdgeDistance == null) {
+    if (usesMainTrackOnlyRays(car)) return createTrackMiss(lengthMeters);
+    return canSampleRecoveryTransition(track, originState, ray)
+      ? null
+      : createTrackMiss(lengthMeters);
+  }
+  const kind = inside ? 'exit' : 'entry';
+  const hitDistance = usesMainTrackOnlyRays(car)
+    ? boundaries.trackEdgeDistance
+    : validatedIndexedTransitionDistance({
+      track,
+      car,
+      origin,
+      ray,
+      progressHint: car.progress,
+      distance: boundaries.trackEdgeDistance,
+      maxDistance: metersToSimUnits(lengthMeters),
+      kind,
+      includePitLane,
+      precision,
+      originInside: inside,
+    });
+  if (hitDistance == null) return null;
   return {
     hit: true,
-    distanceMeters: simUnitsToMeters(boundaries.trackEdgeDistance),
-    kind: inside ? 'exit' : 'entry',
+    distanceMeters: simUnitsToMeters(hitDistance),
+    kind,
   };
 }
 
@@ -223,12 +270,13 @@ function refineTrackTransitionDistance(
   kind,
   includePitLane = true,
   refineSteps = TRACK_RAY_REFINE_STEPS,
+  precision = 'debug',
 ) {
   let low = lowDistance;
   let high = highDistance;
   for (let index = 0; index < refineSteps; index += 1) {
     const middle = (low + high) / 2;
-    const state = nearestRayTrackState(track, car, pointOnRay(origin, ray, middle), progressHint);
+    const state = nearestRayTrackState(track, car, pointOnRay(origin, ray, middle), progressHint, precision);
     const inside = isInsideTrackBorder(state, track, includePitLane);
     if (kind === 'entry') {
       if (inside) high = middle;
@@ -242,12 +290,9 @@ function refineTrackTransitionDistance(
   return high;
 }
 
-function nearestRayTrackState(track, car, point, progressHint) {
-  const useBatchTrainingIndexMode = usesMainTrackOnlyRays(car);
+function nearestRayTrackState(track, car, point, progressHint, precision = 'debug') {
   return nearestTrackState(track, point, progressHint, {
     allowPitOverride: pitOverrideAllowedForCar(car),
-    indexMode: useBatchTrainingIndexMode ? 'sample' : undefined,
-    hintMaxDistance: useBatchTrainingIndexMode ? Infinity : undefined,
   });
 }
 
@@ -259,3 +304,116 @@ function isInsideTrackBorder(state, track, includePitLane = true) {
   if (includePitLane && state.inPitLane) return true;
   return state.crossTrackError <= track.width / 2;
 }
+
+function canSampleRecoveryTransition(track, originState, ray) {
+  if (!canUseIndexedRecoveryRayApproximation(track, originState)) return false;
+  const trackHalfWidth = track.width / 2;
+  const offset = originState.signedOffset ?? 0;
+  if (Math.abs(offset) <= trackHalfWidth) return false;
+  const lateral = ray.x * originState.normalX + ray.y * originState.normalY;
+  if (Math.abs(lateral) < 0.05) return false;
+  return offset > 0 ? lateral < 0 : lateral > 0;
+}
+
+function validatedIndexedTransitionDistance({
+  track,
+  car,
+  origin,
+  ray,
+  progressHint,
+  distance,
+  maxDistance,
+  kind,
+  includePitLane,
+  precision = 'driver',
+  originInside = kind === 'exit',
+}) {
+  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
+  const refineSteps = refineStepsForPrecision(precision);
+  if (refineSteps <= 0) {
+    return distance;
+  }
+
+  const windows = [step * 1.5, step * 8];
+
+  for (const searchWindow of windows) {
+    const low = Math.max(0, distance - searchWindow);
+    const high = Math.min(maxDistance, distance + searchWindow);
+    if (high <= low) continue;
+    const previousInside = validatedInsideTrackBorder(track, car, origin, ray, low, progressHint, includePitLane);
+    const inside = validatedInsideTrackBorder(track, car, origin, ray, high, progressHint, includePitLane);
+    const matched = kind === 'entry'
+      ? !previousInside && inside
+      : previousInside && !inside;
+    if (matched) {
+      if (refineSteps <= 0) return distance;
+      return refineValidatedTransitionDistance(
+        track,
+        car,
+        origin,
+        ray,
+        progressHint,
+        low,
+        high,
+        kind,
+        includePitLane,
+        refineSteps,
+      );
+    }
+  }
+
+  return null;
+}
+
+function sampledIndexedTransitionDistance({
+  track,
+  car,
+  origin,
+  ray,
+  progressHint,
+  distance,
+  maxDistance,
+  kind,
+  includePitLane,
+}) {
+  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
+  const firstIndex = Math.max(1, Math.floor(Math.max(0, distance - step * 1.5) / step));
+  const lastIndex = Math.ceil(Math.min(maxDistance, distance + step * 8) / step);
+  for (let index = firstIndex; index <= lastIndex; index += 1) {
+    const high = Math.min(maxDistance, index * step);
+    const low = Math.max(0, high - step);
+    if (high <= low) continue;
+    const previousInside = validatedInsideTrackBorder(track, car, origin, ray, low, progressHint, includePitLane);
+    const inside = validatedInsideTrackBorder(track, car, origin, ray, high, progressHint, includePitLane);
+    const matched = kind === 'entry'
+      ? !previousInside && inside
+      : previousInside && !inside;
+    if (matched) return high;
+  }
+  return null;
+}
+
+function refineValidatedTransitionDistance(track, car, origin, ray, progressHint, lowDistance, highDistance, kind, includePitLane, refineSteps) {
+  let low = lowDistance;
+  let high = highDistance;
+  for (let index = 0; index < refineSteps; index += 1) {
+    const middle = (low + high) / 2;
+    const inside = validatedInsideTrackBorder(track, car, origin, ray, middle, progressHint, includePitLane);
+    if (kind === 'entry') {
+      if (inside) high = middle;
+      else low = middle;
+    } else if (inside) {
+      low = middle;
+    } else {
+      high = middle;
+    }
+  }
+  return high;
+}
+
+function validatedInsideTrackBorder(track, car, origin, ray, distance, progressHint, includePitLane) {
+  const state = nearestTrackState(track, pointOnRay(origin, ray, distance), progressHint, {
+    allowPitOverride: pitOverrideAllowedForCar(car),
+  });
+  return isInsideTrackBorder(state, track, includePitLane);
+}