@inventure71/paddockjs 0.2.0 → 1.0.0

package/src/app/domBindings.js

@@ -6,7 +6,9 @@ export function querySimulatorDom(root) {
     startLightsLabel: root.querySelector('[data-start-lights-label]'),
     towerLap: root.querySelector('[data-tower-lap-readout]'),
     towerTotalLaps: root.querySelector('[data-tower-total-laps]'),
-    towerSafetyBanner: root.querySelector('[data-tower-safety-banner]'),
+    towerRaceControlBanner: root.querySelector('[data-tower-race-control-banner]'),
+    towerRaceControlKicker: root.querySelector('[data-tower-race-control-kicker]'),
+    towerRaceControlTitle: root.querySelector('[data-tower-race-control-title]'),
     timingGapLabel: root.querySelector('[data-timing-gap-label]'),
     lap: root.querySelector('[data-lap-readout]'),
     drs: root.querySelector('[data-drs-readout]'),
@@ -45,13 +47,17 @@ 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]'),
+    stewardMessage: root.querySelector('[data-steward-message]'),
+    stewardMessageKicker: root.querySelector('[data-steward-message-kicker]'),
+    stewardMessageTitle: root.querySelector('[data-steward-message-title]'),
+    stewardMessageDetail: root.querySelector('[data-steward-message-detail]'),
     raceDataPanel: root.querySelector('[data-race-data-panel]'),
     raceDataKicker: root.querySelector('[data-race-data-kicker]'),
     raceDataTitle: root.querySelector('[data-race-data-title]'),
     raceDataNumber: root.querySelector('[data-race-data-number]'),
     raceDataSubtitle: root.querySelector('[data-race-data-subtitle]'),
     raceDataOpen: root.querySelector('[data-race-data-open]'),
+    raceDataDismiss: root.querySelector('[data-race-data-dismiss]'),
     finishPanel: root.querySelector('[data-race-finish-panel]'),
     finishWinner: root.querySelector('[data-race-finish-winner]'),
     finishClassification: root.querySelector('[data-race-finish-classification]'),
