@inventure71/paddockjs 2.0.0 → 2.0.1

package/src/app/F1SimulatorApp.js

@@ -16,17 +16,12 @@ import { PitLaneStatusRenderer } from './rendering/pitLaneStatusRenderer.js';
 import { ReplayGhostRenderer } from './rendering/replayGhostRenderer.js';
 import { renderTrackSurface } from './rendering/trackRenderer.js';
 import {
-  formatLapGap,
-  formatRaceGap,
-  getPenaltyByDriver,
   getTimingOrderKey,
   getTimingPenaltyKey,
-  isWavedFlagCar,
   renderTimingTower,
   syncTimingGapModeControls,
 } from './readouts/timingTowerRenderer.js';
-import { formatTelemetryGap } from './readouts/readoutFormatters.js';
-import { getOverviewFields, renderCarDriverOverview } from './readouts/carOverviewRenderer.js';
+import { renderCarDriverOverview } from './readouts/carOverviewRenderer.js';
 import { renderLapTelemetry, renderTelemetryReadouts } from './readouts/telemetryRenderer.js';
 import {
   renderRaceFinish,
@@ -327,18 +322,6 @@ export class F1SimulatorApp {
     });
   }
 
-  createRawCarGeometryGraphic(driver) {
-    return this.carRenderer.createRawCarGeometryGraphic(driver);
-  }
-
-  createServiceCountdownLabel() {
-    return this.carRenderer.createServiceCountdownLabel();
-  }
-
-  applyServiceCountdownTone(label, tone) {
-    this.carRenderer.applyServiceCountdownTone(label, tone);
-  }
-
   bindControls() {
     const eventOptions = { signal: this.abortController.signal };
 
@@ -838,32 +821,12 @@ export class F1SimulatorApp {
     return getTimingOrderKey(cars, { timingGapMode: this.timingGapMode });
   }
 
-  isWavedFlagCar(car) {
-    return isWavedFlagCar(car);
-  }
-
-  getPenaltyByDriver(penalties = []) {
-    return getPenaltyByDriver(penalties);
-  }
-
   getTimingPenaltyKey(penalties = []) {
     return getTimingPenaltyKey(penalties, {
       timingPenaltyBadgesEnabled: this.timingPenaltyBadgesEnabled,
     });
   }
 
-  formatTimingGap(car) {
-    return formatRaceGap(car, this.timingGapMode);
-  }
-
-  formatLapGap(laps) {
-    return formatLapGap(laps);
-  }
-
-  formatTelemetryGap(car, mode) {
-    return formatTelemetryGap(car, mode);
-  }
-
   syncTimingGapModeControls() {
     syncTimingGapModeControls({
       readouts: this.readouts,
@@ -886,10 +849,6 @@ export class F1SimulatorApp {
     renderLapTelemetry(this.readouts, telemetry);
   }
 
-  getOverviewFields(driver, mode) {
-    return getOverviewFields(driver, mode);
-  }
-
   renderCarDriverOverview(car) {
     const previousKey = this.lastOverviewRenderKey;
     this.lastOverviewRenderKey = renderCarDriverOverview({

package/src/config/restartOptions.js

@@ -0,0 +1,34 @@
+export function mergeRestartOptions(previousOptions, nextOptions = {}) {
+  const resetFromPreset = Object.hasOwn(nextOptions, 'preset');
+  const previousUi = resetFromPreset ? {} : (previousOptions.ui ?? {});
+  const previousTheme = resetFromPreset ? {} : (previousOptions.theme ?? {});
+  const previousAssets = previousOptions.assets ?? {};
+  const nextAssets = nextOptions.assets ?? {};
+
+  return {
+    ...previousOptions,
+    ...nextOptions,
+    ui: {
+      ...previousUi,
+      ...(nextOptions.ui ?? {}),
+      raceDataBanners: {
+        ...(previousUi.raceDataBanners ?? {}),
+        ...(nextOptions.ui?.raceDataBanners ?? {}),
+      },
+    },
+    theme: {
+      ...previousTheme,
+      ...(nextOptions.theme ?? {}),
+    },
+    assets: {
+      ...previousAssets,
+      ...nextAssets,
+      trackTextures: {
+        ...(previousAssets.trackTextures ?? {}),
+        ...(nextAssets.trackTextures ?? {}),
+      },
+    },
+    drivers: nextOptions.drivers ?? previousOptions.drivers,
+    entries: nextOptions.entries ?? previousOptions.entries,
+  };
+}

package/src/environment/controllerLoop.js

@@ -22,6 +22,7 @@ export function createPaddockDriverControllerLoop({
   let heldFramesRemaining = 0;
   let policyStep = 0;
   let runtimeStep = 0;
+  let observationCache = {};
   let running = false;
   let scheduled = null;
   let previousActions = {};
@@ -33,6 +34,11 @@ export function createPaddockDriverControllerLoop({
     if (!observationSpec) observationSpec = runtime.getObservationSpec();
   }
 
+  async function refreshSpecs() {
+    actionSpec = runtime.getActionSpec();
+    observationSpec = runtime.getObservationSpec();
+  }
+
   async function ensureInitialized(context) {
     if (initialized) return;
     await controller.init?.(context);
@@ -47,9 +53,10 @@ export function createPaddockDriverControllerLoop({
     heldFramesRemaining = 0;
     policyStep = 0;
     runtimeStep = Number(result?.info?.step ?? 0);
+    observationCache = { ...(result?.observation ?? {}) };
     previousActions = {};
     lastError = null;
-    await ensureSpecs();
+    await refreshSpecs();
     const context = buildContext({ resetDriverIds: controlledDrivers() });
     await ensureInitialized(context);
     await controller.reset?.(context);
@@ -71,6 +78,10 @@ export function createPaddockDriverControllerLoop({
     const resetDriverIds = Object.keys(placements);
     previousResult = result;
     result = runtime.resetDrivers(placements, resultOptions);
+    observationCache = {
+      ...observationCache,
+      ...(result?.observation ?? {}),
+    };
     heldActions = null;
     heldFramesRemaining = 0;
     lastError = null;
@@ -106,6 +117,7 @@ export function createPaddockDriverControllerLoop({
     const previousActionsForStep = previousActions;
     previousResult = result;
     result = runtime.step(actions);
+    observationCache = { ...(result?.observation ?? {}) };
     heldFramesRemaining -= 1;
     runtimeStep = Number(result?.info?.step ?? runtimeStep + 1);
     previousActions = actions;
@@ -167,7 +179,10 @@ export function createPaddockDriverControllerLoop({
 
   function buildContext(extra = {}) {
     const drivers = controlledDrivers();
-    const observation = result?.observation ?? runtime.getObservation?.() ?? {};
+    const observation = {
+      ...observationCache,
+      ...(result?.observation ?? runtime.getObservation?.() ?? {}),
+    };
     return {
       runtime,
       mode,

package/src/environment/episode.js

@@ -45,8 +45,9 @@ export function buildDriverEpisodeInfo(episodeState, options, episode) {
   return Object.fromEntries(options.controlledDrivers.map((driverId) => {
     const state = ensureDriverEpisodeState(episodeState, driverId);
     const maxStepTruncated = state.episodeStep >= options.episode.maxSteps;
+    const aggregateTruncated = episode.truncated && episode.endReason !== 'all-drivers-ended';
     const terminated = Boolean(state.terminated || episode.terminated);
-    const truncated = Boolean(state.truncated || maxStepTruncated || episode.truncated);
+    const truncated = Boolean(state.truncated || maxStepTruncated || aggregateTruncated);
     const endReason = state.endReason ??
       (terminated ? episode.endReason : null) ??
       (maxStepTruncated ? 'max-steps' : null) ??
@@ -67,13 +68,21 @@ export function evaluateEpisode(snapshot, options, episodeState, controlledDrive
   }
   let allTerminated = controlledDrivers.length > 0;
   let allTruncated = controlledDrivers.length > 0;
+  let allEnded = controlledDrivers.length > 0;
+  let anyTruncated = false;
   let firstTerminatedReason = null;
   for (const driverId of controlledDrivers) {
     const state = ensureDriverEpisodeState(episodeState, driverId);
+    if (!state.terminated && state.episodeStep >= options.episode.maxSteps) {
+      state.truncated = true;
+      state.endReason ??= 'max-steps';
+    }
     if (!state.terminated) allTerminated = false;
     else firstTerminatedReason ??= state.endReason;
     if (!state.truncated && state.episodeStep < options.episode.maxSteps) allTruncated = false;
-    if (!allTerminated && !allTruncated) break;
+    if (state.truncated || state.episodeStep >= options.episode.maxSteps) anyTruncated = true;
+    if (!state.terminated && !state.truncated && state.episodeStep < options.episode.maxSteps) allEnded = false;
+    if (!allTerminated && !allTruncated && !allEnded) break;
   }
   if (allTerminated) {
     return { terminated: true, truncated: false, endReason: controlledDrivers.length === 1 ? firstTerminatedReason : 'all-drivers-terminated' };
@@ -81,6 +90,9 @@ export function evaluateEpisode(snapshot, options, episodeState, controlledDrive
   if (allTruncated) {
     return { terminated: false, truncated: true, endReason: 'max-steps' };
   }
+  if (allEnded) {
+    return { terminated: false, truncated: anyTruncated, endReason: 'all-drivers-ended' };
+  }
   return { terminated: false, truncated: false, endReason: null };
 }
 

package/src/environment/index.d.ts

@@ -364,6 +364,13 @@ export interface PaddockTrackLookaheadObservation {
   headingDeltaRadians: number;
 }
 
+export interface PaddockAppliedControlsObservation {
+  steering: number;
+  steeringRadians: number;
+  throttle: number;
+  brake: number;
+}
+
 export interface PaddockDriverObservationObject {
   profile: string;
   self: {
@@ -375,6 +382,7 @@ export interface PaddockDriverObservationObject {
     steeringAngleRadians: number;
     throttle: number;
     brake: number;
+    appliedControls: PaddockAppliedControlsObservation | null;
     lap: number;
     completedLaps: number;
     lapProgressMeters: number;
@@ -413,7 +421,7 @@ export interface PaddockDriverObservationObject {
   };
   contactPatches: PaddockContactPatchObservation[];
   race: {
-    position: number;
+    position: number | null;
     totalCars: number;
     raceMode: string;
     pitLaneOpen: boolean;
@@ -590,12 +598,18 @@ export interface PaddockActionSpec {
 }
 
 export interface PaddockObservationSpec {
-  version: 2 | 4;
+  version: 3 | 6;
   controlledDrivers: string[];
   object: Record<string, unknown>;
   vector: {
     schema: PaddockObservationSchemaEntry[];
   };
+  perDriver: Record<string, {
+    object: Record<string, unknown>;
+    vector: {
+      schema: PaddockObservationSchemaEntry[];
+    };
+  }>;
 }
 
 export interface PaddockRolloutTransition {

package/src/environment/observationVector.js

@@ -0,0 +1,200 @@
+const MODEL_RAY_SURFACE_CHANNELS = Object.freeze(['kerb', 'illegalSurface']);
+
+export function buildObservationVector(source, sensors, { includeSchema = true, vectorType = 'array' } = {}) {
+  const includePhysicalDriverSenses = source.profile === 'physical-driver';
+  const schema = includeSchema ? [
+    { 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.lateralG', scale: 'fixed:8g' },
+    { name: 'self.longitudinalG', scale: 'fixed:6g' },
+    { name: 'self.gripUsage', scale: '0..2' },
+    { name: 'self.slipAngleRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.tractionLimited', scale: 'boolean' },
+    { 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' },
+  ] : null;
+  const vector = [
+    source.self.speedKph / 400,
+    source.self.speedMetersPerSecond / 120,
+    source.self.steeringAngleRadians / Math.PI,
+    source.self.throttle,
+    source.self.brake,
+    source.self.lateralG / 8,
+    source.self.longitudinalG / 6,
+    source.self.gripUsage / 2,
+    source.self.slipAngleRadians / Math.PI,
+    source.self.tractionLimited ? 1 : 0,
+    normalizeLapProgress(source),
+    source.self.trackOffsetMeters,
+    source.self.trackHeadingErrorRadians / Math.PI,
+    source.self.onTrack ? 1 : 0,
+    source.self.inPitLane ? 1 : 0,
+    (source.self.tireEnergy ?? 0) / 100,
+    (source.self.pitIntent ?? 0) / 2,
+    source.self.pitStopStatus && source.self.pitStopStatus !== 'pending' && source.self.pitStopStatus !== 'completed' ? 1 : 0,
+    normalizeRacePosition(source),
+    source.race.raceMode === 'green' ? 1 : 0,
+    source.race.raceMode === 'safety-car' ? 1 : 0,
+    source.race.redFlag ? 1 : 0,
+    source.race.pitLaneOpen ? 1 : 0,
+    source.track.curvature ?? 0,
+  ];
+  if (includePhysicalDriverSenses) {
+    pushSchema(schema,
+      { name: 'self.yawRateRadiansPerSecond', unit: 'rad/s', scale: 'fixed:pi' },
+      { name: 'trackRelation.leftBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
+      { name: 'trackRelation.rightBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
+      { name: 'trackRelation.legalWidthMeters', unit: 'm', scale: 'fixed:meters' },
+    );
+    vector.push(
+      source.self.yawRateRadiansPerSecond / Math.PI,
+      source.trackRelation.leftBoundaryMeters,
+      source.trackRelation.rightBoundaryMeters,
+      source.trackRelation.legalWidthMeters,
+    );
+    source.contactPatches.forEach((patch, index) => {
+      pushSchema(schema,
+        { name: `contactPatches[${index}].present`, scale: 'boolean' },
+        { name: `contactPatches[${index}].surfaceCode`, scale: 'surface-code' },
+        { name: `contactPatches[${index}].onLegalSurface`, scale: 'boolean' },
+        { name: `contactPatches[${index}].signedOffsetMeters`, unit: 'm', scale: 'fixed:meters' },
+        { name: `contactPatches[${index}].crossTrackErrorMeters`, unit: 'm', scale: 'fixed:meters' },
+      );
+      vector.push(
+        patch.present ? 1 : 0,
+        patch.surfaceCode / 5,
+        patch.onLegalSurface ? 1 : 0,
+        patch.signedOffsetMeters,
+        patch.crossTrackErrorMeters,
+      );
+    });
+  }
+  source.track.lookahead.forEach((sample, index) => {
+    pushSchema(schema,
+      { 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);
+  });
+  source.rays.forEach((ray, index) => {
+    pushSchema(schema,
+      { 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' },
+      { name: `rays[${index}].car.targetTypeReplayGhost`, scale: 'boolean' },
+    );
+    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,
+      ray.car.targetType === 'replayGhost' ? 1 : 0,
+    );
+    MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
+      if (sensors.rays.channels?.includes?.(channel)) {
+        pushSchema(schema,
+          { name: `rays[${index}].${channel}.distanceRatio`, scale: '0..1' },
+          { name: `rays[${index}].${channel}.hit`, scale: 'boolean' },
+        );
+        vector.push(
+          ratio(ray[channel]?.distanceMeters ?? ray.lengthMeters, ray.lengthMeters),
+          ray[channel]?.hit ? 1 : 0,
+        );
+      }
+    });
+  });
+  const nearbyLimit = sensors.nearbyCars.enabled ? (sensors.nearbyCars.maxCars ?? source.nearbyCars.length) : 0;
+  const nearbyRadius = sensors.nearbyCars.radiusMeters ?? 150;
+  for (let index = 0; index < nearbyLimit; index += 1) {
+    const nearby = source.nearbyCars[index] ?? null;
+    pushSchema(schema,
+      { 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' },
+      { name: `nearbyCars[${index}].entityTypeReplayGhost`, 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,
+      nearby?.entityType === 'replayGhost' ? 1 : 0,
+    );
+    if (includePhysicalDriverSenses) {
+      pushSchema(schema,
+        { name: `nearbyCars[${index}].behind`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].closingRateMetersPerSecond`, unit: 'm/s', scale: 'fixed:100' },
+        { name: `nearbyCars[${index}].timeToContactSeconds`, unit: 's', scale: 'fixed:10' },
+        { name: `nearbyCars[${index}].leftOverlap`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].rightOverlap`, scale: 'boolean' },
+      );
+      vector.push(
+        nearby?.behind ? 1 : 0,
+        (nearby?.closingRateMetersPerSecond ?? 0) / 100,
+        ratio(nearby?.timeToContactSeconds ?? 10, 10),
+        nearby?.leftOverlap ? 1 : 0,
+        nearby?.rightOverlap ? 1 : 0,
+      );
+    }
+  }
+  return { vector: finalizeVector(vector, vectorType), schema: schema ?? [] };
+}
+
+function finalizeVector(vector, vectorType = 'array') {
+  return vectorType === 'float32' ? Float32Array.from(vector) : vector;
+}
+
+function pushSchema(schema, ...entries) {
+  if (schema) schema.push(...entries);
+}
+
+function normalizeLapProgress(source) {
+  return ratio(source.self.lapProgressMeters, source.track.lengthMeters || 1);
+}
+
+function normalizeRacePosition(source) {
+  const totalCars = Number(source.race.totalCars);
+  const position = Number(source.race.position);
+  if (!Number.isFinite(totalCars) || totalCars <= 1 || !Number.isFinite(position)) return 0;
+  return ratio(position - 1, totalCars - 1);
+}
+
+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));
+}