@inventure71/paddockjs 4.2.0 → 4.3.1

package/src/data/index.d.ts

@@ -1,262 +1,16 @@
-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 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;
-}
-
-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 { TeamData } from './teamTypes.js';
+
+export type {
+  PaddockPitCrewStats,
+  PaddockThemeSelector,
+  TeamData,
+} from './teamTypes.js';
+
+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[];

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 };