@inventure71/paddockjs 0.2.0 → 1.0.0

package/src/index.d.ts

@@ -1,5 +1,19 @@
+import type { PaddockActionSpec, PaddockObservationSpec } from './environment/index.js';
+
+export type { PaddockActionSpec, PaddockObservationSpec } from './environment/index.js';
+
 export type TireCompound = 'S' | 'M' | 'H';
-export type CameraMode = 'overview' | 'leader' | 'selected';
+export type PaddockPitIntent = 0 | 1 | 2;
+export type PaddockPitIntentRequest = PaddockPitIntent | {
+  intent?: PaddockPitIntent;
+  pitIntent?: PaddockPitIntent;
+  targetCompound?: TireCompound | string;
+  compound?: TireCompound | string;
+  pitCompound?: TireCompound | string;
+  pitTargetCompound?: TireCompound | string;
+  targetTire?: TireCompound | string;
+};
+export type CameraMode = 'overview' | 'leader' | 'selected' | 'show-all' | 'pit';
 export type RaceBannerMode = 'project' | 'radio' | 'hidden';
 export type RaceBannerEnabledMode = 'project' | 'radio';
 export type RaceDataBannerSize = 'auto' | 'custom';
@@ -22,6 +36,14 @@ export interface TeamData {
   name?: string;
   color?: string;
   icon?: string;
+  pitCrew?: PaddockPitCrewStats;
+  pitCrewStats?: PaddockPitCrewStats;
+}
+
+export interface PaddockPitCrewStats {
+  speed?: number;
+  consistency?: number;
+  reliability?: number;
 }
 
 export interface SimulatorDriver {
@@ -179,6 +201,10 @@ export interface F1SimulatorUiOptions {
     enabled?: true | false | RaceBannerEnabledMode[];
   };
   raceDataBannerSize?: RaceDataBannerSize;
+  raceDataTelemetryDetail?: boolean;
+  penaltyBanners?: boolean;
+  timingPenaltyBadges?: boolean;
+  simulationSpeedControl?: boolean;
   timingTowerVerticalFit?: TimingTowerVerticalFit;
 }
 
@@ -201,9 +227,113 @@ export interface TrackSnapshot {
   width?: number;
   length?: number;
   sectors?: TrackSectorSnapshot[];
+  pitLane?: PitLaneSnapshot;
   [key: string]: unknown;
 }
 
