@inventure71/paddockjs 3.0.0 → 4.1.0

package/src/simulation/race/raceProgress.js

@@ -1,8 +1,10 @@
 import { pointAt } from '../track/trackModel.js';
 import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
 import {
-  affectsRaceOrder,
-} from '../participants/participantInteractions.js';
+  clearRunoffCenterState,
+  takeValidRunoffCenterState,
+} from '../vehicle/runoffResponse.js';
+import { affectsRaceOrder } from '../participants/participantInteractions.js';
 import {
   estimateGapAheadSeconds,
   recordTimingLineCrossings,
@@ -13,13 +15,14 @@ import {
   wholeLapGap,
 } from '../timing/raceTiming.js';
 import { progressDelta } from './raceDistance.js';
+import { assignDrsReferenceCarsForSimulation } from './raceOrder.js';
 import { isRaceDnf } from './retirements.js';
 import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
 
-export function recalculateRaceStateForSimulation(sim, { updateDrs = true } = {}) {
+export function refreshLocalRaceStateForSimulation(sim) {
   sim.cars.forEach((car) => {
-    const previousRaceDistance = car.raceDistance;
     if (car.destroyed || car.outOfRace) {
+      clearRunoffCenterState(car);
       applyWheelSurfaceState(car, sim.track);
       freezeVehicleMotion(car, {
         clearManualControls: true,
@@ -33,52 +36,134 @@ export function recalculateRaceStateForSimulation(sim, { updateDrs = true } = {}
       car.drsZoneEnabled = false;
       return;
     }
+    const centerState = takeValidRunoffCenterState(car);
+    if (centerState) {
+      applyWheelSurfaceState(car, sim.track, { centerState, cacheAsAuto: true });
+    } else {
+      applyWheelSurfaceState(car, sim.track);
+    }
+  });
+}
+
+function resolveLeaderGapSeconds({
+  sim,
+  leader,
+  ahead,
+  car,
+  leaderGapLaps,
+  gapAheadSeconds,
+  currentTime,
+  track,
+}) {
+  if (leaderGapLaps > 0) return Infinity;
+  if (!leader || leader === car) return 0;
+  if (!ahead) return Infinity;
+  if (ahead === leader) {
+    if (sim?.runtimeBenchmarkStats) {
+      sim.runtimeBenchmarkStats.leaderGapAccumulated = (sim.runtimeBenchmarkStats.leaderGapAccumulated ?? 0) + 1;
+    }
+    return gapAheadSeconds;
+  }
+  if (Number.isFinite(gapAheadSeconds) && Number.isFinite(ahead.leaderGapSeconds)) {
+    if (sim?.runtimeBenchmarkStats) {
+      sim.runtimeBenchmarkStats.leaderGapAccumulated = (sim.runtimeBenchmarkStats.leaderGapAccumulated ?? 0) + 1;
+    }
+    return ahead.leaderGapSeconds + gapAheadSeconds;
+  }
+  if (sim?.runtimeBenchmarkStats) {
+    sim.runtimeBenchmarkStats.leaderGapFallbackEstimates = (sim.runtimeBenchmarkStats.leaderGapFallbackEstimates ?? 0) + 1;
+  }
+  return estimateGapAheadSeconds(leader, car, currentTime, track);
+}
+
+function recordTimingStateForCar(car, currentTime, track, previousRaceDistanceForTiming, runtimeBenchmarkStats) {
+  recordTimingSample(car, currentTime);
+  recordTimingLineCrossings(car, previousRaceDistanceForTiming, currentTime, track);
+  car.previousRaceDistanceForTiming = car.raceDistance;
+  if (runtimeBenchmarkStats) {
+    runtimeBenchmarkStats.timingStateUpdates = (runtimeBenchmarkStats.timingStateUpdates ?? 0) + 1;
+  }
+}
+
+export function recalculateRaceStateForSimulation(sim, { updateDrs = true, refreshSurfaces = true } = {}) {
+  let sectorPerformanceDirty = false;
+  sim.cars.forEach((car) => {
+    const previousRaceDistance = car.raceDistance;
+    const previousRaceDistanceForTiming = car.previousRaceDistanceForTiming;
+    if (car.destroyed || car.outOfRace) {
+      if (refreshSurfaces) applyWheelSurfaceState(car, sim.track);
+      freezeVehicleMotion(car, {
+        clearManualControls: true,
+        physicsMode: sim.physicsMode,
+        stabilityState: car.destroyed ? 'destroyed' : car.stabilityState,
+      });
+      car.canAttack = false;
+      car.drsEligible = false;
+      car.drsActive = false;
+      car.drsZoneId = null;
+      car.drsZoneEnabled = false;
+      recordTimingStateForCar(car, sim.time, sim.track, previousRaceDistanceForTiming, sim.runtimeBenchmarkStats);
+      return;
+    }
     if (car.gridLocked) {
       const gridPoint = pointAt(sim.track, car.gridDistance);
-      applyWheelSurfaceState(car, sim.track);
+      if (refreshSurfaces) applyWheelSurfaceState(car, sim.track);
       car.progress = gridPoint.distance;
       car.raceDistance = car.gridDistance;
       car.lap = 1;
       resetLapTelemetry(car, sim.time, sim.track, sim.totalLaps);
+      sectorPerformanceDirty = true;
+      recordTimingStateForCar(car, sim.time, sim.track, previousRaceDistanceForTiming, sim.runtimeBenchmarkStats);
       return;
     }
 
-    applyWheelSurfaceState(car, sim.track);
+    if (refreshSurfaces) applyWheelSurfaceState(car, sim.track);
     const previousProgress = car.progress ?? car.trackState.distance;
     const delta = progressDelta(car.trackState.distance, previousProgress, sim.track.length);
     car.raceDistance = (car.raceDistance ?? previousProgress) + delta;
     car.progress = car.trackState.distance;
     car.lap = sim.computeLap(car.raceDistance);
-    updateLapTelemetry(car, previousRaceDistance, sim.time, sim.track, sim.totalLaps);
+    sectorPerformanceDirty = updateLapTelemetry(car, previousRaceDistance, sim.time, sim.track, sim.totalLaps) || sectorPerformanceDirty;
+    recordTimingStateForCar(car, sim.time, sim.track, previousRaceDistanceForTiming, sim.runtimeBenchmarkStats);
   });
 
-  updateSectorPerformance(sim.cars);
-  sim.cars.forEach((car) => {
-    recordTimingSample(car, sim.time);
-    recordTimingLineCrossings(car, car.previousRaceDistanceForTiming, sim.time, sim.track);
-    car.previousRaceDistanceForTiming = car.raceDistance;
-  });
+  if (sectorPerformanceDirty) {
+    sim.runtimeBenchmarkStats && (sim.runtimeBenchmarkStats.sectorPerformanceDirtyCommits = (sim.runtimeBenchmarkStats.sectorPerformanceDirtyCommits ?? 0) + 1);
+  }
+  updateSectorPerformance(sim.cars, sim.runtimeBenchmarkStats);
 
   const ordered = sim.orderedCars();
-  const orderedIds = new Set(ordered.map((car) => car.id));
-  sim.cars.forEach((car) => {
-    if (orderedIds.has(car.id) || affectsRaceOrder(car)) return;
-    car.rank = null;
-    car.classifiedRank = null;
-    car.gapAhead = Infinity;
-    car.gapAheadLaps = 0;
-    car.intervalAheadLaps = 0;
-    car.leaderGapLaps = 0;
-    car.gapAheadSeconds = Infinity;
-    car.intervalAheadSeconds = Infinity;
-    car.leaderGapSeconds = Infinity;
-    car.drsEligible = false;
-    car.drsActive = false;
-    car.drsZoneId = null;
-    car.drsZoneEnabled = false;
-    car.canAttack = false;
-  });
+  const drsReferenceByIndex = updateDrs ? assignDrsReferenceCarsForSimulation(sim, ordered) : null;
+  if (ordered.length !== sim.cars.length) {
+    if (sim?.runtimeBenchmarkStats) {
+      sim.runtimeBenchmarkStats.excludedCarResetScans = (sim.runtimeBenchmarkStats.excludedCarResetScans ?? 0) + 1;
+    }
+    sim.cars.forEach((car) => {
+      if (affectsRaceOrder(car)) return;
+      car.rank = null;
+      car.classifiedRank = null;
+      car.gapAhead = Infinity;
+      car.gapAheadLaps = 0;
+      car.intervalAheadLaps = 0;
+      car.leaderGapLaps = 0;
+      car.gapAheadSeconds = Infinity;
+      car.intervalAheadSeconds = Infinity;
+      car.leaderGapSeconds = Infinity;
+      car.drsEligible = false;
+      car.drsActive = false;
+      car.drsZoneId = null;
+      car.drsZoneEnabled = false;
+      car.canAttack = false;
+    });
+  } else if (sim?.runtimeBenchmarkStats) {
+    sim.runtimeBenchmarkStats.excludedCarResetSkips = (sim.runtimeBenchmarkStats.excludedCarResetSkips ?? 0) + 1;
+  }
   const leader = ordered[0];
+  let liveRaceOrderCount = ordered.length;
+  while (liveRaceOrderCount > 0 && isRaceDnf(ordered[liveRaceOrderCount - 1])) {
+    liveRaceOrderCount -= 1;
+  }
+  const aggressionFieldDepth = Math.max(1, liveRaceOrderCount - 1);
   ordered.forEach((car, index) => {
     if (isRaceDnf(car)) {
       car.rank = index + 1;
@@ -98,7 +183,7 @@ export function recalculateRaceStateForSimulation(sim, { updateDrs = true } = {}
       return;
     }
     const ahead = ordered[index - 1];
-    const drsReference = sim.getDrsReferenceCar(car);
+    const drsReference = drsReferenceByIndex?.[car.index] ?? null;
     const gap = ahead ? ahead.raceDistance - car.raceDistance : Infinity;
     const intervalAheadLaps = ahead ? wholeLapGap(ahead.raceDistance, car.raceDistance, sim.track.length) : 0;
     const leaderGapLaps = leader ? wholeLapGap(leader.raceDistance, car.raceDistance, sim.track.length) : 0;
@@ -112,11 +197,18 @@ export function recalculateRaceStateForSimulation(sim, { updateDrs = true } = {}
       ? estimateGapAheadSeconds(ahead, car, sim.time, sim.track)
       : Infinity;
     car.intervalAheadSeconds = car.gapAheadSeconds;
-    car.leaderGapSeconds = leaderGapLaps > 0
-      ? Infinity
-      : (leader && leader !== car ? estimateGapAheadSeconds(leader, car, sim.time, sim.track) : 0);
+    car.leaderGapSeconds = resolveLeaderGapSeconds({
+      sim,
+      leader,
+      ahead,
+      car,
+      leaderGapLaps,
+      gapAheadSeconds: car.gapAheadSeconds,
+      currentTime: sim.time,
+      track: sim.track,
+    });
     car.canAttack = !sim.safetyCar.deployed && !car.finished && !activePitStop;
-    car.aggression = sim.computeAggression(car, index);
+    car.aggression = sim.computeAggression(car, index, aggressionFieldDepth);
     if (activePitStop) {
       car.drsEligible = false;
       car.drsActive = false;
@@ -124,6 +216,6 @@ export function recalculateRaceStateForSimulation(sim, { updateDrs = true } = {}
       car.drsZoneEnabled = false;
     } else if (updateDrs) sim.updateDrsLatch(car, drsReference, Boolean(drsReference));
   });
-  sim.evaluateRaceFinish();
+  sim.evaluateRaceFinish(ordered);
   return ordered;
 }

package/src/simulation/race/raceSetup.js

@@ -1,5 +1,6 @@
 import { buildTrackModel, createProceduralTrack, TRACK } from '../track/trackModel.js';
 import { attachTrackQueryIndex, createTrackQueryIndex, forkTrackQueryIndex } from '../track/trackQueryIndex.js';
+import { attachTrackSnapshotJsonSerializer } from '../track/trackSnapshotJson.js';
 import { createMulberry32 } from '../simMath.js';
 import { createCar } from '../vehicle/vehicleState.js';
 import { normalizePhysicsMode } from '../vehicle/vehiclePhysics.js';
@@ -78,6 +79,7 @@ export function initializeRaceSimulation(simulation, {
     tireCompounds: simulation.rules.modules?.tireStrategy?.compounds,
     PIT_INTENT_NONE,
   });
+  attachTrackSnapshotJsonSerializer(simulation.track);
   simulation.recalculateRaceState({ updateDrs: false });
   simulation.cars.forEach((car) => resetTimingHistory(car, simulation.time));
   simulation.cars.forEach((car) => resetTimingLineCrossings(car, simulation.time));

package/src/simulation/race/raceStep.js

@@ -6,6 +6,13 @@ import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
 import { applyRedFlagHoldForSimulation } from './redFlag.js';
 import { freezeRetiredCar, updateStalledDnfForSimulation } from './stalledDnf.js';
 
+function measureRuntimePhase(simulation, name, run) {
+  const profiler = simulation.runtimeProfiler;
+  return typeof profiler?.measure === 'function'
+    ? profiler.measure(name, run)
+    : run();
+}
+
 export function runRaceStep(simulation, dt) {
   const delta = clamp(dt, 0, 1 / 20);
   if (!Number.isFinite(delta) || delta <= 0) return;
@@ -14,22 +21,22 @@ export function runRaceStep(simulation, dt) {
   simulation.events = [];
   updateReplayGhosts(simulation.replayGhosts, simulation.time);
   simulation.updateStartSequence();
-  const orderedCars = simulation.recalculateRaceState({ updateDrs: false }) ?? simulation.orderedCars();
 
   if (simulation.raceControl.mode === 'pre-start' && simulation.cars.every((car) => car.gridLocked)) {
     simulation.holdGridCars();
-    simulation.recalculateRaceState({ updateDrs: false });
+    measureRuntimePhase(simulation, 'broadRaceCommit', () => simulation.recalculateRaceState({ updateDrs: false }));
     return;
   }
 
   if (simulation.raceControl.redFlag) {
     applyRedFlagHoldForSimulation(simulation);
-    simulation.recalculateRaceState({ updateDrs: false });
+    measureRuntimePhase(simulation, 'broadRaceCommit', () => simulation.recalculateRaceState({ updateDrs: false }));
     return;
   }
 
   simulation.updateSafetyCar(delta);
 
+  const orderedCars = simulation.orderedCars();
   const raceContext = simulation.driverRaceContext(orderedCars);
   const orderedIndexById = new Map(orderedCars.map((car, index) => [car.id, index]));
   const driveCars = orderedCars.length === simulation.cars.length
@@ -60,21 +67,26 @@ export function runRaceStep(simulation, dt) {
       brake: controls.brake ?? 0,
     };
     if (simulation.physicsMode === 'advanced') {
-      applyWheelSurfaceState(car, simulation.track);
+      measureRuntimePhase(simulation, 'prePhysicsWheelSurface', () => {
+        applyWheelSurfaceState(car, simulation.track);
+      });
     }
-    integrateVehiclePhysics(car, controls, delta, {
-      physicsMode: simulation.physicsMode,
-      tireDegradationEnabled: simulation.rules.modules?.tireDegradation?.enabled !== false,
+    measureRuntimePhase(simulation, 'physicsIntegration', () => {
+      integrateVehiclePhysics(car, controls, delta, {
+        physicsMode: simulation.physicsMode,
+        tireDegradationEnabled: simulation.rules.modules?.tireDegradation?.enabled !== false,
+      });
+    });
+    measureRuntimePhase(simulation, 'runoffResponse', () => {
+      simulation.applyRunoffResponse(car);
     });
-    simulation.applyRunoffResponse(car);
     car.contactCooldown = Math.max(0, car.contactCooldown - delta);
   });
 
-  simulation.resolveCollisions();
-  simulation.recalculateRaceState();
-  if (updateStalledDnfForSimulation(simulation, delta)) {
-    simulation.recalculateRaceState();
-  }
+  measureRuntimePhase(simulation, 'collisions', () => simulation.resolveCollisions());
+  measureRuntimePhase(simulation, 'localSurfaceRefresh', () => simulation.refreshLocalRaceState());
+  updateStalledDnfForSimulation(simulation, delta);
+  measureRuntimePhase(simulation, 'broadRaceCommit', () => simulation.recalculateRaceState({ refreshSurfaces: false }));
   simulation.reviewTrackLimits();
   simulation.reviewPitLaneSpeeding();
 }

package/src/simulation/raceSimulation.js

@@ -21,7 +21,7 @@ import {
 } from './vehicle/contactResolution.js';
 import { applyRunoffResponseForSimulation } from './vehicle/runoffResponse.js';
 import { resetLapTelemetry, resetTimingHistory, resetTimingLineCrossings } from './timing/raceTiming.js';
-import { updateDrsLatch as updateDrsLatchState } from './timing/drsTiming.js';
+import { updateDrsLatchForSimulation as updateDrsLatchState } from './timing/drsTiming.js';
 import {
   PIT_INTENT_NONE,
   setPitIntentForSimulation,
@@ -87,7 +87,7 @@ import {
   finishDistanceForRace,
   progressDelta,
 } from './race/raceDistance.js';
-import { recalculateRaceStateForSimulation } from './race/raceProgress.js';
+import { recalculateRaceStateForSimulation, refreshLocalRaceStateForSimulation } from './race/raceProgress.js';
 import { evaluateRaceFinishForSimulation } from './race/raceFinish.js';
 import { applyGridDropForSimulation } from './race/gridPenalties.js';
 import { initializeRaceSimulation, normalizePitIntentForRace } from './race/raceSetup.js';
@@ -98,6 +98,7 @@ import {
   snapshotRace,
   snapshotRaceObservation,
   snapshotRaceRender,
+  snapshotRaceRenderInto,
   snapshotRaceTraining,
 } from './snapshots/raceSnapshots.js';
 import {
@@ -370,8 +371,8 @@ export class F1RaceSimulation {
     applyGridDropForSimulation(this, driverId, positions);
   }
 
-  reviewCollision(first, second, collision) {
-    reviewCollisionForSimulation(this, first, second, collision);
+  reviewCollision(first, second, collision, options) {
+    reviewCollisionForSimulation(this, first, second, collision, options);
   }
 
   reviewTireRequirement(car) {
@@ -400,6 +401,10 @@ export class F1RaceSimulation {
     return snapshotRaceRender(this);
   }
 
+  snapshotRenderInto(target = {}) {
+    return snapshotRaceRenderInto(this, target);
+  }
+
   snapshotObservation() {
     return snapshotRaceObservation(this);
   }
@@ -420,8 +425,8 @@ export class F1RaceSimulation {
     return driverRaceContextForSimulation(this, orderedCars);
   }
 
-  computeAggression(car, orderIndex = Math.max(0, (car.rank ?? 1) - 1)) {
-    return computeAggressionForSimulation(this, car, orderIndex);
+  computeAggression(car, orderIndex = Math.max(0, (car.rank ?? 1) - 1), fieldDepth = null) {
+    return computeAggressionForSimulation(this, car, orderIndex, fieldDepth);
   }
 
   updateStartSequence() {
@@ -448,12 +453,16 @@ export class F1RaceSimulation {
     applyRunoffResponseForSimulation(this, car);
   }
 
-  recalculateRaceState({ updateDrs = true } = {}) {
-    return recalculateRaceStateForSimulation(this, { updateDrs });
+  recalculateRaceState({ updateDrs = true, refreshSurfaces = true } = {}) {
+    return recalculateRaceStateForSimulation(this, { updateDrs, refreshSurfaces });
+  }
+
+  refreshLocalRaceState() {
+    refreshLocalRaceStateForSimulation(this);
   }
 
-  evaluateRaceFinish() {
-    evaluateRaceFinishForSimulation(this);
+  evaluateRaceFinish(orderedCars = undefined) {
+    evaluateRaceFinishForSimulation(this, orderedCars);
   }
 
   applyOutstandingServicePenalties() {
@@ -481,13 +490,7 @@ export class F1RaceSimulation {
   }
 
   updateDrsLatch(car, ahead, hasReference = Boolean(ahead)) {
-    updateDrsLatchState(car, ahead, {
-      hasReference,
-      safetyCarDeployed: this.safetyCar.deployed,
-      time: this.time,
-      track: this.track,
-      rules: this.rules,
-    });
+    updateDrsLatchState(this, car, ahead, hasReference);
   }
 
   resolveCollisions() {

package/src/simulation/rules/collisionSteward.js

@@ -1,7 +1,21 @@
 import { simSpeedToKph } from '../units.js';
 
 export function calculateCollisionPenalties({ first, second, collision = null, rule }) {
-  if (!rule) return [];
+  const penalties = [];
+  emitCollisionPenalties({
+    first,
+    second,
+    collision,
+    rule,
+    emit: (penalty) => {
+      penalties.push(penalty);
+    },
+  });
+  return penalties;
+}
+
+export function emitCollisionPenalties({ first, second, collision = null, rule, emit, emitContext = null }) {
+  if (!rule || typeof emit !== 'function') return 0;
   const severity = collision?.depth ?? 0;
   const severityThreshold = (rule.minimumSeverity ?? 0) + (rule.relaxedSeverityMargin ?? 0) * (1 - rule.strictness);
   const impactSpeed = collision?.impactSpeed ?? 0;
@@ -12,41 +26,44 @@ export function calculateCollisionPenalties({ first, second, collision = null, r
     ? collision.sharedFaultDriverIds
     : [];
 
-  if (severity < severityThreshold) return [];
-  if (impactSpeed < impactSpeedThreshold) return [];
+  if (severity < severityThreshold) return 0;
+  if (impactSpeed < impactSpeedThreshold) return 0;
 
+  let emitted = 0;
   if (sharedFaultDriverIds.length > 0) {
-    return sharedFaultDriverIds
-      .map((driverId) => {
-        const car = first.id === driverId ? first : second.id === driverId ? second : null;
-        if (!car) return null;
-        const other = first.id === driverId ? second : first;
-        return buildCollisionPenalty(car, other, rule, {
-          severity,
-          severityThreshold,
-          impactSpeed,
-          impactSpeedThreshold,
-          aheadDriverId: null,
-          atFaultDriverId: driverId,
-          sharedFault: true,
-          reason: 'Unclear collision responsibility',
-        });
-      })
-      .filter(Boolean);
+    for (let index = 0; index < sharedFaultDriverIds.length; index += 1) {
+      const driverId = sharedFaultDriverIds[index];
+      const car = first.id === driverId ? first : second.id === driverId ? second : null;
+      if (!car) continue;
+      const other = first.id === driverId ? second : first;
+      emit(buildCollisionPenalty(car, other, rule, {
+        severity,
+        severityThreshold,
+        impactSpeed,
+        impactSpeedThreshold,
+        aheadDriverId: null,
+        atFaultDriverId: driverId,
+        sharedFault: true,
+        reason: 'Unclear collision responsibility',
+      }), emitContext);
+      emitted += 1;
+    }
+    return emitted;
   }
 
-  if (!atFaultDriverId || !aheadDriverId) return [];
+  if (!atFaultDriverId || !aheadDriverId) return 0;
 
   const atFault = first.id === atFaultDriverId ? first : second;
   const other = first.id === atFaultDriverId ? second : first;
-  return [buildCollisionPenalty(atFault, other, rule, {
+  emit(buildCollisionPenalty(atFault, other, rule, {
     severity,
     severityThreshold,
     impactSpeed,
     impactSpeedThreshold,
     aheadDriverId,
     atFaultDriverId,
-  })];
+  }), emitContext);
+  return 1;
 }
 
 function buildCollisionPenalty(car, other, rule, context) {