@@ -66,6 +72,8 @@ export function querySimulatorDom(root) {
     timingGapModeButtons: root.querySelectorAll('[data-timing-gap-mode]'),
     cameraButtons: root.querySelectorAll('[data-camera-mode]'),
     overviewModeButtons: root.querySelectorAll('[data-overview-mode]'),
+    bannerMuteButtons: root.querySelectorAll('[data-race-data-banners-muted]'),
+    simulationSpeedButtons: root.querySelectorAll('[data-simulation-speed]'),
     zoomInButton: root.querySelector('[data-zoom-in]'),
     zoomOutButton: root.querySelector('[data-zoom-out]'),
     readouts,

package/src/config/defaultOptions.js

@@ -13,7 +13,7 @@ export const DEFAULT_F1_SIMULATOR_OPTIONS = {
   showBackLink: true,
   ui: {
     layoutPreset: 'standard',
-    cameraControls: 'embedded',
+    cameraControls: 'external',
     showFps: true,
     showTimingTower: true,
     showTelemetry: true,
@@ -25,6 +25,7 @@ export const DEFAULT_F1_SIMULATOR_OPTIONS = {
       sectorTimes: true,
     },
     showRaceDataPanel: true,
+    raceDataTelemetryDetail: false,
     raceDataBanners: {
       initial: 'project',
       enabled: ['project', 'radio'],
@@ -45,7 +46,7 @@ export const PADDOCK_SIMULATOR_PRESETS = {
   dashboard: {
     ui: {
       layoutPreset: 'standard',
-      cameraControls: 'embedded',
+      cameraControls: 'external',
       showFps: true,
       showTimingTower: true,
       showTelemetry: true,
@@ -73,7 +74,7 @@ export const PADDOCK_SIMULATOR_PRESETS = {
   'compact-race': {
     ui: {
       layoutPreset: 'standard',
-      cameraControls: 'embedded',
+      cameraControls: 'external',
       showFps: false,
       showTimingTower: false,
       showTelemetry: false,
@@ -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', 'pit']);
+
 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,68 @@
+import { clamp } from '../simulation/simMath.js';
+import { VEHICLE_LIMITS } from '../simulation/vehiclePhysics.js';
+
+export function resolveActionMap(actions = {}, controlledDrivers = [], { policy = 'strict' } = {}) {
+  const errors = [];
+  const controlsByDriver = {};
+  const pitIntentByDriver = {};
+
+  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;
+    const pitIntent = normalizePitIntentAction(action, driverId, policy, errors);
+    if (pitIntent != null) pitIntentByDriver[driverId] = pitIntent;
+  });
+
+  return { controlsByDriver, pitIntentByDriver, 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 normalizePitIntentAction(action, driverId, policy, errors) {
+  if (!Object.hasOwn(action, 'pitIntent')) return null;
+  const number = Number(action.pitIntent);
+  if (Number.isInteger(number) && number >= 0 && number <= 2) {
+    const pitCompound = normalizePitCompoundAction(action, driverId, policy, errors);
+    if (pitCompound === false) return null;
+    return pitCompound == null ? number : { intent: number, targetCompound: pitCompound };
+  }
+  handleActionError(`Invalid pitIntent action for controlled driver: ${driverId}`, policy, errors);
+  return null;
+}
+
+function normalizePitCompoundAction(action, driverId, policy, errors) {
+  if (!Object.hasOwn(action, 'pitCompound') && !Object.hasOwn(action, 'pitTargetCompound')) return null;
+  const value = action.pitCompound ?? action.pitTargetCompound;
+  if (typeof value === 'string' && value.trim()) return value.trim();
+  handleActionError(`Invalid pitCompound action for controlled driver: ${driverId}`, policy, errors);
+  return false;
+}
+
+export 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/evaluation.js

@@ -0,0 +1,184 @@
+import { simUnitsToMeters } from '../simulation/units.js';
+import { createPaddockEnvironment } from './runtime.js';
+
+export const DEFAULT_EVALUATION_CASES = Object.freeze([
+  {
+    name: 'cornering',
+    seed: 7101,
+    trackSeed: 2601,
+    maxSteps: 420,
+    scenario: { preset: 'cornering' },
+  },
+  {
+    name: 'off-track-recovery',
+    seed: 7102,
+    trackSeed: 2602,
+    maxSteps: 360,
+    scenario: { preset: 'off-track-recovery' },
+  },
+  {
+    name: 'overtaking-pack',
+    seed: 7103,
+    trackSeed: 2603,
+    maxSteps: 600,
+    scenario: { preset: 'overtaking-pack' },
+  },
+  {
+    name: 'pit-entry',
+    seed: 7104,
+    trackSeed: 2604,
+    maxSteps: 480,
+    scenario: { preset: 'pit-entry' },
+  },
+]);
+
+export function runEnvironmentEvaluation({
+  baseOptions,
+  policy,
+  cases = DEFAULT_EVALUATION_CASES,
+  createEnvironment = createPaddockEnvironment,
+} = {}) {
+  if (!baseOptions || typeof baseOptions !== 'object') {
+    throw new Error('PaddockJS environment evaluation requires baseOptions.');
+  }
+  if (!policy) {
+    throw new Error('PaddockJS environment evaluation requires a policy function or object with predict().');
+  }
+
+  return {
+    cases: cases.map((evaluationCase) => runEvaluationCase({
+      baseOptions,
+      policy,
+      evaluationCase,
+      createEnvironment,
+    })),
+  };
+}
+
+export function createEvaluationTracker(initialResult) {
+  const initialCars = carsById(initialResult.state.snapshot);
+  const metrics = Object.fromEntries(initialResult.info.controlledDrivers.map((driverId) => {
+    const car = initialCars.get(driverId);
+    return [driverId, {
+      distanceMeters: 0,
+      lapProgressMeters: lapProgressMetersFromSnapshotCar(car),
+      offTrackSteps: car && car.surface !== 'track' ? 1 : 0,
+      contactCount: 0,
+      recoverySuccess: false,
+      passCount: 0,
+      lapTimeSeconds: null,
+      startedOffTrack: Boolean(car && car.surface !== 'track'),
+      startPosition: car?.rank ?? null,
+      bestPosition: car?.rank ?? null,
+      startDistanceMeters: cumulativeDistanceMetersFromSnapshotCar(car),
+    }];
+  }));
+
+  return {
+    update(result) {
+      const currentCars = carsById(result.state.snapshot);
+      result.info.controlledDrivers.forEach((driverId) => {
+        const car = currentCars.get(driverId);
+        const entry = metrics[driverId];
+        if (!car || !entry) return;
+        entry.distanceMeters = Math.max(0, cumulativeDistanceMetersFromSnapshotCar(car) - entry.startDistanceMeters);
+        entry.lapProgressMeters = lapProgressMetersFromSnapshotCar(car);
+        if (car.surface !== 'track') entry.offTrackSteps += 1;
+        if (entry.startedOffTrack && car.surface === 'track') entry.recoverySuccess = true;
+        if (Number.isFinite(car.rank)) {
+          entry.bestPosition = entry.bestPosition == null ? car.rank : Math.min(entry.bestPosition, car.rank);
+          entry.passCount = entry.startPosition == null ? 0 : Math.max(0, entry.startPosition - entry.bestPosition);
+        }
+        const completedLaps = car.lapTelemetry?.completedLaps ?? 0;
+        if (completedLaps > 0 && entry.lapTimeSeconds == null) {
+          entry.lapTimeSeconds = result.info.elapsedSeconds;
+        }
+      });
+      result.events.forEach((event) => {
+        if (event.type !== 'collision') return;
+        Object.keys(metrics).forEach((driverId) => {
+          if (event.driverId === driverId || event.carId === driverId || event.otherCarId === driverId || event.driverIds?.includes?.(driverId)) {
+            metrics[driverId].contactCount += 1;
+          }
+        });
+      });
+    },
+    finish() {
+      return Object.fromEntries(Object.entries(metrics).map(([driverId, entry]) => [
+        driverId,
+        {
+          distanceMeters: entry.distanceMeters,
+          lapProgressMeters: entry.lapProgressMeters,
+          offTrackSteps: entry.offTrackSteps,
+          contactCount: entry.contactCount,
+          recoverySuccess: entry.recoverySuccess,
+          passCount: entry.passCount,
+          lapTimeSeconds: entry.lapTimeSeconds,
+        },
+      ]));
+    },
+  };
+}
+
+function cumulativeDistanceMetersFromSnapshotCar(car) {
+  const distance = Number(car?.distanceMeters ?? car?.raceDistanceMeters);
+  if (Number.isFinite(distance)) return distance;
+  return simUnitsToMeters(car?.raceDistance ?? 0);
+}
+
+function lapProgressMetersFromSnapshotCar(car) {
+  const progressMeters = Number(car?.lapProgressMeters ?? car?.progressMeters);
+  if (Number.isFinite(progressMeters)) return progressMeters;
+  return simUnitsToMeters(car?.progress ?? 0);
+}
+
+function runEvaluationCase({ baseOptions, policy, evaluationCase, createEnvironment }) {
+  const env = createEnvironment({
+    ...baseOptions,
+    seed: evaluationCase.seed ?? baseOptions.seed,
+    trackSeed: evaluationCase.trackSeed ?? baseOptions.trackSeed,
+    scenario: {
+      ...(baseOptions.scenario ?? {}),
+      ...(evaluationCase.scenario ?? {}),
+    },
+  });
+  let result = env.reset();
+  const tracker = createEvaluationTracker(result);
+  const maxSteps = Math.max(1, Math.floor(evaluationCase.maxSteps ?? baseOptions.episode?.maxSteps ?? 1000));
+  let steps = 0;
+  while (!result.done && steps < maxSteps) {
+    const actions = Object.fromEntries(result.info.controlledDrivers.map((driverId) => [
+      driverId,
+      predictAction(policy, result.observation[driverId], {
+        driverId,
+        caseName: evaluationCase.name,
+        step: steps,
+        result,
+      }),
+    ]));
+    result = env.step(actions);
+    tracker.update(result);
+    steps += 1;
+  }
+  env.destroy?.();
+  return {
+    name: evaluationCase.name,
+    seed: evaluationCase.seed ?? baseOptions.seed,
+    trackSeed: evaluationCase.trackSeed ?? baseOptions.trackSeed,
+    steps,
+    done: result.done,
+    endReason: result.info.endReason,
+    metrics: tracker.finish(),
+  };
+}
+
+function predictAction(policy, observation, context) {
+  const action = typeof policy === 'function'
+    ? policy(observation, context)
+    : policy.predict(observation, context);
+  return action ?? { steering: 0, throttle: 0, brake: 1 };
+}
+
+function carsById(snapshot) {
+  return new Map(snapshot.cars.map((car) => [car.id, car]));
+}

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 };
+}