@inventure71/paddockjs 2.0.0 → 2.0.1

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,36 +43,47 @@ export function estimateSurfaceHits(
     return misses;
   }
 
-  const originState = context?.originState ?? nearestRayTrackState(snapshot.track, car, origin, car.progress);
-  const indexedHits = estimateIndexedSurfaceHits({
-    car,
-    track: snapshot.track,
-    ray,
-    origin,
-    vector,
-    requested,
-    originState,
-    sharedRayQuery,
-  });
-  if (indexedHits) return { ...misses, ...indexedHits };
-  const analyticHits = estimateAnalyticSurfaceHits({
-    car,
-    track: snapshot.track,
-    ray,
-    vector,
-    requested,
-    originState,
-  });
-  if (analyticHits) return { ...misses, ...analyticHits };
+  const originState = context?.precision === precision
+    ? context.originState
+    : nearestRayTrackState(snapshot.track, car, origin, car.progress, precision);
+  const originHits = surfaceHitsAtOrigin(requested, originState);
+  if (!usesSampledDriverContract(car, precision)) {
+    const indexedHits = estimateIndexedSurfaceHits({
+      car,
+      track: snapshot.track,
+      ray,
+      origin,
+      vector,
+      requested,
+      originState,
+      precision,
+      sharedRayQuery,
+    });
+    if (indexedHits) return { ...misses, ...indexedHits, ...originHits };
+    const analyticHits = estimateAnalyticSurfaceHits({
+      car,
+      track: snapshot.track,
+      ray,
+      vector,
+      requested,
+      originState,
+    });
+    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 +104,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,7 +162,7 @@ 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;
@@ -168,9 +192,23 @@ function estimateIndexedSurfaceHits({ car, track, ray, origin, vector, requested
       ? minFinite(boundaries.trackEdgeDistance, boundaries.kerbOuterDistance)
       : boundaries.kerbOuterDistance;
     if (boundaryDistance == null) return null;
+    const hitDistance = precision === 'debug' || usesMainTrackOnlyRays(car)
+      ? 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 +218,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,15 +341,19 @@ function matchesSurfaceChannel(channel, state) {
   return false;
 }
 
-function nearestRayTrackState(track, car, point, progressHint) {
+function nearestRayTrackState(track, car, point, progressHint, precision = 'debug') {
   const useBatchTrainingIndexMode = usesMainTrackOnlyRays(car);
   return nearestTrackState(track, point, progressHint, {
     allowPitOverride: pitOverrideAllowedForCar(car),
-    indexMode: useBatchTrainingIndexMode ? 'sample' : undefined,
+    indexMode: usesSampledDriverContract(car, precision) ? 'legacy' : useBatchTrainingIndexMode ? 'sample' : undefined,
     hintMaxDistance: useBatchTrainingIndexMode ? Infinity : undefined,
   });
 }
 
+function usesSampledDriverContract(car, precision) {
+  return precision === 'driver' && !usesMainTrackOnlyRays(car);
+}
+
 function minFinite(...values) {
   const minimum = Math.min(...values.filter((value) => Number.isFinite(value)));
   return Number.isFinite(minimum) ? minimum : null;

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,19 +39,36 @@ 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,
-    track: snapshot.track,
-    origin,
-    originState,
-    ray,
-    lengthMeters,
-    includePitLane,
-    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;
+  if (!usesSampledDriverContract(car, precision)) {
+    const indexedHit = estimateIndexedTrackHit({
+      car,
+      track: snapshot.track,
+      origin,
+      originState,
+      ray,
+      lengthMeters,
+      includePitLane,
+      precision,
+      sharedRayQuery,
+    });
+    if (indexedHit) return indexedHit;
+  }
   const analyticHit = estimateAnalyticMainTrackHit({
     car,
     track: snapshot.track,
@@ -65,7 +83,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 +104,7 @@ export function estimateTrackHit(
         kind,
         includePitLane,
         refineStepsForPrecision(precision),
+        precision,
       );
       return {
         hit: true,
@@ -138,7 +157,16 @@ 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;
@@ -154,10 +182,25 @@ function estimateIndexedTrackHit({ car, track, origin, originState, ray, lengthM
   );
   if (!boundaries.available) return null;
   if (boundaries.trackEdgeDistance == null) return null;
+  const kind = inside ? 'exit' : 'entry';
+  const hitDistance = 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 +266,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,15 +286,19 @@ function refineTrackTransitionDistance(
   return high;
 }
 
-function nearestRayTrackState(track, car, point, progressHint) {
+function nearestRayTrackState(track, car, point, progressHint, precision = 'debug') {
   const useBatchTrainingIndexMode = usesMainTrackOnlyRays(car);
   return nearestTrackState(track, point, progressHint, {
     allowPitOverride: pitOverrideAllowedForCar(car),
-    indexMode: useBatchTrainingIndexMode ? 'sample' : undefined,
+    indexMode: usesSampledDriverContract(car, precision) ? 'legacy' : useBatchTrainingIndexMode ? 'sample' : undefined,
     hintMaxDistance: useBatchTrainingIndexMode ? Infinity : undefined,
   });
 }
 
+function usesSampledDriverContract(car, precision) {
+  return precision === 'driver' && !usesMainTrackOnlyRays(car);
+}
+
 function refineStepsForPrecision(precision) {
   return precision === 'debug' ? TRACK_RAY_REFINE_STEPS : DRIVER_RAY_REFINE_STEPS;
 }
@@ -259,3 +307,118 @@ function isInsideTrackBorder(state, track, includePitLane = true) {
   if (includePitLane && state.inPitLane) return true;
   return state.crossTrackError <= track.width / 2;
 }
+
+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 && usesMainTrackOnlyRays(car)) return distance;
+  if (refineSteps <= 0) {
+    return sampledIndexedTransitionDistance({
+      track,
+      car,
+      origin,
+      ray,
+      progressHint,
+      distance,
+      maxDistance,
+      kind,
+      includePitLane,
+    });
+  }
+
+  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),
+    indexMode: 'legacy',
+  });
+  return isInsideTrackBorder(state, track, includePitLane);
+}