@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/environment/observations.js

@@ -1,27 +1,74 @@
-import { metersToSimUnits, simSpeedToMetersPerSecond, simUnitsToMeters } from '../simulation/units.js';
+import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
 import { normalizeAngle } from '../simulation/simMath.js';
-import { pointAt } from '../simulation/trackModel.js';
+import { pointAt } from '../simulation/track/trackModel.js';
 import { normalizeLookaheadMeters } from './observationOptions.js';
-import { buildNearbyCars, buildRaySensors } from './sensors.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, buildRaySensors, createRayBatchContext, normalizeRayOptions } from './sensors.js';
+import { buildObservationVector } from './observationVector.js';
 
-export function buildEnvironmentObservation({ snapshot, options, events = [] }) {
+const EMPTY_EVENTS = Object.freeze([]);
+
+export function buildEnvironmentObservation({ snapshot, options, events = [], controlledDrivers = options.controlledDrivers }) {
   const carsById = new Map(snapshot.cars.map((entry) => [entry.id, entry]));
-  const eventsByDriver = groupEventsByDriver(events, options.controlledDrivers);
-  return Object.fromEntries(options.controlledDrivers.map((driverId) => {
+  const eventsByDriver = groupEventsByDriver(events, controlledDrivers);
+  const defaultSensors = defaultSensorOptions(options);
+  const hasSensorOverrides = Object.keys(options.sensorsByDriver ?? {}).length > 0;
+  let rayBatchContext = null;
+  const getRayBatchContext = () => {
+    rayBatchContext ??= createRayBatchContext(snapshot);
+    return rayBatchContext;
+  };
+  const observations = {};
+  controlledDrivers.forEach((driverId) => {
     const car = carsById.get(driverId);
-    if (!car) return [driverId, emptyObservation(driverId)];
+    if (!car) {
+      observations[driverId] = formatObservation(emptyObservation(driverId), options.observation);
+      return;
+    }
+
+    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);
+  });
+  return observations;
+}
 
-    const driverEvents = eventsByDriver.get(driverId) ?? [];
-    const sensors = effectiveSensorOptions(options, car.id);
-    const object = buildDriverObservationObject(car, snapshot, options, driverEvents, sensors);
-    const { vector, schema } = buildDriverVector(object, sensors);
-    return [driverId, { object, vector, schema, events: driverEvents }];
-  }));
+function formatObservation(observation, options = {}) {
+  const output = options.output ?? 'full';
+  const includeSchema = options.includeSchema !== false;
+  const formatted = { events: observation.events ?? [] };
+  if ((output === 'full' || output === 'object') && observation.object) formatted.object = observation.object;
+  if ((output === 'full' || output === 'vector') && observation.vector) formatted.vector = observation.vector;
+  if (includeSchema) formatted.schema = observation.schema;
+  return formatted;
 }
 
 function groupEventsByDriver(events, controlledDrivers) {
+  if (!events.length) return null;
   const byDriver = new Map(controlledDrivers.map((driverId) => [driverId, []]));
-  if (!events.length) return byDriver;
   const controlledSet = new Set(controlledDrivers);
   events.forEach((event) => {
     const driverIds = new Set([
@@ -37,22 +84,28 @@ function groupEventsByDriver(events, controlledDrivers) {
   return byDriver;
 }
 
-function buildDriverObservationObject(car, snapshot, options, events, sensors) {
+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: {
-      id: car.id,
-      speedKph: car.speedKph,
-      speedMetersPerSecond: simSpeedToMetersPerSecond(car.speed ?? 0),
-      headingRadians: car.heading,
-      steeringAngleRadians: car.steeringAngle ?? 0,
-      throttle: car.throttle ?? 0,
-      brake: car.brake ?? 0,
+      ...body,
       lap: car.lap,
       completedLaps: car.lapTelemetry?.completedLaps ?? 0,
       lapProgressMeters: simUnitsToMeters(car.progress ?? 0),
-      trackOffsetMeters: simUnitsToMeters(car.signedOffset ?? 0),
-      trackHeadingErrorRadians: car.trackHeadingError ?? estimateTrackHeadingError(car, snapshot),
-      onTrack: isCarLegallyOnTrack(car),
+      trackOffsetMeters: trackRelation.lateralOffsetMeters,
+      trackHeadingErrorRadians: trackHeadingError,
+      onTrack,
       surface: car.surface ?? 'track',
       inPitLane: Boolean(car.inPitLane),
       pitLanePart: car.pitLanePart ?? null,
@@ -66,6 +119,8 @@ function buildDriverObservationObject(car, snapshot, options, events, sensors) {
       pitStopPenaltyServiceRemainingSeconds: car.pitStop?.penaltyServiceRemainingSeconds ?? null,
       pitStopsCompleted: car.pitStop?.stopsCompleted ?? 0,
     },
+    trackRelation,
+    contactPatches: buildContactPatchSenses(car),
     race: {
       position: car.rank,
       totalCars: snapshot.cars.length,
@@ -80,8 +135,8 @@ function buildDriverObservationObject(car, snapshot, options, events, sensors) {
       curvature: car.trackState?.curvature ?? pointAt(snapshot.track, car.progress ?? 0).curvature ?? 0,
       lookahead: buildTrackLookahead(car, snapshot, options),
     },
-    rays: sensors.rays.enabled ? buildRaySensors(car, snapshot, sensors.rays) : [],
-    nearbyCars: sensors.nearbyCars.enabled ? buildNearbyCars(car, snapshot, sensors.nearbyCars) : [],
+    rays: sensors.rays.enabled ? buildRaySensors(sensorCar, snapshot, sensors.rays, rayBatchContextForSensors(sensors, getRayBatchContext)) : [],
+    nearbyCars,
     events,
   };
 }
@@ -92,7 +147,10 @@ function estimateTrackHeadingError(car, snapshot) {
 }
 
 function buildTrackLookahead(car, snapshot, options) {
-  const distances = normalizeLookaheadMeters(options.observation?.lookaheadMeters);
+  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));
@@ -112,128 +170,81 @@ function isCarLegallyOnTrack(car) {
   return ['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box'].includes(car.surface ?? 'track');
 }
 
-function buildDriverVector(object, sensors) {
-  const schema = [
-    { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
-    { name: 'self.speedMetersPerSecond', unit: 'm/s', scale: 'fixed:120' },
-    { name: 'self.steeringAngleRadians', unit: 'rad', scale: 'fixed:pi' },
-    { name: 'self.throttle', scale: '0..1' },
-    { name: 'self.brake', scale: '0..1' },
-    { name: 'self.lapProgressRatio', scale: '0..1' },
-    { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
-    { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
-    { name: 'self.onTrack', scale: 'boolean' },
-    { name: 'self.inPitLane', scale: 'boolean' },
-    { name: 'self.tireEnergy', scale: '0..100' },
-    { name: 'self.pitIntent', scale: '0..2' },
-    { name: 'self.pitStopActive', scale: 'boolean' },
-    { name: 'race.positionNormalized', scale: '0..1' },
-    { name: 'race.raceModeGreen', scale: 'boolean' },
-    { name: 'race.raceModeSafetyCar', scale: 'boolean' },
-    { name: 'race.redFlag', scale: 'boolean' },
-    { name: 'race.pitLaneOpen', scale: 'boolean' },
-    { name: 'track.curvature', scale: 'track-curvature' },
-  ];
-  const vector = [
-    object.self.speedKph / 400,
-    object.self.speedMetersPerSecond / 120,
-    object.self.steeringAngleRadians / Math.PI,
-    object.self.throttle,
-    object.self.brake,
-    normalizeLapProgress(object),
-    object.self.trackOffsetMeters,
-    object.self.trackHeadingErrorRadians / Math.PI,
-    object.self.onTrack ? 1 : 0,
-    object.self.inPitLane ? 1 : 0,
-    (object.self.tireEnergy ?? 0) / 100,
-    (object.self.pitIntent ?? 0) / 2,
-    object.self.pitStopStatus && object.self.pitStopStatus !== 'pending' && object.self.pitStopStatus !== 'completed' ? 1 : 0,
-    normalizeRacePosition(object),
-    object.race.raceMode === 'green' ? 1 : 0,
-    object.race.raceMode === 'safety-car' ? 1 : 0,
-    object.race.redFlag ? 1 : 0,
-    object.race.pitLaneOpen ? 1 : 0,
-    object.track.curvature ?? 0,
-  ];
-  object.track.lookahead.forEach((sample, index) => {
-    schema.push(
-      { name: `track.lookahead[${index}].curvature`, scale: 'track-curvature' },
-      { name: `track.lookahead[${index}].headingDeltaRadians`, unit: 'rad', scale: 'fixed:pi' },
-    );
-    vector.push(sample.curvature ?? 0, (sample.headingDeltaRadians ?? 0) / Math.PI);
-  });
-  object.rays.forEach((ray, index) => {
-    schema.push(
-      { name: `rays[${index}].track.distanceRatio`, scale: '0..1' },
-      { name: `rays[${index}].track.hit`, scale: 'boolean' },
-      { name: `rays[${index}].track.kindExit`, scale: 'boolean' },
-      { name: `rays[${index}].track.kindEntry`, scale: 'boolean' },
-      { name: `rays[${index}].car.distanceRatio`, scale: '0..1' },
-      { name: `rays[${index}].car.hit`, scale: 'boolean' },
-      { name: `rays[${index}].car.relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
-    );
-    vector.push(
-      ratio(ray.track.distanceMeters, ray.lengthMeters),
-      ray.track.hit ? 1 : 0,
-      ray.track.kind === 'exit' ? 1 : 0,
-      ray.track.kind === 'entry' ? 1 : 0,
-      ratio(ray.car.distanceMeters, ray.lengthMeters),
-      ray.car.hit ? 1 : 0,
-      ray.car.relativeSpeedKph / 200,
-    );
-  });
-  const nearbyLimit = sensors.nearbyCars.enabled ? (sensors.nearbyCars.maxCars ?? object.nearbyCars.length) : 0;
-  const nearbyRadius = sensors.nearbyCars.radiusMeters ?? 150;
-  for (let index = 0; index < nearbyLimit; index += 1) {
-    const nearby = object.nearbyCars[index] ?? null;
-    schema.push(
-      { name: `nearbyCars[${index}].present`, scale: 'boolean' },
-      { name: `nearbyCars[${index}].relativeForwardRatio`, scale: '-1..1' },
-      { name: `nearbyCars[${index}].relativeRightRatio`, scale: '-1..1' },
-      { name: `nearbyCars[${index}].relativeDistanceRatio`, scale: '0..1' },
-      { name: `nearbyCars[${index}].relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
-      { name: `nearbyCars[${index}].relativeHeadingRadians`, unit: 'rad', scale: 'fixed:pi' },
-      { name: `nearbyCars[${index}].ahead`, scale: 'boolean' },
-      { name: `nearbyCars[${index}].sameLap`, scale: 'boolean' },
-    );
-    vector.push(
-      nearby ? 1 : 0,
-      clampRatio((nearby?.relativeForwardMeters ?? 0) / nearbyRadius),
-      clampRatio((nearby?.relativeRightMeters ?? 0) / nearbyRadius),
-      ratio(nearby?.relativeDistanceMeters ?? nearbyRadius, nearbyRadius),
-      (nearby?.relativeSpeedKph ?? 0) / 200,
-      (nearby?.relativeHeadingRadians ?? 0) / Math.PI,
-      nearby?.ahead ? 1 : 0,
-      nearby?.sameLap ? 1 : 0,
-    );
-  }
-  return { vector, schema };
+function buildDriverVector(object, sensors, { includeSchema = true, vectorType = 'array' } = {}) {
+  return buildObservationVector(object, sensors, { includeSchema, vectorType });
 }
 
-function normalizeLapProgress(object) {
-  return ratio(object.self.lapProgressMeters, object.track.lengthMeters || 1);
-}
-
-function normalizeRacePosition(object) {
-  const total = Math.max(1, object.race.totalCars - 1);
-  return object.race.totalCars <= 1 ? 0 : (object.race.position - 1) / total;
+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 rays = sensors.rays.enabled ? buildRaySensors(sensorCar, snapshot, sensors.rays, rayBatchContextForSensors(sensors, getRayBatchContext)) : [];
+  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,
+    nearbyCars,
+  };
+  return buildObservationVector(source, sensors, {
+    includeSchema: false,
+    vectorType: options.observation?.vectorType,
+  });
 }
 
-function ratio(value, max) {
-  const finite = Number.isFinite(value) ? value : max;
-  return Math.max(0, Math.min(1, finite / Math.max(1e-9, max)));
+function rayBatchContextForSensors(sensors, getRayBatchContext) {
+  if (!getRayBatchContext || !sensors.rays?.channels?.includes('car')) return null;
+  return getRayBatchContext();
 }
 
-function clampRatio(value) {
-  return Math.max(-1, Math.min(1, Number.isFinite(value) ? value : 0));
+export function defaultSensorOptions(options) {
+  return {
+    rays: normalizeRayOptions(options.sensors.rays),
+    nearbyCars: options.sensors.nearbyCars,
+  };
 }
 
-function effectiveSensorOptions(options, driverId) {
+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: {
-      ...options.sensors.rays,
-      ...(options.sensorsByDriver?.[driverId]?.rays ?? {}),
-    },
+    rays: normalizeRayOptions(mergeDriverRayOptions(options.sensors.rays, rayOverrides)),
     nearbyCars: {
       ...options.sensors.nearbyCars,
       ...(options.sensorsByDriver?.[driverId]?.nearbyCars ?? {}),
@@ -241,6 +252,25 @@ function effectiveSensorOptions(options, driverId) {
   };
 }
 
+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: {
@@ -249,9 +279,18 @@ function emptyObservation(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,
@@ -271,6 +310,16 @@ function emptyObservation(driverId) {
         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: [],
@@ -282,3 +331,12 @@ function emptyObservation(driverId) {
     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,11 +1,16 @@
 import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
 import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
-import { normalizeLookaheadMeters } from './observationOptions.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';
 
 const DEFAULT_SEED = 1971;
 const DEFAULT_FRAME_SKIP = 1;
 const DEFAULT_MAX_STEPS = 10000;
+const RESULT_STATE_OUTPUTS = new Set(['full', 'minimal', 'none']);
+const RESET_OBSERVATION_SCOPES = new Set(['all', 'reset']);
 
 const DEFAULT_SENSOR_OPTIONS = {
   rays: {
@@ -37,6 +42,7 @@ export function resolveEnvironmentOptions(options = {}) {
     ...options,
     seed,
     trackSeed,
+    trackGeneration: options.trackGeneration ?? {},
     totalLaps: options.totalLaps,
     drivers: normalizedDrivers,
   };
@@ -60,16 +66,19 @@ export function resolveEnvironmentOptions(options = {}) {
     }
   });
 
+  const externalRenderer = normalizeExternalRenderer(options.externalRenderer);
+
   return {
     ...resolved,
+    physicsMode: normalizePhysicsMode(options.physicsMode),
+    warmup: normalizeWarmupOptions(options.warmup, 'environment'),
     drivers: participantDrivers,
     controlledDrivers,
     frameSkip: normalizePositiveInteger(options.frameSkip, DEFAULT_FRAME_SKIP, 'frameSkip'),
     actionPolicy: options.actionPolicy === 'report' ? 'report' : 'strict',
     scenario,
     observation: {
-      ...(options.observation ?? {}),
-      lookaheadMeters: normalizeLookaheadMeters(options.observation?.lookaheadMeters),
+      ...normalizeObservationOptions(options.observation ?? {}),
     },
     sensors: mergeSensorOptions(options.sensors),
     sensorsByDriver: options.sensorsByDriver ?? {},
@@ -77,7 +86,21 @@ export function resolveEnvironmentOptions(options = {}) {
       maxSteps: normalizePositiveInteger(options.episode?.maxSteps, DEFAULT_MAX_STEPS, 'episode.maxSteps'),
       endOnRaceFinish: options.episode?.endOnRaceFinish !== false,
     },
+    result: normalizeResultOptions(options.result),
     reward: typeof options.reward === 'function' ? options.reward : null,
+    externalRenderer,
+  };
+}
+
+export function normalizeResultOptions(result = {}) {
+  const stateOutput = RESULT_STATE_OUTPUTS.has(result.stateOutput) ? result.stateOutput : 'full';
+  const resetDriversObservationScope = RESET_OBSERVATION_SCOPES.has(result.resetDriversObservationScope)
+    ? result.resetDriversObservationScope
+    : 'all';
+  return {
+    ...result,
+    stateOutput,
+    resetDriversObservationScope,
   };
 }
 
@@ -145,13 +168,22 @@ function normalizePositiveInteger(value, fallback, label) {
 
 function mergeSensorOptions(sensors = {}) {
   return {
-    rays: {
+    rays: normalizeRayOptions({
       ...DEFAULT_SENSOR_OPTIONS.rays,
       ...(sensors.rays ?? {}),
-    },
+    }),
     nearbyCars: {
       ...DEFAULT_SENSOR_OPTIONS.nearbyCars,
       ...(sensors.nearbyCars ?? {}),
     },
   };
 }
+
+function normalizeExternalRenderer(value) {
+  if (value == null) return null;
+  if (typeof value === 'function') return { onFrame: value };
+  if (typeof value === 'object' && typeof value.onFrame === 'function') {
+    return { onFrame: value.onFrame };
+  }
+  throw new Error('PaddockJS environment externalRenderer must be a function or an object with onFrame(frame).');
+}

package/src/environment/recorder.js

@@ -10,19 +10,26 @@ export function createRolloutRecorder() {
       transitions.length = 0;
     },
     toJSON() {
-      return transitions.map((entry) => ({ ...entry }));
+      return transitions.map((entry) => cloneTrainingValue(entry));
     },
   };
 }
 
 export function createRolloutTransition(previousResult, action, nextResult) {
   return {
-    observation: previousResult.observation,
-    action,
-    reward: nextResult.reward,
-    nextObservation: nextResult.observation,
+    observation: cloneTrainingValue(previousResult.observation),
+    action: cloneTrainingValue(action),
+    reward: cloneTrainingValue(nextResult.reward),
+    nextObservation: cloneTrainingValue(nextResult.observation),
     terminated: nextResult.terminated,
     truncated: nextResult.truncated,
-    info: nextResult.info,
+    info: cloneTrainingValue(nextResult.info),
   };
 }
+
+function cloneTrainingValue(value) {
+  if (value == null || typeof value !== 'object') return value;
+  if (ArrayBuffer.isView(value)) return Array.from(value);
+  if (Array.isArray(value)) return value.map(cloneTrainingValue);
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneTrainingValue(entry)]));
+}

package/src/environment/rewards.js

@@ -19,8 +19,10 @@ export function createProgressReward(options = {}) {
     const currentCar = findSnapshotCar(context.state?.snapshot, driverId);
     const progressMeters = getProgressMeters(previousCar, currentCar);
     const self = context.current?.object?.self ?? {};
-    const speedKph = Number(self.speedKph ?? 0);
-    const isOnTrack = self.onTrack !== false;
+    const speedKph = Number(self.speedKph ?? currentCar?.speedKph ?? 0);
+    const isOnTrack = context.metrics?.offTrack != null
+      ? !context.metrics.offTrack
+      : self.onTrack ?? isSnapshotCarOnTrack(currentCar);
     const collisionCount = countDriverCollisions(context.events, driverId);
     const steering = Math.abs(Number(context.action?.steering ?? 0));
     const brake = Math.abs(Number(context.action?.brake ?? 0));
@@ -49,6 +51,15 @@ function getProgressMeters(previousCar, currentCar) {
   return current - previous;
 }
 
+function isSnapshotCarOnTrack(car) {
+  if (!car) return true;
+  if (car.inPitLane) return true;
+  if (Array.isArray(car.wheels) && car.wheels.length > 0) {
+    return car.wheels.every((wheel) => wheel.onTrack || wheel.inPitLane);
+  }
+  return ['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box'].includes(car.surface ?? 'track');
+}
+
 function countDriverCollisions(events = [], driverId) {
   if (!driverId || !Array.isArray(events)) return 0;
   return events.filter((event) => isCollisionEvent(event) && eventIncludesDriver(event, driverId)).length;