+export interface TrackPointSnapshot {
+  x: number;
+  y: number;
+  heading?: number;
+  distance?: number;
+}
+
+export interface PitLaneSnapshot {
+  enabled: boolean;
+  side: -1 | 1;
+  width: number;
+  offset?: number;
+  boxCount: number;
+  teamCount: number;
+  boxesPerTeam: number;
+  entry: {
+    trackDistance: number;
+    distanceFromStart: number;
+    trackPoint: TrackPointSnapshot;
+    edgePoint: TrackPointSnapshot;
+    trackConnectPoint: TrackPointSnapshot;
+    lanePoint: TrackPointSnapshot;
+    roadCenterline: TrackPointSnapshot[];
+    connector: TrackPointSnapshot[];
+  };
+  exit: {
+    trackDistance: number;
+    distanceFromStart: number;
+    trackPoint: TrackPointSnapshot;
+    edgePoint: TrackPointSnapshot;
+    trackConnectPoint: TrackPointSnapshot;
+    lanePoint: TrackPointSnapshot;
+    roadCenterline: TrackPointSnapshot[];
+    connector: TrackPointSnapshot[];
+  };
+  mainLane: {
+    start: TrackPointSnapshot;
+    end: TrackPointSnapshot;
+    points: TrackPointSnapshot[];
+    length: number;
+    heading: number;
+  };
+  fastLane?: {
+    offset: number;
+    width: number;
+  };
+  workingLane?: {
+    start: TrackPointSnapshot;
+    end: TrackPointSnapshot;
+    points: TrackPointSnapshot[];
+    offset: number;
+    width: number;
+  };
+  serviceNormal: { x: number; y: number };
+  teams?: PitTeamSnapshot[];
+  boxes: PitBoxSnapshot[];
+  serviceAreas?: PitServiceAreaSnapshot[];
+}
+
+export interface PitTeamSnapshot {
+  id: string;
+  name: string;
+  color: string;
+  index: number;
+  boxIds: string[];
+  serviceAreaId?: string | null;
+}
+
+export interface PitBoxSnapshot {
+  id: string;
+  index: number;
+  teamIndex: number;
+  teamBoxIndex: number;
+  teamId?: string;
+  teamName?: string;
+  teamColor?: string;
+  distanceAlongLane: number;
+  laneTarget: TrackPointSnapshot;
+  center: TrackPointSnapshot;
+  length: number;
+  depth: number;
+  corners: TrackPointSnapshot[];
+}
+
+export interface PitServiceAreaSnapshot {
+  id: string;
+  index: number;
+  teamIndex: number;
+  teamId?: string;
+  teamName?: string;
+  teamColor?: string;
+  distanceAlongLane: number;
+  queueDistanceAlongLane: number;
+  laneTarget: TrackPointSnapshot;
+  center: TrackPointSnapshot;
+  queuePoint: TrackPointSnapshot;
+  length: number;
+  depth: number;
+  corners: TrackPointSnapshot[];
+  queueCorners: TrackPointSnapshot[];
+  garageBoxIds: string[];
+}
+
 export interface TrackSectorSnapshot {
   index: number;
   id: string;
@@ -222,6 +352,8 @@ export interface LapTelemetrySnapshot {
   currentSectorElapsed: number | null;
   currentSectorProgress: number | null;
   currentSectors: Array<number | null>;
+  sectorProgress: Array<number | null>;
+  liveSectors: Array<number | null>;
   sectorPerformance: {
     current: Array<SectorPerformanceStatus | null>;
     last: Array<SectorPerformanceStatus | null>;
@@ -234,12 +366,187 @@ export interface LapTelemetrySnapshot {
   completedLaps: number;
 }
 
+export interface PitStopSnapshot {
+  status: 'pending' | 'entering' | 'queued' | 'servicing' | 'exiting' | 'completed';
+  intent: PaddockPitIntent;
+  phase: 'entry' | 'queue' | 'queue-release' | 'penalty' | 'service' | 'exit' | null;
+  boxIndex: number;
+  boxId: string;
+  garageBoxIndex?: number | null;
+  garageBoxId?: string | null;
+  teamId?: string | null;
+  teamColor?: string | null;
+  stopsCompleted: number;
+  queueingForService?: boolean;
+  plannedRaceDistance: number | null;
+  entryRaceDistance: number | null;
+  serviceRemainingSeconds: number | null;
+  penaltyServiceRemainingSeconds: number | null;
+  penaltyServiceTotalSeconds: number | null;
+  servingPenaltyIds: string[];
+  targetTire?: TireCompound | string | null;
+  serviceProfile?: {
+    baseSeconds: number;
+    seconds: number;
+    perfect: boolean;
+    variabilityEnabled: boolean;
+    teamId?: string | null;
+    pitCrew: Required<PaddockPitCrewStats>;
+    speedDeltaSeconds: number;
+    consistencyDeltaSeconds: number;
+    issueDelaySeconds: number;
+    issue?: string | null;
+  } | null;
+}
+
 export interface RaceEvent {
   type: string;
   at?: number;
+  firstShapeId?: string;
+  secondShapeId?: string;
+  contactType?: 'body-body' | 'body-wheel' | 'wheel-body' | 'wheel-wheel' | string;
+  depth?: number;
+  timeOfImpact?: number;
+  [key: string]: unknown;
+}
+
+export type PaddockRulesetName = 'paddock' | 'custom' | 'grandPrix2025' | 'fia2025';
+
+export interface PaddockPitStopRules {
+  enabled?: boolean;
+  pitLaneSpeedLimitKph?: number;
+  defaultStopSeconds?: number;
+  variability?: {
+    enabled?: boolean;
+    perfect?: boolean;
+    speedImpactSeconds?: number;
+    consistencyJitterSeconds?: number;
+    issueChance?: number;
+    issueMaxDelaySeconds?: number;
+  };
+  maxConcurrentPitLaneCars?: number;
+  minimumPitLaneGapMeters?: number;
+  doubleStacking?: boolean;
+  tirePitRequestThresholdPercent?: number;
+  tirePitCommitThresholdPercent?: number;
+}
+
+export interface PaddockTireStrategyRules {
+  enabled?: boolean;
+  compounds?: TireCompound[];
+  mandatoryDistinctDryCompounds?: number | null;
+}
+
+export interface PaddockPenaltySubsectionRules {
+  strictness?: number;
+  timePenaltySeconds?: number;
+  consequences?: PaddockPenaltyConsequence[];
+}
+
+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 PaddockTrackLimitPenaltyRules extends PaddockPenaltySubsectionRules {
+  warningsBeforePenalty?: number;
+  relaxedMarginMeters?: number;
+}
+
+export interface PaddockCollisionPenaltyRules extends PaddockPenaltySubsectionRules {
+  minimumSeverity?: number;
+  relaxedSeverityMargin?: number;
+  minimumImpactSpeedKph?: number;
+  relaxedImpactSpeedKph?: number;
+}
+
+export interface PaddockPitLaneSpeedingPenaltyRules extends PaddockPenaltySubsectionRules {
+  speedLimitKph?: number;
+  marginKph?: number;
+  relaxedMarginKph?: number;
+}
+
+export interface PaddockPenaltyRules {
+  enabled?: boolean;
+  stewardStrictness?: number;
+  trackLimits?: PaddockTrackLimitPenaltyRules;
+  collision?: PaddockCollisionPenaltyRules;
+  tireRequirement?: PaddockPenaltySubsectionRules;
+  pitLaneSpeeding?: PaddockPitLaneSpeedingPenaltyRules;
+}
+
+export interface PaddockRaceModules {
+  pitStops?: PaddockPitStopRules;
+  tireStrategy?: PaddockTireStrategyRules;
+  penalties?: PaddockPenaltyRules;
+  weather?: { enabled?: boolean };
+  reliability?: { enabled?: boolean };
+  fuelLoad?: { enabled?: boolean };
+}
+
+export interface PaddockRaceRules {
+  ruleset?: PaddockRulesetName;
+  profile?: PaddockRulesetName;
+  modules?: PaddockRaceModules;
+  drsDetectionSeconds?: number;
+  safetyCarSpeed?: number;
+  safetyCarLeadDistance?: number;
+  safetyCarGap?: number;
+  collisionRestitution?: number;
+  standingStart?: boolean;
+  startLightCount?: number;
+  startLightInterval?: number;
+  startLightsOutHold?: number;
+}
+
+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 interface WheelSurfaceSnapshot {
+  id: string;
+  x: number;
+  y: number;
+  signedOffset: number;
+  crossTrackError: number;
+  surface: string;
+  onTrack: boolean;
+  inPitLane: boolean;
+  fullyOutsideWhiteLine: boolean;
+}
+
 export interface CarSnapshot {
   id: string;
   rank: number;
@@ -250,12 +557,32 @@ export interface CarSnapshot {
   tire: TireCompound;
   lap: number;
   speedKph: number;
+  finishRank?: number | null;
+  status?: 'racing' | 'waved-flag' | string;
+  raceStatus?: 'racing' | 'waved-flag' | string;
+  wavedFlag?: boolean;
   finished?: boolean;
   finishTime?: number | null;
+  penaltySeconds?: number;
+  adjustedFinishTime?: number | null;
   classifiedRank?: number | null;
   intervalAheadSeconds?: number | null;
   leaderGapSeconds?: number | null;
+  gapAheadLaps?: number;
+  intervalAheadLaps?: number;
+  leaderGapLaps?: number;
   lapTelemetry?: LapTelemetrySnapshot;
+  surface?: string;
+  signedOffset?: number;
+  crossTrackError?: number;
+  inPitLane?: boolean;
+  wheels?: WheelSurfaceSnapshot[];
+  pitLanePart?: 'entry' | 'fast-lane' | 'working-lane' | 'exit' | 'service-box' | 'garage-box' | null;
+  pitBoxId?: string | null;
+  pitLaneCrossTrackError?: number | null;
+  usedTireCompounds?: Array<TireCompound | string>;
+  pitIntent?: PaddockPitIntent;
+  pitStop?: PitStopSnapshot | null;
   [key: string]: unknown;
 }
 
@@ -266,6 +593,12 @@ export interface RaceClassificationEntry {
   lap: number;
   finished: boolean;
   finishTime?: number | null;
+  penaltySeconds?: number;
+  adjustedFinishTime?: number | null;
+  gapLaps?: number;
+  intervalLaps?: number;
+  positionDrop?: number;
+  disqualified?: boolean;
   [key: string]: unknown;
 }
 
@@ -280,6 +613,15 @@ export interface RaceSnapshot {
   totalLaps: number;
   raceControl: {
     mode: string;
+    redFlag: boolean;
+    pitLaneOpen: boolean;
+    pitLaneStatus?: {
+      enabled: boolean;
+      open: boolean;
+      reason: string;
+      color: string;
+      light: string;
+    };
     finished: boolean;
     finishedAt: number | null;
     winner: CarSnapshot | null;
@@ -289,12 +631,20 @@ export interface RaceSnapshot {
       [key: string]: unknown;
     };
   };
+  pitLaneStatus?: {
+    enabled: boolean;
+    open: boolean;
+    reason: string;
+    color: string;
+    light: string;
+  };
   safetyCar: {
     deployed: boolean;
     [key: string]: unknown;
   };
-  rules: Record<string, unknown>;
+  rules: PaddockRaceRules;
   events: RaceEvent[];
+  penalties: PaddockPenaltyEntry[];
   cars: CarSnapshot[];
 }
 
@@ -308,7 +658,7 @@ export interface F1SimulatorCallbacks {
   onLoadingChange?: (state: { loading: boolean; phase: string }) => void;
   onReady?: (payload: { snapshot: RaceSnapshot }) => void;
   onError?: (error: unknown, context: LifecycleErrorContext) => void;
-  onDriverSelect?: (driver: CarSnapshot, snapshot: RaceSnapshot) => void;
+  onDriverSelect?: (driver: NormalizedSimulatorDriver, snapshot: RaceSnapshot) => void;
   onRaceEvent?: (event: RaceEvent, snapshot: RaceSnapshot) => void;
   onLapChange?: (payload: {
     previousLeaderLap: number | null;
@@ -323,6 +673,34 @@ export interface F1SimulatorCallbacks {
   }) => void;
 }
 
+export interface F1SimulatorExpertOptions {
+  enabled: boolean;
+  controlledDrivers: string[];
+  frameSkip?: number;
+  visualizeSensors?: boolean | {
+    rays?: boolean;
+  };
+}
+
+export interface F1SimulatorExpertAction {
+  steering: number;
+  throttle: number;
+  brake: number;
+  pitIntent?: PaddockPitIntent;
+  pitCompound?: TireCompound | string;
+  pitTargetCompound?: TireCompound | string;
+}
+
+export interface F1SimulatorExpertApi {
+  reset(options?: unknown): unknown;
+  step(actions: Record<string, F1SimulatorExpertAction>): unknown;
+  getObservation(): unknown;
+  getState(): unknown;
+  getActionSpec(): PaddockActionSpec;
+  getObservationSpec(): PaddockObservationSpec;
+  destroy(): void;
+}
+
 export interface F1SimulatorOptions extends F1SimulatorCallbacks {
   preset?: PaddockPresetName;
   drivers: SimulatorDriver[];
@@ -330,6 +708,7 @@ export interface F1SimulatorOptions extends F1SimulatorCallbacks {
   seed?: number;
   trackSeed?: number;
   totalLaps?: number;
+  rules?: PaddockRaceRules;
   initialCameraMode?: CameraMode;
   theme?: F1SimulatorTheme;
   title?: string;
@@ -339,8 +718,11 @@ export interface F1SimulatorOptions extends F1SimulatorCallbacks {
   showBackLink?: boolean;
   ui?: F1SimulatorUiOptions;
   assets?: F1SimulatorAssets;
+  expert?: F1SimulatorExpertOptions;
 }
 
+export type F1SimulatorRestartOptions = Partial<Omit<F1SimulatorOptions, 'assets' | 'expert'>>;
+
 export interface MountRaceCanvasOptions {
   includeRaceDataPanel?: boolean;
   includeTimingTower?: boolean;
@@ -355,20 +737,30 @@ export interface MountTelemetryPanelOptions {
 export interface MountRaceTelemetryDrawerOptions {
   timingTowerVerticalFit?: TimingTowerVerticalFit;
   drawerInitiallyOpen?: boolean;
+  raceDataTelemetryDetail?: boolean;
 }
 
 export interface F1MountedSimulator {
+  readonly expert: F1SimulatorExpertApi | null;
   destroy(): void;
-  restart(nextOptions?: Partial<F1SimulatorOptions>): void;
+  restart(nextOptions?: F1SimulatorRestartOptions): void;
   selectDriver(driverId: string): void;
   setSafetyCarDeployed(deployed: boolean): void;
+  setRedFlagDeployed(deployed: boolean): void;
+  setPitLaneOpen(open: boolean): void;
   callSafetyCar(): void;
   clearSafetyCar(): void;
   toggleSafetyCar(): void;
+  setPitIntent(driverId: string, intent: PaddockPitIntentRequest, targetCompound?: TireCompound | string): boolean;
+  getPitIntent(driverId: string): PaddockPitIntent;
+  getPitTargetCompound(driverId: string): TireCompound | string | null;
+  servePenalty(penaltyId: string): PaddockPenaltyEntry | null;
+  cancelPenalty(penaltyId: string): PaddockPenaltyEntry | null;
   getSnapshot(): RaceSnapshot | null;
 }
 
 export interface PaddockSimulatorController {
+  readonly expert: F1SimulatorExpertApi | null;
   mountRaceControls<T extends Element>(root: T): T;
   mountCameraControls<T extends Element>(root: T): T;
   mountSafetyCarControl<T extends Element>(root: T): T;
@@ -387,12 +779,19 @@ export interface PaddockSimulatorController {
   querySelectorAll(selector: string): Element[];
   start(): Promise<PaddockSimulatorController>;
   destroy(): void;
-  restart(nextOptions?: Partial<F1SimulatorOptions>): void;
+  restart(nextOptions?: F1SimulatorRestartOptions): void;
   selectDriver(driverId: string): void;
   setSafetyCarDeployed(deployed: boolean): void;
+  setRedFlagDeployed(deployed: boolean): void;
+  setPitLaneOpen(open: boolean): void;
   callSafetyCar(): void;
   clearSafetyCar(): void;
   toggleSafetyCar(): void;
+  setPitIntent(driverId: string, intent: PaddockPitIntentRequest, targetCompound?: TireCompound | string): boolean;
+  getPitIntent(driverId: string): PaddockPitIntent;
+  getPitTargetCompound(driverId: string): TireCompound | string | null;
+  servePenalty(penaltyId: string): PaddockPenaltyEntry | null;
+  cancelPenalty(penaltyId: string): PaddockPenaltyEntry | null;
   getSnapshot(): RaceSnapshot | null;
 }
 
@@ -416,7 +815,7 @@ export function buildChampionshipDriverGrid(
 export function formatDriverNumber(driverNumber: number | string | null | undefined): string;
 export function normalizeSimulatorDrivers(
   drivers: SimulatorDriver[],
-  options?: { entries?: ChampionshipEntryBlueprint[] },
+  options?: { entries?: ChampionshipEntryBlueprint[]; caller?: string },
 ): NormalizedSimulatorDriver[];
 
 export function metersToSimUnits(meters: number): number;

package/src/index.js

@@ -91,13 +91,17 @@ export async function mountF1Simulator(root, options = {}) {
   await app.init();
 
   return {
+    get expert() {
+      return app.expert ?? null;
+    },
     destroy() {
       app.destroy();
       root.innerHTML = '';
     },
     restart(nextOptions = {}) {
-      resolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(resolvedOptions, nextOptions));
-      app.restart(resolvedOptions);
+      const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(resolvedOptions, nextOptions));
+      app.restart(nextResolvedOptions);
+      resolvedOptions = nextResolvedOptions;
     },
     selectDriver(driverId) {
       app.selectCar(driverId, { focus: true });
@@ -105,6 +109,12 @@ export async function mountF1Simulator(root, options = {}) {
     setSafetyCarDeployed(deployed) {
       app.setSafetyCarDeployed(deployed);
     },
+    setRedFlagDeployed(deployed) {
+      app.setRedFlagDeployed(deployed);
+    },
+    setPitLaneOpen(open) {
+      app.setPitLaneOpen(open);
+    },
     callSafetyCar() {
       app.setSafetyCarDeployed(true);
     },
@@ -115,6 +125,21 @@ export async function mountF1Simulator(root, options = {}) {
       const active = app.getSnapshot()?.raceControl.mode === 'safety-car';
       app.setSafetyCarDeployed(!active);
     },
+    setPitIntent(driverId, intent, targetCompound) {
+      return app.setPitIntent(driverId, intent, targetCompound);
+    },
+    getPitIntent(driverId) {
+      return app.getPitIntent(driverId);
+    },
+    getPitTargetCompound(driverId) {
+      return app.getPitTargetCompound(driverId);
+    },
+    servePenalty(penaltyId) {
+      return app.servePenalty(penaltyId);
+    },
+    cancelPenalty(penaltyId) {
+      return app.cancelPenalty(penaltyId);
+    },
     getSnapshot() {
       return app.getSnapshot();
     },