@inventure71/paddockjs 0.3.0 → 1.0.0

package/src/environment/index.js

@@ -1,2 +1,15 @@
 export { createPaddockEnvironment } from './runtime.js';
 export { createProgressReward } from './rewards.js';
+export { createRolloutRecorder, createRolloutTransition } from './recorder.js';
+export {
+  DEFAULT_EVALUATION_CASES,
+  createEvaluationTracker,
+  runEnvironmentEvaluation,
+} from './evaluation.js';
+export {
+  ENVIRONMENT_SCENARIO_PRESETS,
+} from './scenarios.js';
+export {
+  createEnvironmentWorkerProtocol,
+  handleEnvironmentMessage,
+} from './workerProtocol.js';

package/src/environment/observationOptions.js

@@ -0,0 +1,12 @@
+export const DEFAULT_VECTOR_LOOKAHEAD_METERS = Object.freeze([20, 50, 100, 150]);
+
+export function normalizeLookaheadMeters(value) {
+  if (value == null) return [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
+  if (!Array.isArray(value)) return [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
+
+  const distances = value
+    .map((item) => Number(item))
+    .filter((item) => Number.isFinite(item));
+
+  return distances.length ? distances : [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
+}

package/src/environment/observations.js

@@ -1,24 +1,43 @@
-import { simSpeedToMetersPerSecond, simUnitsToMeters } from '../simulation/units.js';
+import { metersToSimUnits, simSpeedToMetersPerSecond, simUnitsToMeters } from '../simulation/units.js';
+import { normalizeAngle } from '../simulation/simMath.js';
+import { pointAt } from '../simulation/trackModel.js';
+import { normalizeLookaheadMeters } from './observationOptions.js';
 import { buildNearbyCars, buildRaySensors } from './sensors.js';
 
 export function buildEnvironmentObservation({ snapshot, options, events = [] }) {
+  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 car = snapshot.cars.find((entry) => entry.id === driverId);
+    const car = carsById.get(driverId);
     if (!car) return [driverId, emptyObservation(driverId)];
 
-    const driverEvents = events.filter((event) =>
-      event.driverId === driverId ||
-      event.carId === driverId ||
-      event.otherCarId === driverId ||
-      event.driverIds?.includes?.(driverId));
-    const object = buildDriverObservationObject(car, snapshot, options, driverEvents);
-    const { vector, schema } = buildDriverVector(object);
+    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 buildDriverObservationObject(car, snapshot, options, events) {
-  const sensors = effectiveSensorOptions(options, car.id);
+function groupEventsByDriver(events, controlledDrivers) {
+  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([
+      event.driverId,
+      event.carId,
+      event.otherCarId,
+      ...(event.driverIds ?? []),
+    ].filter(Boolean));
+    driverIds.forEach((driverId) => {
+      if (controlledSet.has(driverId)) byDriver.get(driverId)?.push(event);
+    });
+  });
+  return byDriver;
+}
+
+function buildDriverObservationObject(car, snapshot, options, events, sensors) {
   return {
     self: {
       id: car.id,
@@ -32,41 +51,183 @@ function buildDriverObservationObject(car, snapshot, options, events) {
       completedLaps: car.lapTelemetry?.completedLaps ?? 0,
       lapProgressMeters: simUnitsToMeters(car.progress ?? 0),
       trackOffsetMeters: simUnitsToMeters(car.signedOffset ?? 0),
-      trackHeadingErrorRadians: car.trackHeadingError ?? 0,
-      onTrack: (car.surface ?? 'track') === 'track',
+      trackHeadingErrorRadians: car.trackHeadingError ?? estimateTrackHeadingError(car, snapshot),
+      onTrack: isCarLegallyOnTrack(car),
       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,
     },
     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(car, snapshot, sensors.rays) : [],
     nearbyCars: sensors.nearbyCars.enabled ? buildNearbyCars(car, snapshot, sensors.nearbyCars) : [],
     events,
   };
 }
 
-function buildDriverVector(object) {
+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 = normalizeLookaheadMeters(options.observation?.lookaheadMeters);
+  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) {
   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: 'race.position', scale: 'fixed:field-position' },
+    { 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.race.position,
+    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 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 ratio(value, max) {
+  const finite = Number.isFinite(value) ? value : max;
+  return Math.max(0, Math.min(1, finite / Math.max(1e-9, max)));
+}
+
+function clampRatio(value) {
+  return Math.max(-1, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+
 function effectiveSensorOptions(options, driverId) {
   return {
     rays: {
@@ -98,9 +259,20 @@ function emptyObservation(driverId) {
         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,
       },
-      race: { position: 0, totalCars: 0, raceMode: 'missing', totalLaps: 0 },
+      race: { position: 0, totalCars: 0, raceMode: 'missing', pitLaneOpen: false, redFlag: false, totalLaps: 0 },
+      track: { lengthMeters: 0, widthMeters: 0, curvature: 0, lookahead: [] },
       rays: [],
       nearbyCars: [],
       events: [],

package/src/environment/options.js

@@ -1,5 +1,7 @@
 import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
 import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
+import { normalizeLookaheadMeters } from './observationOptions.js';
+import { resolveScenarioPlacementConfig } from './scenarios.js';
 
 const DEFAULT_SEED = 1971;
 const DEFAULT_FRAME_SKIP = 1;
@@ -65,6 +67,10 @@ export function resolveEnvironmentOptions(options = {}) {
     frameSkip: normalizePositiveInteger(options.frameSkip, DEFAULT_FRAME_SKIP, 'frameSkip'),
     actionPolicy: options.actionPolicy === 'report' ? 'report' : 'strict',
     scenario,
+    observation: {
+      ...(options.observation ?? {}),
+      lookaheadMeters: normalizeLookaheadMeters(options.observation?.lookaheadMeters),
+    },
     sensors: mergeSensorOptions(options.sensors),
     sensorsByDriver: options.sensorsByDriver ?? {},
     episode: {
@@ -118,6 +124,7 @@ function resolveScenario(scenario = {}, controlledDrivers, driverIds) {
   return {
     participants,
     nonControlled: 'ai',
+    ...resolveScenarioPlacementConfig(scenario, driverIds),
   };
 }
 

package/src/environment/recorder.js

@@ -0,0 +1,28 @@
+export function createRolloutRecorder() {
+  const transitions = [];
+  return {
+    recordStep(previousResult, action, nextResult) {
+      const transition = createRolloutTransition(previousResult, action, nextResult);
+      transitions.push(transition);
+      return transition;
+    },
+    clear() {
+      transitions.length = 0;
+    },
+    toJSON() {
+      return transitions.map((entry) => ({ ...entry }));
+    },
+  };
+}
+
+export function createRolloutTransition(previousResult, action, nextResult) {
+  return {
+    observation: previousResult.observation,
+    action,
+    reward: nextResult.reward,
+    nextObservation: nextResult.observation,
+    terminated: nextResult.terminated,
+    truncated: nextResult.truncated,
+    info: nextResult.info,
+  };
+}

package/src/environment/runtime.js

@@ -1,21 +1,22 @@
 import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.js';
-import { resolveActionMap } from './actions.js';
+import { handleActionError, resolveActionMap } from './actions.js';
 import { collectStepEvents } from './events.js';
 import { createEpisodeState, evaluateEpisode } from './episode.js';
 import { buildEnvironmentObservation } from './observations.js';
 import { resolveEnvironmentOptions } from './options.js';
+import { applyEnvironmentScenario } from './scenarios.js';
 import { buildActionSpec, buildObservationSpec } from './specs.js';
 
 export function createPaddockEnvironment(options = {}) {
   let resolvedOptions = resolveEnvironmentOptions(options);
-  let sim = createRaceSimulation(resolvedOptions);
+  let sim = createSimulationWithEnvironmentScenario(resolvedOptions);
   return createEnvironmentRuntime({
     getSimulation: () => sim,
     setSimulation(nextSim) {
       sim = nextSim;
     },
     createSimulation(nextOptions) {
-      return createRaceSimulation(nextOptions);
+      return createSimulationWithEnvironmentScenario(nextOptions);
     },
     getOptions: () => resolvedOptions,
     setOptions(nextOptions) {
@@ -26,9 +27,17 @@ export function createPaddockEnvironment(options = {}) {
   });
 }
 
+function createSimulationWithEnvironmentScenario(options) {
+  const sim = createRaceSimulation(options);
+  applyEnvironmentScenario(sim, options);
+  return sim;
+}
+
 export function createEnvironmentRuntime(host) {
   const episodeState = createEpisodeState();
 
+  initializeControlledPitIntent(host);
+
   function reset(nextOptions = {}) {
     const options = resolveEnvironmentOptions({
       ...host.getOptions(),
@@ -36,6 +45,7 @@ export function createEnvironmentRuntime(host) {
     });
     host.setOptions(options);
     host.setSimulation(host.createSimulation(options));
+    initializeControlledPitIntent(host);
     episodeState.step = 0;
     episodeState.previousSnapshot = null;
     const result = buildResult({ host, episodeState, events: [], actionErrors: [] });
@@ -47,19 +57,28 @@ export function createEnvironmentRuntime(host) {
   function step(actions = {}) {
     const options = host.getOptions();
     const sim = host.getSimulation();
-    const { controlsByDriver, errors } = resolveActionMap(actions, options.controlledDrivers, {
+    const { controlsByDriver, pitIntentByDriver, errors } = resolveActionMap(actions, options.controlledDrivers, {
       policy: options.actionPolicy,
     });
 
     Object.entries(controlsByDriver).forEach(([driverId, controls]) => {
       sim.setCarControls(driverId, controls);
     });
+    Object.entries(pitIntentByDriver).forEach(([driverId, pitIntent]) => {
+      const applied = Boolean(sim.setPitIntent?.(driverId, pitIntent));
+      if (!applied && !isNoopPitIntent(pitIntent)) {
+        handleActionError(`Pit intent could not be applied for controlled driver: ${driverId}`, options.actionPolicy, errors);
+      }
+    });
 
-    episodeState.previousSnapshot = sim.snapshot();
+    episodeState.previousSnapshot = episodeState.lastResult?.state?.snapshot ?? sim.snapshot();
     const stepEvents = [];
     for (let index = 0; index < options.frameSkip; index += 1) {
       sim.step(FIXED_STEP);
-      stepEvents.push(...collectStepEvents(sim.snapshot().events));
+      const events = typeof sim.consumeStepEvents === 'function'
+        ? sim.consumeStepEvents()
+        : sim.events;
+      stepEvents.push(...collectStepEvents(events));
     }
     episodeState.step += 1;
     const result = buildResult({ host, episodeState, events: stepEvents, actionErrors: errors, actions });
@@ -93,6 +112,22 @@ export function createEnvironmentRuntime(host) {
   return { reset, step, getObservation, getState, getActionSpec, getObservationSpec, destroy };
 }
 
+function isNoopPitIntent(pitIntent) {
+  if (pitIntent && typeof pitIntent === 'object') {
+    return Number(pitIntent.intent ?? pitIntent.pitIntent) === 0;
+  }
+  return Number(pitIntent) === 0;
+}
+
+function initializeControlledPitIntent(host) {
+  const sim = host.getSimulation?.();
+  const options = host.getOptions?.();
+  options?.controlledDrivers?.forEach?.((driverId) => {
+    sim?.setAutomaticPitIntentEnabled?.(driverId, false);
+    sim?.setPitIntent?.(driverId, 0);
+  });
+}
+
 function buildResult({ host, episodeState, events, actionErrors, actions = {} }) {
   const options = host.getOptions();
   const snapshot = host.getSimulation().snapshot();

package/src/environment/scenarios.js

@@ -0,0 +1,220 @@
+import { normalizeAngle } from '../simulation/simMath.js';
+import { offsetTrackPoint, pointAt } from '../simulation/trackModel.js';
+import { kphToSimSpeed, metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+
+export const ENVIRONMENT_SCENARIO_PRESETS = Object.freeze([
+  'cornering',
+  'off-track-recovery',
+  'overtaking-pack',
+  'pit-entry',
+]);
+
+export function resolveScenarioPlacementConfig(scenario = {}, driverIds = new Set()) {
+  const preset = scenario.preset == null ? null : String(scenario.preset);
+  if (preset && !ENVIRONMENT_SCENARIO_PRESETS.includes(preset)) {
+    throw new Error(`PaddockJS environment scenario.preset must be one of: ${ENVIRONMENT_SCENARIO_PRESETS.join(', ')}.`);
+  }
+
+  const placements = normalizePlacementMap(scenario.placements, driverIds);
+  const traffic = normalizeTrafficLayout(scenario.traffic, driverIds);
+
+  return {
+    preset,
+    placements,
+    traffic,
+  };
+}
+
+export function applyEnvironmentScenario(sim, options) {
+  const scenario = options.scenario ?? {};
+  if (!scenario.preset && Object.keys(scenario.placements ?? {}).length === 0 && (scenario.traffic ?? []).length === 0) {
+    return;
+  }
+
+  const snapshot = sim.snapshot();
+  const carsById = new Map(snapshot.cars.map((car) => [car.id, car]));
+  const placements = {
+    ...buildPresetPlacements(snapshot, options),
+    ...(scenario.placements ?? {}),
+  };
+
+  Object.entries(placements).forEach(([driverId, placement]) => {
+    if (!carsById.has(driverId)) return;
+    applyPlacement(sim, snapshot.track, carsById.get(driverId), driverId, placement);
+  });
+
+  const nextSnapshot = sim.snapshot();
+  const nextCarsById = new Map(nextSnapshot.cars.map((car) => [car.id, car]));
+  scenario.traffic?.forEach((trafficPlacement) => {
+    const reference = nextCarsById.get(trafficPlacement.relativeTo);
+    const car = nextCarsById.get(trafficPlacement.driverId);
+    if (!reference || !car) return;
+    applyPlacement(sim, nextSnapshot.track, car, trafficPlacement.driverId, {
+      distanceMeters: reference.distanceMeters + trafficPlacement.deltaDistanceMeters,
+      offsetMeters: trafficPlacement.offsetMeters,
+      speedKph: trafficPlacement.speedKph ?? reference.speedKph,
+      headingErrorRadians: trafficPlacement.headingErrorRadians ?? 0,
+    });
+  });
+}
+
+function normalizePlacementMap(value, driverIds) {
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('PaddockJS environment scenario.placements must be an object keyed by driver id.');
+  }
+  return Object.fromEntries(Object.entries(value).map(([driverId, placement]) => {
+    assertKnownDriver(driverId, driverIds, 'scenario placement');
+    return [driverId, normalizePlacement(placement, `scenario.placements.${driverId}`)];
+  }));
+}
+
+function normalizeTrafficLayout(value, driverIds) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error('PaddockJS environment scenario.traffic must be an array.');
+  }
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== 'object') {
+      throw new Error(`PaddockJS environment scenario.traffic[${index}] must be an object.`);
+    }
+    assertKnownDriver(entry.driverId, driverIds, `scenario.traffic[${index}].driverId`);
+    assertKnownDriver(entry.relativeTo, driverIds, `scenario.traffic[${index}].relativeTo`);
+    return {
+      driverId: entry.driverId,
+      relativeTo: entry.relativeTo,
+      deltaDistanceMeters: finiteNumber(entry.deltaDistanceMeters, 0, `scenario.traffic[${index}].deltaDistanceMeters`),
+      offsetMeters: finiteNumber(entry.offsetMeters, 0, `scenario.traffic[${index}].offsetMeters`),
+      speedKph: optionalFiniteNumber(entry.speedKph, `scenario.traffic[${index}].speedKph`),
+      headingErrorRadians: finiteNumber(entry.headingErrorRadians, 0, `scenario.traffic[${index}].headingErrorRadians`),
+    };
+  });
+}
+
+function normalizePlacement(placement, label) {
+  if (!placement || typeof placement !== 'object') {
+    throw new Error(`PaddockJS environment ${label} must be an object.`);
+  }
+  const distanceMeters = placement.distanceMeters ?? placement.startDistanceMeters;
+  return {
+    distanceMeters: optionalFiniteNumber(distanceMeters, `${label}.distanceMeters`),
+    offsetMeters: finiteNumber(placement.offsetMeters, 0, `${label}.offsetMeters`),
+    speedKph: optionalFiniteNumber(placement.speedKph, `${label}.speedKph`),
+    headingErrorRadians: finiteNumber(placement.headingErrorRadians, 0, `${label}.headingErrorRadians`),
+  };
+}
+
+function buildPresetPlacements(snapshot, options) {
+  const preset = options.scenario?.preset;
+  if (!preset) return {};
+  const controlledDriverId = options.controlledDrivers[0];
+  const cars = snapshot.cars;
+  const track = snapshot.track;
+  const primaryDistance = presetBaseDistance(track, preset);
+  const placements = {};
+
+  if (preset === 'cornering') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: 0,
+      speedKph: 135,
+      headingErrorRadians: 0,
+    };
+  } else if (preset === 'off-track-recovery') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: simUnitsToMeters(track.width / 2) + 7,
+      speedKph: 52,
+      headingErrorRadians: -0.45,
+    };
+  } else if (preset === 'pit-entry') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: 0,
+      speedKph: 120,
+      headingErrorRadians: 0,
+    };
+  } else if (preset === 'overtaking-pack') {
+    const baseMeters = simUnitsToMeters(primaryDistance);
+    cars.slice(0, 4).forEach((car, index) => {
+      placements[car.id] = {
+        distanceMeters: baseMeters + (index - 1) * 18,
+        offsetMeters: index % 2 === 0 ? -2.2 : 2.2,
+        speedKph: 135 - index * 3,
+        headingErrorRadians: 0,
+      };
+    });
+  }
+
+  return placements;
+}
+
+function presetBaseDistance(track, preset) {
+  if (preset === 'cornering') return findHighCurvatureDistance(track) - metersToSimUnits(70);
+  if (preset === 'off-track-recovery') return track.length * 0.42;
+  if (preset === 'overtaking-pack') return track.length * 0.35;
+  if (preset === 'pit-entry') {
+    const pitDistance = track.pitLane?.entry?.trackDistance ??
+      track.pitLane?.entry?.distanceFromStart ??
+      track.length * 0.92;
+    return pitDistance - metersToSimUnits(170);
+  }
+  return 0;
+}
+
+function findHighCurvatureDistance(track) {
+  const samples = Array.isArray(track.samples) ? track.samples : [];
+  const fallback = track.length * 0.25;
+  const best = samples
+    .filter((sample) => sample.distance > metersToSimUnits(350))
+    .reduce((selected, sample) => {
+      if (!selected || (sample.curvature ?? 0) > (selected.curvature ?? 0)) return sample;
+      return selected;
+    }, null);
+  return best?.distance ?? fallback;
+}
+
+function applyPlacement(sim, track, currentCar, driverId, placement) {
+  const currentDistanceMeters = currentCar.distanceMeters ?? simUnitsToMeters(currentCar.raceDistance ?? currentCar.progress ?? 0);
+  const raceDistance = metersToSimUnits(Math.max(0, placement.distanceMeters ?? currentDistanceMeters));
+  const offset = metersToSimUnits(placement.offsetMeters ?? 0);
+  const base = pointAt(track, raceDistance);
+  const position = offsetTrackPoint(base, offset);
+  const heading = normalizeAngle(base.heading + (placement.headingErrorRadians ?? 0));
+  const partial = {
+    x: position.x,
+    y: position.y,
+    previousX: position.x,
+    previousY: position.y,
+    progress: base.distance,
+    raceDistance,
+    desiredOffset: offset,
+    heading,
+    previousHeading: heading,
+  };
+  if (placement.speedKph != null) partial.speed = kphToSimSpeed(placement.speedKph);
+  sim.setCarState(driverId, partial);
+}
+
+function assertKnownDriver(driverId, driverIds, label) {
+  if (typeof driverId !== 'string' || driverId.length === 0) {
+    throw new Error(`PaddockJS environment ${label} must be a driver id.`);
+  }
+  if (!driverIds.has(driverId)) {
+    throw new Error(`PaddockJS environment ${label} does not exist: ${driverId}`);
+  }
+}
+
+function finiteNumber(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number)) {
+    throw new Error(`PaddockJS environment ${label} must be a finite number.`);
+  }
+  return number;
+}
+
+function optionalFiniteNumber(value, label) {
+  if (value == null) return undefined;
+  return finiteNumber(value, undefined, label);
+}