@inventure71/paddockjs 2.0.1 → 4.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/data/index.d.ts

@@ -0,0 +1,212 @@
+export type TireCompound = 'S' | 'M' | 'H';
+export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
+
+export interface PaddockProceduralTrackOptions {
+  profile?: PaddockProceduralTrackProfile;
+  minLengthMeters?: number;
+  maxLengthMeters?: number;
+  startStraightMeters?: number;
+  includePitLane?: boolean;
+  length?: {
+    minMeters?: number;
+    maxMeters?: number;
+  };
+  startStraight?: {
+    gridMeters?: number;
+    exitMeters?: number;
+    blendMeters?: number;
+    lockExtraMeters?: number;
+  };
+  pitLane?: {
+    enabled?: boolean;
+  };
+  shape?: {
+    scale?: number;
+    cornerDensity?: number;
+    variation?: number;
+  };
+  validation?: {
+    minClearanceMultiplier?: number;
+    minShapeVariation?: number;
+    minNonAdjacentArcMeters?: number;
+    maxLocalTurnRadians?: number;
+    maxSampleHeadingDeltaRadians?: number;
+  };
+  attempts?: {
+    primary?: number;
+    fallback?: number;
+  };
+}
+
+export interface CustomField {
+  label: string;
+  value: string;
+}
+
+export type CustomFieldInput = CustomField[] | Record<string, string>;
+export type PaddockThemeSelector = 'default' | 'active' | 'selectedTeam' | 'team' | `team:${string}` | string;
+
+export interface PaddockPitCrewStats {
+  speed?: number;
+  consistency?: number;
+  reliability?: number;
+}
+
+export interface TeamData {
+  id?: string;
+  name?: string;
+  color?: string;
+  icon?: string;
+  theme?: PaddockThemeSelector;
+  pitCrew?: PaddockPitCrewStats;
+  pitCrewStats?: PaddockPitCrewStats;
+}
+
+export interface SimulatorDriver {
+  id: string;
+  name: string;
+  color: string;
+  link?: string;
+  icon?: string;
+  code?: string;
+  timingName?: string;
+  tire?: TireCompound;
+  raceData?: string[];
+  customFields?: CustomFieldInput;
+  team?: TeamData | null;
+  driverNumber?: number;
+}
+
+export interface DriverRatings {
+  pace: number;
+  racecraft: number;
+  aggression: number;
+  riskTolerance: number;
+  patience: number;
+  consistency: number;
+}
+
+export interface VehicleRatings {
+  power: number;
+  braking: number;
+  aero: number;
+  dragEfficiency: number;
+  mechanicalGrip: number;
+  weightControl: number;
+  tireCare: number;
+}
+
+export interface DriverBlueprint extends Partial<DriverRatings> {
+  customFields?: CustomFieldInput;
+}
+
+export interface VehicleBlueprint extends Partial<VehicleRatings> {
+  id?: string | null;
+  name?: string | null;
+  customFields?: CustomFieldInput;
+}
+
+export interface DriverConstructorArgs {
+  ratings: DriverRatings;
+  customFields: CustomField[];
+  pace: number;
+  racecraft: number;
+  consistency: number;
+  personality: {
+    aggression: number;
+    riskTolerance: number;
+    patience: number;
+  };
+}
+
+export interface VehicleConstructorArgs {
+  id: string | null;
+  name: string | null;
+  ratings: VehicleRatings;
+  customFields: CustomField[];
+  powerNewtons: number;
+  brakeNewtons: number;
+  downforceCoefficient: number;
+  dragCoefficient: number;
+  tireGrip: number;
+  mass: number;
+  tireCare: number;
+}
+
+export class DriverData {
+  constructor(input?: DriverBlueprint);
+  readonly pace: number;
+  readonly racecraft: number;
+  readonly aggression: number;
+  readonly riskTolerance: number;
+  readonly patience: number;
+  readonly consistency: number;
+  readonly customFields: CustomField[];
+  ratings(): DriverRatings;
+  toConstructorArgs(): DriverConstructorArgs;
+}
+
+export class VehicleData {
+  constructor(input?: VehicleBlueprint);
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly power: number;
+  readonly braking: number;
+  readonly aero: number;
+  readonly dragEfficiency: number;
+  readonly mechanicalGrip: number;
+  readonly weightControl: number;
+  readonly tireCare: number;
+  readonly customFields: CustomField[];
+  ratings(): VehicleRatings;
+  toConstructorArgs(): VehicleConstructorArgs;
+}
+
+export interface ChampionshipEntryBlueprint {
+  driverId: string;
+  driverNumber?: number;
+  timingName?: string;
+  driver?: DriverData | DriverBlueprint;
+  vehicle?: VehicleData | VehicleBlueprint;
+  team?: TeamData;
+}
+
+export interface NormalizedSimulatorDriver extends SimulatorDriver {
+  code: string;
+  timingCode: string;
+  raceName: string;
+  driverNumber: number;
+  team: TeamData | null;
+  pace: number;
+  racecraft: number;
+  consistency: number;
+  personality: DriverConstructorArgs['personality'];
+  vehicle: VehicleConstructorArgs;
+  constructorArgs: {
+    driver: DriverConstructorArgs;
+    vehicle: VehicleConstructorArgs;
+  };
+  championship: {
+    id: string;
+    name: string;
+    season: number;
+    entryIndex: number;
+    vehicleId: string | null;
+  };
+}
+
+export const CHAMPIONSHIP_ENTRY_BLUEPRINTS: ChampionshipEntryBlueprint[];
+export const DEMO_PROJECT_DRIVERS: SimulatorDriver[];
+
+export function buildChampionshipDriverGrid(
+  drivers?: SimulatorDriver[],
+  entries?: ChampionshipEntryBlueprint[],
+): NormalizedSimulatorDriver[];
+export function formatDriverNumber(driverNumber: number | string | null | undefined): string;
+export function normalizeSimulatorDrivers(
+  drivers: SimulatorDriver[],
+  options?: { entries?: ChampionshipEntryBlueprint[]; caller?: string },
+): NormalizedSimulatorDriver[];
+export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): unknown;
+export function kphToSimSpeed(kph: number): number;
+export function simSpeedToKph(simSpeed: number): number;

