@inventure71/paddockjs 2.0.0 → 3.0.0

package/src/config/timingGapMode.js

@@ -0,0 +1,13 @@
+export const TIMING_GAP_MODES = new Set(['interval', 'leader']);
+
+export function normalizeTimingGapMode(value) {
+  return value === 'leader' ? 'leader' : 'interval';
+}
+
+export function getTimingGapModeLabel(mode) {
+  return normalizeTimingGapMode(mode) === 'leader' ? 'Gap' : 'Int';
+}
+
+export function getNextTimingGapMode(mode) {
+  return normalizeTimingGapMode(mode) === 'leader' ? 'interval' : 'leader';
+}

package/src/config/urlOptions.js

@@ -0,0 +1,25 @@
+const SAFE_ABSOLUTE_URL_PROTOCOLS = new Set(['http:', 'https:']);
+
+export function normalizePublicUrlOption(value, fallback) {
+  const fallbackValue = typeof fallback === 'string' && fallback.trim() !== ''
+    ? fallback.trim()
+    : '';
+  if (typeof value !== 'string') return fallbackValue;
+
+  const candidate = value.trim();
+  if (candidate === '') return fallbackValue;
+  if (/[\u0000-\u001F\u007F]/.test(candidate)) return fallbackValue;
+  if (candidate.includes('\\')) return fallbackValue;
+  if (candidate.startsWith('#')) return candidate;
+  if (candidate.startsWith('//')) return fallbackValue;
+
+  const schemeMatch = /^[A-Za-z][A-Za-z0-9+.-]*:/.exec(candidate);
+  if (!schemeMatch) return candidate;
+
+  try {
+    const url = new URL(candidate);
+    return SAFE_ABSOLUTE_URL_PROTOCOLS.has(url.protocol) ? candidate : fallbackValue;
+  } catch {
+    return fallbackValue;
+  }
+}

package/src/data/championship.js

@@ -1,6 +1,7 @@
 import { DriverData } from './driverData.js';
 import { DEMO_PROJECT_DRIVERS } from './demoDrivers.js';
 import { VehicleData } from './vehicleData.js';
+import { DEFAULT_DARK_THEME_TOKENS, normalizeCssColorToken } from '../config/themeOptions.js';
 
 export { DriverData, DRIVER_STAT_DEFINITIONS } from './driverData.js';
 export { VehicleData, VEHICLE_STAT_DEFINITIONS } from './vehicleData.js';
@@ -187,7 +188,7 @@ function normalizeTeam(team, driver, timingCode) {
     ...source,
     id,
     name,
-    color: source.color ?? driver.color,
+    color: normalizeCssColorToken(source.color ?? driver.color, driver.color),
     icon: source.icon ?? normalizeTeamIcon(source.name ?? source.id ?? timingCode ?? driver.name),
   };
 }
@@ -201,22 +202,26 @@ export function buildChampionshipDriverGrid(drivers = DEMO_PROJECT_DRIVERS, entr
   const usedTimingCodes = new Set();
 
   return drivers.map((driver, index) => {
+    const safeDriver = {
+      ...driver,
+      color: normalizeCssColorToken(driver.color, DEFAULT_DARK_THEME_TOKENS.primary),
+    };
     const entry = {
-      ...(blueprintByDriverId.get(driver.id) ?? {}),
-      ...(entryByDriverId.get(driver.id) ?? {}),
+      ...(blueprintByDriverId.get(safeDriver.id) ?? {}),
+      ...(entryByDriverId.get(safeDriver.id) ?? {}),
     };
-    const timingCode = pickUniqueTimingCode(entry.timingName ?? driver.timingName ?? driver.name ?? driver.code, usedTimingCodes);
-    const driverNumber = entry.driverNumber ?? driver.driverNumber ?? index + 1;
-    const driverArgs = buildDriverConstructorArgs({ driverId: driver.id, ...entry });
-    const vehicleArgs = buildVehicleConstructorArgs({ driverId: driver.id, ...entry });
+    const timingCode = pickUniqueTimingCode(entry.timingName ?? safeDriver.timingName ?? safeDriver.name ?? safeDriver.code, usedTimingCodes);
+    const driverNumber = entry.driverNumber ?? safeDriver.driverNumber ?? index + 1;
+    const driverArgs = buildDriverConstructorArgs({ driverId: safeDriver.id, ...entry });
+    const vehicleArgs = buildVehicleConstructorArgs({ driverId: safeDriver.id, ...entry });
 
     return {
-      ...driver,
+      ...safeDriver,
       code: timingCode,
       timingCode,
       raceName: timingCode,
       driverNumber,
-      team: normalizeTeam(entry.team, driver, timingCode),
+      team: normalizeTeam(entry.team, safeDriver, timingCode),
       pace: driverArgs.pace,
       racecraft: driverArgs.racecraft,
       consistency: driverArgs.consistency,

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;
@@ -156,8 +168,7 @@ export function createPaddockDriverControllerLoop({
 
   function stop() {
     running = false;
-    if (scheduled && typeof scheduled.cancel === 'function') scheduled.cancel();
-    else if (typeof scheduled === 'number' && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(scheduled);
+    cancelScheduled(scheduled);
     scheduled = null;
   }
 
@@ -167,7 +178,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,
@@ -235,9 +249,24 @@ function now() {
     : Date.now();
 }
 
+function cancelScheduled(handle) {
+  if (handle == null) return;
+  if (typeof handle.cancel === 'function') {
+    handle.cancel();
+    return;
+  }
+  if (typeof handle === 'number') {
+    if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(handle);
+    if (typeof clearTimeout === 'function') clearTimeout(handle);
+  }
+}
+
 function defaultScheduler() {
   if (typeof requestAnimationFrame === 'function') {
-    return (callback) => requestAnimationFrame(callback);
+    return (callback) => {
+      const id = requestAnimationFrame(callback);
+      return { cancel: () => cancelAnimationFrame(id) };
+    };
   }
   return (callback) => {
     const id = setTimeout(callback, 0);

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

@@ -1,5 +1,5 @@
 export type TireCompound = 'S' | 'M' | 'H';
-export type PaddockPhysicsMode = 'arcade' | 'simulator';
+export type PaddockPhysicsMode = 'arcade' | 'advanced';
 export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
 
 export interface PaddockProceduralTrackOptions {
@@ -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;
@@ -470,7 +478,6 @@ export interface PaddockEnvironmentOptions {
   seed?: number;
   trackSeed?: number;
   trackGeneration?: PaddockProceduralTrackOptions;
-  trackQueryIndex?: boolean;
   totalLaps?: number;
   frameSkip?: number;
   physicsMode?: PaddockPhysicsMode;
@@ -590,12 +597,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));
+}