@inventure71/paddockjs 0.2.0 → 0.3.0

package/src/app/domBindings.js

@@ -45,7 +45,6 @@ export function querySimulatorDom(root) {
     telemetryDrawerWorkbench: root.querySelector('[data-race-telemetry-drawer]'),
     telemetryDrawer: root.querySelector('[data-telemetry-drawer]'),
     telemetryDrawerToggle: root.querySelector('[data-telemetry-drawer-toggle]'),
-    telemetryDrawerClose: root.querySelector('[data-telemetry-drawer-close]'),
     raceDataPanel: root.querySelector('[data-race-data-panel]'),
     raceDataKicker: root.querySelector('[data-race-data-kicker]'),
     raceDataTitle: root.querySelector('[data-race-data-title]'),

package/src/config/defaultOptions.js

@@ -25,6 +25,7 @@ export const DEFAULT_F1_SIMULATOR_OPTIONS = {
       sectorTimes: true,
     },
     showRaceDataPanel: true,
+    raceDataTelemetryDetail: false,
     raceDataBanners: {
       initial: 'project',
       enabled: ['project', 'radio'],
@@ -109,6 +110,8 @@ export const PADDOCK_THEME_CSS_VARIABLES = {
   raceViewMinHeight: '--paddock-race-view-min-height',
 };
 
+const SUPPORTED_CAMERA_MODES = new Set(['overview', 'leader', 'selected', 'show-all']);
+
 export function resolveF1SimulatorOptions(options = {}) {
   const presetName = Object.hasOwn(PADDOCK_SIMULATOR_PRESETS, options.preset)
     ? options.preset
@@ -140,6 +143,10 @@ export function resolveF1SimulatorOptions(options = {}) {
   if (!['auto', 'custom'].includes(ui.raceDataBannerSize)) {
     ui.raceDataBannerSize = DEFAULT_F1_SIMULATOR_OPTIONS.ui.raceDataBannerSize;
   }
+  ui.raceDataTelemetryDetail = Boolean(ui.raceDataTelemetryDetail);
+  const initialCameraMode = SUPPORTED_CAMERA_MODES.has(options.initialCameraMode)
+    ? options.initialCameraMode
+    : DEFAULT_F1_SIMULATOR_OPTIONS.initialCameraMode;
   const mergedOptions = {
     ...DEFAULT_F1_SIMULATOR_OPTIONS,
     ...preset,
@@ -159,6 +166,7 @@ export function resolveF1SimulatorOptions(options = {}) {
     ...preset,
     ...options,
     preset: presetName ?? options.preset,
+    initialCameraMode,
     ui,
     theme,
     drivers,

package/src/data/championship.js

@@ -136,6 +136,7 @@ function pickUniqueTimingCode(source, usedCodes) {
 function assertUniqueDriverNumbers(entries) {
   const seen = new Set();
   entries.forEach((entry) => {
+    if (entry.driverNumber == null) return;
     if (seen.has(entry.driverNumber)) {
       throw new Error(`Duplicate championship driver number: ${entry.driverNumber}`);
     }
@@ -143,6 +144,17 @@ function assertUniqueDriverNumbers(entries) {
   });
 }
 
+function assertUniqueEntryDriverIds(entries) {
+  const seen = new Set();
+  entries.forEach((entry) => {
+    if (entry.driverId == null) return;
+    if (seen.has(entry.driverId)) {
+      throw new Error(`Duplicate championship entry driver id: ${entry.driverId}`);
+    }
+    seen.add(entry.driverId);
+  });
+}
+
 function buildDriverConstructorArgs(entry) {
   const driver = entry.driver instanceof DriverData
     ? entry.driver
@@ -181,6 +193,7 @@ function normalizeTeam(team, driver, timingCode) {
 }
 
 export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entries = CHAMPIONSHIP_DRIVER_ENTRIES) {
+  assertUniqueEntryDriverIds(entries);
   assertUniqueDriverNumbers(entries);
 
   const entryByDriverId = new Map(entries.map((entry) => [entry.driverId, entry]));

package/src/data/normalizeDrivers.js

@@ -1,10 +1,11 @@
 import { buildChampionshipDriverGrid } from './championship.js';
 
-export function normalizeSimulatorDrivers(drivers, { entries } = {}) {
+export function normalizeSimulatorDrivers(drivers, { entries, caller = 'mountF1Simulator' } = {}) {
   if (!Array.isArray(drivers) || drivers.length === 0) {
-    throw new Error('mountF1Simulator requires a non-empty drivers array.');
+    throw new Error(`${caller} requires a non-empty drivers array.`);
   }
 
+  const seenDriverIds = new Set();
   drivers.forEach((driver, index) => {
     if (!driver || typeof driver !== 'object') {
       throw new Error(`Invalid simulator driver at index ${index}.`);
@@ -12,6 +13,10 @@ export function normalizeSimulatorDrivers(drivers, { entries } = {}) {
     if (!driver.id) {
       throw new Error(`Simulator driver at index ${index} is missing an id.`);
     }
+    if (seenDriverIds.has(driver.id)) {
+      throw new Error(`Duplicate simulator driver id: ${driver.id}`);
+    }
+    seenDriverIds.add(driver.id);
     if (!driver.name) {
       throw new Error(`Simulator driver "${driver.id}" is missing a name.`);
     }

package/src/environment/actions.js

@@ -0,0 +1,45 @@
+import { clamp } from '../simulation/simMath.js';
+import { VEHICLE_LIMITS } from '../simulation/vehiclePhysics.js';
+
+export function resolveActionMap(actions = {}, controlledDrivers = [], { policy = 'strict' } = {}) {
+  const errors = [];
+  const controlsByDriver = {};
+
+  controlledDrivers.forEach((driverId) => {
+    const action = actions?.[driverId];
+    if (!action || typeof action !== 'object') {
+      handleActionError(`Missing action for controlled driver: ${driverId}`, policy, errors);
+      return;
+    }
+    const normalized = normalizeAction(action, driverId, policy, errors);
+    if (normalized) controlsByDriver[driverId] = normalized;
+  });
+
+  return { controlsByDriver, errors };
+}
+
+export function normalizeAction(action, driverId = 'unknown', policy = 'strict', errors = []) {
+  const steering = finiteActionValue(action.steering, `Invalid steering action for controlled driver: ${driverId}`, policy, errors);
+  const throttle = finiteActionValue(action.throttle, `Invalid throttle action for controlled driver: ${driverId}`, policy, errors);
+  const brake = finiteActionValue(action.brake, `Invalid brake action for controlled driver: ${driverId}`, policy, errors);
+
+  if (steering == null || throttle == null || brake == null) return null;
+
+  return {
+    steering: clamp(steering, -1, 1) * VEHICLE_LIMITS.maxSteer,
+    throttle: clamp(throttle, 0, 1),
+    brake: clamp(brake, 0, 1),
+  };
+}
+
+function finiteActionValue(value, message, policy, errors) {
+  const number = Number(value ?? 0);
+  if (Number.isFinite(number)) return number;
+  handleActionError(message, policy, errors);
+  return null;
+}
+
+function handleActionError(message, policy, errors) {
+  if (policy === 'strict') throw new Error(message);
+  errors.push(message);
+}

package/src/environment/episode.js

@@ -0,0 +1,17 @@
+export function createEpisodeState() {
+  return {
+    step: 0,
+    previousSnapshot: null,
+    lastResult: null,
+  };
+}
+
+export function evaluateEpisode(snapshot, options, episodeState) {
+  if (snapshot.raceControl.finished && options.episode.endOnRaceFinish) {
+    return { terminated: true, truncated: false, endReason: 'race-finish' };
+  }
+  if (episodeState.step >= options.episode.maxSteps) {
+    return { terminated: false, truncated: true, endReason: 'max-steps' };
+  }
+  return { terminated: false, truncated: false, endReason: null };
+}

package/src/environment/events.js

@@ -0,0 +1,17 @@
+export function collectStepEvents(events = []) {
+  return events.map((event) => normalizeEnvironmentEvent(event));
+}
+
+function normalizeEnvironmentEvent(event) {
+  if (event.type === 'contact') {
+    return {
+      ...event,
+      type: 'collision',
+      driverIds: [event.carId, event.otherCarId].filter(Boolean),
+      primaryDriverId: event.carId ?? null,
+      otherDriverId: event.otherCarId ?? null,
+      severity: event.severity ?? null,
+    };
+  }
+  return { ...event };
+}

package/src/environment/index.d.ts

@@ -0,0 +1,241 @@
+export type TireCompound = 'S' | 'M' | 'H';
+
+export interface TeamData {
+  id?: string;
+  name?: string;
+  color?: string;
+  icon?: string;
+}
+
+export interface SimulatorDriver {
+  id: string;
+  name: string;
+  color: string;
+  link?: string;
+  icon?: string;
+  code?: string;
+  timingName?: string;
+  tire?: TireCompound;
+  raceData?: string[];
+  customFields?: Array<{ label: string; value: string }> | Record<string, string>;
+  team?: TeamData | null;
+  driverNumber?: number;
+}
+
+export interface ChampionshipEntryBlueprint {
+  driverId: string;
+  driverNumber?: number;
+  timingName?: string;
+  driver?: unknown;
+  vehicle?: unknown;
+  team?: TeamData;
+}
+
+export interface RaceEvent {
+  type: string;
+  at?: number;
+  [key: string]: unknown;
+}
+
+export interface RaceSnapshot {
+  time: number;
+  totalLaps: number;
+  raceControl: {
+    mode: string;
+    finished: boolean;
+    [key: string]: unknown;
+  };
+  track: Record<string, unknown>;
+  cars: Array<Record<string, unknown>>;
+  events: RaceEvent[];
+  [key: string]: unknown;
+}
+
+export interface PaddockAction {
+  steering: number;
+  throttle: number;
+  brake: number;
+}
+
+export type PaddockActionMap = Record<string, PaddockAction>;
+
+export interface PaddockSensorRayResult {
+  angleDegrees: number;
+  angleRadians: number;
+  lengthMeters: number;
+  track: {
+    hit: boolean;
+    distanceMeters: number;
+    kind: 'exit' | 'entry' | null;
+  };
+  car: {
+    hit: boolean;
+    distanceMeters: number;
+    driverId: string | null;
+    relativeSpeedKph: number;
+  };
+}
+
+export interface PaddockNearbyCarObservation {
+  id: string;
+  relativeForwardMeters: number;
+  relativeRightMeters: number;
+  relativeDistanceMeters: number;
+  relativeSpeedKph: number;
+  relativeHeadingRadians: number;
+  ahead: boolean;
+  sameLap: boolean;
+}
+
+export interface PaddockDriverObservationObject {
+  self: {
+    id: string;
+    speedKph: number;
+    speedMetersPerSecond: number;
+    headingRadians: number;
+    steeringAngleRadians: number;
+    throttle: number;
+    brake: number;
+    lap: number;
+    completedLaps: number;
+    lapProgressMeters: number;
+    trackOffsetMeters: number;
+    trackHeadingErrorRadians: number;
+    onTrack: boolean;
+    surface: string;
+    tireEnergy: number | null;
+  };
+  race: {
+    position: number;
+    totalCars: number;
+    raceMode: string;
+    totalLaps: number;
+  };
+  rays: PaddockSensorRayResult[];
+  nearbyCars: PaddockNearbyCarObservation[];
+  events: RaceEvent[];
+}
+
+export interface PaddockObservationSchemaEntry {
+  name: string;
+  unit?: string;
+  scale?: string;
+}
+
+export interface PaddockDriverObservation {
+  object: PaddockDriverObservationObject;
+  vector: number[];
+  schema: PaddockObservationSchemaEntry[];
+  events: RaceEvent[];
+}
+
+export interface PaddockEnvironmentOptions {
+  drivers: SimulatorDriver[];
+  entries?: ChampionshipEntryBlueprint[];
+  controlledDrivers: string[];
+  seed?: number;
+  trackSeed?: number;
+  totalLaps?: number;
+  frameSkip?: number;
+  actionPolicy?: 'strict' | 'report';
+  scenario?: {
+    participants?: 'all' | 'controlled-only' | string[];
+    nonControlled?: 'ai';
+  };
+  sensors?: {
+    rays?: {
+      enabled?: boolean;
+      anglesDegrees?: number[];
+      lengthMeters?: number;
+      detectTrack?: boolean;
+      detectCars?: boolean;
+    };
+    nearbyCars?: {
+      enabled?: boolean;
+      maxCars?: number;
+      radiusMeters?: number;
+    };
+  };
+  sensorsByDriver?: Record<string, PaddockEnvironmentOptions['sensors']>;
+  episode?: {
+    maxSteps?: number;
+    endOnRaceFinish?: boolean;
+  };
+  reward?: (payload: PaddockRewardContext) => number;
+}
+
+export interface PaddockRewardContext {
+  driverId: string;
+  previous: RaceSnapshot | null;
+  current: PaddockDriverObservation;
+  action: PaddockAction | undefined;
+  events: RaceEvent[];
+  state: { snapshot: RaceSnapshot };
+}
+
+export interface PaddockProgressRewardWeights {
+  progress: number;
+  speed: number;
+  offTrack: number;
+  collision: number;
+  steering: number;
+  brake: number;
+}
+
+export interface PaddockProgressRewardOptions {
+  weights?: Partial<PaddockProgressRewardWeights>;
+}
+
+export interface PaddockActionSpec {
+  version: 1;
+  controlledDrivers: string[];
+  action: {
+    type: 'continuous';
+    perDriver: {
+      steering: { min: -1; max: 1; unit: 'normalized' };
+      throttle: { min: 0; max: 1; unit: 'normalized' };
+      brake: { min: 0; max: 1; unit: 'normalized' };
+    };
+  };
+}
+
+export interface PaddockObservationSpec {
+  version: 1;
+  controlledDrivers: string[];
+  object: Record<string, unknown>;
+  vector: {
+    schema: PaddockObservationSchemaEntry[];
+  };
+}
+
+export interface PaddockEnvironmentResult {
+  observation: Record<string, PaddockDriverObservation>;
+  reward: null | Record<string, number>;
+  terminated: boolean;
+  truncated: boolean;
+  done: boolean;
+  events: RaceEvent[];
+  state: { snapshot: RaceSnapshot };
+  info: {
+    step: number;
+    elapsedSeconds: number;
+    seed: number;
+    trackSeed: number;
+    controlledDrivers: string[];
+    actionErrors: string[];
+    endReason: string | null;
+  };
+}
+
+export interface PaddockEnvironment {
+  reset(options?: Partial<PaddockEnvironmentOptions>): PaddockEnvironmentResult;
+  step(actions: PaddockActionMap): PaddockEnvironmentResult;
+  getObservation(): PaddockEnvironmentResult['observation'];
+  getState(): PaddockEnvironmentResult['state'];
+  getActionSpec(): PaddockActionSpec;
+  getObservationSpec(): PaddockObservationSpec;
+  destroy(): void;
+}
+
+export function createPaddockEnvironment(options: PaddockEnvironmentOptions): PaddockEnvironment;
+export function createProgressReward(options?: PaddockProgressRewardOptions): (context: PaddockRewardContext) => number;

package/src/environment/index.js

@@ -0,0 +1,2 @@
+export { createPaddockEnvironment } from './runtime.js';
+export { createProgressReward } from './rewards.js';

package/src/environment/observations.js

@@ -0,0 +1,112 @@
+import { simSpeedToMetersPerSecond, simUnitsToMeters } from '../simulation/units.js';
+import { buildNearbyCars, buildRaySensors } from './sensors.js';
+
+export function buildEnvironmentObservation({ snapshot, options, events = [] }) {
+  return Object.fromEntries(options.controlledDrivers.map((driverId) => {
+    const car = snapshot.cars.find((entry) => entry.id === 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);
+    return [driverId, { object, vector, schema, events: driverEvents }];
+  }));
+}
+
+function buildDriverObservationObject(car, snapshot, options, events) {
+  const sensors = effectiveSensorOptions(options, car.id);
+  return {
+    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,
+      lap: car.lap,
+      completedLaps: car.lapTelemetry?.completedLaps ?? 0,
+      lapProgressMeters: simUnitsToMeters(car.progress ?? 0),
+      trackOffsetMeters: simUnitsToMeters(car.signedOffset ?? 0),
+      trackHeadingErrorRadians: car.trackHeadingError ?? 0,
+      onTrack: (car.surface ?? 'track') === 'track',
+      surface: car.surface ?? 'track',
+      tireEnergy: car.tireEnergy ?? null,
+    },
+    race: {
+      position: car.rank,
+      totalCars: snapshot.cars.length,
+      raceMode: snapshot.raceControl.mode,
+      totalLaps: snapshot.totalLaps,
+    },
+    rays: sensors.rays.enabled ? buildRaySensors(car, snapshot, sensors.rays) : [],
+    nearbyCars: sensors.nearbyCars.enabled ? buildNearbyCars(car, snapshot, sensors.nearbyCars) : [],
+    events,
+  };
+}
+
+function buildDriverVector(object) {
+  const schema = [
+    { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
+    { 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' },
+  ];
+  const vector = [
+    object.self.speedKph / 400,
+    object.self.trackOffsetMeters,
+    object.self.trackHeadingErrorRadians / Math.PI,
+    object.self.onTrack ? 1 : 0,
+    object.race.position,
+  ];
+  return { vector, schema };
+}
+
+function effectiveSensorOptions(options, driverId) {
+  return {
+    rays: {
+      ...options.sensors.rays,
+      ...(options.sensorsByDriver?.[driverId]?.rays ?? {}),
+    },
+    nearbyCars: {
+      ...options.sensors.nearbyCars,
+      ...(options.sensorsByDriver?.[driverId]?.nearbyCars ?? {}),
+    },
+  };
+}
+
+function emptyObservation(driverId) {
+  return {
+    object: {
+      self: {
+        id: driverId,
+        speedKph: 0,
+        speedMetersPerSecond: 0,
+        headingRadians: 0,
+        steeringAngleRadians: 0,
+        throttle: 0,
+        brake: 0,
+        lap: 0,
+        completedLaps: 0,
+        lapProgressMeters: 0,
+        trackOffsetMeters: 0,
+        trackHeadingErrorRadians: 0,
+        onTrack: false,
+        surface: 'missing',
+        tireEnergy: null,
+      },
+      race: { position: 0, totalCars: 0, raceMode: 'missing', totalLaps: 0 },
+      rays: [],
+      nearbyCars: [],
+      events: [],
+    },
+    vector: [],
+    schema: [],
+    events: [],
+  };
+}

package/src/environment/options.js

@@ -0,0 +1,150 @@
+import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
+import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
+
+const DEFAULT_SEED = 1971;
+const DEFAULT_FRAME_SKIP = 1;
+const DEFAULT_MAX_STEPS = 10000;
+
+const DEFAULT_SENSOR_OPTIONS = {
+  rays: {
+    enabled: true,
+    anglesDegrees: [-135, -60, -20, 0, 20, 60, 135, 180],
+    lengthMeters: 120,
+    detectTrack: true,
+    detectCars: true,
+  },
+  nearbyCars: {
+    enabled: true,
+    maxCars: 6,
+    radiusMeters: 150,
+  },
+};
+
+export function resolveEnvironmentOptions(options = {}) {
+  if (!Array.isArray(options.controlledDrivers) || options.controlledDrivers.length === 0) {
+    throw new Error('PaddockJS environment controlledDrivers is required.');
+  }
+
+  const seed = normalizeSeed(options.seed, createGeneratedSeed);
+  const trackSeed = normalizeSeed(options.trackSeed, createGeneratedSeed);
+  const normalizedDrivers = normalizeSimulatorDrivers(options.drivers, {
+    entries: options.entries ?? CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+    caller: 'createPaddockEnvironment',
+  });
+  const resolved = {
+    ...options,
+    seed,
+    trackSeed,
+    totalLaps: options.totalLaps,
+    drivers: normalizedDrivers,
+  };
+  const driverIds = new Set(resolved.drivers.map((driver) => driver.id));
+  const controlledDrivers = [...new Set(options.controlledDrivers)];
+
+  controlledDrivers.forEach((driverId) => {
+    if (!driverIds.has(driverId)) {
+      throw new Error(`PaddockJS environment controlled driver does not exist: ${driverId}`);
+    }
+  });
+
+  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}`);
+    }
+  });
+
+  return {
+    ...resolved,
+    drivers: participantDrivers,
+    controlledDrivers,
+    frameSkip: normalizePositiveInteger(options.frameSkip, DEFAULT_FRAME_SKIP, 'frameSkip'),
+    actionPolicy: options.actionPolicy === 'report' ? 'report' : 'strict',
+    scenario,
+    sensors: mergeSensorOptions(options.sensors),
+    sensorsByDriver: options.sensorsByDriver ?? {},
+    episode: {
+      maxSteps: normalizePositiveInteger(options.episode?.maxSteps, DEFAULT_MAX_STEPS, 'episode.maxSteps'),
+      endOnRaceFinish: options.episode?.endOnRaceFinish !== false,
+    },
+    reward: typeof options.reward === 'function' ? options.reward : null,
+  };
+}
+
+function normalizeSeed(value, fallbackFactory) {
+  if (value == null) return fallbackFactory();
+  const number = Number(value);
+  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 (
+    participants !== 'all' &&
+    participants !== 'controlled-only' &&
+    !Array.isArray(participants)
+  ) {
+    throw new Error('PaddockJS environment scenario.participants must be "all", "controlled-only", or an array of driver ids.');
+  }
+  if (scenario.nonControlled != null && scenario.nonControlled !== 'ai') {
+    throw new Error('PaddockJS environment first slice only supports scenario.nonControlled: "ai".');
+  }
+  if (Array.isArray(participants)) {
+    participants.forEach((driverId) => {
+      if (!driverIds.has(driverId)) {
+        throw new Error(`PaddockJS environment scenario participant does not exist: ${driverId}`);
+      }
+    });
+    controlledDrivers.forEach((driverId) => {
+      if (!participants.includes(driverId)) {
+        throw new Error(`PaddockJS environment controlled driver must be included in scenario participants: ${driverId}`);
+      }
+    });
+  }
+  return {
+    participants,
+    nonControlled: 'ai',
+  };
+}
+
+function resolveParticipants(participants, controlledDrivers, drivers) {
+  if (participants === 'controlled-only') return new Set(controlledDrivers);
+  if (Array.isArray(participants)) return new Set(participants);
+  return new Set(drivers.map((driver) => driver.id));
+}
+
+function normalizePositiveInteger(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Math.floor(Number(value));
+  if (!Number.isFinite(number) || number < 1) {
+    throw new Error(`PaddockJS environment ${label} must be a positive integer.`);
+  }
+  return number;
+}
+
+function mergeSensorOptions(sensors = {}) {
+  return {
+    rays: {
+      ...DEFAULT_SENSOR_OPTIONS.rays,
+      ...(sensors.rays ?? {}),
+    },
+    nearbyCars: {
+      ...DEFAULT_SENSOR_OPTIONS.nearbyCars,
+      ...(sensors.nearbyCars ?? {}),
+    },
+  };
+}