@inventure71/paddockjs 0.2.0 → 1.0.0

package/src/environment/index.d.ts

@@ -0,0 +1,521 @@
+export type TireCompound = 'S' | 'M' | 'H';
+export type PaddockPitIntent = 0 | 1 | 2;
+export type PaddockScenarioPreset = 'cornering' | 'off-track-recovery' | 'overtaking-pack' | 'pit-entry';
+
+export interface TeamData {
+  id?: string;
+  name?: string;
+  color?: string;
+  icon?: string;
+  pitCrew?: PaddockPitCrewStats;
+  pitCrewStats?: PaddockPitCrewStats;
+}
+
+export interface PaddockPitCrewStats {
+  speed?: number;
+  consistency?: number;
+  reliability?: number;
+}
+
+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 type PaddockRulesetName = 'paddock' | 'custom' | 'grandPrix2025' | 'fia2025';
+
+export interface PaddockPenaltyEntry {
+  id: string;
+  type: string;
+  at: number;
+  lap: number;
+  driverId: string;
+  strictness: number;
+  status: PaddockPenaltyStatus;
+  penaltySeconds: number;
+  pendingPenaltySeconds?: number;
+  consequences: PaddockPenaltyConsequence[];
+  serviceType?: 'driveThrough' | 'stopGo' | null;
+  serviceRequired?: boolean;
+  serviceServedAt?: number | null;
+  appliedAt?: number;
+  cancelledAt?: number;
+  unserved?: boolean;
+  positionDrop?: number;
+  gridDrop?: number;
+  disqualified?: boolean;
+  reason?: string;
+  otherCarId?: string;
+  aheadDriverId?: string;
+  atFaultDriverId?: string;
+  sharedFault?: boolean;
+  impactSpeedKph?: number;
+  impactSpeedThresholdKph?: number;
+  [key: string]: unknown;
+}
+
+export type PaddockPenaltyConsequence =
+  | { type: 'warning' }
+  | { type: 'time'; seconds: number }
+  | { type: 'driveThrough'; conversionSeconds?: number }
+  | { type: 'stopGo'; seconds?: number; conversionSeconds?: number }
+  | { type: 'positionDrop'; positions: number }
+  | { type: 'gridDrop'; positions: number }
+  | { type: 'disqualification' };
+
+export type PaddockPenaltyStatus = 'issued' | 'served' | 'applied' | 'cancelled';
+
+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[];
+  penalties: PaddockPenaltyEntry[];
+  [key: string]: unknown;
+}
+
+export interface PaddockAction {
+  steering: number;
+  throttle: number;
+  brake: number;
+  pitIntent?: PaddockPitIntent;
+  pitCompound?: TireCompound | string;
+  pitTargetCompound?: TireCompound | string;
+}
+
+export type PaddockActionMap = Record<string, PaddockAction>;
+
+export interface PaddockRaceRules {
+  ruleset?: PaddockRulesetName;
+  profile?: PaddockRulesetName;
+  modules?: {
+    pitStops?: {
+      enabled?: boolean;
+      pitLaneSpeedLimitKph?: number;
+      defaultStopSeconds?: number;
+      variability?: {
+        enabled?: boolean;
+        perfect?: boolean;
+        speedImpactSeconds?: number;
+        consistencyJitterSeconds?: number;
+        issueChance?: number;
+        issueMaxDelaySeconds?: number;
+      };
+      doubleStacking?: boolean;
+      maxConcurrentPitLaneCars?: number;
+      minimumPitLaneGapMeters?: number;
+      tirePitRequestThresholdPercent?: number;
+      tirePitCommitThresholdPercent?: number;
+    };
+    tireStrategy?: {
+      enabled?: boolean;
+      compounds?: TireCompound[];
+      mandatoryDistinctDryCompounds?: number | null;
+    };
+    penalties?: {
+      enabled?: boolean;
+      stewardStrictness?: number;
+      trackLimits?: {
+        strictness?: number;
+        warningsBeforePenalty?: number;
+        relaxedMarginMeters?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+      };
+      collision?: {
+        strictness?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+        minimumSeverity?: number;
+        relaxedSeverityMargin?: number;
+        minimumImpactSpeedKph?: number;
+        relaxedImpactSpeedKph?: number;
+      };
+      tireRequirement?: {
+        strictness?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+      };
+      pitLaneSpeeding?: {
+        strictness?: number;
+        speedLimitKph?: number;
+        marginKph?: number;
+        relaxedMarginKph?: number;
+        timePenaltySeconds?: number;
+        consequences?: PaddockPenaltyConsequence[];
+      };
+    };
+    weather?: { enabled?: boolean };
+    reliability?: { enabled?: boolean };
+    fuelLoad?: { enabled?: boolean };
+  };
+  drsDetectionSeconds?: number;
+  safetyCarSpeed?: number;
+  safetyCarLeadDistance?: number;
+  safetyCarGap?: number;
+  collisionRestitution?: number;
+  standingStart?: boolean;
+  startLightCount?: number;
+  startLightInterval?: number;
+  startLightsOutHold?: number;
+}
+
+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 PaddockTrackLookaheadObservation {
+  distanceMeters: number;
+  curvature: number;
+  headingDeltaRadians: number;
+}
+
+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;
+    inPitLane: boolean;
+    pitLanePart: 'entry' | 'fast-lane' | 'working-lane' | 'exit' | 'service-box' | 'garage-box' | null;
+    pitBoxId: string | null;
+    tireEnergy: number | null;
+    pitIntent: PaddockPitIntent;
+    pitTargetCompound: TireCompound | string | null;
+    pitStopStatus: 'pending' | 'entering' | 'queued' | 'servicing' | 'exiting' | 'completed' | null;
+    pitStopPhase: 'entry' | 'queue' | 'queue-release' | 'penalty' | 'service' | 'exit' | null;
+    pitStopServiceRemainingSeconds: number | null;
+    pitStopPenaltyServiceRemainingSeconds: number | null;
+    pitStopsCompleted: number;
+  };
+  race: {
+    position: number;
+    totalCars: number;
+    raceMode: string;
+    pitLaneOpen: boolean;
+    redFlag: boolean;
+    totalLaps: number;
+  };
+  track: {
+    lengthMeters: number;
+    widthMeters: number;
+    curvature: number;
+    lookahead: PaddockTrackLookaheadObservation[];
+  };
+  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;
+  rules?: PaddockRaceRules;
+  actionPolicy?: 'strict' | 'report';
+  scenario?: {
+    participants?: 'all' | 'controlled-only' | string[];
+    nonControlled?: 'ai';
+    preset?: PaddockScenarioPreset;
+    placements?: Record<string, PaddockScenarioPlacement>;
+    traffic?: PaddockScenarioTrafficPlacement[];
+  };
+  sensors?: {
+    rays?: {
+      enabled?: boolean;
+      anglesDegrees?: number[];
+      lengthMeters?: number;
+      detectTrack?: boolean;
+      detectCars?: boolean;
+    };
+    nearbyCars?: {
+      enabled?: boolean;
+      maxCars?: number;
+      radiusMeters?: number;
+    };
+  };
+  sensorsByDriver?: Record<string, PaddockEnvironmentOptions['sensors']>;
+  observation?: {
+    lookaheadMeters?: number[];
+  };
+  episode?: {
+    maxSteps?: number;
+    endOnRaceFinish?: boolean;
+  };
+  reward?: (payload: PaddockRewardContext) => number;
+}
+
+export interface PaddockScenarioPlacement {
+  distanceMeters?: number;
+  startDistanceMeters?: number;
+  offsetMeters?: number;
+  speedKph?: number;
+  headingErrorRadians?: number;
+}
+
+export interface PaddockScenarioTrafficPlacement {
+  driverId: string;
+  relativeTo: string;
+  deltaDistanceMeters?: number;
+  offsetMeters?: number;
+  speedKph?: number;
+  headingErrorRadians?: 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' };
+      pitIntent: { values: [0, 1, 2]; unit: 'request'; optional: true };
+      pitCompound: { values: string[]; unit: 'compound'; optional: true };
+    };
+  };
+}
+
+export interface PaddockObservationSpec {
+  version: 2;
+  controlledDrivers: string[];
+  object: Record<string, unknown>;
+  vector: {
+    schema: PaddockObservationSchemaEntry[];
+  };
+}
+
+export interface PaddockRolloutTransition {
+  observation: Record<string, PaddockDriverObservation>;
+  action: PaddockActionMap;
+  reward: null | Record<string, number>;
+  nextObservation: Record<string, PaddockDriverObservation>;
+  terminated: boolean;
+  truncated: boolean;
+  info: PaddockEnvironmentResult['info'];
+}
+
+export interface PaddockRolloutRecorder {
+  recordStep(
+    previousResult: PaddockEnvironmentResult,
+    action: PaddockActionMap,
+    nextResult: PaddockEnvironmentResult
+  ): PaddockRolloutTransition;
+  clear(): void;
+  toJSON(): PaddockRolloutTransition[];
+}
+
+export interface PaddockEvaluationCase {
+  name: string;
+  seed?: number;
+  trackSeed?: number;
+  maxSteps?: number;
+  scenario?: PaddockEnvironmentOptions['scenario'];
+}
+
+export interface PaddockEvaluationDriverMetrics {
+  distanceMeters: number;
+  lapProgressMeters: number;
+  offTrackSteps: number;
+  contactCount: number;
+  recoverySuccess: boolean;
+  passCount: number;
+  lapTimeSeconds: number | null;
+}
+
+export interface PaddockEvaluationCaseReport {
+  name: string;
+  seed?: number;
+  trackSeed?: number;
+  steps: number;
+  done: boolean;
+  endReason: string | null;
+  metrics: Record<string, PaddockEvaluationDriverMetrics>;
+}
+
+export interface PaddockEvaluationReport {
+  cases: PaddockEvaluationCaseReport[];
+}
+
+export type PaddockPolicyLike =
+  | ((observation: PaddockDriverObservation, context: Record<string, unknown>) => PaddockAction)
+  | { predict(observation: PaddockDriverObservation, context: Record<string, unknown>): PaddockAction };
+
+export interface PaddockEnvironmentWorkerMessage {
+  id?: string | number | null;
+  type: 'reset' | 'step' | 'getActionSpec' | 'getObservationSpec' | 'getObservation' | 'getState' | 'destroy' | string;
+  options?: Partial<PaddockEnvironmentOptions>;
+  actions?: PaddockActionMap;
+}
+
+export interface PaddockEnvironmentWorkerResponse {
+  id: string | number | null;
+  ok: boolean;
+  type: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface PaddockEnvironmentWorkerProtocol {
+  handle(message: PaddockEnvironmentWorkerMessage): PaddockEnvironmentWorkerResponse;
+}
+
+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;
+export function createRolloutRecorder(): PaddockRolloutRecorder;
+export function createRolloutTransition(
+  previousResult: PaddockEnvironmentResult,
+  action: PaddockActionMap,
+  nextResult: PaddockEnvironmentResult
+): PaddockRolloutTransition;
+export const ENVIRONMENT_SCENARIO_PRESETS: readonly PaddockScenarioPreset[];
+export const DEFAULT_EVALUATION_CASES: readonly PaddockEvaluationCase[];
+export function createEvaluationTracker(initialResult: PaddockEnvironmentResult): {
+  update(result: PaddockEnvironmentResult): void;
+  finish(): Record<string, PaddockEvaluationDriverMetrics>;
+};
+export function runEnvironmentEvaluation(options: {
+  baseOptions: PaddockEnvironmentOptions;
+  policy: PaddockPolicyLike;
+  cases?: PaddockEvaluationCase[];
+  createEnvironment?: (options: PaddockEnvironmentOptions) => PaddockEnvironment;
+}): PaddockEvaluationReport;
+export function createEnvironmentWorkerProtocol(env: PaddockEnvironment): PaddockEnvironmentWorkerProtocol;
+export function handleEnvironmentMessage(
+  env: PaddockEnvironment,
+  message: PaddockEnvironmentWorkerMessage
+): PaddockEnvironmentWorkerResponse;

package/src/environment/index.js

@@ -0,0 +1,15 @@
+export { createPaddockEnvironment } from './runtime.js';
+export { createProgressReward } from './rewards.js';
+export { createRolloutRecorder, createRolloutTransition } from './recorder.js';
+export {
+  DEFAULT_EVALUATION_CASES,
+  createEvaluationTracker,
+  runEnvironmentEvaluation,
+} from './evaluation.js';
+export {
+  ENVIRONMENT_SCENARIO_PRESETS,
+} from './scenarios.js';
+export {
+  createEnvironmentWorkerProtocol,
+  handleEnvironmentMessage,
+} from './workerProtocol.js';

package/src/environment/observationOptions.js

@@ -0,0 +1,12 @@
+export const DEFAULT_VECTOR_LOOKAHEAD_METERS = Object.freeze([20, 50, 100, 150]);
+
+export function normalizeLookaheadMeters(value) {
+  if (value == null) return [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
+  if (!Array.isArray(value)) return [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
+
+  const distances = value
+    .map((item) => Number(item))
+    .filter((item) => Number.isFinite(item));
+
+  return distances.length ? distances : [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
+}