@inventure71/paddockjs 1.0.0 → 2.0.0

package/src/environment/index.d.ts

@@ -1,6 +1,113 @@
 export type TireCompound = 'S' | 'M' | 'H';
+export type PaddockPhysicsMode = 'arcade' | 'simulator';
+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 type PaddockStabilityState = 'stable' | 'understeer' | 'oversteer' | 'spin-risk' | 'destroyed';
 export type PaddockPitIntent = 0 | 1 | 2;
 export type PaddockScenarioPreset = 'cornering' | 'off-track-recovery' | 'overtaking-pack' | 'pit-entry';
+export type PaddockParticipantInteractionProfile =
+  | 'normal'
+  | 'isolated-training'
+  | 'batch-training'
+  | 'phantom-race'
+  | 'time-trial-overlay';
+
+export interface PaddockParticipantInteraction {
+  profile: PaddockParticipantInteractionProfile;
+  collidable: boolean;
+  detectableByRays: boolean;
+  detectableAsNearby: boolean;
+  blocksPitLane: boolean;
+  affectsRaceOrder: boolean;
+}
+
+export type PaddockParticipantInteractionOverride =
+  Partial<PaddockParticipantInteraction> & { profile?: PaddockParticipantInteractionProfile };
+
+export interface PaddockParticipantInteractionsOptions {
+  defaultProfile?: PaddockParticipantInteractionProfile;
+  drivers?: Record<string, PaddockParticipantInteractionOverride>;
+}
+
+export interface PaddockReplayGhostTrajectorySample {
+  timeSeconds: number;
+  x: number;
+  y: number;
+  headingRadians: number;
+  speedKph?: number;
+  progressMeters?: number;
+}
+
+export interface PaddockReplayGhostOptions {
+  id: string;
+  label?: string;
+  color?: string;
+  opacity?: number;
+  visible?: boolean;
+  trajectory: PaddockReplayGhostTrajectorySample[];
+  sensors?: {
+    detectableByRays?: boolean;
+    detectableAsNearby?: boolean;
+  };
+}
+
+export interface PaddockReplayGhostSnapshot {
+  id: string;
+  label: string;
+  color: string;
+  opacity: number;
+  visible: boolean;
+  previousX: number;
+  previousY: number;
+  x: number;
+  y: number;
+  previousHeading: number;
+  heading: number;
+  speedKph: number;
+  progressMeters: number;
+  timeSeconds: number;
+  sensors: {
+    detectableByRays: boolean;
+    detectableAsNearby: boolean;
+  };
+}
 
 export interface TeamData {
   id?: string;
@@ -92,6 +199,7 @@ export type PaddockPenaltyStatus = 'issued' | 'served' | 'applied' | 'cancelled'
 
 export interface RaceSnapshot {
   time: number;
+  physicsMode: PaddockPhysicsMode;
   totalLaps: number;
   raceControl: {
     mode: string;
@@ -100,6 +208,7 @@ export interface RaceSnapshot {
   };
   track: Record<string, unknown>;
   cars: Array<Record<string, unknown>>;
+  replayGhosts: PaddockReplayGhostSnapshot[];
   events: RaceEvent[];
   penalties: PaddockPenaltyEntry[];
   [key: string]: unknown;
@@ -143,6 +252,14 @@ export interface PaddockRaceRules {
       compounds?: TireCompound[];
       mandatoryDistinctDryCompounds?: number | null;
     };
+    tireDegradation?: {
+      enabled?: boolean;
+    };
+    stalledDnf?: {
+      enabled?: boolean;
+      maxStoppedSeconds?: number;
+      speedThresholdKph?: number;
+    };
     penalties?: {
       enabled?: boolean;
       stewardStrictness?: number;
@@ -192,22 +309,38 @@ export interface PaddockRaceRules {
 }
 
 export interface PaddockSensorRayResult {
+  id?: string;
   angleDegrees: number;
   angleRadians: number;
   lengthMeters: number;
+  roadEdge: {
+    hit: boolean;
+    distanceMeters: number;
+    kind: 'exit' | 'entry' | null;
+  };
   track: {
     hit: boolean;
     distanceMeters: number;
     kind: 'exit' | 'entry' | null;
   };
+  kerb: PaddockSurfaceRayHit;
+  illegalSurface: PaddockSurfaceRayHit;
   car: {
     hit: boolean;
     distanceMeters: number;
     driverId: string | null;
+    targetId?: string | null;
+    targetType?: 'car' | 'replayGhost' | null;
     relativeSpeedKph: number;
   };
 }
 
+export interface PaddockSurfaceRayHit {
+  hit: boolean;
+  distanceMeters: number;
+  surface: string | null;
+}
+
 export interface PaddockNearbyCarObservation {
   id: string;
   relativeForwardMeters: number;
@@ -216,7 +349,13 @@ export interface PaddockNearbyCarObservation {
   relativeSpeedKph: number;
   relativeHeadingRadians: number;
   ahead: boolean;
+  behind: boolean;
   sameLap: boolean;
+  closingRateMetersPerSecond: number;
+  timeToContactSeconds: number | null;
+  leftOverlap: boolean;
+  rightOverlap: boolean;
+  entityType?: 'car' | 'replayGhost';
 }
 
 export interface PaddockTrackLookaheadObservation {
@@ -226,11 +365,13 @@ export interface PaddockTrackLookaheadObservation {
 }
 
 export interface PaddockDriverObservationObject {
+  profile: string;
   self: {
     id: string;
     speedKph: number;
     speedMetersPerSecond: number;
     headingRadians: number;
+    yawRateRadiansPerSecond: number;
     steeringAngleRadians: number;
     throttle: number;
     brake: number;
@@ -252,7 +393,25 @@ export interface PaddockDriverObservationObject {
     pitStopServiceRemainingSeconds: number | null;
     pitStopPenaltyServiceRemainingSeconds: number | null;
     pitStopsCompleted: number;
+    lateralG: number;
+    longitudinalG: number;
+    gripUsage: number;
+    slipAngleRadians: number;
+    tractionLimited: boolean;
+    stabilityState: PaddockStabilityState;
+    destroyed: boolean;
+    destroyReason: string | null;
+  };
+  trackRelation: {
+    lateralOffsetMeters: number;
+    headingErrorRadians: number;
+    legalWidthMeters: number;
+    leftBoundaryMeters: number;
+    rightBoundaryMeters: number;
+    onLegalSurface: boolean;
+    surface: string;
   };
+  contactPatches: PaddockContactPatchObservation[];
   race: {
     position: number;
     totalCars: number;
@@ -272,6 +431,17 @@ export interface PaddockDriverObservationObject {
   events: RaceEvent[];
 }
 
+export interface PaddockContactPatchObservation {
+  id: 'front-left' | 'front-right' | 'rear-left' | 'rear-right' | string;
+  present: boolean;
+  signedOffsetMeters: number;
+  crossTrackErrorMeters: number;
+  surface: string;
+  surfaceCode: number;
+  onLegalSurface: boolean;
+  inPitLane: boolean;
+}
+
 export interface PaddockObservationSchemaEntry {
   name: string;
   unit?: string;
@@ -279,21 +449,34 @@ export interface PaddockObservationSchemaEntry {
 }
 
 export interface PaddockDriverObservation {
-  object: PaddockDriverObservationObject;
-  vector: number[];
-  schema: PaddockObservationSchemaEntry[];
+  object?: PaddockDriverObservationObject;
+  vector?: number[] | Float32Array;
+  schema?: PaddockObservationSchemaEntry[];
   events: RaceEvent[];
 }
 
+export type PaddockWarmupPolicy = 'config-change' | 'always' | 'never';
+
+export interface PaddockWarmupOptions {
+  enabled?: boolean;
+  policy?: PaddockWarmupPolicy;
+  steps?: number;
+}
+
 export interface PaddockEnvironmentOptions {
   drivers: SimulatorDriver[];
   entries?: ChampionshipEntryBlueprint[];
   controlledDrivers: string[];
   seed?: number;
   trackSeed?: number;
+  trackGeneration?: PaddockProceduralTrackOptions;
+  trackQueryIndex?: boolean;
   totalLaps?: number;
   frameSkip?: number;
+  physicsMode?: PaddockPhysicsMode;
   rules?: PaddockRaceRules;
+  participantInteractions?: PaddockParticipantInteractionsOptions;
+  replayGhosts?: PaddockReplayGhostOptions[];
   actionPolicy?: 'strict' | 'report';
   scenario?: {
     participants?: 'all' | 'controlled-only' | string[];
@@ -307,6 +490,15 @@ export interface PaddockEnvironmentOptions {
       enabled?: boolean;
       anglesDegrees?: number[];
       lengthMeters?: number;
+      defaultLengthMeters?: number;
+      layout?: 'compact' | 'driver-front-heavy' | 'lidar-lite' | string;
+      rays?: Array<number | {
+        id?: string;
+        angleDegrees: number;
+        lengthMeters?: number;
+      }>;
+      channels?: Array<'roadEdge' | 'kerb' | 'illegalSurface' | 'car'>;
+      precision?: 'driver' | 'debug';
       detectTrack?: boolean;
       detectCars?: boolean;
     };
@@ -318,13 +510,27 @@ export interface PaddockEnvironmentOptions {
   };
   sensorsByDriver?: Record<string, PaddockEnvironmentOptions['sensors']>;
   observation?: {
+    profile?: 'default' | 'physical-driver' | 'debug-map' | string;
+    output?: 'full' | 'vector' | 'object';
+    includeSchema?: boolean;
+    vectorType?: 'array' | 'float32';
     lookaheadMeters?: number[];
   };
+  result?: {
+    stateOutput?: 'full' | 'minimal' | 'none';
+    resetDriversObservationScope?: 'all' | 'reset';
+  };
+  warmup?: PaddockWarmupOptions | boolean;
   episode?: {
     maxSteps?: number;
     endOnRaceFinish?: boolean;
   };
   reward?: (payload: PaddockRewardContext) => number;
+  externalRenderer?: PaddockExternalRendererHook | ((frame: PaddockExternalRenderFrame) => void);
+}
+
+export interface PaddockExternalRendererHook {
+  onFrame(frame: PaddockExternalRenderFrame): void;
 }
 
 export interface PaddockScenarioPlacement {
@@ -351,6 +557,8 @@ export interface PaddockRewardContext {
   action: PaddockAction | undefined;
   events: RaceEvent[];
   state: { snapshot: RaceSnapshot };
+  metrics: PaddockEnvironmentDriverMetrics;
+  episode: PaddockDriverRuntimeState;
 }
 
 export interface PaddockProgressRewardWeights {
@@ -382,7 +590,7 @@ export interface PaddockActionSpec {
 }
 
 export interface PaddockObservationSpec {
-  version: 2;
+  version: 2 | 4;
   controlledDrivers: string[];
   object: Record<string, unknown>;
   vector: {
@@ -446,11 +654,114 @@ export type PaddockPolicyLike =
   | ((observation: PaddockDriverObservation, context: Record<string, unknown>) => PaddockAction)
   | { predict(observation: PaddockDriverObservation, context: Record<string, unknown>): PaddockAction };
 
+export interface PaddockDriverControllerContext {
+  runtime: PaddockControllerRuntime;
+  mode: string;
+  actionRepeat: number;
+  controlledDrivers: string[];
+  actionSpec: PaddockActionSpec;
+  observationSpec: PaddockObservationSpec;
+  result: PaddockEnvironmentResult | unknown;
+  previousResult: PaddockEnvironmentResult | unknown | null;
+  observation: Record<string, PaddockDriverObservation>;
+  orderedObservations: Array<{
+    driverId: string;
+    index: number;
+    observation: PaddockDriverObservation | null;
+    vector: number[] | Float32Array | null;
+  }>;
+  metrics: Record<string, PaddockEnvironmentDriverMetrics>;
+  events: RaceEvent[];
+  info: PaddockEnvironmentResult['info'] | unknown | null;
+  previousActions: PaddockActionMap;
+  orderedPreviousActions: Array<PaddockAction | null>;
+  actions: PaddockActionMap | null;
+  policyStep: number;
+  runtimeStep: number;
+  heldFramesRemaining: number;
+  actionIndex: number;
+  resetDriverIds: string[];
+}
+
+export interface PaddockExternalRenderFrame {
+  snapshot: RaceSnapshot;
+  observation: Record<string, unknown>;
+  meta?: Record<string, unknown> | null;
+}
+
+export interface PaddockExternalRendererSource {
+  subscribe(onFrame: (frame: PaddockExternalRenderFrame) => void): () => void;
+}
+
+export interface PaddockExternalRendererState {
+  attached: boolean;
+  lastMeta: Record<string, unknown> | null;
+  lastFrameAt: number | null;
+  lastError: string | null;
+}
+
+export interface PaddockDriverController {
+  init?(context: PaddockDriverControllerContext): void | Promise<void>;
+  reset?(context: PaddockDriverControllerContext): void | Promise<void>;
+  decideBatch(context: PaddockDriverControllerContext): PaddockActionMap | Promise<PaddockActionMap>;
+  onStep?(context: PaddockDriverControllerContext): void | Promise<void>;
+}
+
+export interface PaddockControllerRuntime {
+  reset(options?: unknown): PaddockEnvironmentResult | unknown;
+  step(actions: PaddockActionMap): PaddockEnvironmentResult | unknown;
+  resetDrivers?(
+    placements: Record<string, PaddockScenarioPlacement>,
+    resultOptions?: PaddockEnvironmentResultOptions
+  ): PaddockEnvironmentResult | unknown;
+  getObservation(): Record<string, PaddockDriverObservation>;
+  getState?(options?: { output?: 'full' | 'minimal' | 'none' }): PaddockEnvironmentResult['state'] | unknown;
+  getActionSpec(): PaddockActionSpec;
+  getObservationSpec(): PaddockObservationSpec;
+  destroy?(): void;
+}
+
+export interface PaddockDriverControllerLoopOptions {
+  runtime: PaddockControllerRuntime;
+  controller: PaddockDriverController;
+  actionRepeat?: number;
+  mode?: string;
+  scheduler?: null | ((callback: () => void | Promise<void>) => unknown);
+}
+
+export interface PaddockDriverControllerLoop {
+  readonly result: PaddockEnvironmentResult | unknown | null;
+  readonly actionSpec: PaddockActionSpec | null;
+  readonly observationSpec: PaddockObservationSpec | null;
+  readonly stats: {
+    policyStep: number;
+    runtimeStep: number;
+    heldFramesRemaining: number;
+    actions: PaddockActionMap | null;
+    actionRepeat: number;
+    lastDecisionMs: number;
+    running: boolean;
+    lastError: unknown | null;
+  };
+  reset(options?: unknown): Promise<PaddockEnvironmentResult | unknown>;
+  resetDrivers(
+    placements: Record<string, PaddockScenarioPlacement>,
+    resultOptions?: PaddockEnvironmentResultOptions
+  ): Promise<PaddockEnvironmentResult | unknown>;
+  step(): Promise<PaddockEnvironmentResult | unknown>;
+  stepFrame(): Promise<PaddockEnvironmentResult | unknown>;
+  start(): void;
+  stop(): void;
+}
+
 export interface PaddockEnvironmentWorkerMessage {
   id?: string | number | null;
-  type: 'reset' | 'step' | 'getActionSpec' | 'getObservationSpec' | 'getObservation' | 'getState' | 'destroy' | string;
+  type: 'reset' | 'resetDrivers' | 'step' | 'getActionSpec' | 'getObservationSpec' | 'getObservation' | 'getState' | 'destroy' | string;
   options?: Partial<PaddockEnvironmentOptions>;
   actions?: PaddockActionMap;
+  placements?: Record<string, PaddockScenarioPlacement>;
+  resultOptions?: PaddockEnvironmentResultOptions;
+  stateOptions?: { output?: 'full' | 'minimal' | 'none' };
 }
 
 export interface PaddockEnvironmentWorkerResponse {
@@ -468,11 +779,12 @@ export interface PaddockEnvironmentWorkerProtocol {
 export interface PaddockEnvironmentResult {
   observation: Record<string, PaddockDriverObservation>;
   reward: null | Record<string, number>;
+  metrics: Record<string, PaddockEnvironmentDriverMetrics>;
   terminated: boolean;
   truncated: boolean;
   done: boolean;
   events: RaceEvent[];
-  state: { snapshot: RaceSnapshot };
+  state: { snapshot: RaceSnapshot } | null;
   info: {
     step: number;
     elapsedSeconds: number;
@@ -481,20 +793,60 @@ export interface PaddockEnvironmentResult {
     controlledDrivers: string[];
     actionErrors: string[];
     endReason: string | null;
+    drivers: Record<string, PaddockDriverRuntimeState>;
   };
 }
 
+export type PaddockEnvironmentSnapshotResult = PaddockEnvironmentResult & {
+  state: { snapshot: RaceSnapshot };
+};
+
 export interface PaddockEnvironment {
   reset(options?: Partial<PaddockEnvironmentOptions>): PaddockEnvironmentResult;
+  resetDrivers(
+    placements: Record<string, PaddockScenarioPlacement>,
+    resultOptions?: PaddockEnvironmentResultOptions
+  ): PaddockEnvironmentResult;
   step(actions: PaddockActionMap): PaddockEnvironmentResult;
   getObservation(): PaddockEnvironmentResult['observation'];
-  getState(): PaddockEnvironmentResult['state'];
+  getState(options?: { output?: 'full' | 'minimal' | 'none' }): PaddockEnvironmentResult['state'];
   getActionSpec(): PaddockActionSpec;
   getObservationSpec(): PaddockObservationSpec;
   destroy(): void;
 }
 
+export interface PaddockEnvironmentResultOptions {
+  stateOutput?: 'full' | 'minimal' | 'none';
+  observationScope?: 'all' | 'reset';
+  resetDriversObservationScope?: 'all' | 'reset';
+}
+
+export interface PaddockDriverRuntimeState {
+  terminated: boolean;
+  truncated: boolean;
+  endReason: string | null;
+  episodeStep: number;
+  episodeId: number;
+}
+
+export interface PaddockEnvironmentDriverMetrics {
+  progressDeltaMeters: number;
+  legalProgressDeltaMeters: number;
+  offTrack: boolean;
+  kerb: boolean;
+  fullyOutsideWhiteLine: boolean;
+  severeCut: boolean;
+  destroyed: boolean;
+  destroyReason: string | null;
+  under30kph: boolean;
+  spinOrBackwards: boolean;
+  completedLap: boolean;
+  lapTimeSeconds: number | null;
+  contactCount: number;
+}
+
 export function createPaddockEnvironment(options: PaddockEnvironmentOptions): PaddockEnvironment;
+export function createPaddockDriverControllerLoop(options: PaddockDriverControllerLoopOptions): PaddockDriverControllerLoop;
 export function createProgressReward(options?: PaddockProgressRewardOptions): (context: PaddockRewardContext) => number;
 export function createRolloutRecorder(): PaddockRolloutRecorder;
 export function createRolloutTransition(
@@ -504,8 +856,8 @@ export function createRolloutTransition(
 ): PaddockRolloutTransition;
 export const ENVIRONMENT_SCENARIO_PRESETS: readonly PaddockScenarioPreset[];
 export const DEFAULT_EVALUATION_CASES: readonly PaddockEvaluationCase[];
-export function createEvaluationTracker(initialResult: PaddockEnvironmentResult): {
-  update(result: PaddockEnvironmentResult): void;
+export function createEvaluationTracker(initialResult: PaddockEnvironmentSnapshotResult): {
+  update(result: PaddockEnvironmentSnapshotResult): void;
   finish(): Record<string, PaddockEvaluationDriverMetrics>;
 };
 export function runEnvironmentEvaluation(options: {

package/src/environment/index.js

@@ -1,4 +1,5 @@
 export { createPaddockEnvironment } from './runtime.js';
+export { createPaddockDriverControllerLoop } from './controllerLoop.js';
 export { createProgressReward } from './rewards.js';
 export { createRolloutRecorder, createRolloutTransition } from './recorder.js';
 export {