package/src/data/index.js

@@ -0,0 +1,14 @@
+export {
+  CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+  DriverData,
+  VehicleData,
+  buildChampionshipDriverGrid,
+  formatDriverNumber,
+} from './championship.js';
+export { DEMO_PROJECT_DRIVERS } from './demoDrivers.js';
+export { normalizeSimulatorDrivers } from './normalizeDrivers.js';
+export { createProceduralTrack } from '../simulation/track/trackModel.js';
+export {
+  kphToSimSpeed,
+  simSpeedToKph,
+} from '../simulation/units.js';

package/src/environment/controllerLoop.js

@@ -168,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;
   }
 
@@ -250,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

@@ -2,6 +2,9 @@ export function createEpisodeState() {
   return {
     step: 0,
     drivers: new Map(),
+    observationScratch: {},
+    metricScratch: {},
+    destroyedCarsById: new Map(),
     previousSnapshot: null,
     lastResult: null,
   };
@@ -30,7 +33,14 @@ export function resetDriverEpisodes(episodeState, driverIds = []) {
 }
 
 export function markDestroyedDriverEpisodes(episodeState, driverIds = [], snapshot = null) {
-  const carsById = new Map((snapshot?.cars ?? []).map((car) => [car.id, car]));
+  const carsById = episodeState.destroyedCarsById ?? new Map();
+  episodeState.destroyedCarsById = carsById;
+  carsById.clear();
+  const cars = snapshot?.cars ?? [];
+  for (let index = 0; index < cars.length; index += 1) {
+    const car = cars[index];
+    carsById.set(car.id, car);
+  }
   driverIds.forEach((driverId) => {
     const car = carsById.get(driverId);
     if (!car?.destroyed && !car?.dnf && !car?.outOfRace) return;

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 {
@@ -478,7 +478,6 @@ export interface PaddockEnvironmentOptions {
   seed?: number;
   trackSeed?: number;
   trackGeneration?: PaddockProceduralTrackOptions;
-  trackQueryIndex?: boolean;
   totalLaps?: number;
   frameSkip?: number;
   physicsMode?: PaddockPhysicsMode;

package/src/environment/metrics.js

@@ -5,6 +5,21 @@ import { simUnitsToMeters } from '../simulation/units.js';
 const LEGAL_SURFACES = new Set(['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box']);
 const ILLEGAL_SURFACES = new Set(['grass', 'gravel', 'runoff', 'barrier']);
 const UNSTABLE_STATES = new Set(['spun', 'backwards', 'spin-risk', 'understeer', 'oversteer', 'destroyed']);
+export const ENVIRONMENT_METRIC_FIELDS = Object.freeze([
+  'progressDeltaMeters',
+  'legalProgressDeltaMeters',
+  'offTrack',
+  'kerb',
+  'fullyOutsideWhiteLine',
+  'severeCut',
+  'destroyed',
+  'destroyReason',
+  'under30kph',
+  'spinOrBackwards',
+  'completedLap',
+  'lapTimeSeconds',
+  'contactCount',
+]);
 
 export function isEnvironmentCarOffTrack(car) {
   if (!car) return false;
@@ -15,19 +30,32 @@ export function isEnvironmentContactEvent(event) {
   return ['collision', 'contact', 'car-contact'].includes(event?.type);
 }
 
-export function buildDriverMetrics({ snapshot, previousSnapshot = null, options, events = [] }) {
-  const previousById = new Map((previousSnapshot?.cars ?? []).map((car) => [car.id, car]));
-  const currentById = new Map(snapshot.cars.map((car) => [car.id, car]));
-  const contactCounts = contactCountsByDriver(events);
+export function buildDriverMetrics({ snapshot, previousSnapshot = null, options, events = [], scratch = null }) {
+  const previousById = carsByIdForMetrics(previousSnapshot, scratch, 'previousCarsById');
+  const currentById = carsByIdForMetrics(snapshot, scratch, 'currentCarsById');
+  const contactCounts = contactCountsByDriver(events, scratch);
   const metrics = {};
   options.controlledDrivers.forEach((driverId) => {
     const car = currentById.get(driverId);
     const previous = previousById.get(driverId);
-    metrics[driverId] = car ? buildMetricForDriver(car, previous, snapshot, contactCounts.get(driverId) ?? 0) : emptyMetrics();
+    metrics[driverId] = car ? buildMetricForDriver(car, previous, snapshot, contactCounts?.get(driverId) ?? 0) : emptyMetrics();
   });
   return metrics;
 }
 
+function carsByIdForMetrics(snapshot, scratch, key) {
+  if (!scratch) return new Map((snapshot?.cars ?? []).map((car) => [car.id, car]));
+  const carsById = scratch[key] ?? new Map();
+  scratch[key] = carsById;
+  carsById.clear();
+  const cars = snapshot?.cars ?? [];
+  for (let index = 0; index < cars.length; index += 1) {
+    const car = cars[index];
+    carsById.set(car.id, car);
+  }
+  return carsById;
+}
+
 function buildMetricForDriver(car, previous, snapshot, contactCount) {
   const progressDeltaMeters = progressDelta(car, previous);
   const wheelState = classifyWheels(car);
@@ -140,20 +168,35 @@ function lastLapTimeSeconds(car) {
   return car.lapTelemetry?.lastLapTime ?? car.lapTelemetry?.bestLapTime ?? null;
 }
 
-function contactCountsByDriver(events) {
-  const counts = new Map();
-  if (!events.length) return counts;
+function contactCountsByDriver(events, scratch = null) {
+  if (!events.length) return null;
+  const counts = scratch ? (scratch.contactCounts ?? new Map()) : new Map();
+  const eventDriverIds = scratch ? (scratch.eventDriverIds ?? []) : [];
+  if (scratch) {
+    scratch.contactCounts = counts;
+    scratch.eventDriverIds = eventDriverIds;
+  }
+  counts.clear();
   events.forEach((event) => {
     if (!isEnvironmentContactEvent(event)) return;
-    const eventDriverIds = new Set([
-      event.driverId,
-      event.carId,
-      event.otherCarId,
-      ...(event.driverIds ?? []),
-    ].filter(Boolean));
-    eventDriverIds.forEach((driverId) => {
+    eventDriverIds.length = 0;
+    pushEventDriverId(eventDriverIds, event.driverId);
+    pushEventDriverId(eventDriverIds, event.carId);
+    pushEventDriverId(eventDriverIds, event.otherCarId);
+    const extraDriverIds = event.driverIds ?? [];
+    for (let index = 0; index < extraDriverIds.length; index += 1) {
+      pushEventDriverId(eventDriverIds, extraDriverIds[index]);
+    }
+    for (let index = 0; index < eventDriverIds.length; index += 1) {
+      const driverId = eventDriverIds[index];
       counts.set(driverId, (counts.get(driverId) ?? 0) + 1);
-    });
+    }
   });
+  eventDriverIds.length = 0;
   return counts;
 }
+
+function pushEventDriverId(target, driverId) {
+  if (!driverId || target.includes(driverId)) return;
+  target.push(driverId);
+}

package/src/environment/observationVector.js

@@ -91,40 +91,36 @@ export function buildObservationVector(source, sensors, { includeSchema = true,
     );
     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,
-        );
-      }
+  if (typeof source.appendRayVectorValues === 'function') {
+    source.appendRayVectorValues(vector);
+  } else if (Array.isArray(source.rayVectorValues)) {
+    source.rayVectorValues.forEach((values, index) => {
+      pushRaySchema(schema, index, sensors);
+      vector.push(...values);
     });
-  });
+  } else {
+    source.rays.forEach((ray, index) => {
+      pushRaySchema(schema, index, sensors);
+      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)) {
+          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) {
@@ -179,6 +175,27 @@ function pushSchema(schema, ...entries) {
   if (schema) schema.push(...entries);
 }
 
+function pushRaySchema(schema, index, sensors) {
+  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' },
+  );
+  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' },
+      );
+    }
+  });
+}
+
 function normalizeLapProgress(source) {
   return ratio(source.self.lapProgressMeters, source.track.lengthMeters || 1);
 }