@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/data/index.d.ts

@@ -1,199 +1,16 @@
-export type TireCompound = 'S' | 'M' | 'H';
-export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
+import type { TeamData } from './teamTypes.js';
 
-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 {
+  PaddockPitCrewStats,
+  PaddockThemeSelector,
+  TeamData,
+} from './teamTypes.js';
 
-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;
-  };
-}
+import type { PaddockProceduralTrackProfile, PaddockProceduralTrackOptions, PaddockTrackPoint, PaddockDrsZone, PaddockResolvedProceduralTrackOptions, PaddockProceduralTrack } from './trackTypes.js';
+import type { TireCompound, CustomField, CustomFieldInput, EntryPresentation, SimulatorDriver, DriverRatings, VehicleRatings, DriverBlueprint, VehicleBlueprint, DriverConstructorArgs, VehicleConstructorArgs, DriverData, VehicleData, ChampionshipEntryBlueprint, NormalizedSimulatorDriver } from './entryTypes.js';
+export type { PaddockProceduralTrackProfile, PaddockProceduralTrackOptions, PaddockTrackPoint, PaddockDrsZone, PaddockResolvedProceduralTrackOptions, PaddockProceduralTrack } from './trackTypes.js';
+export type { TireCompound, CustomField, CustomFieldInput, EntryPresentation, SimulatorDriver, DriverRatings, VehicleRatings, DriverBlueprint, VehicleBlueprint, DriverConstructorArgs, VehicleConstructorArgs, ChampionshipEntryBlueprint, NormalizedSimulatorDriver } from './entryTypes.js';
+export { DriverData, VehicleData } from './entryTypes.js';
 
 export const CHAMPIONSHIP_ENTRY_BLUEPRINTS: ChampionshipEntryBlueprint[];
 export const DEMO_PROJECT_DRIVERS: SimulatorDriver[];
@@ -207,6 +24,6 @@ export function normalizeSimulatorDrivers(
   drivers: SimulatorDriver[],
   options?: { entries?: ChampionshipEntryBlueprint[]; caller?: string },
 ): NormalizedSimulatorDriver[];
-export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): unknown;
+export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): PaddockProceduralTrack;
 export function kphToSimSpeed(kph: number): number;
 export function simSpeedToKph(simSpeed: number): number;

package/src/data/ratingScale.js

@@ -0,0 +1,14 @@
+export const RATING_MINIMUM = 0;
+export const RATING_NEUTRAL = 50;
+export const RATING_MAXIMUM = 100;
+
+export function clampRating(value, label, domain) {
+  const rating = Number(value);
+  if (!Number.isFinite(rating)) throw new Error(`Invalid ${domain} rating for ${label}: ${value}`);
+  return Math.min(Math.max(rating, RATING_MINIMUM), RATING_MAXIMUM);
+}
+
+export function applyRating(definition, value, direction = 1) {
+  const normalized = (value - definition.neutral) / (definition.maximum - definition.neutral);
+  return definition.base + normalized * definition.variance * direction;
+}

package/src/data/teamTypes.d.ts

@@ -0,0 +1,23 @@
+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;
+}

package/src/data/trackTypes.d.ts

@@ -0,0 +1,101 @@
+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 PaddockTrackPoint {
+  x: number;
+  y: number;
+}
+
+export interface PaddockDrsZone {
+  id: string;
+  startRatio: number;
+  endRatio: number;
+}
+
+export interface PaddockResolvedProceduralTrackOptions {
+  profile: PaddockProceduralTrackProfile;
+  length: {
+    min: number;
+    max: number;
+  };
+  startStraight: {
+    grid: number;
+    exit: number;
+    blend: number;
+    lockExtra: number;
+  };
+  pitLane: {
+    enabled: boolean;
+  };
+  shape: {
+    scale: number;
+    cornerDensity: number;
+    variation: number;
+  };
+  validation: {
+    minClearanceMultiplier: number;
+    minShapeVariation: number;
+    minNonAdjacentArcDistance: number;
+    maxLocalTurnRadians: number;
+    maxSampleHeadingDeltaRadians: number;
+  };
+  attempts: {
+    primary: number;
+    fallback: number;
+  };
+  cacheKey: string;
+  [key: string]: unknown;
+}
+
+export interface PaddockProceduralTrack {
+  name: string;
+  width: number;
+  kerbWidth: number;
+  gravelWidth: number;
+  runoffWidth: number;
+  barrierWidth: number;
+  sampleCount: number;
+  seed?: number;
+  curveInterpolation?: string;
+  centerlineControls?: readonly PaddockTrackPoint[];
+  drsZones?: readonly PaddockDrsZone[] | null;
+  pitLane?: { enabled?: boolean } | null;
+  generationOptions?: PaddockResolvedProceduralTrackOptions;
+  [key: string]: unknown;
+}

