@inventure71/paddockjs 4.2.0 → 4.3.1

package/src/environment/controllerLoop.js

@@ -1,3 +1,5 @@
+import { cancelScheduled, defaultScheduler, now } from './controllerScheduler.js';
+
 export function createPaddockDriverControllerLoop({
   runtime,
   controller,
@@ -28,6 +30,8 @@ export function createPaddockDriverControllerLoop({
   let previousActions = {};
   let lastDecisionMs = 0;
   let lastError = null;
+  let generation = 0;
+  let generationController = new AbortController();
 
   async function ensureSpecs() {
     if (!actionSpec) actionSpec = runtime.getActionSpec();
@@ -39,14 +43,24 @@ export function createPaddockDriverControllerLoop({
     observationSpec = runtime.getObservationSpec();
   }
 
+  async function runControllerHook(name, context) {
+    try {
+      return await controller[name]?.(context);
+    } catch (error) {
+      if (context.signal.aborted) return;
+      throw error;
+    }
+  }
+
   async function ensureInitialized(context) {
     if (initialized) return;
-    await controller.init?.(context);
-    initialized = true;
+    await runControllerHook('init', context);
+    if (!context.signal.aborted) initialized = true;
   }
 
   async function resetRuntime(options = {}, { stopPlayback = true } = {}) {
     if (stopPlayback) stop();
+    const resetGeneration = generation;
     result = runtime.reset(options);
     previousResult = null;
     heldActions = null;
@@ -57,9 +71,11 @@ export function createPaddockDriverControllerLoop({
     previousActions = {};
     lastError = null;
     await refreshSpecs();
+    if (generation !== resetGeneration) return result;
     const context = buildContext({ resetDriverIds: controlledDrivers() });
     await ensureInitialized(context);
-    await controller.reset?.(context);
+    if (generation !== resetGeneration) return result;
+    await runControllerHook('reset', context);
     return result;
   }
 
@@ -75,6 +91,9 @@ export function createPaddockDriverControllerLoop({
     if (typeof runtime.resetDrivers !== 'function') {
       throw new Error('The supplied Paddock runtime does not support resetDrivers().');
     }
+    const resumePlayback = running;
+    stop();
+    const resetGeneration = generation;
     const resetDriverIds = Object.keys(placements);
     previousResult = result;
     result = runtime.resetDrivers(placements, resultOptions);
@@ -89,29 +108,39 @@ export function createPaddockDriverControllerLoop({
       delete previousActions[driverId];
     });
     await ensureSpecs();
+    if (generation !== resetGeneration) return result;
     const context = buildContext({ resetDriverIds });
     await ensureInitialized(context);
-    await controller.reset?.(context);
+    if (generation !== resetGeneration) return result;
+    await runControllerHook('reset', context);
+    if (resumePlayback && generation === resetGeneration) start();
     return result;
   }
 
-  async function beginDecision() {
+  async function beginDecision(expectedGeneration) {
     await ensureResult();
+    if (generation !== expectedGeneration) return false;
     const context = buildContext();
     await ensureInitialized(context);
+    if (generation !== expectedGeneration) return false;
     const startedAt = now();
-    const actions = await controller.decideBatch(context);
+    const actions = await runControllerHook('decideBatch', context);
+    if (generation !== expectedGeneration) return false;
     lastDecisionMs = now() - startedAt;
     heldActions = actions && typeof actions === 'object' ? actions : {};
     heldFramesRemaining = repeat;
     policyStep += 1;
+    return true;
   }
 
-  async function stepFrame() {
+  async function stepFrame(expectedGeneration = generation) {
     await ensureResult();
+    if (generation !== expectedGeneration) return result;
     if (!heldActions || heldFramesRemaining <= 0) {
-      await beginDecision();
+      const decisionReady = await beginDecision(expectedGeneration);
+      if (!decisionReady) return result;
     }
+    if (generation !== expectedGeneration) return result;
     const actionIndex = repeat - heldFramesRemaining;
     const actions = heldActions;
     const previousActionsForStep = previousActions;
@@ -121,7 +150,8 @@ export function createPaddockDriverControllerLoop({
     heldFramesRemaining -= 1;
     runtimeStep = Number(result?.info?.step ?? runtimeStep + 1);
     previousActions = actions;
-    await controller.onStep?.(buildContext({
+    if (generation !== expectedGeneration) return result;
+    await runControllerHook('onStep', buildContext({
       actionIndex,
       actions,
       previousActions: previousActionsForStep,
@@ -133,8 +163,10 @@ export function createPaddockDriverControllerLoop({
   async function step() {
     let latest = result;
     const targetPolicyStep = policyStep + 1;
+    const expectedGeneration = generation;
     while (policyStep < targetPolicyStep || heldFramesRemaining > 0) {
-      latest = await stepFrame();
+      latest = await stepFrame(expectedGeneration);
+      if (generation !== expectedGeneration) break;
       if (latest?.done) break;
       if (policyStep >= targetPolicyStep && heldFramesRemaining <= 0) break;
     }
@@ -145,18 +177,21 @@ export function createPaddockDriverControllerLoop({
     if (running) return;
     lastError = null;
     running = true;
+    const expectedGeneration = generation;
     const schedule = scheduler ?? defaultScheduler();
     const tick = async () => {
-      if (!running) return;
+      if (!running || generation !== expectedGeneration) return;
       scheduled = null;
       try {
-        await stepFrame();
+        await stepFrame(expectedGeneration);
       } catch (error) {
+        if (generation !== expectedGeneration) return;
         lastError = error;
         running = false;
         scheduled = null;
         return;
       }
+      if (generation !== expectedGeneration) return;
       if (!running || result?.done) {
         running = false;
         return;
@@ -167,9 +202,17 @@ export function createPaddockDriverControllerLoop({
   }
 
   function stop() {
+    const previousController = generationController;
+    const previousSchedule = scheduled;
     running = false;
-    cancelScheduled(scheduled);
+    generation += 1;
+    generationController = new AbortController();
     scheduled = null;
+    try {
+      cancelScheduled(previousSchedule);
+    } finally {
+      previousController.abort();
+    }
   }
 
   function controlledDrivers() {
@@ -184,6 +227,7 @@ export function createPaddockDriverControllerLoop({
     };
     return {
       runtime,
+      signal: generationController.signal,
       mode,
       actionRepeat: repeat,
       controlledDrivers: drivers,
@@ -242,34 +286,3 @@ export function createPaddockDriverControllerLoop({
     },
   };
 }
-
-function now() {
-  return typeof performance !== 'undefined' && typeof performance.now === 'function'
-    ? performance.now()
-    : Date.now();
-}
-
-function cancelScheduled(handle) {
-  if (handle == null) return;
-  if (typeof handle.cancel === 'function') {
-    handle.cancel();
-    return;
-  }
-  if (typeof handle === 'number') {
-    if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(handle);
-    if (typeof clearTimeout === 'function') clearTimeout(handle);
-  }
-}
-
-function defaultScheduler() {
-  if (typeof requestAnimationFrame === 'function') {
-    return (callback) => {
-      const id = requestAnimationFrame(callback);
-      return { cancel: () => cancelAnimationFrame(id) };
-    };
-  }
-  return (callback) => {
-    const id = setTimeout(callback, 0);
-    return { cancel: () => clearTimeout(id) };
-  };
-}

package/src/environment/controllerScheduler.js

@@ -0,0 +1,30 @@
+export function now() {
+  return typeof performance !== 'undefined' && typeof performance.now === 'function'
+    ? performance.now()
+    : Date.now();
+}
+
+export function cancelScheduled(handle) {
+  if (handle == null) return;
+  if (typeof handle.cancel === 'function') {
+    handle.cancel();
+    return;
+  }
+  if (typeof handle === 'number') {
+    if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(handle);
+    if (typeof clearTimeout === 'function') clearTimeout(handle);
+  }
+}
+
+export function defaultScheduler() {
+  if (typeof requestAnimationFrame === 'function') {
+    return (callback) => {
+      const id = requestAnimationFrame(callback);
+      return { cancel: () => cancelAnimationFrame(id) };
+    };
+  }
+  return (callback) => {
+    const id = setTimeout(callback, 0);
+    return { cancel: () => clearTimeout(id) };
+  };
+}

package/src/environment/driverObservations.js

@@ -0,0 +1,260 @@
+import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+import { normalizeAngle } from '../simulation/simMath.js';
+import { pointAt } from '../simulation/track/trackModel.js';
+import { normalizeLookaheadMeters } from './observationOptions.js';
+import { buildBodySenses } from './sensors/bodySenses.js';
+import { buildBoundarySenses } from './sensors/boundarySenses.js';
+import { buildContactPatchSenses } from './sensors/contactSenses.js';
+import { enrichOpponentRadar } from './sensors/opponentRadar.js';
+import { buildNearbyCars, appendRaySensorVectorValues, buildRaySensors } from './sensors.js';
+import { buildObservationVector } from './observationVector.js';
+
+export function buildDriverObservation(car, snapshot, options, events, sensors, sensorContexts) {
+  const output = options.observation?.output ?? 'full';
+  const includeSchema = options.observation?.includeSchema !== false;
+  const wantsObject = output === 'full' || output === 'object';
+  const wantsVector = output === 'full' || output === 'vector';
+  const object = wantsObject
+    ? buildDriverObservationObject(car, snapshot, options, events, sensors, sensorContexts)
+    : null;
+  let vector;
+  let schema = [];
+  if (wantsVector) {
+    const encoded = !object && !includeSchema
+      ? buildDriverVectorDirect(car, snapshot, options, sensors, sensorContexts)
+      : buildObservationVector(
+        object ?? buildDriverObservationObject(car, snapshot, options, events, sensors, sensorContexts),
+        sensors,
+        { includeSchema, vectorType: options.observation?.vectorType },
+      );
+    vector = encoded.vector;
+    schema = encoded.schema;
+  }
+  return { object, vector, schema, events };
+}
+
+function buildDriverNearbyCars(car, snapshot, sensors, sensorContexts) {
+  if (!sensors.nearbyCars.enabled) return [];
+  const context = sensorContexts?.getNearbyBatchContext();
+  return enrichOpponentRadar(car, buildNearbyCars(car, snapshot, sensors.nearbyCars, context), snapshot, context);
+}
+
+function buildDriverObservationObject(car, snapshot, options, events, sensors, sensorContexts = null) {
+  const sensorCar = withEnvironmentControlFlag(car, options);
+  const onTrack = isCarLegallyOnTrack(car);
+  const body = buildBodySenses(car);
+  const trackHeadingError = car.trackHeadingError ?? estimateTrackHeadingError(car, snapshot);
+  const trackRelation = {
+    ...buildBoundarySenses(car, snapshot, onTrack),
+    headingErrorRadians: trackHeadingError,
+  };
+  const nearbyCars = buildDriverNearbyCars(car, snapshot, sensors, sensorContexts);
+  return {
+    profile: options.observation?.profile ?? 'default',
+    self: {
+      ...body,
+      lap: car.lap,
+      completedLaps: car.lapTelemetry?.completedLaps ?? 0,
+      lapProgressMeters: simUnitsToMeters(car.progress ?? 0),
+      trackOffsetMeters: trackRelation.lateralOffsetMeters,
+      trackHeadingErrorRadians: trackHeadingError,
+      onTrack,
+      surface: car.surface ?? 'track',
+      inPitLane: Boolean(car.inPitLane),
+      pitLanePart: car.pitLanePart ?? null,
+      pitBoxId: car.pitBoxId ?? null,
+      tireEnergy: car.tireEnergy ?? null,
+      pitIntent: car.pitIntent ?? car.pitStop?.intent ?? 0,
+      pitTargetCompound: car.pitStop?.targetTire ?? null,
+      pitStopStatus: car.pitStop?.status ?? null,
+      pitStopPhase: car.pitStop?.phase ?? null,
+      pitStopServiceRemainingSeconds: car.pitStop?.serviceRemainingSeconds ?? null,
+      pitStopPenaltyServiceRemainingSeconds: car.pitStop?.penaltyServiceRemainingSeconds ?? null,
+      pitStopsCompleted: car.pitStop?.stopsCompleted ?? 0,
+    },
+    trackRelation,
+    contactPatches: buildContactPatchSenses(car),
+    race: {
+      position: car.rank,
+      totalCars: snapshot.cars.length,
+      raceMode: snapshot.raceControl.mode,
+      pitLaneOpen: Boolean(snapshot.raceControl.pitLaneOpen),
+      redFlag: Boolean(snapshot.raceControl.redFlag),
+      totalLaps: snapshot.totalLaps,
+    },
+    track: {
+      lengthMeters: simUnitsToMeters(snapshot.track.length ?? 0),
+      widthMeters: simUnitsToMeters(snapshot.track.width ?? 0),
+      curvature: car.trackState?.curvature ?? pointAt(snapshot.track, car.progress ?? 0).curvature ?? 0,
+      lookahead: buildTrackLookahead(car, snapshot, options),
+    },
+    rays: sensors.rays.enabled ? buildRaySensors(sensorCar, snapshot, sensors.rays, rayBatchContextForSensors(sensors, sensorContexts?.getRayBatchContext)) : [],
+    nearbyCars,
+    events,
+  };
+}
+
+function estimateTrackHeadingError(car, snapshot) {
+  const base = pointAt(snapshot.track, car.progress ?? 0);
+  return normalizeAngle((car.heading ?? base.heading) - base.heading);
+}
+
+function buildTrackLookahead(car, snapshot, options) {
+  const distances = Array.isArray(options.observation?.lookaheadMeters)
+    ? options.observation.lookaheadMeters
+    : normalizeLookaheadMeters(options.observation?.lookaheadMeters);
+  if (!distances.length) return [];
+  const base = pointAt(snapshot.track, car.progress ?? 0);
+  return distances.map((distanceMeters) => {
+    const sample = pointAt(snapshot.track, (car.progress ?? 0) + metersToSimUnits(distanceMeters));
+    return {
+      distanceMeters,
+      curvature: sample.curvature ?? 0,
+      headingDeltaRadians: normalizeAngle(sample.heading - base.heading),
+    };
+  });
+}
+
+function isCarLegallyOnTrack(car) {
+  if (Array.isArray(car.wheels) && car.wheels.length > 0) {
+    return car.wheels.every((wheel) => wheel.onTrack || wheel.inPitLane);
+  }
+  if (car.inPitLane) return true;
+  return ['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box'].includes(car.surface ?? 'track');
+}
+
+function buildDriverVectorDirect(car, snapshot, options, sensors, sensorContexts = null) {
+  const profile = options.observation?.profile ?? 'default';
+  const includePhysicalDriverSenses = profile === 'physical-driver';
+  const onTrack = isCarLegallyOnTrack(car);
+  const body = buildBodySenses(car);
+  const trackHeadingError = car.trackHeadingError ?? estimateTrackHeadingError(car, snapshot);
+  const sensorCar = withEnvironmentControlFlag(car, options);
+  const trackRelation = {
+    ...buildBoundarySenses(car, snapshot, onTrack),
+    headingErrorRadians: trackHeadingError,
+  };
+  const contactPatches = includePhysicalDriverSenses ? buildContactPatchSenses(car) : [];
+  const appendRayVectorValues = sensors.rays.enabled
+    ? (vector) => appendRaySensorVectorValues(
+      vector,
+      sensorCar,
+      snapshot,
+      sensors.rays,
+      rayBatchContextForSensors(sensors, sensorContexts?.getRayBatchContext, { scratch: true }),
+    )
+    : null;
+  const nearbyCars = buildDriverNearbyCars(car, snapshot, sensors, sensorContexts);
+  const trackLengthMeters = simUnitsToMeters(snapshot.track.length ?? 0);
+  const trackCurvature = car.trackState?.curvature ?? pointAt(snapshot.track, car.progress ?? 0).curvature ?? 0;
+  const source = {
+    profile,
+    self: {
+      ...body,
+      lapProgressMeters: simUnitsToMeters(car.progress ?? 0),
+      trackOffsetMeters: trackRelation.lateralOffsetMeters,
+      trackHeadingErrorRadians: trackHeadingError,
+      onTrack,
+      inPitLane: Boolean(car.inPitLane),
+      tireEnergy: car.tireEnergy ?? null,
+      pitIntent: car.pitIntent ?? car.pitStop?.intent ?? 0,
+      pitStopStatus: car.pitStop?.status ?? null,
+    },
+    trackRelation,
+    contactPatches,
+    race: {
+      position: car.rank,
+      totalCars: snapshot.cars.length,
+      raceMode: snapshot.raceControl.mode,
+      pitLaneOpen: Boolean(snapshot.raceControl.pitLaneOpen),
+      redFlag: Boolean(snapshot.raceControl.redFlag),
+    },
+    track: {
+      lengthMeters: trackLengthMeters,
+      curvature: trackCurvature,
+      lookahead: buildTrackLookahead(car, snapshot, options),
+    },
+    rays: [],
+    appendRayVectorValues,
+    nearbyCars,
+  };
+  return buildObservationVector(source, sensors, {
+    includeSchema: false,
+    vectorType: options.observation?.vectorType,
+  });
+}
+
+function rayBatchContextForSensors(sensors, getRayBatchContext, { scratch = false } = {}) {
+  if (!getRayBatchContext || !sensors.rays?.channels?.includes('car')) return null;
+  return getRayBatchContext({ scratch });
+}
+
+export function emptyObservation(driverId) {
+  return {
+    object: {
+      self: {
+        id: driverId,
+        speedKph: 0,
+        speedMetersPerSecond: 0,
+        headingRadians: 0,
+        yawRateRadiansPerSecond: 0,
+        steeringAngleRadians: 0,
+        throttle: 0,
+        brake: 0,
+        lateralG: 0,
+        longitudinalG: 0,
+        gripUsage: 0,
+        slipAngleRadians: 0,
+        tractionLimited: false,
+        stabilityState: 'stable',
+        destroyed: false,
+        destroyReason: null,
+        lap: 0,
+        completedLaps: 0,
+        lapProgressMeters: 0,
+        trackOffsetMeters: 0,
+        trackHeadingErrorRadians: 0,
+        onTrack: false,
+        surface: 'missing',
+        inPitLane: false,
+        pitLanePart: null,
+        pitBoxId: null,
+        tireEnergy: null,
+        pitIntent: 0,
+        pitTargetCompound: null,
+        pitStopStatus: null,
+        pitStopPhase: null,
+        pitStopServiceRemainingSeconds: null,
+        pitStopPenaltyServiceRemainingSeconds: null,
+        pitStopsCompleted: 0,
+      },
+      trackRelation: {
+        lateralOffsetMeters: 0,
+        headingErrorRadians: 0,
+        legalWidthMeters: 0,
+        leftBoundaryMeters: 0,
+        rightBoundaryMeters: 0,
+        onLegalSurface: false,
+        surface: 'missing',
+      },
+      contactPatches: [],
+      race: { position: 0, totalCars: 0, raceMode: 'missing', pitLaneOpen: false, redFlag: false, totalLaps: 0 },
+      track: { lengthMeters: 0, widthMeters: 0, curvature: 0, lookahead: [] },
+      rays: [],
+      nearbyCars: [],
+      events: [],
+    },
+    vector: [],
+    schema: [],
+    events: [],
+  };
+}
+
+function withEnvironmentControlFlag(car, options) {
+  if (!car || car.environmentControlled) return car;
+  if (!Array.isArray(options?.controlledDrivers) || !options.controlledDrivers.includes(car.id)) return car;
+  return {
+    ...car,
+    environmentControlled: true,
+  };
+}

package/src/environment/driverReset.js

@@ -0,0 +1,51 @@
+export function initializeControlledPitIntent(host) {
+  const sim = host.getSimulation?.();
+  const options = host.getOptions?.();
+  initializeControlledPitIntentForSimulation(sim, options);
+}
+
+export function initializeControlledPitIntentForSimulation(sim, options) {
+  options?.controlledDrivers?.forEach?.((driverId) => {
+    sim?.setAutomaticPitIntentEnabled?.(driverId, false);
+    sim?.setPitIntent?.(driverId, 0);
+    const car = sim?.cars?.find?.((item) => item.id === driverId);
+    if (car) car.environmentControlled = true;
+  });
+}
+
+function resetEnvironmentPitStop(car) {
+  const stop = car?.pitStop;
+  if (!stop) return;
+  stop.status = 'pending';
+  stop.phase = null;
+  stop.intent = 0;
+  stop.queueingForService = false;
+  stop.route = null;
+  stop.routeProgress = 0;
+  stop.routeStartRaceDistance = null;
+  stop.routeEndRaceDistance = null;
+  stop.serviceRemaining = 0;
+  stop.penaltyServiceRemaining = 0;
+  stop.penaltyServiceTotal = 0;
+  stop.servingPenaltyIds = [];
+  stop.serviceProfile = null;
+}
+
+export function applyControlledRunoffResponse(sim, options) {
+  options?.controlledDrivers?.forEach?.((driverId) => {
+    const car = sim?.cars?.find?.((item) => item.id === driverId);
+    if (car) sim?.applyRunoffResponse?.(car);
+  });
+}
+
+
+export function resetControlledDriverState(sim, driverIds) {
+  driverIds.forEach((driverId) => {
+    sim.clearCarControls?.(driverId);
+    sim.setAutomaticPitIntentEnabled?.(driverId, false);
+    const car = sim.cars?.find?.((item) => item.id === driverId);
+    resetEnvironmentPitStop(car);
+    sim.setPitIntent?.(driverId, 0);
+    if (car) sim.applyRunoffResponse?.(car);
+  });
+}

package/src/environment/episode.js

@@ -92,7 +92,6 @@ export function evaluateEpisode(snapshot, options, episodeState, controlledDrive
     if (!state.truncated && state.episodeStep < options.episode.maxSteps) allTruncated = false;
     if (state.truncated || state.episodeStep >= options.episode.maxSteps) anyTruncated = true;
     if (!state.terminated && !state.truncated && state.episodeStep < options.episode.maxSteps) allEnded = false;
-    if (!allTerminated && !allTruncated && !allEnded) break;
   }
   if (allTerminated) {
     return { terminated: true, truncated: false, endReason: controlledDrivers.length === 1 ? firstTerminatedReason : 'all-drivers-terminated' };

package/src/environment/evaluation.js

@@ -1,5 +1,5 @@
-import { simUnitsToMeters } from '../simulation/units.js';
-import { isEnvironmentCarOffTrack, isEnvironmentContactEvent } from './metrics.js';
+import { createEvaluationTracker } from './evaluationTracker.js';
+export { createEvaluationTracker } from './evaluationTracker.js';
 import { createPaddockEnvironment } from './runtime.js';
 
 export const DEFAULT_EVALUATION_CASES = Object.freeze([
@@ -37,6 +37,7 @@ export function runEnvironmentEvaluation({
   baseOptions,
   policy,
   cases = DEFAULT_EVALUATION_CASES,
+  lapScope = 'since-start',
   createEnvironment = createPaddockEnvironment,
 } = {}) {
   if (!baseOptions || typeof baseOptions !== 'object') {
@@ -52,6 +53,7 @@ export function runEnvironmentEvaluation({
       policy,
       evaluationCase,
       createEnvironment,
+      lapScope,
     })),
   };
 }
@@ -61,89 +63,7 @@ function isEvaluationPolicy(policy) {
     (policy != null && typeof policy.predict === 'function');
 }
 
-export function createEvaluationTracker(initialResult) {
-  if (!initialResult?.state?.snapshot) {
-    throw new Error('PaddockJS environment evaluation tracker requires result.state.snapshot; use result.stateOutput "minimal" or "full".');
-  }
-  const initialCars = carsById(initialResult.state.snapshot);
-  const metrics = Object.fromEntries(initialResult.info.controlledDrivers.map((driverId) => {
-    const car = initialCars.get(driverId);
-    const offTrack = isEnvironmentCarOffTrack(car);
-    return [driverId, {
-      distanceMeters: 0,
-      lapProgressMeters: lapProgressMetersFromSnapshotCar(car),
-      offTrackSteps: offTrack ? 1 : 0,
-      contactCount: 0,
-      recoverySuccess: false,
-      passCount: 0,
-      lapTimeSeconds: null,
-      startedOffTrack: offTrack,
-      startPosition: car?.rank ?? null,
-      bestPosition: car?.rank ?? null,
-      startDistanceMeters: cumulativeDistanceMetersFromSnapshotCar(car),
-    }];
-  }));
-
-  return {
-    update(result) {
-      const currentCars = carsById(result.state.snapshot);
-      result.info.controlledDrivers.forEach((driverId) => {
-        const car = currentCars.get(driverId);
-        const entry = metrics[driverId];
-        if (!car || !entry) return;
-        entry.distanceMeters = Math.max(0, cumulativeDistanceMetersFromSnapshotCar(car) - entry.startDistanceMeters);
-        entry.lapProgressMeters = lapProgressMetersFromSnapshotCar(car);
-        const offTrack = isEnvironmentCarOffTrack(car);
-        if (offTrack) entry.offTrackSteps += 1;
-        if (entry.startedOffTrack && !offTrack) entry.recoverySuccess = true;
-        if (Number.isFinite(car.rank)) {
-          entry.bestPosition = entry.bestPosition == null ? car.rank : Math.min(entry.bestPosition, car.rank);
-          entry.passCount = entry.startPosition == null ? 0 : Math.max(0, entry.startPosition - entry.bestPosition);
-        }
-        const completedLaps = car.lapTelemetry?.completedLaps ?? 0;
-        if (completedLaps > 0 && entry.lapTimeSeconds == null) {
-          entry.lapTimeSeconds = result.info.elapsedSeconds;
-        }
-      });
-      result.events.forEach((event) => {
-        if (!isEnvironmentContactEvent(event)) return;
-        Object.keys(metrics).forEach((driverId) => {
-          if (event.driverId === driverId || event.carId === driverId || event.otherCarId === driverId || event.driverIds?.includes?.(driverId)) {
-            metrics[driverId].contactCount += 1;
-          }
-        });
-      });
-    },
-    finish() {
-      return Object.fromEntries(Object.entries(metrics).map(([driverId, entry]) => [
-        driverId,
-        {
-          distanceMeters: entry.distanceMeters,
-          lapProgressMeters: entry.lapProgressMeters,
-          offTrackSteps: entry.offTrackSteps,
-          contactCount: entry.contactCount,
-          recoverySuccess: entry.recoverySuccess,
-          passCount: entry.passCount,
-          lapTimeSeconds: entry.lapTimeSeconds,
-        },
-      ]));
-    },
-  };
-}
-
-function cumulativeDistanceMetersFromSnapshotCar(car) {
-  const distance = Number(car?.distanceMeters ?? car?.raceDistanceMeters);
-  if (Number.isFinite(distance)) return distance;
-  return simUnitsToMeters(car?.raceDistance ?? 0);
-}
-
-function lapProgressMetersFromSnapshotCar(car) {
-  const progressMeters = Number(car?.lapProgressMeters ?? car?.progressMeters);
-  if (Number.isFinite(progressMeters)) return progressMeters;
-  return simUnitsToMeters(car?.progress ?? 0);
-}
-
-function runEvaluationCase({ baseOptions, policy, evaluationCase, createEnvironment }) {
+function runEvaluationCase({ baseOptions, policy, evaluationCase, createEnvironment, lapScope }) {
   const env = createEnvironment({
     ...baseOptions,
     result: {
@@ -159,7 +79,7 @@ function runEvaluationCase({ baseOptions, policy, evaluationCase, createEnvironm
   });
   try {
     let result = env.reset();
-    const tracker = createEvaluationTracker(result);
+    const tracker = createEvaluationTracker(result, { lapScope });
     const maxSteps = Math.max(1, Math.floor(evaluationCase.maxSteps ?? baseOptions.episode?.maxSteps ?? 1000));
     let steps = 0;
     while (!result.done && steps < maxSteps) {
@@ -200,7 +120,3 @@ function predictAction(policy, observation, context) {
     : policy.predict(observation, context);
   return action ?? { steering: 0, throttle: 0, brake: 1 };
 }
-
-function carsById(snapshot) {
-  return new Map(snapshot.cars.map((car) => [car.id, car]));
-}