@inventure71/paddockjs 4.2.0 → 4.3.1

package/src/environment/observations.js

@@ -1,19 +1,9 @@
-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,
-  createRayBatchContext,
-  normalizeRayOptions,
-} from './sensors.js';
-import { buildObservationVector } from './observationVector.js';
+import { writeEventDriverIds } from './events.js';
+import { defaultSensorOptions, effectiveSensorOptions } from './sensorOptions.js';
+import { buildDriverObservation, emptyObservation } from './driverObservations.js';
+import { createNearbyBatchContext } from './sensors/sensorTargets.js';
+import { createRayBatchContext } from './sensors.js';
+export { defaultSensorOptions, effectiveSensorOptions } from './sensorOptions.js';
 
 const EMPTY_EVENTS = Object.freeze([]);
 
@@ -40,6 +30,11 @@ export function buildEnvironmentObservation({
     rayBatchContext ??= createRayBatchContext(snapshot);
     return rayBatchContext;
   };
+  let nearbyBatchContext = null;
+  const sensorContexts = {
+    getRayBatchContext,
+    getNearbyBatchContext: () => nearbyBatchContext ??= createNearbyBatchContext(snapshot),
+  };
   const observations = {};
   controlledDrivers.forEach((driverId) => {
     const car = carsById.get(driverId);
@@ -50,27 +45,10 @@ export function buildEnvironmentObservation({
 
     const driverEvents = eventsByDriver?.get(driverId) ?? EMPTY_EVENTS;
     const sensors = effectiveSensorOptions(options, car.id, defaultSensors, hasSensorOverrides);
-    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, driverEvents, sensors, getRayBatchContext)
-      : null;
-    const { vector, schema } = wantsVector
-      ? object
-        ? buildDriverVector(object, sensors, {
-          includeSchema,
-          vectorType: options.observation?.vectorType,
-        })
-        : includeSchema
-          ? buildDriverVector(buildDriverObservationObject(car, snapshot, options, driverEvents, sensors, getRayBatchContext), sensors, {
-            includeSchema,
-            vectorType: options.observation?.vectorType,
-          })
-          : buildDriverVectorDirect(car, snapshot, options, driverEvents, sensors, getRayBatchContext)
-      : { vector: undefined, schema: [] };
-    observations[driverId] = formatObservation({ object, vector, schema, events: driverEvents }, options.observation);
+    observations[driverId] = formatObservation(
+      buildDriverObservation(car, snapshot, options, driverEvents, sensors, sensorContexts),
+      options.observation,
+    );
   });
   return observations;
 }
@@ -115,14 +93,7 @@ function groupEventsByDriver(events, controlledDrivers, scratch = null) {
     controlledSet.add(driverId);
   }
   events.forEach((event) => {
-    eventDriverIds.length = 0;
-    pushEventDriverId(eventDriverIds, event.driverId);
-    pushEventDriverId(eventDriverIds, event.carId);
-    pushEventDriverId(eventDriverIds, event.otherCarId);
-    const extraDriverIds = event.driverIds ?? [];
-    for (let index = 0; index < extraDriverIds.length; index += 1) {
-      pushEventDriverId(eventDriverIds, extraDriverIds[index]);
-    }
+    writeEventDriverIds(eventDriverIds, event);
     for (let index = 0; index < eventDriverIds.length; index += 1) {
       const driverId = eventDriverIds[index];
       if (controlledSet.has(driverId)) byDriver.get(driverId)?.push(event);
@@ -132,280 +103,9 @@ function groupEventsByDriver(events, controlledDrivers, scratch = null) {
   return byDriver;
 }
 
-function pushEventDriverId(target, driverId) {
-  if (!driverId || target.includes(driverId)) return;
-  target.push(driverId);
-}
-
 function rayBatchContextScratchForObservation(scratch) {
   if (!scratch) return true;
   const rayScratch = scratch.rayBatchContextScratch ?? {};
   scratch.rayBatchContextScratch = rayScratch;
   return rayScratch;
 }
-
-function buildDriverObservationObject(car, snapshot, options, events, sensors, getRayBatchContext = 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 = sensors.nearbyCars.enabled
-    ? enrichOpponentRadar(car, buildNearbyCars(car, snapshot, sensors.nearbyCars), snapshot)
-    : [];
-  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, 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 buildDriverVector(object, sensors, { includeSchema = true, vectorType = 'array' } = {}) {
-  return buildObservationVector(object, sensors, { includeSchema, vectorType });
-}
-
-function buildDriverVectorDirect(car, snapshot, options, events, sensors, getRayBatchContext = 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, getRayBatchContext, { scratch: true }),
-    )
-    : null;
-  const nearbyCars = sensors.nearbyCars.enabled
-    ? enrichOpponentRadar(car, buildNearbyCars(car, snapshot, sensors.nearbyCars), snapshot)
-    : [];
-  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 defaultSensorOptions(options) {
-  return {
-    rays: normalizeRayOptions(options.sensors.rays),
-    nearbyCars: options.sensors.nearbyCars,
-  };
-}
-
-export function effectiveSensorOptions(options, driverId, defaultSensors = defaultSensorOptions(options), hasSensorOverrides = true) {
-  if (!hasSensorOverrides || !options.sensorsByDriver?.[driverId]) return defaultSensors;
-  const rayOverrides = options.sensorsByDriver?.[driverId]?.rays ?? {};
-  return {
-    rays: normalizeRayOptions(mergeDriverRayOptions(options.sensors.rays, rayOverrides)),
-    nearbyCars: {
-      ...options.sensors.nearbyCars,
-      ...(options.sensorsByDriver?.[driverId]?.nearbyCars ?? {}),
-    },
-  };
-}
-
-function mergeDriverRayOptions(baseRays, rayOverrides = {}) {
-  const merged = {
-    ...baseRays,
-    ...rayOverrides,
-  };
-  if (Object.hasOwn(rayOverrides, 'rays')) return merged;
-  if (Object.hasOwn(rayOverrides, 'layout') || Object.hasOwn(rayOverrides, 'anglesDegrees')) {
-    delete merged.rays;
-    return merged;
-  }
-  if (Object.hasOwn(rayOverrides, 'lengthMeters') || Object.hasOwn(rayOverrides, 'defaultLengthMeters')) {
-    merged.rays = (baseRays.rays ?? []).map((ray) => ({
-      id: ray.id,
-      angleDegrees: ray.angleDegrees,
-    }));
-  }
-  return merged;
-}
-
-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/options.js

@@ -1,10 +1,11 @@
 import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
+import { createRuntimeSeed } from '../config/runtimeSeed.js';
 import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
 import { normalizePhysicsMode } from '../simulation/vehicle/vehiclePhysics.js';
 import { normalizeWarmupOptions } from '../simulation/warmup/runtimeWarmup.js';
 import { normalizeObservationOptions } from './observationOptions.js';
 import { resolveScenarioPlacementConfig } from './scenarios.js';
-import { normalizeRayOptions } from './sensors.js';
+import { mergeRayOptionOverrides, normalizeRayOptions } from './sensors/rayConfig.js';
 
 const DEFAULT_SEED = 1971;
 const DEFAULT_FRAME_SKIP = 1;
@@ -32,8 +33,8 @@ export function resolveEnvironmentOptions(options = {}) {
     throw new Error('PaddockJS environment controlledDrivers is required.');
   }
 
-  const seed = normalizeSeed(options.seed, createGeneratedSeed);
-  const trackSeed = normalizeSeed(options.trackSeed, createGeneratedSeed);
+  const seed = normalizeSeed(options.seed, createRuntimeSeed);
+  const trackSeed = normalizeSeed(options.trackSeed, createRuntimeSeed);
   const normalizedDrivers = normalizeSimulatorDrivers(options.drivers, {
     entries: options.entries ?? CHAMPIONSHIP_ENTRY_BLUEPRINTS,
     caller: 'createPaddockEnvironment',
@@ -58,13 +59,6 @@ export function resolveEnvironmentOptions(options = {}) {
   const scenario = resolveScenario(options.scenario, controlledDrivers, driverIds);
   const participants = resolveParticipants(scenario.participants, controlledDrivers, resolved.drivers);
   const participantDrivers = resolved.drivers.filter((driver) => participants.has(driver.id));
-  const participantIds = new Set(participantDrivers.map((driver) => driver.id));
-
-  controlledDrivers.forEach((driverId) => {
-    if (!participantIds.has(driverId)) {
-      throw new Error(`PaddockJS environment controlled driver must be included in scenario participants: ${driverId}`);
-    }
-  });
 
   const externalRenderer = normalizeExternalRenderer(options.externalRenderer);
 
@@ -110,16 +104,6 @@ function normalizeSeed(value, fallbackFactory) {
   return Number.isFinite(number) ? number : DEFAULT_SEED;
 }
 
-function createGeneratedSeed() {
-  const values = new Uint32Array(1);
-  try {
-    globalThis.crypto?.getRandomValues?.(values);
-  } catch {
-    values[0] = 0;
-  }
-  return (values[0] || Math.floor(Date.now() + performance.now() * 1000)) >>> 0;
-}
-
 function resolveScenario(scenario = {}, controlledDrivers, driverIds) {
   const participants = scenario.participants ?? 'all';
   if (
@@ -168,10 +152,7 @@ function normalizePositiveInteger(value, fallback, label) {
 
 function mergeSensorOptions(sensors = {}) {
   return {
-    rays: normalizeRayOptions({
-      ...DEFAULT_SENSOR_OPTIONS.rays,
-      ...(sensors.rays ?? {}),
-    }),
+    rays: normalizeRayOptions(mergeRayOptionOverrides(DEFAULT_SENSOR_OPTIONS.rays, sensors.rays ?? {})),
     nearbyCars: {
       ...DEFAULT_SENSOR_OPTIONS.nearbyCars,
       ...(sensors.nearbyCars ?? {}),

package/src/environment/renderFrames.js

@@ -0,0 +1,21 @@
+export function emitExternalRenderFrame(host, result, meta = {}, observationSnapshot = null) {
+  const options = host.getOptions?.();
+  const onFrame = options?.externalRenderer?.onFrame;
+  if (typeof onFrame !== 'function') return;
+  try {
+    onFrame({
+      snapshot: result?.state?.snapshot ??
+        observationSnapshot ??
+        host.getSimulation?.()?.snapshotObservation?.() ??
+        host.getSimulation?.()?.snapshot?.(),
+      observation: result?.observation ?? {},
+      meta: {
+        ...meta,
+        step: result?.info?.step ?? null,
+        elapsedSeconds: result?.info?.elapsedSeconds ?? null,
+      },
+    });
+  } catch {
+    // External rendering hooks are observer-only and must not break stepping.
+  }
+}

package/src/environment/resetOptions.js

@@ -0,0 +1,41 @@
+import { mergeRayOptionOverrides } from './sensors/rayConfig.js';
+
+export function mergeEnvironmentResetOptions(currentOptions, nextOptions = {}) {
+  return mergePlainObjects(currentOptions, nextOptions);
+}
+
+const REPLACE_OBJECT_PATHS = new Set([
+  'scenario.placements',
+]);
+
+function mergePlainObjects(base, overrides, path = []) {
+  if (!isPlainObject(base) || !isPlainObject(overrides)) return overrides;
+  const merged = { ...base };
+  Object.entries(overrides).forEach(([key, value]) => {
+    if (value === undefined) return;
+    const nextPath = [...path, key];
+    if (isPlainObject(value) && isPlainObject(base[key]) && isRayOptionsPath(nextPath)) {
+      merged[key] = mergeRayOptionOverrides(base[key], value);
+      return;
+    }
+    merged[key] = isPlainObject(value) &&
+      isPlainObject(base[key]) &&
+      !REPLACE_OBJECT_PATHS.has(nextPath.join('.'))
+      ? mergePlainObjects(base[key], value, nextPath)
+      : value;
+  });
+  return merged;
+}
+
+function isPlainObject(value) {
+  return value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+
+
+function isRayOptionsPath(path) {
+  return (path.length === 2 && path[0] === 'sensors' && path[1] === 'rays') ||
+    (path.length === 3 && path[0] === 'sensorsByDriver' && path[2] === 'rays');
+}

package/src/environment/results.js

@@ -0,0 +1,125 @@
+import { buildDriverEpisodeInfo, evaluateEpisode, markDestroyedDriverEpisodes } from './episode.js';
+import { buildDriverMetrics } from './metrics.js';
+import { buildEnvironmentObservation } from './observations.js';
+
+export function buildEnvironmentResult({
+  host,
+  episodeState,
+  events,
+  actionErrors,
+  actions = {},
+  controlledDrivers = null,
+  stateOutput = null,
+  rewardEnabled = false,
+}) {
+  const options = host.getOptions();
+  const sim = host.getSimulation();
+  const resultDrivers = controlledDrivers ?? options.controlledDrivers;
+  const resolvedStateOutput = stateOutput ?? options.result.stateOutput;
+  const observationSnapshot = snapshotForResult(sim, options, resolvedStateOutput);
+  markDestroyedDriverEpisodes(episodeState, options.controlledDrivers, observationSnapshot);
+  const observation = buildEnvironmentObservation({
+    snapshot: observationSnapshot,
+    options,
+    events,
+    controlledDrivers: resultDrivers,
+    scratch: episodeState.observationScratch,
+  });
+  const episode = evaluateEpisode(observationSnapshot, options, episodeState, resultDrivers);
+  const metrics = buildDriverMetrics({
+    snapshot: observationSnapshot,
+    previousSnapshot: episodeState.previousSnapshot,
+    options: { ...options, controlledDrivers: resultDrivers },
+    events,
+    scratch: episodeState.metricScratch,
+  });
+  const rewardEpisodeInfo = buildDriverEpisodeInfo(episodeState, {
+    ...options,
+    controlledDrivers: resultDrivers,
+  }, episode);
+  const driverEpisode = resultDrivers === options.controlledDrivers
+    ? episode
+    : evaluateEpisode(observationSnapshot, options, episodeState, options.controlledDrivers);
+  const driverEpisodeInfo = buildDriverEpisodeInfo(episodeState, options, driverEpisode);
+  const { state, rewardSnapshot } = buildResultState(sim, observationSnapshot, resolvedStateOutput);
+  const reward = rewardEnabled
+    ? computeReward({
+      options: { ...options, controlledDrivers: resultDrivers },
+      observation,
+      events,
+      snapshot: rewardSnapshot,
+      actions,
+      previousSnapshot: episodeState.previousSnapshot,
+      metrics,
+      driverEpisodeInfo: rewardEpisodeInfo,
+    })
+    : null;
+  episodeState.lastObservationSnapshot = observationSnapshot;
+  episodeState.lastRewardSnapshot = rewardSnapshot;
+  return {
+    observation,
+    reward,
+    metrics,
+    terminated: episode.terminated,
+    truncated: episode.truncated,
+    done: episode.terminated || episode.truncated,
+    events,
+    state,
+    info: {
+      step: episodeState.step,
+      elapsedSeconds: observationSnapshot.time,
+      seed: options.seed,
+      trackSeed: options.trackSeed,
+      controlledDrivers: [...resultDrivers],
+      actionErrors,
+      endReason: episode.endReason,
+      drivers: driverEpisodeInfo,
+    },
+  };
+}
+
+function buildResultState(sim, observationSnapshot, stateOutput) {
+  if (stateOutput === 'none') return { state: null, rewardSnapshot: observationSnapshot };
+  if (stateOutput === 'minimal') return { state: { snapshot: observationSnapshot }, rewardSnapshot: observationSnapshot };
+  const snapshot = sim.snapshot();
+  return { state: { snapshot }, rewardSnapshot: snapshot };
+}
+
+export function snapshotForResult(sim, options, stateOutput) {
+  if (canUseTrainingSnapshot(options, stateOutput) && !hasExternalRenderer(options)) {
+    return sim.snapshotTraining?.() ?? sim.snapshotObservation?.() ?? sim.snapshot();
+  }
+  return sim.snapshotObservation?.() ?? sim.snapshot();
+}
+
+function hasExternalRenderer(options) {
+  return typeof options?.externalRenderer?.onFrame === 'function';
+}
+
+function canUseTrainingSnapshot(options, stateOutput) {
+  return stateOutput === 'none' &&
+    options.observation?.output === 'vector' &&
+    options.observation?.includeSchema === false;
+}
+
+function computeReward({ options, observation, events, snapshot, actions, previousSnapshot, metrics, driverEpisodeInfo }) {
+  if (!options.reward) return null;
+  return Object.fromEntries(options.controlledDrivers.map((driverId) => [
+    driverId,
+    normalizeRewardValue(options.reward({
+      driverId,
+      previous: previousSnapshot,
+      current: observation[driverId],
+      action: actions?.[driverId],
+      events: observation[driverId]?.events ?? events,
+      state: { snapshot },
+      metrics: metrics?.[driverId] ?? null,
+      episode: driverEpisodeInfo?.[driverId] ?? null,
+    })),
+  ]));
+}
+
+function normalizeRewardValue(value) {
+  const reward = Number(value ?? 0);
+  return Number.isFinite(reward) ? reward : 0;
+}

package/src/environment/rewards.js

@@ -1,3 +1,5 @@
+import { isEnvironmentContactEvent, writeEventDriverIds } from './events.js';
+
 const DEFAULT_PROGRESS_REWARD_WEIGHTS = Object.freeze({
   progress: 1,
   speed: 0.01,
@@ -23,7 +25,7 @@ export function createProgressReward(options = {}) {
     const isOnTrack = context.metrics?.offTrack != null
       ? !context.metrics.offTrack
       : self.onTrack ?? isSnapshotCarOnTrack(currentCar);
-    const collisionCount = countDriverCollisions(context.events, driverId);
+    const collisionCount = context.metrics?.contactCount ?? countDriverCollisions(context.events, driverId);
     const steering = Math.abs(Number(context.action?.steering ?? 0));
     const brake = Math.abs(Number(context.action?.brake ?? 0));
 
@@ -62,19 +64,11 @@ function isSnapshotCarOnTrack(car) {
 
 function countDriverCollisions(events = [], driverId) {
   if (!driverId || !Array.isArray(events)) return 0;
-  return events.filter((event) => isCollisionEvent(event) && eventIncludesDriver(event, driverId)).length;
-}
-
-function isCollisionEvent(event) {
-  return event?.type === 'collision' || event?.type === 'contact';
-}
-
-function eventIncludesDriver(event, driverId) {
-  if (event.driverId === driverId ||
-      event.carId === driverId ||
-      event.primaryDriverId === driverId ||
-      event.otherDriverId === driverId) {
-    return true;
-  }
-  return Array.isArray(event.driverIds) && event.driverIds.includes(driverId);
+  const driverIds = [];
+  let count = 0;
+  events.forEach((event) => {
+    if (!isEnvironmentContactEvent(event)) return;
+    if (writeEventDriverIds(driverIds, event).includes(driverId)) count += 1;
+  });
+  return count;
 }