@inventure71/paddockjs 3.0.0 → 4.0.0

package/src/simulation/rules/rulesReview.js

@@ -1,4 +1,4 @@
-import { calculateCollisionPenalties } from './collisionSteward.js';
+import { emitCollisionPenalties } from './collisionSteward.js';
 import { calculateTireRequirementPenalty } from './tireRequirementSteward.js';
 import { calculateTrackLimitReview } from './trackLimitsSteward.js';
 import { calculatePitLaneSpeedingReview } from './pitLaneSpeedingSteward.js';
@@ -6,25 +6,16 @@ import { getPenaltyRule } from '../rulesConfig.js';
 import { simSpeedToKph } from '../units.js';
 import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
 
-function forwardVector(car) {
-  return { x: Math.cos(car.heading), y: Math.sin(car.heading) };
+function velocityComponentX(car) {
+  return Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)
+    ? car.velocityX
+    : Math.cos(car.heading) * car.speed;
 }
 
-function velocityVector(car) {
-  if (Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)) {
-    return { x: car.velocityX, y: car.velocityY };
-  }
-  const forward = forwardVector(car);
-  return { x: forward.x * car.speed, y: forward.y * car.speed };
-}
-
-function dot(a, b) {
-  return a.x * b.x + a.y * b.y;
-}
-
-function normalizeVector(vector) {
-  const length = Math.hypot(vector.x, vector.y) || 1;
-  return { x: vector.x / length, y: vector.y / length };
+function velocityComponentY(car) {
+  return Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)
+    ? car.velocityY
+    : Math.sin(car.heading) * car.speed;
 }
 
 function progressDelta(a, b, trackLength) {
@@ -34,48 +25,62 @@ function progressDelta(a, b, trackLength) {
   return delta;
 }
 
-function createCollisionStewardContext(first, second, collision) {
-  const distanceDelta = collision.trackLength
-    ? progressDelta(second.progress ?? second.raceDistance ?? 0, first.progress ?? first.raceDistance ?? 0, collision.trackLength)
+function prepareCollisionStewardContext(scratch = null) {
+  const target = scratch
+    ? (scratch.collisionStewardContext ??= { sharedFaultDriverIds: [] })
+    : { sharedFaultDriverIds: [] };
+  target.sharedFaultDriverIds ??= [];
+  return target;
+}
+
+function writeCollisionFacts(target, collision, trackLength) {
+  target.depth = collision?.depth ?? 0;
+  target.trackLength = trackLength ?? collision?.trackLength ?? null;
+  target.firstShapeId = collision?.firstShapeId ?? null;
+  target.secondShapeId = collision?.secondShapeId ?? null;
+  target.contactType = collision?.contactType ?? null;
+  target.timeOfImpact = collision?.timeOfImpact ?? null;
+  target.swept = Boolean(collision?.swept);
+  target.axis = collision?.axis ?? null;
+  target.impactSpeed = 0;
+  target.aheadDriverId = null;
+  target.atFaultDriverId = null;
+  target.sharedFault = false;
+  target.sharedFaultDriverIds.length = 0;
+  return target;
+}
+
+function writeCollisionStewardContext(target, first, second, collision, trackLength = null) {
+  writeCollisionFacts(target, collision, trackLength);
+  const distanceDelta = target.trackLength
+    ? progressDelta(second.progress ?? second.raceDistance ?? 0, first.progress ?? first.raceDistance ?? 0, target.trackLength)
     : (second.raceDistance ?? 0) - (first.raceDistance ?? 0);
   const sideBySideTolerance = VEHICLE_LIMITS.carLength * 0.18;
   if (Math.abs(distanceDelta) <= sideBySideTolerance) {
-    const firstVelocity = velocityVector(first);
-    const secondVelocity = velocityVector(second);
-    const relativeVelocity = {
-      x: firstVelocity.x - secondVelocity.x,
-      y: firstVelocity.y - secondVelocity.y,
-    };
-    return {
-      ...collision,
-      impactSpeed: Math.hypot(relativeVelocity.x, relativeVelocity.y),
-      aheadDriverId: null,
-      atFaultDriverId: null,
-      sharedFault: true,
-      sharedFaultDriverIds: [first.id, second.id],
-    };
+    const relativeVelocityX = velocityComponentX(first) - velocityComponentX(second);
+    const relativeVelocityY = velocityComponentY(first) - velocityComponentY(second);
+    target.impactSpeed = Math.hypot(relativeVelocityX, relativeVelocityY);
+    target.sharedFault = true;
+    target.sharedFaultDriverIds[0] = first.id;
+    target.sharedFaultDriverIds[1] = second.id;
+    target.sharedFaultDriverIds.length = 2;
+    return target;
   }
 
   const firstBehind = distanceDelta > 0;
   const behind = firstBehind ? first : second;
   const ahead = firstBehind ? second : first;
-  const directionBehindToAhead = normalizeVector({
-    x: ahead.x - behind.x,
-    y: ahead.y - behind.y,
-  });
-  const behindVelocity = velocityVector(behind);
-  const aheadVelocity = velocityVector(ahead);
-  const relativeVelocity = {
-    x: behindVelocity.x - aheadVelocity.x,
-    y: behindVelocity.y - aheadVelocity.y,
-  };
-
-  return {
-    ...collision,
-    impactSpeed: Math.max(0, dot(relativeVelocity, directionBehindToAhead)),
-    aheadDriverId: ahead.id,
-    atFaultDriverId: behind.id,
-  };
+  const directionX = ahead.x - behind.x;
+  const directionY = ahead.y - behind.y;
+  const directionLength = Math.hypot(directionX, directionY) || 1;
+  const normalX = directionX / directionLength;
+  const normalY = directionY / directionLength;
+  const relativeVelocityX = velocityComponentX(behind) - velocityComponentX(ahead);
+  const relativeVelocityY = velocityComponentY(behind) - velocityComponentY(ahead);
+  target.impactSpeed = Math.max(0, relativeVelocityX * normalX + relativeVelocityY * normalY);
+  target.aheadDriverId = ahead.id;
+  target.atFaultDriverId = behind.id;
+  return target;
 }
 
 function isLegallyInsidePitLaneForTrackLimits(car) {
@@ -84,14 +89,30 @@ function isLegallyInsidePitLaneForTrackLimits(car) {
   return wheels.length > 0 && wheels.some((wheel) => wheel.inPitLane);
 }
 
-export function reviewCollisionForSimulation(sim, first, second, collision) {
+function recordPenaltyOnSimulation(penalty, sim) {
+  sim.recordPenalty(penalty);
+}
+
+export function reviewCollisionForSimulation(sim, first, second, collision, options = {}) {
   const rule = getPenaltyRule(sim.rules, 'collision');
-  calculateCollisionPenalties({
+  const stats = options.stats ?? sim.runtimeBenchmarkStats ?? null;
+  if (stats) stats.collisionStewardReviews = (stats.collisionStewardReviews ?? 0) + 1;
+  const context = writeCollisionStewardContext(
+    prepareCollisionStewardContext(options.scratch ?? null),
+    first,
+    second,
+    collision,
+    options.trackLength ?? null,
+  );
+  emitCollisionPenalties({
     first,
     second,
-    collision: createCollisionStewardContext(first, second, collision),
+    collision: context,
     rule,
-  }).forEach((penalty) => sim.recordPenalty(penalty));
+    emit: recordPenaltyOnSimulation,
+    emitContext: sim,
+  });
+  if (stats) stats.collisionStewardPenaltyArrayAllocations = stats.collisionStewardPenaltyArrayAllocations ?? 0;
 }
 
 export function reviewTireRequirementForSimulation(sim, car) {

package/src/simulation/snapshots/raceSnapshots.js

@@ -13,6 +13,7 @@ import {
   serializeCar,
   serializeObservationCar,
   serializeRenderCar,
+  serializeRenderCarInto,
   serializeTrainingCar,
 } from '../vehicle/vehicleSnapshots.js';
 import { createLapTelemetry, serializeLapTelemetry } from '../timing/raceTiming.js';
@@ -113,6 +114,33 @@ export function snapshotRaceRender(sim) {
   };
 }
 
+export function snapshotRaceRenderInto(sim, target = {}) {
+  const pitLaneStatus = pitLaneStatusSnapshot(sim.raceControl, sim.track.pitLane, sim.rules.modules?.pitStops);
+  const vehicleSnapshotDependencies = createVehicleSnapshotDependencies(sim);
+  target.time = sim.time;
+  target.world = WORLD;
+  target.physicsMode = sim.physicsMode;
+  target.track = sim.track;
+  target.totalLaps = sim.totalLaps;
+  target.raceControl ??= {};
+  target.raceControl.mode = sim.raceControl.mode;
+  target.raceControl.redFlag = Boolean(sim.raceControl.redFlag);
+  target.raceControl.pitLaneOpen = pitLaneStatus.open;
+  target.raceControl.pitLaneStatus = pitLaneStatus;
+  target.raceControl.finished = sim.raceControl.finished;
+  target.raceControl.start = visibleStartState(sim);
+  target.pitLaneStatus = pitLaneStatus;
+  target.safetyCar = Object.assign(target.safetyCar ?? {}, sim.safetyCar);
+  target.cars = renderCarsForSnapshotInto(
+    target.cars ?? [],
+    sim,
+    sim.orderedCars(),
+    vehicleSnapshotDependencies,
+  );
+  target.replayGhosts = serializeReplayGhosts(sim.replayGhosts);
+  return target;
+}
+
 export function snapshotRaceObservation(sim) {
   const pitLaneStatus = pitLaneStatusSnapshot(sim.raceControl, sim.track.pitLane, sim.rules.modules?.pitStops);
   const vehicleSnapshotDependencies = createVehicleSnapshotDependencies(sim);
@@ -191,3 +219,12 @@ function carsForSnapshot(sim, ordered) {
     .map((car) => ({ car, rank: affectsRaceOrder(car) ? (car.rank ?? null) : null }));
   return [...ranked, ...unranked];
 }
+
+function renderCarsForSnapshotInto(targetCars, sim, ordered, dependencies) {
+  const entries = carsForSnapshot(sim, ordered);
+  targetCars.length = entries.length;
+  entries.forEach(({ car }, index) => {
+    targetCars[index] = serializeRenderCarInto(targetCars[index] ?? {}, car, dependencies);
+  });
+  return targetCars;
+}

package/src/simulation/timing/drsTiming.js

@@ -25,63 +25,176 @@ function isProgressInZone(track, progress, zone) {
     : wrapped >= start || wrapped <= end;
 }
 
+function getZoneById(zones, zoneId) {
+  for (let index = 0; index < zones.length; index += 1) {
+    if (zones[index].id === zoneId) return zones[index];
+  }
+  return null;
+}
+
+function findNextDrsZoneIndex(track, progress) {
+  const zones = track?.drsZones ?? [];
+  if (!zones.length) return -1;
+  let bestIndex = -1;
+  let bestDistance = Infinity;
+  for (let index = 0; index < zones.length; index += 1) {
+    const distance = distanceForward(progress, zones[index].start, track.length);
+    if (distance <= 1e-6 || distance >= bestDistance) continue;
+    bestDistance = distance;
+    bestIndex = index;
+  }
+  return bestIndex >= 0 ? bestIndex : 0;
+}
+
+function resolveNextDrsZone(track, car, progress, runtimeBenchmarkStats = null) {
+  const zones = track?.drsZones ?? [];
+  if (!zones.length) {
+    car._drsNextZoneIndex = null;
+    return null;
+  }
+  const cachedIndex = car._drsNextZoneIndex;
+  if (Number.isInteger(cachedIndex) && cachedIndex >= 0 && cachedIndex < zones.length) {
+    if (runtimeBenchmarkStats) {
+      runtimeBenchmarkStats.drsNextZoneCacheHits = (runtimeBenchmarkStats.drsNextZoneCacheHits ?? 0) + 1;
+    }
+    return zones[cachedIndex];
+  }
+  const nextIndex = findNextDrsZoneIndex(track, progress);
+  car._drsNextZoneIndex = nextIndex;
+  if (runtimeBenchmarkStats) {
+    runtimeBenchmarkStats.drsNextZoneScans = (runtimeBenchmarkStats.drsNextZoneScans ?? 0) + 1;
+  }
+  return nextIndex >= 0 ? zones[nextIndex] : null;
+}
+
+function tryCachedDrsZoneNoCrossingFastPath(track, car, runtimeBenchmarkStats = null) {
+  const zones = track?.drsZones ?? [];
+  const cachedIndex = car._drsNextZoneIndex;
+  if (!Number.isInteger(cachedIndex) || cachedIndex < 0 || cachedIndex >= zones.length) return false;
+
+  const previousProgress = car.previousProgress ?? car.progress;
+  const travelled = car.progress - previousProgress;
+  if (travelled <= 0 || travelled > track.length / 2) return false;
+
+  const startOffset = zones[cachedIndex].start - previousProgress;
+  if (startOffset > 0 && startOffset <= travelled + 0.001) return false;
+
+  if (runtimeBenchmarkStats) {
+    runtimeBenchmarkStats.drsNextZoneCacheHits = (runtimeBenchmarkStats.drsNextZoneCacheHits ?? 0) + 1;
+    runtimeBenchmarkStats.drsNextZoneFastPathChecks = (runtimeBenchmarkStats.drsNextZoneFastPathChecks ?? 0) + 1;
+  }
+  return true;
+}
+
 export function recordDrsDetection(car, zoneId, currentTime) {
-  const previous = car.drsDetection?.[zoneId] ?? { passage: 0, time: -Infinity };
-  const next = { passage: previous.passage + 1, time: currentTime };
-  car.drsDetection = {
-    ...(car.drsDetection ?? {}),
-    [zoneId]: next,
-  };
+  const detections = car.drsDetection ?? (car.drsDetection = {});
+  const next = detections[zoneId] ?? { passage: 0, time: -Infinity };
+  next.passage += 1;
+  next.time = currentTime;
+  detections[zoneId] = next;
   return next;
 }
 
-export function updateDrsLatch(car, ahead, {
-  hasReference = Boolean(ahead),
-  safetyCarDeployed = false,
+function updateDrsLatchCore(
+  car,
+  ahead,
+  hasReference,
+  safetyCarDeployed,
   time,
   track,
   rules,
-} = {}) {
+  runtimeBenchmarkStats = null,
+) {
   if (safetyCarDeployed || car.finished) {
     car.drsEligible = false;
     car.drsActive = false;
     car.drsZoneId = null;
     car.drsZoneEnabled = false;
+    car._drsZoneRef = null;
     return;
   }
 
   const previousProgress = car.previousProgress ?? car.progress;
-  const currentZone = car.drsZoneId
-    ? track.drsZones.find((zone) => zone.id === car.drsZoneId)
-    : null;
+  const zones = track.drsZones;
+  let activeZone = null;
+  if (car.drsZoneId) {
+    activeZone = car._drsZoneRef?.id === car.drsZoneId ? car._drsZoneRef : null;
+    if (!activeZone) {
+      activeZone = getZoneById(zones, car.drsZoneId);
+      if (activeZone) car._drsZoneRef = activeZone;
+    }
+  }
 
-  if (currentZone && !isProgressInZone(track, car.progress, currentZone)) {
+  if (activeZone && !isProgressInZone(track, car.progress, activeZone)) {
     car.drsZoneId = null;
     car.drsZoneEnabled = false;
+    car._drsZoneRef = null;
+    activeZone = null;
   }
 
   if (!car.drsZoneId) {
-    const crossedZone = track.drsZones.find((zone) => (
-      crossesDistance(previousProgress, car.progress, zone.start, track.length)
-    ));
+    if (tryCachedDrsZoneNoCrossingFastPath(track, car, runtimeBenchmarkStats)) {
+      car.drsEligible = false;
+      car.drsActive = false;
+      return;
+    }
+    const crossedZone = resolveNextDrsZone(track, car, previousProgress, runtimeBenchmarkStats);
     if (crossedZone) {
-      car.drsZoneId = crossedZone.id;
-      const crossing = recordDrsDetection(car, crossedZone.id, time);
-      const aheadCrossing = ahead?.drsDetection?.[crossedZone.id];
-      car.drsZoneEnabled = Boolean(
-        hasReference &&
-        aheadCrossing &&
-        aheadCrossing.passage === crossing.passage &&
-        crossing.time >= aheadCrossing.time &&
-        crossing.time - aheadCrossing.time <= rules.drsDetectionSeconds + 1e-6
-      );
+      const nextZoneIndex = car._drsNextZoneIndex;
+      if (crossesDistance(previousProgress, car.progress, crossedZone.start, track.length)) {
+        car.drsZoneId = crossedZone.id;
+        car._drsZoneRef = crossedZone;
+        activeZone = crossedZone;
+        if (Number.isInteger(nextZoneIndex) && nextZoneIndex >= 0 && nextZoneIndex < zones.length) {
+          car._drsNextZoneIndex = findNextDrsZoneIndex(track, car.progress);
+        }
+        const crossing = recordDrsDetection(car, crossedZone.id, time);
+        const aheadCrossing = ahead?.drsDetection?.[crossedZone.id];
+        car.drsZoneEnabled = Boolean(
+          hasReference &&
+          aheadCrossing &&
+          aheadCrossing.passage === crossing.passage &&
+          crossing.time >= aheadCrossing.time &&
+          crossing.time - aheadCrossing.time <= rules.drsDetectionSeconds + 1e-6
+        );
+      }
     }
   }
 
-  const activeZone = car.drsZoneId
-    ? track.drsZones.find((zone) => zone.id === car.drsZoneId)
-    : null;
   const inLatchedZone = activeZone ? isProgressInZone(track, car.progress, activeZone) : false;
   car.drsEligible = Boolean(car.drsZoneEnabled && inLatchedZone);
   car.drsActive = car.drsEligible;
 }
+
+export function updateDrsLatch(car, ahead, {
+  hasReference = Boolean(ahead),
+  safetyCarDeployed = false,
+  time,
+  track,
+  rules,
+  runtimeBenchmarkStats = null,
+} = {}) {
+  return updateDrsLatchCore(
+    car,
+    ahead,
+    hasReference,
+    safetyCarDeployed,
+    time,
+    track,
+    rules,
+    runtimeBenchmarkStats,
+  );
+}
+
+export function updateDrsLatchForSimulation(sim, car, ahead, hasReference = Boolean(ahead)) {
+  return updateDrsLatchCore(
+    car,
+    ahead,
+    hasReference,
+    sim.safetyCar.deployed,
+    sim.time,
+    sim.track,
+    sim.rules,
+    sim.runtimeBenchmarkStats,
+  );
+}

package/src/simulation/timing/gapEstimation.js

@@ -3,8 +3,12 @@ import { getTimingLineCrossingTime, getTimingLineNumber } from './timingLines.js
 
 export function estimateGapAheadSeconds(ahead, car, currentTime, track) {
   if (!ahead) return Infinity;
-  const timingLineGap = estimateTimingLineGapSeconds(ahead, car, currentTime, track);
-  if (Number.isFinite(timingLineGap)) return timingLineGap;
+  const aheadLastStored = ahead.timingLineLastStored;
+  const carLastStored = car.timingLineLastStored;
+  if (Number.isInteger(aheadLastStored) && Number.isInteger(carLastStored)) {
+    const timingLineGap = estimateTimingLineGapSeconds(ahead, car, currentTime, track);
+    if (Number.isFinite(timingLineGap)) return timingLineGap;
+  }
 
   const crossingTime = interpolateTimeAtDistance(ahead.timingHistory, car.raceDistance);
   if (Number.isFinite(crossingTime)) {
@@ -22,11 +26,29 @@ export function wholeLapGap(aheadDistance, carDistance, trackLength) {
 
 export function estimateTimingLineGapSeconds(ahead, car, currentTime, track) {
   if (!ahead || !car) return Infinity;
+  const aheadLastStored = ahead.timingLineLastStored;
+  const carLastStored = car.timingLineLastStored;
+  if (!Number.isInteger(aheadLastStored) || !Number.isInteger(carLastStored)) return null;
+  const aheadFirstStored = ahead.timingLineFirstStored;
+  const carFirstStored = car.timingLineFirstStored;
+  if (!Number.isInteger(aheadFirstStored) || !Number.isInteger(carFirstStored)) return null;
   const currentLine = getTimingLineNumber(track, Math.min(ahead.raceDistance ?? 0, car.raceDistance ?? 0));
   if (currentLine == null) return null;
   const oldestLine = Math.max(0, currentLine - (track.timingLines?.count ?? 0));
+  const startLine = Math.min(
+    currentLine,
+    aheadLastStored,
+    carLastStored,
+  );
+  const earliestLine = Math.max(
+    oldestLine,
+    aheadFirstStored,
+    carFirstStored,
+  );
+
+  if (startLine < earliestLine) return null;
 
-  for (let lineNumber = currentLine; lineNumber >= oldestLine; lineNumber -= 1) {
+  for (let lineNumber = startLine; lineNumber >= earliestLine; lineNumber -= 1) {
     const aheadTime = getTimingLineCrossingTime(ahead, lineNumber);
     const carTime = getTimingLineCrossingTime(car, lineNumber);
     if (Number.isFinite(aheadTime) && Number.isFinite(carTime)) {