package/src/data/vehicleData.js

@@ -1,8 +1,6 @@
 import { normalizeCustomFields } from './customFields.js';
 
-const RATING_MINIMUM = 0;
-const RATING_NEUTRAL = 50;
-const RATING_MAXIMUM = 100;
+import { RATING_MINIMUM, RATING_NEUTRAL, RATING_MAXIMUM, clampRating, applyRating } from './ratingScale.js';
 
 export const VEHICLE_STAT_DEFINITIONS = {
   power: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 43000, variance: 3200, output: 'powerNewtons' },
@@ -14,18 +12,6 @@ export const VEHICLE_STAT_DEFINITIONS = {
   tireCare: { minimum: RATING_MINIMUM, neutral: RATING_NEUTRAL, maximum: RATING_MAXIMUM, base: 1, variance: 0.12, output: 'tireCare' },
 };
 
-function clampRating(value, label) {
-  const rating = Number(value);
-  if (!Number.isFinite(rating)) throw new Error(`Invalid vehicle rating for ${label}: ${value}`);
-  return Math.min(Math.max(rating, RATING_MINIMUM), RATING_MAXIMUM);
-}
-
-function applyRating(definition, value) {
-  const normalized = (value - definition.neutral) / (definition.maximum - definition.neutral);
-  const direction = definition.direction ?? 1;
-  return definition.base + normalized * definition.variance * direction;
-}
-
 export class VehicleData {
   constructor({
     id = null,
@@ -38,17 +24,19 @@ export class VehicleData {
     weightControl = RATING_NEUTRAL,
     tireCare = RATING_NEUTRAL,
     customFields = [],
+    driverModel = null,
   } = {}) {
     this.id = id;
     this.name = name;
-    this.power = clampRating(power, 'power');
-    this.braking = clampRating(braking, 'braking');
-    this.aero = clampRating(aero, 'aero');
-    this.dragEfficiency = clampRating(dragEfficiency, 'dragEfficiency');
-    this.mechanicalGrip = clampRating(mechanicalGrip, 'mechanicalGrip');
-    this.weightControl = clampRating(weightControl, 'weightControl');
-    this.tireCare = clampRating(tireCare, 'tireCare');
+    this.power = clampRating(power, 'power', 'vehicle');
+    this.braking = clampRating(braking, 'braking', 'vehicle');
+    this.aero = clampRating(aero, 'aero', 'vehicle');
+    this.dragEfficiency = clampRating(dragEfficiency, 'dragEfficiency', 'vehicle');
+    this.mechanicalGrip = clampRating(mechanicalGrip, 'mechanicalGrip', 'vehicle');
+    this.weightControl = clampRating(weightControl, 'weightControl', 'vehicle');
+    this.tireCare = clampRating(tireCare, 'tireCare', 'vehicle');
     this.customFields = normalizeCustomFields(customFields);
+    this.driverModel = driverModel;
   }
 
   ratings() {
@@ -67,7 +55,7 @@ export class VehicleData {
     const ratings = this.ratings();
     const values = Object.fromEntries(Object.entries(VEHICLE_STAT_DEFINITIONS).map(([key, definition]) => [
       definition.output,
-      applyRating(definition, ratings[key]),
+      applyRating(definition, ratings[key], definition.direction ?? 1),
     ]));
 
     return {
@@ -75,6 +63,7 @@ export class VehicleData {
       name: this.name,
       ratings,
       customFields: this.customFields,
+      driverModel: this.driverModel,
       ...values,
     };
   }

package/src/environment/actions.js

@@ -1,5 +1,6 @@
 import { clamp } from '../simulation/simMath.js';
 import { VEHICLE_LIMITS } from '../simulation/vehicle/vehiclePhysics.js';
+import { normalizePitIntent } from '../simulation/pit/pitIntent.js';
 
 export function resolveActionMap(actions = {}, controlledDrivers = [], { policy = 'strict' } = {}) {
   const errors = [];
@@ -52,8 +53,8 @@ function finiteActionValue(value, message, policy, errors) {
 
 function normalizePitIntentAction(action, driverId, policy, errors) {
   if (!Object.hasOwn(action, 'pitIntent')) return null;
-  const number = Number(action.pitIntent);
-  if (Number.isInteger(number) && number >= 0 && number <= 2) {
+  const number = normalizePitIntent(action.pitIntent);
+  if (number != null) {
     const pitCompound = normalizePitCompoundAction(action, driverId, policy, errors);
     if (pitCompound === false) return null;
     return pitCompound == null ? number : { intent: number, targetCompound: pitCompound };

package/src/environment/controllerLoop.js

@@ -1,3 +1,5 @@
+import { cancelScheduled, defaultScheduler, now } from './controllerScheduler.js';
+
 export function createPaddockDriverControllerLoop({
   runtime,
   controller,
@@ -28,6 +30,8 @@ export function createPaddockDriverControllerLoop({
   let previousActions = {};
   let lastDecisionMs = 0;
   let lastError = null;
+  let generation = 0;
+  let generationController = new AbortController();
 
   async function ensureSpecs() {
     if (!actionSpec) actionSpec = runtime.getActionSpec();
@@ -39,14 +43,24 @@ export function createPaddockDriverControllerLoop({
     observationSpec = runtime.getObservationSpec();
   }
 
+  async function runControllerHook(name, context) {
+    try {
+      return await controller[name]?.(context);
+    } catch (error) {
+      if (context.signal.aborted) return;
+      throw error;
+    }
+  }
+
   async function ensureInitialized(context) {
     if (initialized) return;
-    await controller.init?.(context);
-    initialized = true;
+    await runControllerHook('init', context);
+    if (!context.signal.aborted) initialized = true;
   }
 
   async function resetRuntime(options = {}, { stopPlayback = true } = {}) {
     if (stopPlayback) stop();
+    const resetGeneration = generation;
     result = runtime.reset(options);
     previousResult = null;
     heldActions = null;
@@ -57,9 +71,11 @@ export function createPaddockDriverControllerLoop({
     previousActions = {};
     lastError = null;
     await refreshSpecs();
+    if (generation !== resetGeneration) return result;
     const context = buildContext({ resetDriverIds: controlledDrivers() });
     await ensureInitialized(context);
-    await controller.reset?.(context);
+    if (generation !== resetGeneration) return result;
+    await runControllerHook('reset', context);
     return result;
   }
 
@@ -75,6 +91,9 @@ export function createPaddockDriverControllerLoop({
     if (typeof runtime.resetDrivers !== 'function') {
       throw new Error('The supplied Paddock runtime does not support resetDrivers().');
     }
+    const resumePlayback = running;
+    stop();
+    const resetGeneration = generation;
     const resetDriverIds = Object.keys(placements);
     previousResult = result;
     result = runtime.resetDrivers(placements, resultOptions);
@@ -89,29 +108,39 @@ export function createPaddockDriverControllerLoop({
       delete previousActions[driverId];
     });
     await ensureSpecs();
+    if (generation !== resetGeneration) return result;
     const context = buildContext({ resetDriverIds });
     await ensureInitialized(context);
-    await controller.reset?.(context);
+    if (generation !== resetGeneration) return result;
+    await runControllerHook('reset', context);
+    if (resumePlayback && generation === resetGeneration) start();
     return result;
   }
 
-  async function beginDecision() {
+  async function beginDecision(expectedGeneration) {
     await ensureResult();
+    if (generation !== expectedGeneration) return false;
     const context = buildContext();
     await ensureInitialized(context);
+    if (generation !== expectedGeneration) return false;
     const startedAt = now();
-    const actions = await controller.decideBatch(context);
+    const actions = await runControllerHook('decideBatch', context);
+    if (generation !== expectedGeneration) return false;
     lastDecisionMs = now() - startedAt;
     heldActions = actions && typeof actions === 'object' ? actions : {};
     heldFramesRemaining = repeat;
     policyStep += 1;
+    return true;
   }
 
-  async function stepFrame() {
+  async function stepFrame(expectedGeneration = generation) {
     await ensureResult();
+    if (generation !== expectedGeneration) return result;
     if (!heldActions || heldFramesRemaining <= 0) {
-      await beginDecision();
+      const decisionReady = await beginDecision(expectedGeneration);
+      if (!decisionReady) return result;
     }
+    if (generation !== expectedGeneration) return result;
     const actionIndex = repeat - heldFramesRemaining;
     const actions = heldActions;
     const previousActionsForStep = previousActions;
@@ -121,7 +150,8 @@ export function createPaddockDriverControllerLoop({
     heldFramesRemaining -= 1;
     runtimeStep = Number(result?.info?.step ?? runtimeStep + 1);
     previousActions = actions;
-    await controller.onStep?.(buildContext({
+    if (generation !== expectedGeneration) return result;
+    await runControllerHook('onStep', buildContext({
       actionIndex,
       actions,
       previousActions: previousActionsForStep,
@@ -133,8 +163,10 @@ export function createPaddockDriverControllerLoop({
   async function step() {
     let latest = result;
     const targetPolicyStep = policyStep + 1;
+    const expectedGeneration = generation;
     while (policyStep < targetPolicyStep || heldFramesRemaining > 0) {
-      latest = await stepFrame();
+      latest = await stepFrame(expectedGeneration);
+      if (generation !== expectedGeneration) break;
       if (latest?.done) break;
       if (policyStep >= targetPolicyStep && heldFramesRemaining <= 0) break;
     }
@@ -145,18 +177,21 @@ export function createPaddockDriverControllerLoop({
     if (running) return;
     lastError = null;
     running = true;
+    const expectedGeneration = generation;
     const schedule = scheduler ?? defaultScheduler();
     const tick = async () => {
-      if (!running) return;
+      if (!running || generation !== expectedGeneration) return;
       scheduled = null;
       try {
-        await stepFrame();
+        await stepFrame(expectedGeneration);
       } catch (error) {
+        if (generation !== expectedGeneration) return;
         lastError = error;
         running = false;
         scheduled = null;
         return;
       }
+      if (generation !== expectedGeneration) return;
       if (!running || result?.done) {
         running = false;
         return;
@@ -167,9 +202,17 @@ export function createPaddockDriverControllerLoop({
   }
 
   function stop() {
+    const previousController = generationController;
+    const previousSchedule = scheduled;
     running = false;
-    cancelScheduled(scheduled);
+    generation += 1;
+    generationController = new AbortController();
     scheduled = null;
+    try {
+      cancelScheduled(previousSchedule);
+    } finally {
+      previousController.abort();
+    }
   }
 
   function controlledDrivers() {
@@ -184,6 +227,7 @@ export function createPaddockDriverControllerLoop({
     };
     return {
       runtime,
+      signal: generationController.signal,
       mode,
       actionRepeat: repeat,
       controlledDrivers: drivers,
@@ -242,34 +286,3 @@ export function createPaddockDriverControllerLoop({
     },
   };
 }
-
-function now() {
-  return typeof performance !== 'undefined' && typeof performance.now === 'function'
-    ? performance.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) => {
-      const id = requestAnimationFrame(callback);
-      return { cancel: () => cancelAnimationFrame(id) };
-    };
-  }
-  return (callback) => {
-    const id = setTimeout(callback, 0);
-    return { cancel: () => clearTimeout(id) };
-  };
-}

package/src/environment/controllerScheduler.js

@@ -0,0 +1,30 @@
+export function now() {
+  return typeof performance !== 'undefined' && typeof performance.now === 'function'
+    ? performance.now()
+    : Date.now();
+}
+
+export 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);
+  }
+}
+
+export function defaultScheduler() {
+  if (typeof requestAnimationFrame === 'function') {
+    return (callback) => {
+      const id = requestAnimationFrame(callback);
+      return { cancel: () => cancelAnimationFrame(id) };
+    };
+  }
+  return (callback) => {
+    const id = setTimeout(callback, 0);
+    return { cancel: () => clearTimeout(id) };
+  };
+}