@inventure71/paddockjs 4.1.0 → 4.2.0

package/src/environment/index.d.ts

@@ -39,6 +39,69 @@ export interface PaddockProceduralTrackOptions {
   };
 }
 
+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 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';
@@ -674,8 +737,8 @@ export interface PaddockDriverControllerContext {
   controlledDrivers: string[];
   actionSpec: PaddockActionSpec;
   observationSpec: PaddockObservationSpec;
-  result: PaddockEnvironmentResult | unknown;
-  previousResult: PaddockEnvironmentResult | unknown | null;
+  result: PaddockEnvironmentResult;
+  previousResult: PaddockEnvironmentResult | null;
   observation: Record<string, PaddockDriverObservation>;
   orderedObservations: Array<{
     driverId: string;
@@ -685,7 +748,7 @@ export interface PaddockDriverControllerContext {
   }>;
   metrics: Record<string, PaddockEnvironmentDriverMetrics>;
   events: RaceEvent[];
-  info: PaddockEnvironmentResult['info'] | unknown | null;
+  info: PaddockEnvironmentResult['info'] | null;
   previousActions: PaddockActionMap;
   orderedPreviousActions: Array<PaddockAction | null>;
   actions: PaddockActionMap | null;
@@ -721,14 +784,14 @@ export interface PaddockDriverController {
 }
 
 export interface PaddockControllerRuntime {
-  reset(options?: unknown): PaddockEnvironmentResult | unknown;
-  step(actions: PaddockActionMap): PaddockEnvironmentResult | unknown;
+  reset(options?: unknown): PaddockEnvironmentResult;
+  step(actions: PaddockActionMap): PaddockEnvironmentResult;
   resetDrivers?(
     placements: Record<string, PaddockScenarioPlacement>,
     resultOptions?: PaddockEnvironmentResultOptions
-  ): PaddockEnvironmentResult | unknown;
+  ): PaddockEnvironmentResult;
   getObservation(): Record<string, PaddockDriverObservation>;
-  getState?(options?: { output?: 'full' | 'minimal' | 'none' }): PaddockEnvironmentResult['state'] | unknown;
+  getState?(options?: { output?: 'full' | 'minimal' | 'none' }): PaddockEnvironmentResult['state'];
   getActionSpec(): PaddockActionSpec;
   getObservationSpec(): PaddockObservationSpec;
   destroy?(): void;
@@ -743,7 +806,7 @@ export interface PaddockDriverControllerLoopOptions {
 }
 
 export interface PaddockDriverControllerLoop {
-  readonly result: PaddockEnvironmentResult | unknown | null;
+  readonly result: PaddockEnvironmentResult | null;
   readonly actionSpec: PaddockActionSpec | null;
   readonly observationSpec: PaddockObservationSpec | null;
   readonly stats: {
@@ -756,13 +819,13 @@ export interface PaddockDriverControllerLoop {
     running: boolean;
     lastError: unknown | null;
   };
-  reset(options?: unknown): Promise<PaddockEnvironmentResult | unknown>;
+  reset(options?: unknown): Promise<PaddockEnvironmentResult>;
   resetDrivers(
     placements: Record<string, PaddockScenarioPlacement>,
     resultOptions?: PaddockEnvironmentResultOptions
-  ): Promise<PaddockEnvironmentResult | unknown>;
-  step(): Promise<PaddockEnvironmentResult | unknown>;
-  stepFrame(): Promise<PaddockEnvironmentResult | unknown>;
+  ): Promise<PaddockEnvironmentResult>;
+  step(): Promise<PaddockEnvironmentResult>;
+  stepFrame(): Promise<PaddockEnvironmentResult>;
   start(): void;
   stop(): void;
 }

package/src/index.d.ts

@@ -2,6 +2,7 @@ import type {
   PaddockActionSpec,
   PaddockDriverControllerLoop,
   PaddockDriverControllerLoopOptions,
+  PaddockEnvironmentResult,
   PaddockEnvironmentOptions,
   PaddockObservationSpec,
   PaddockParticipantInteraction as EnvPaddockParticipantInteraction,
@@ -20,6 +21,8 @@ export type {
   PaddockDriverControllerContext,
   PaddockDriverControllerLoop,
   PaddockDriverControllerLoopOptions,
+  PaddockEnvironmentResult,
+  PaddockEnvironmentSnapshotResult,
   PaddockObservationSpec,
 } from './environment/index.js';
 
@@ -71,6 +74,69 @@ export interface PaddockProceduralTrackOptions {
   };
 }
 
+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 type PaddockStabilityState = 'stable' | 'understeer' | 'oversteer' | 'spin-risk' | 'destroyed';
 export type PaddockPitIntent = 0 | 1 | 2;
 export type PaddockPitIntentRequest = PaddockPitIntent | {
@@ -959,14 +1025,14 @@ export interface PaddockEnvironmentResultOptions {
 }
 
 export interface F1SimulatorExpertApi {
-  reset(options?: unknown): unknown;
-  step(actions: Record<string, F1SimulatorExpertAction>): unknown;
+  reset(options?: unknown): PaddockEnvironmentResult;
+  step(actions: Record<string, F1SimulatorExpertAction>): PaddockEnvironmentResult;
   resetDrivers?(
     placements: Record<string, PaddockScenarioPlacement>,
     resultOptions?: PaddockEnvironmentResultOptions
-  ): unknown;
-  getObservation(): unknown;
-  getState(): unknown;
+  ): PaddockEnvironmentResult;
+  getObservation(): PaddockEnvironmentResult['observation'];
+  getState(): PaddockEnvironmentResult['state'];
   getActionSpec(): PaddockActionSpec;
   getObservationSpec(): PaddockObservationSpec;
   attachExternalRenderer(source: PaddockExternalRendererSource): void;
@@ -1133,7 +1199,7 @@ export function simSpeedToMetersPerSecond(simSpeed: number): number;
 
 export function createPaddockSimulator(options: F1SimulatorOptions): PaddockSimulatorController;
 export function mountF1Simulator(root: Element, options: F1SimulatorOptions): Promise<F1MountedSimulator>;
-export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): unknown;
+export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): PaddockProceduralTrack;
 export function createPaddockDriverControllerLoop(options: PaddockDriverControllerLoopOptions): PaddockDriverControllerLoop;
 
 export function mountRaceControls<T extends Element>(root: T, simulator: PaddockSimulatorController): T;

package/src/simulation/collisionGeometry.js

@@ -1,7 +1,4 @@
-import {
-  getVehicleGeometryState,
-  vehicleAxes,
-} from './vehicle/vehicleGeometry.js';
+import { getVehicleGeometryState } from './vehicle/vehicleGeometry.js';
 import { normalizeAngle } from './simMath.js';
 
 const DEFAULT_SWEEP_STEPS = 16;
@@ -340,17 +337,18 @@ function writeInterpolatedBodyShape(target, geometryState, amount) {
   const x = pose.previousX + (pose.x - pose.previousX) * amount;
   const y = pose.previousY + (pose.y - pose.previousY) * amount;
   const heading = normalizeAngle(pose.previousHeading + headingDelta * amount);
-  const axes = vehicleAxes(heading);
+  const cos = Math.cos(heading);
+  const sin = Math.sin(heading);
   const halfLength = target.halfLength;
   const halfWidth = target.halfWidth;
 
   target.center.x = x;
   target.center.y = y;
   target.heading = heading;
-  target.forward.x = axes.forward.x;
-  target.forward.y = axes.forward.y;
-  target.right.x = axes.right.x;
-  target.right.y = axes.right.y;
+  target.forward.x = cos;
+  target.forward.y = sin;
+  target.right.x = -sin;
+  target.right.y = cos;
 
   writeOffsetCorner(target.corners[0], target.center, target.forward, target.right, halfLength, halfWidth);
   writeOffsetCorner(target.corners[1], target.center, target.forward, target.right, halfLength, -halfWidth);

package/src/simulation/driver/driverController.js

@@ -4,7 +4,7 @@ import { decideRacingControls } from './racingControls.js';
 import { decideRejoinControls } from './rejoinControls.js';
 import { shouldContinueRejoinRecovery } from './edgeRecovery.js';
 import { decideSafetyCarControls } from './safetyCarControls.js';
-import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode } from '../vehicle/vehiclePhysics.js';
 
 export function decideDriverControls({ car, orderIndex, race }) {
   if (car.manualControls) return car.manualControls;
@@ -37,7 +37,7 @@ export function decideDriverControls({ car, orderIndex, race }) {
 }
 
 function shouldStabilizeSimulatorCar(car, race) {
-  if (race.physicsMode !== 'advanced') return false;
+  if (!isSimulatorPhysicsMode(race.physicsMode)) return false;
   const gripUsage = car.gripUsage ?? 0;
   const slipAngle = Math.abs(car.slipAngleRadians ?? 0);
   const edgeDistance = race.track.width / 2 - VEHICLE_LIMITS.carWidth * 2.25;

package/src/simulation/driver/edgeRecovery.js

@@ -1,11 +1,11 @@
 import { clamp, normalizeAngle } from '../simMath.js';
 import { metersToSimUnits } from '../units.js';
 import { pointAt } from '../track/trackModel.js';
-import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode } from '../vehicle/vehiclePhysics.js';
 import { REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_MAX } from './driverControlConstants.js';
 
 export function calculateTrackEdgeGuard(car, race) {
-  const simulatorMode = race.physicsMode === 'advanced';
+  const simulatorMode = isSimulatorPhysicsMode(race.physicsMode);
   const trackLimit = race.track.width / 2;
   const halfCarWidth = VEHICLE_LIMITS.carWidth / 2;
   const wholeCarOutsideLimit = trackLimit + halfCarWidth;

package/src/simulation/driver/racingControls.js

@@ -1,7 +1,7 @@
 import { clamp, normalizeAngle } from '../simMath.js';
 import { kphToSimSpeed, metersToSimUnits, simUnitsToMeters } from '../units.js';
-import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
-import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { pointAtInto, sampleHeadingAt, sampleHeadingCurvatureAtInto } from '../track/trackModel.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode } from '../vehicle/vehiclePhysics.js';
 import { BRAKING_LOOKAHEAD_MAX_DISTANCE, CURVATURE_LOOKAHEAD_SAMPLES, EDGE_RECOVERY_MIN_LOOKAHEAD, LOOKAHEAD_BASE_DISTANCE, LOOKAHEAD_MAX_DISTANCE, OVERTAKE_LATERAL_MIN, PREVIEW_CURVATURE_CAP, TRAFFIC_GAP_AHEAD, TRAFFIC_SIDE_GAP } from './driverControlConstants.js';
 import { createDriverInput } from './driverInput.js';
 import { angleToPoint } from './driverMath.js';
@@ -10,15 +10,14 @@ import { calculateActualOverlapPenalty, calculatePlannedTrafficPenalty, planRaci
 import { analyzeTrackEdgeMotion } from './recoveryDynamics.js';
 
 export function decideRacingControls(car, orderIndex, race) {
-  if (race.physicsMode === 'advanced') {
+  if (isSimulatorPhysicsMode(race.physicsMode)) {
     return decideSimulatorRacingControls(car, orderIndex, race);
   }
   return decideArcadeRacingControls(car, orderIndex, race);
 }
 
-export function decideArcadeRacingControls(car, orderIndex, race) {
-  return decideRacingControlsForMode(car, orderIndex, race, {
-    simulatorMode: false,
+const ARCADE_CONTROL_PROFILE = {
+  simulatorMode: false,
     baseLookaheadSpeedFactor: (aggression) => 1.62 - aggression * 0.12,
     previewLookaheadSpeedFactor: 3.15,
     edgeLookaheadPenaltyMeters: 18,
@@ -73,12 +72,14 @@ export function decideArcadeRacingControls(car, orderIndex, race) {
     recoveryHeadingThrottleStart: 0.38,
     throttleResponseKph: 16,
     throttleScale: () => 1,
-  });
+};
+
+export function decideArcadeRacingControls(car, orderIndex, race) {
+  return decideRacingControlsForMode(car, orderIndex, race, ARCADE_CONTROL_PROFILE);
 }
 
-export function decideSimulatorRacingControls(car, orderIndex, race) {
-  return decideRacingControlsForMode(car, orderIndex, race, {
-    simulatorMode: true,
+const SIMULATOR_CONTROL_PROFILE = {
+  simulatorMode: true,
     baseLookaheadSpeedFactor: (aggression) => 2.45 - aggression * 0.06,
     previewLookaheadSpeedFactor: 6.15,
     edgeLookaheadPenaltyMeters: 34,
@@ -141,7 +142,10 @@ export function decideSimulatorRacingControls(car, orderIndex, race) {
       0,
       1,
     ),
-  });
+};
+
+export function decideSimulatorRacingControls(car, orderIndex, race) {
+  return decideRacingControlsForMode(car, orderIndex, race, SIMULATOR_CONTROL_PROFILE);
 }
 
 function decideRacingControlsForMode(car, orderIndex, race, profile) {
@@ -170,7 +174,7 @@ function decideRacingControlsForMode(car, orderIndex, race, profile) {
     EDGE_RECOVERY_MIN_LOOKAHEAD,
     LOOKAHEAD_MAX_DISTANCE,
   );
-  const targetBase = pointAt(race.track, car.progress + lookahead);
+  const targetBase = pointAtInto(race.track, car.progress + lookahead, TARGET_BASE_SCRATCH);
   const curvature = Math.max(
     car.trackState.curvature,
     targetBase.curvature,
@@ -189,8 +193,9 @@ function decideRacingControlsForMode(car, orderIndex, race, profile) {
     -edgeGuard.recoveryOffset,
     edgeGuard.recoveryOffset,
   );
-  const target = offsetTrackPoint(targetBase, targetOffset);
-  const angleError = angleToPoint(car, target);
+  TARGET_POINT_SCRATCH.x = targetBase.x + targetBase.normalX * targetOffset;
+  TARGET_POINT_SCRATCH.y = targetBase.y + targetBase.normalY * targetOffset;
+  const angleError = angleToPoint(car, TARGET_POINT_SCRATCH);
   const headingError = normalizeAngle(targetBase.heading - car.heading);
   const lateralError = car.trackState?.signedOffset ?? 0;
   const outwardDriftAngle = simulatorMode &&
@@ -363,15 +368,20 @@ function decideRacingControlsForMode(car, orderIndex, race, profile) {
     .controls();
 }
 
+const LOOKAHEAD_SAMPLE_SCRATCH = { heading: 0, curvature: 0 };
+const TARGET_BASE_SCRATCH = { x: 0, y: 0, heading: 0, normalX: 0, normalY: 0, curvature: 0, distance: 0 };
+const TARGET_POINT_SCRATCH = { x: 0, y: 0 };
+
 export function maxLookaheadCurvature(track, progress, lookahead) {
   let maximum = 0;
-  let previous = pointAt(track, progress);
+  const sample = LOOKAHEAD_SAMPLE_SCRATCH;
+  let previousHeading = sampleHeadingCurvatureAtInto(track, progress, sample).heading;
+  const segmentDistance = Math.max(1, lookahead / CURVATURE_LOOKAHEAD_SAMPLES);
   for (let index = 1; index <= CURVATURE_LOOKAHEAD_SAMPLES; index += 1) {
-    const sample = pointAt(track, progress + lookahead * (index / CURVATURE_LOOKAHEAD_SAMPLES));
-    const segmentDistance = Math.max(1, lookahead / CURVATURE_LOOKAHEAD_SAMPLES);
-    const segmentCurvature = Math.abs(normalizeAngle(sample.heading - previous.heading)) / segmentDistance;
+    sampleHeadingCurvatureAtInto(track, progress + lookahead * (index / CURVATURE_LOOKAHEAD_SAMPLES), sample);
+    const segmentCurvature = Math.abs(normalizeAngle(sample.heading - previousHeading)) / segmentDistance;
     maximum = Math.max(maximum, Math.abs(sample.curvature ?? 0), Math.min(segmentCurvature, PREVIEW_CURVATURE_CAP));
-    previous = sample;
+    previousHeading = sample.heading;
   }
   return maximum;
 }
@@ -380,16 +390,16 @@ export function calculateRacingLineOffset(car, race, lookahead, curvature, edgeG
   const cornerStrength = clamp((curvature - 0.00012) / 0.00095, 0, 1);
   if (cornerStrength <= 0) return 0;
 
-  const entry = pointAt(race.track, car.progress - lookahead * 0.35);
-  const apex = pointAt(race.track, car.progress + lookahead * 0.55);
-  const exit = pointAt(race.track, car.progress + lookahead * 1.25);
-  const signedEntry = normalizeAngle(apex.heading - entry.heading);
-  const signedExit = normalizeAngle(exit.heading - apex.heading);
+  const entryHeading = sampleHeadingAt(race.track, car.progress - lookahead * 0.35);
+  const apexHeading = sampleHeadingAt(race.track, car.progress + lookahead * 0.55);
+  const exitHeading = sampleHeadingAt(race.track, car.progress + lookahead * 1.25);
+  const signedEntry = normalizeAngle(apexHeading - entryHeading);
+  const signedExit = normalizeAngle(exitHeading - apexHeading);
   const turnDirection = Math.sign(Math.abs(signedEntry) > Math.abs(signedExit) ? signedEntry : signedExit);
   if (turnDirection === 0) return 0;
 
   const aggression = car.aggression ?? car.personality?.baseAggression ?? 0.5;
-  const simulatorMode = race.physicsMode === 'advanced';
+  const simulatorMode = isSimulatorPhysicsMode(race.physicsMode);
   const safeEdge = race.track.width / 2 - VEHICLE_LIMITS.carWidth *
     (simulatorMode ? 2.05 - aggression * 0.08 : 1.15 - aggression * 0.12);
   const apexOffset = turnDirection * safeEdge *

package/src/simulation/driver/racingLinePlan.js

@@ -18,15 +18,16 @@ export function planRacingLine(car, orderIndex, race) {
   let bestOffset = currentOffset;
   let bestScore = -Infinity;
 
-  LANE_OFFSETS.forEach((rawOffset) => {
-    const offset = clamp(rawOffset, -trackLimit, trackLimit);
+  for (let laneIndex = 0; laneIndex < LANE_OFFSETS.length; laneIndex += 1) {
+    const offset = clamp(LANE_OFFSETS[laneIndex], -trackLimit, trackLimit);
     const edgeClearance = trackLimit - Math.abs(offset);
     let score = 80;
     score -= Math.abs(offset - preferred) * 0.18;
     score -= Math.abs(offset - currentOffset) * (0.09 - aggression * 0.025);
     score -= Math.max(0, LANE_EDGE_CLEARANCE_TARGET - edgeClearance) * (0.92 - aggression * 0.42);
 
-    traffic.forEach((entry) => {
+    for (let trafficIndex = 0; trafficIndex < traffic.length; trafficIndex += 1) {
+      const entry = traffic[trafficIndex];
       const lateral = Math.abs(entry.signedOffset - offset);
       if (entry.gap > 0 && entry.gap < TRAFFIC_GAP_AHEAD) {
         const overlapRisk = clamp(TRAFFIC_SIDE_OVERLAP - lateral, 0, TRAFFIC_SIDE_OVERLAP);
@@ -38,7 +39,7 @@ export function planRacingLine(car, orderIndex, race) {
         const sideOverlapRisk = clamp(TRAFFIC_SIDE_OVERLAP - lateral, 0, TRAFFIC_SIDE_OVERLAP);
         score -= sideOverlapRisk * (TRAFFIC_SIDE_OVERLAP + entry.gap) * 0.052 * (1 - riskTolerance * 0.22);
       }
-    });
+    }
 
     if (ahead && car.gapAhead < TRAFFIC_GAP_AHEAD) {
       const passSide = attackPlan?.targetOffset ?? clamp(
@@ -73,7 +74,7 @@ export function planRacingLine(car, orderIndex, race) {
       bestScore = score;
       bestOffset = offset;
     }
-  });
+  }
 
   const laneChangeRate = metersToSimUnits(0.95 + car.racecraft * 0.32 + aggression * 0.78);
   car.desiredOffset = currentOffset + clamp(bestOffset - currentOffset, -laneChangeRate, laneChangeRate);

package/src/simulation/driver/rejoinControls.js

@@ -4,11 +4,11 @@ import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
 import { REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_MAX } from './driverControlConstants.js';
 import { angleToPoint } from './driverMath.js';
 import { createDriverInput } from './driverInput.js';
-import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode } from '../vehicle/vehiclePhysics.js';
 import { analyzeTrackEdgeMotion } from './recoveryDynamics.js';
 
 export function decideRejoinControls(car, race) {
-  if (race.physicsMode === 'advanced') {
+  if (isSimulatorPhysicsMode(race.physicsMode)) {
     return decideSimulatorRejoinControls(car, race);
   }
   return decideArcadeRejoinControls(car, race);
@@ -103,7 +103,7 @@ export function decideSimulatorRejoinControls(car, race) {
 }
 
 function decideRejoinControlsForMode(car, race, profile) {
-  const simulatorMode = race.physicsMode === 'advanced';
+  const simulatorMode = isSimulatorPhysicsMode(race.physicsMode);
   const lookahead = clamp(car.speed * (profile.simulatorMode ? 0.58 : 0.72) + REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_MAX);
   const edgeMotion = analyzeTrackEdgeMotion(car, race);
   const lowSpeedOffTrack = !car.trackState.onTrack && car.speed < kphToSimSpeed(24);

package/src/simulation/driver/trafficScan.js

@@ -2,25 +2,43 @@ import { metersToSimUnits } from '../units.js';
 import { DEFEND_REAR_GAP, TRAFFIC_GAP_AHEAD, TRAFFIC_SIDE_GAP, TRAFFIC_REAR_WINDOW } from './driverControlConstants.js';
 import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
 
+const TRAFFIC_REAR_SCAN_WINDOW = metersToSimUnits(39);
+const TRAFFIC_FORWARD_SCAN_WINDOW = metersToSimUnits(134);
+const TRAFFIC_BESIDE_WINDOW = metersToSimUnits(28);
+
+// Entries are reused across calls: drivers consume the scan synchronously
+// within a single control decision, so a module-level pool avoids re-allocating
+// the candidate list for every car on every step.
+const TRAFFIC_SCRATCH = [];
+const TRAFFIC_ENTRY_POOL = [];
+
 export function scanNearbyTraffic(car, race) {
-  return race.cars
-    .filter((other) => other !== car)
-    .map((other) => ({
-      car: other,
-      gap: other.raceDistance - car.raceDistance,
-      signedOffset: other.trackState?.signedOffset ?? 0,
-      speed: other.speed,
-    }))
-    .filter((entry) => entry.gap > -metersToSimUnits(39) && entry.gap < metersToSimUnits(134));
+  const traffic = TRAFFIC_SCRATCH;
+  traffic.length = 0;
+  const cars = race.cars;
+  for (let index = 0; index < cars.length; index += 1) {
+    const other = cars[index];
+    if (other === car) continue;
+    const gap = other.raceDistance - car.raceDistance;
+    if (gap <= -TRAFFIC_REAR_SCAN_WINDOW || gap >= TRAFFIC_FORWARD_SCAN_WINDOW) continue;
+    const entry = TRAFFIC_ENTRY_POOL[traffic.length] ??= { car: null, gap: 0, signedOffset: 0, speed: 0 };
+    entry.car = other;
+    entry.gap = gap;
+    entry.signedOffset = other.trackState?.signedOffset ?? 0;
+    entry.speed = other.speed;
+    traffic.push(entry);
+  }
+  return traffic;
 }
 
 export function findDefensiveThreat(traffic) {
   let closest = null;
 
-  traffic.forEach((entry) => {
-    if (entry.gap >= -VEHICLE_LIMITS.carLength * 1.1 || entry.gap < -DEFEND_REAR_GAP) return;
+  for (let index = 0; index < traffic.length; index += 1) {
+    const entry = traffic[index];
+    if (entry.gap >= -VEHICLE_LIMITS.carLength * 1.1 || entry.gap < -DEFEND_REAR_GAP) continue;
     if (!closest || entry.gap > closest.gap) closest = entry;
-  });
+  }
 
   return closest;
 }
@@ -28,24 +46,32 @@ export function findDefensiveThreat(traffic) {
 export function findLaneTrafficAhead(traffic, offset, maxDistance) {
   let closest = null;
 
-  traffic.forEach((entry) => {
-    if (entry.gap <= 0 || entry.gap > maxDistance) return;
-    if (Math.abs(entry.signedOffset - offset) > TRAFFIC_SIDE_GAP) return;
+  for (let index = 0; index < traffic.length; index += 1) {
+    const entry = traffic[index];
+    if (entry.gap <= 0 || entry.gap > maxDistance) continue;
+    if (Math.abs(entry.signedOffset - offset) > TRAFFIC_SIDE_GAP) continue;
     if (!closest || entry.gap < closest.gap) closest = entry;
-  });
+  }
 
   return closest;
 }
 
 export function findLaneTrafficBeside(traffic, offset) {
   let closest = null;
+  let closestLateral = 0;
+  let closestRisk = -Infinity;
 
-  traffic.forEach((entry) => {
+  for (let index = 0; index < traffic.length; index += 1) {
+    const entry = traffic[index];
     const lateral = Math.abs(entry.signedOffset - offset);
-    if (Math.abs(entry.gap) > metersToSimUnits(28) || lateral > TRAFFIC_SIDE_GAP) return;
-    const risk = (metersToSimUnits(28) - Math.abs(entry.gap)) + (TRAFFIC_SIDE_GAP - lateral);
-    if (!closest || risk > closest.risk) closest = { ...entry, lateral, risk };
-  });
+    if (Math.abs(entry.gap) > TRAFFIC_BESIDE_WINDOW || lateral > TRAFFIC_SIDE_GAP) continue;
+    const risk = (TRAFFIC_BESIDE_WINDOW - Math.abs(entry.gap)) + (TRAFFIC_SIDE_GAP - lateral);
+    if (!closest || risk > closestRisk) {
+      closest = entry;
+      closestLateral = lateral;
+      closestRisk = risk;
+    }
+  }
 
-  return closest;
+  return closest ? { ...closest, lateral: closestLateral, risk: closestRisk } : null;
 }

package/src/simulation/participants/participantInteractions.js

@@ -41,14 +41,6 @@ export const PARTICIPANT_INTERACTION_PROFILES = Object.freeze({
   }),
 });
 
-const INTERACTION_FLAGS = Object.freeze([
-  'collidable',
-  'detectableByRays',
-  'detectableAsNearby',
-  'blocksPitLane',
-  'affectsRaceOrder',
-]);
-
 export function normalizeParticipantInteractions(options = {}) {
   const defaultProfile = resolveProfileName(options.defaultProfile);
   const defaultInteraction = { ...PARTICIPANT_INTERACTION_PROFILES[defaultProfile] };
@@ -73,11 +65,15 @@ export function attachParticipantInteractions(cars = [], options = {}) {
 
 export function resolveInteraction(override = {}, fallbackProfile = 'normal') {
   const profile = resolveProfileName(override?.profile ?? fallbackProfile);
-  const resolved = { ...PARTICIPANT_INTERACTION_PROFILES[profile] };
-  INTERACTION_FLAGS.forEach((flag) => {
-    if (override?.[flag] != null) resolved[flag] = Boolean(override[flag]);
-  });
-  return resolved;
+  const base = PARTICIPANT_INTERACTION_PROFILES[profile];
+  return {
+    profile,
+    collidable: override?.collidable != null ? Boolean(override.collidable) : base.collidable,
+    detectableByRays: override?.detectableByRays != null ? Boolean(override.detectableByRays) : base.detectableByRays,
+    detectableAsNearby: override?.detectableAsNearby != null ? Boolean(override.detectableAsNearby) : base.detectableAsNearby,
+    blocksPitLane: override?.blocksPitLane != null ? Boolean(override.blocksPitLane) : base.blocksPitLane,
+    affectsRaceOrder: override?.affectsRaceOrder != null ? Boolean(override.affectsRaceOrder) : base.affectsRaceOrder,
+  };
 }
 
 export function canCollide(first, second) {
@@ -110,8 +106,21 @@ export function affectsRaceOrder(car) {
 }
 
 export function serializeParticipantInteraction(interaction) {
-  const normalized = resolveInteraction(interaction ?? {}, interaction?.profile ?? 'normal');
-  return { ...normalized };
+  return resolveInteraction(interaction ?? {}, interaction?.profile ?? 'normal');
+}
+
+const SERIALIZED_INTERACTION_SOURCE = Symbol('serializedInteractionSource');
+const SERIALIZED_INTERACTION_VALUE = Symbol('serializedInteractionValue');
+
+// Render snapshots are pooled and rebuilt every frame; the interaction config
+// only changes when a new object is attached, so cache the serialized form per
+// car keyed on the interaction reference.
+export function serializeParticipantInteractionCached(car) {
+  if (car[SERIALIZED_INTERACTION_SOURCE] !== car.interaction || !car[SERIALIZED_INTERACTION_VALUE]) {
+    car[SERIALIZED_INTERACTION_SOURCE] = car.interaction;
+    car[SERIALIZED_INTERACTION_VALUE] = serializeParticipantInteraction(car.interaction);
+  }
+  return car[SERIALIZED_INTERACTION_VALUE];
 }
 
 function resolveProfileName(profile) {