@inventure71/paddockjs 2.0.0 → 2.0.1

package/src/environment/specs.js

@@ -1,7 +1,8 @@
 import { normalizeLookaheadMeters } from './observationOptions.js';
+import { effectiveSensorOptions } from './observations.js';
 import { normalizeRayOptions } from './sensors.js';
 
-const PHYSICAL_RAY_SURFACE_CHANNELS = Object.freeze(['kerb', 'illegalSurface']);
+const MODEL_RAY_SURFACE_CHANNELS = Object.freeze(['kerb', 'illegalSurface']);
 
 export function buildActionSpec(options) {
   const compounds = Array.isArray(options.rules?.modules?.tireStrategy?.compounds) &&
@@ -32,7 +33,7 @@ export function buildObservationSpec(options) {
     : normalizeLookaheadMeters(options.observation?.lookaheadMeters);
   const profile = options.observation?.profile ?? 'default';
   return {
-    version: profile === 'physical-driver' ? 4 : 2,
+    version: profile === 'physical-driver' ? 6 : 3,
     controlledDrivers: [...options.controlledDrivers],
     object: {
       profile,
@@ -45,12 +46,15 @@ export function buildObservationSpec(options) {
         { name: 'steeringAngleRadians', unit: 'rad' },
         { name: 'throttle', unit: 'normalized' },
         { name: 'brake', unit: 'normalized' },
+        { name: 'appliedControls', unit: 'nullable:normalized-controls' },
         { name: 'lateralG', unit: 'g' },
         { name: 'longitudinalG', unit: 'g' },
         { name: 'gripUsage', unit: 'ratio' },
         { name: 'slipAngleRadians', unit: 'rad' },
         { name: 'tractionLimited', unit: 'boolean' },
         { name: 'stabilityState', unit: 'label' },
+        { name: 'destroyed', unit: 'boolean' },
+        { name: 'destroyReason', unit: 'nullable:label' },
         { name: 'lap', unit: 'count' },
         { name: 'completedLaps', unit: 'count' },
         { name: 'lapProgressMeters', unit: 'm' },
@@ -99,40 +103,8 @@ export function buildObservationSpec(options) {
         { name: 'redFlag', unit: 'boolean' },
         { name: 'totalLaps', unit: 'count' },
       ],
-      rays: {
-        enabled: Boolean(rayOptions.enabled),
-        anglesDegrees: [...rayOptions.anglesDegrees],
-        lengthMeters: rayOptions.lengthMeters,
-        defaultLengthMeters: rayOptions.defaultLengthMeters,
-        rays: rayOptions.rays.map((ray) => ({ ...ray })),
-        channels: [...rayOptions.channels],
-        precision: rayOptions.precision,
-        track: {
-          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
-          hit: { unit: 'boolean' },
-          kind: { values: ['exit', 'entry', null] },
-        },
-        roadEdge: {
-          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
-          hit: { unit: 'boolean' },
-          kind: { values: ['exit', 'entry', null] },
-        },
-        kerb: surfaceRaySpec(rayOptions.lengthMeters),
-        illegalSurface: surfaceRaySpec(rayOptions.lengthMeters),
-        car: {
-          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
-          hit: { unit: 'boolean' },
-          driverId: { nullable: true },
-          targetId: { nullable: true },
-          targetType: { values: ['car', 'replayGhost', null] },
-          relativeSpeedKph: { unit: 'kph' },
-        },
-      },
-      nearbyCars: {
-        enabled: Boolean(nearbyOptions.enabled),
-        maxCars: nearbyOptions.maxCars,
-        radiusMeters: nearbyOptions.radiusMeters,
-      },
+      rays: buildRayObjectSpec(rayOptions),
+      nearbyCars: buildNearbyObjectSpec(nearbyOptions),
       track: {
         lengthMeters: { unit: 'm' },
         widthMeters: { unit: 'm' },
@@ -149,6 +121,69 @@ export function buildObservationSpec(options) {
     vector: {
       schema: buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters, profile }),
     },
+    perDriver: buildPerDriverObservationSpecs(options, { rayOptions, nearbyOptions, lookaheadMeters, profile }),
+  };
+}
+
+function buildPerDriverObservationSpecs(options, { rayOptions, nearbyOptions, lookaheadMeters, profile }) {
+  if (Object.keys(options.sensorsByDriver ?? {}).length === 0) return {};
+  const defaultSensors = { rays: rayOptions, nearbyCars: nearbyOptions };
+  return Object.fromEntries(options.controlledDrivers.map((driverId) => {
+    const sensors = effectiveSensorOptions(options, driverId, defaultSensors, true);
+    return [driverId, {
+      object: {
+        rays: buildRayObjectSpec(sensors.rays),
+        nearbyCars: buildNearbyObjectSpec(sensors.nearbyCars),
+      },
+      vector: {
+        schema: buildVectorSchema({
+          rayOptions: sensors.rays,
+          nearbyOptions: sensors.nearbyCars,
+          lookaheadMeters,
+          profile,
+        }),
+      },
+    }];
+  }));
+}
+
+function buildRayObjectSpec(rayOptions) {
+  return {
+    enabled: Boolean(rayOptions.enabled),
+    anglesDegrees: [...rayOptions.anglesDegrees],
+    lengthMeters: rayOptions.lengthMeters,
+    defaultLengthMeters: rayOptions.defaultLengthMeters,
+    rays: rayOptions.rays.map((ray) => ({ ...ray })),
+    channels: [...rayOptions.channels],
+    precision: rayOptions.precision,
+    track: {
+      distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+      hit: { unit: 'boolean' },
+      kind: { values: ['exit', 'entry', null] },
+    },
+    roadEdge: {
+      distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+      hit: { unit: 'boolean' },
+      kind: { values: ['exit', 'entry', null] },
+    },
+    kerb: surfaceRaySpec(rayOptions.lengthMeters),
+    illegalSurface: surfaceRaySpec(rayOptions.lengthMeters),
+    car: {
+      distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+      hit: { unit: 'boolean' },
+      driverId: { nullable: true },
+      targetId: { nullable: true },
+      targetType: { values: ['car', 'replayGhost', null] },
+      relativeSpeedKph: { unit: 'kph' },
+    },
+  };
+}
+
+function buildNearbyObjectSpec(nearbyOptions) {
+  return {
+    enabled: Boolean(nearbyOptions.enabled),
+    maxCars: nearbyOptions.maxCars,
+    radiusMeters: nearbyOptions.radiusMeters,
   };
 }
 
@@ -193,6 +228,7 @@ function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters, profile
         { name: `contactPatches[${index}].surfaceCode`, scale: 'surface-code' },
         { name: `contactPatches[${index}].onLegalSurface`, scale: 'boolean' },
         { name: `contactPatches[${index}].signedOffsetMeters`, unit: 'm', scale: 'fixed:meters' },
+        { name: `contactPatches[${index}].crossTrackErrorMeters`, unit: 'm', scale: 'fixed:meters' },
       );
     }
   }
@@ -212,15 +248,16 @@ function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters, profile
         { name: `rays[${index}].car.distanceRatio`, scale: '0..1' },
         { name: `rays[${index}].car.hit`, scale: 'boolean' },
         { name: `rays[${index}].car.relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
+        { name: `rays[${index}].car.targetTypeReplayGhost`, scale: 'boolean' },
       );
-      if (includePhysicalDriverSenses) {
-        PHYSICAL_RAY_SURFACE_CHANNELS.forEach((channel) => {
+      MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
+        if (rayOptions.channels?.includes?.(channel)) {
           schema.push(
             { name: `rays[${index}].${channel}.distanceRatio`, scale: '0..1' },
             { name: `rays[${index}].${channel}.hit`, scale: 'boolean' },
           );
-        });
-      }
+        }
+      });
     });
   }
   if (nearbyOptions.enabled) {
@@ -234,6 +271,7 @@ function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters, profile
         { name: `nearbyCars[${index}].relativeHeadingRadians`, unit: 'rad', scale: 'fixed:pi' },
         { name: `nearbyCars[${index}].ahead`, scale: 'boolean' },
         { name: `nearbyCars[${index}].sameLap`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].entityTypeReplayGhost`, scale: 'boolean' },
       );
       if (includePhysicalDriverSenses) {
         schema.push(

package/src/index.d.ts

@@ -648,6 +648,8 @@ export interface CarSnapshot {
   tire: TireCompound;
   interaction?: PaddockParticipantInteraction;
   lap: number;
+  velocityX?: number | null;
+  velocityY?: number | null;
   speedKph: number;
   finishRank?: number | null;
   status?: 'racing' | 'waved-flag' | 'destroyed' | string;

package/src/index.js

@@ -1,6 +1,7 @@
 import './styles.css';
 import { F1SimulatorApp } from './app/F1SimulatorApp.js';
 import { resolveF1SimulatorOptions } from './config/defaultOptions.js';
+import { mergeRestartOptions } from './config/restartOptions.js';
 import { createF1SimulatorShell } from './ui/shellTemplate.js';
 export {
   createPaddockSimulator,
@@ -51,38 +52,6 @@ function assertMountRoot(root) {
   }
 }
 
-function mergeRestartOptions(previousOptions, nextOptions) {
-  const resetFromPreset = Object.hasOwn(nextOptions, 'preset');
-  const previousUi = resetFromPreset ? {} : previousOptions.ui;
-  const previousTheme = resetFromPreset ? {} : previousOptions.theme;
-  return {
-    ...previousOptions,
-    ...nextOptions,
-    ui: {
-      ...previousUi,
-      ...(nextOptions.ui ?? {}),
-      raceDataBanners: {
-        ...(previousUi.raceDataBanners ?? {}),
-        ...(nextOptions.ui?.raceDataBanners ?? {}),
-      },
-    },
-    theme: {
-      ...previousTheme,
-      ...(nextOptions.theme ?? {}),
-    },
-    assets: {
-      ...previousOptions.assets,
-      ...(nextOptions.assets ?? {}),
-      trackTextures: {
-        ...previousOptions.assets.trackTextures,
-        ...(nextOptions.assets?.trackTextures ?? {}),
-      },
-    },
-    drivers: nextOptions.drivers ?? previousOptions.drivers,
-    entries: nextOptions.entries ?? previousOptions.entries,
-  };
-}
-
 export async function mountF1Simulator(root, options = {}) {
   assertMountRoot(root);
 

package/src/simulation/pit/pitFlow.js

@@ -17,6 +17,7 @@ import {
   isPitServiceQueueOccupied,
   releasePitQueue,
 } from './pitService.js';
+import { syncPitCarKinematics } from './pitKinematics.js';
 import {
   createPitApproachPoints,
   createRoute,
@@ -209,6 +210,10 @@ export function advancePitStopCar(sim, car, delta) {
     car.speed = 0;
     car.throttle = 0;
     car.brake = 1;
+    car.steeringAngle = 0;
+    car.yawRate = 0;
+    car.turnRadius = Infinity;
+    syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
     applyWheelSurfaceState(car, sim.track);
     car.progress = car.trackState.distance;
     car.raceDistance = getPitBoxRaceDistance(sim, stop, {

package/src/simulation/pit/pitKinematics.js

@@ -0,0 +1,24 @@
+export function syncPitCarKinematics(car, { physicsMode = 'simulator' } = {}) {
+  const speed = Number.isFinite(car.speed) ? car.speed : 0;
+  const heading = Number.isFinite(car.heading) ? car.heading : 0;
+  if (physicsMode === 'simulator') {
+    car.velocityX = Math.cos(heading) * speed;
+    car.velocityY = Math.sin(heading) * speed;
+  } else {
+    car.velocityX = null;
+    car.velocityY = null;
+  }
+  car.appliedControls = {
+    steering: car.steeringAngle ?? 0,
+    throttle: car.throttle ?? 0,
+    brake: car.brake ?? 0,
+  };
+  car.lateralAcceleration = 0;
+  car.longitudinalAcceleration = 0;
+  car.lateralG = 0;
+  car.longitudinalG = 0;
+  car.gripUsage = 0;
+  car.slipAngleRadians = 0;
+  car.tractionLimited = false;
+  car.stabilityState = 'stable';
+}

package/src/simulation/pit/pitQueue.js

@@ -1,5 +1,6 @@
 import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
 import { createRoute, routePoint } from './pitRouting.js';
+import { syncPitCarKinematics } from './pitKinematics.js';
 import { PIT_QUEUE_RELEASE_SPEED } from './pitServiceConstants.js';
 import { getPitBoxRaceDistance } from './pitOccupancy.js';
 
@@ -17,6 +18,10 @@ export function beginPitQueue(sim, car, box) {
   car.speed = 0;
   car.throttle = 0;
   car.brake = 1;
+  car.steeringAngle = 0;
+  car.yawRate = 0;
+  car.turnRadius = Infinity;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
   applyWheelSurfaceState(car, sim.track);
   car.progress = car.trackState.distance;
   car.raceDistance = getPitBoxRaceDistance(sim, stop, {

package/src/simulation/pit/pitRouteMovement.js

@@ -8,6 +8,7 @@ import {
   routeLimiterActiveAt,
   sampleRoute,
 } from './pitRouting.js';
+import { syncPitCarKinematics } from './pitKinematics.js';
 import { completePitPenaltyService } from './pitPenaltyService.js';
 import { completePitService } from './pitTireService.js';
 import { getPitBoxRaceDistance, getPitStopBox } from './pitOccupancy.js';
@@ -51,6 +52,7 @@ export function applyPitRoutePosition(sim, car, delta) {
       VEHICLE_LIMITS.maxSteer,
     );
     car.turnRadius = Math.abs(car.yawRate) < 0.001 ? Infinity : car.speed / Math.abs(car.yawRate);
+    syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
     stop.routeProgress = nextProgress;
     const routeAmount = route.length > 0 ? stop.routeProgress / route.length : 1;
     car.raceDistance = stop.routeStartRaceDistance +
@@ -111,6 +113,7 @@ export function applyPitRoutePosition(sim, car, delta) {
     VEHICLE_LIMITS.maxSteer,
   );
   car.turnRadius = Math.abs(car.yawRate) < 0.001 ? Infinity : car.speed / Math.abs(car.yawRate);
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
   applyWheelSurfaceState(car, sim.track);
   stop.routeProgress = nextProgress;
   const routeAmount = route.length > 0 ? stop.routeProgress / route.length : 1;
@@ -148,6 +151,10 @@ export function advancePitService(sim, car, delta) {
   car.speed = 0;
   car.throttle = 0;
   car.brake = 1;
+  car.steeringAngle = 0;
+  car.yawRate = 0;
+  car.turnRadius = Infinity;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
   applyWheelSurfaceState(car, sim.track);
   car.progress = car.trackState.distance;
   car.raceDistance = getPitBoxRaceDistance(sim, stop, box);

package/src/simulation/pit/pitService.js

@@ -2,6 +2,7 @@ import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
 import { normalizePitCrewStats } from './pitState.js';
 import { beginPitPenaltyService } from './pitPenaltyService.js';
 import { beginTireService } from './pitTireService.js';
+import { syncPitCarKinematics } from './pitKinematics.js';
 import { getPitBoxRaceDistance } from './pitOccupancy.js';
 
 export { normalizePitCrewStats };
@@ -32,6 +33,7 @@ export function beginPitService(sim, car, box) {
   car.steeringAngle = 0;
   car.yawRate = 0;
   car.turnRadius = Infinity;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
   applyWheelSurfaceState(car, sim.track);
   car.progress = car.trackState.distance;
   car.raceDistance = getPitBoxRaceDistance(sim, stop, box);

package/src/simulation/pit/pitTireService.js

@@ -6,6 +6,7 @@ import {
   pitMainLanePointAt,
   routePoint,
 } from './pitRouting.js';
+import { syncPitCarKinematics } from './pitKinematics.js';
 import { getPitBoxRaceDistance, getPitStopBox } from './pitOccupancy.js';
 import { calculatePitServiceProfile } from './pitServiceProfile.js';
 import { PIT_BOX_APPROACH_DISTANCE, PIT_EXIT_RELEASE_SPEED_KPH } from './pitServiceConstants.js';
@@ -79,6 +80,7 @@ export function finishPitExit(sim, car) {
   car.speed = Math.max(car.speed, kphToSimSpeed(PIT_EXIT_RELEASE_SPEED_KPH));
   car.throttle = 0.55;
   car.brake = 0;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
   applyWheelSurfaceState(car, sim.track);
   car.progress = car.trackState.distance;
   car.raceDistance = Math.max(car.raceDistance ?? 0, stop.routeEndRaceDistance ?? car.raceDistance ?? 0);

package/src/simulation/race/raceLifecycle.js

@@ -2,6 +2,7 @@ import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
 import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
 import { clamp } from '../simMath.js';
 import { nearestTrackStateForCar } from '../track/trackStatePolicy.js';
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
 
 export function setPitLaneOpenState(sim, open) {
   const next = Boolean(open);
@@ -58,12 +59,7 @@ export function holdGridCars(sim) {
     car.x = position.x;
     car.y = position.y;
     car.heading = gridPoint.heading;
-    car.speed = 0;
-    car.throttle = 0;
-    car.brake = 1;
-    car.steeringAngle = 0;
-    car.yawRate = 0;
-    car.turnRadius = Infinity;
+    freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
     car.progress = gridPoint.distance;
     car.raceDistance = car.gridDistance;
     applyWheelSurfaceState(car, sim.track);

package/src/simulation/race/raceProgress.js

@@ -14,13 +14,18 @@ import {
 } from '../timing/raceTiming.js';
 import { progressDelta } from './raceDistance.js';
 import { isRaceDnf } from './retirements.js';
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
 
 export function recalculateRaceStateForSimulation(sim, { updateDrs = true } = {}) {
   sim.cars.forEach((car) => {
     const previousRaceDistance = car.raceDistance;
     if (car.destroyed || car.outOfRace) {
       applyWheelSurfaceState(car, sim.track);
-      car.speed = 0;
+      freezeVehicleMotion(car, {
+        clearManualControls: true,
+        physicsMode: sim.physicsMode,
+        stabilityState: car.destroyed ? 'destroyed' : car.stabilityState,
+      });
       car.canAttack = false;
       car.drsEligible = false;
       car.drsActive = false;

package/src/simulation/race/raceStep.js

@@ -40,7 +40,7 @@ export function runRaceStep(simulation, dt) {
     ];
   driveCars.forEach((car) => {
     if (car.destroyed || car.outOfRace) {
-      freezeRetiredCar(car);
+      freezeRetiredCar(car, { physicsMode: simulation.physicsMode });
       return;
     }
     const orderIndex = orderedIndexById.get(car.id);

package/src/simulation/race/redFlag.js

@@ -1,11 +1,11 @@
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
+
 export function applyRedFlagHoldForSimulation(sim) {
   sim.cars.forEach((car) => {
     car.previousX = car.x;
     car.previousY = car.y;
     car.previousHeading = car.heading;
-    car.speed = 0;
-    car.throttle = 0;
-    car.brake = 1;
+    freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
     car.drsActive = false;
     car.drsEligible = false;
     car.drsZoneId = null;

package/src/simulation/race/safetyCar.js

@@ -1,5 +1,6 @@
 import { pointAt } from '../track/trackModel.js';
 import { kphToSimSpeed } from '../units.js';
+import { freezeVehicleMotion, syncVehicleVelocityToHeading } from '../vehicle/vehicleKinematics.js';
 
 export function setSafetyCarState(sim, deployed) {
   const next = Boolean(deployed);
@@ -60,9 +61,7 @@ export function setRedFlagState(sim, deployed) {
     sim.raceControl.mode = 'red-flag';
     sim.raceControl.frozenOrder = sim.orderedCars().map((car) => car.id);
     sim.cars.forEach((car) => {
-      car.speed = 0;
-      car.throttle = 0;
-      car.brake = 1;
+      freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
       car.drsActive = false;
       car.drsEligible = false;
       car.drsZoneId = null;
@@ -75,8 +74,15 @@ export function setRedFlagState(sim, deployed) {
       ? sim.orderedCars().map((car) => car.id)
       : null;
     sim.cars.forEach((car) => {
-      if (!car.finished) {
+      if (car.destroyed || car.outOfRace) {
+        freezeVehicleMotion(car, {
+          clearManualControls: true,
+          physicsMode: sim.physicsMode,
+          stabilityState: car.destroyed ? 'destroyed' : car.stabilityState,
+        });
+      } else if (!car.finished) {
         car.speed = Math.max(car.speed, kphToSimSpeed(60));
+        if (sim.physicsMode === 'simulator') syncVehicleVelocityToHeading(car);
         car.brake = 0;
         car.throttle = Math.max(car.throttle ?? 0, 0.35);
       }

package/src/simulation/race/stalledDnf.js

@@ -1,5 +1,6 @@
 import { markCarDnf } from './retirements.js';
 import { simSpeedToKph } from '../units.js';
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
 
 const LEGAL_STALL_SURFACES = new Set(['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box']);
 
@@ -48,7 +49,7 @@ function retireStalledCar(sim, car) {
   if (car.finished || car.destroyed || car.outOfRace) return;
   car.outOfRace = true;
   markCarDnf(sim, car, { reason: 'stalled-off-track' });
-  freezeRetiredCar(car);
+  freezeRetiredCar(car, { physicsMode: sim.physicsMode });
   sim.events.unshift({
     type: 'car-dnf',
     at: sim.time,
@@ -58,27 +59,17 @@ function retireStalledCar(sim, car) {
   });
 }
 
-export function freezeRetiredCar(car) {
-  car.speed = 0;
-  car.velocityX = 0;
-  car.velocityY = 0;
-  car.throttle = 0;
-  car.brake = 1;
-  car.appliedControls = { steering: 0, throttle: 0, brake: 1 };
-  car.manualControls = null;
+export function freezeRetiredCar(car, { physicsMode = 'simulator' } = {}) {
+  freezeVehicleMotion(car, {
+    clearManualControls: true,
+    physicsMode,
+    stabilityState: 'destroyed',
+  });
   car.canAttack = false;
   car.drsActive = false;
   car.drsEligible = false;
   car.drsZoneId = null;
   car.drsZoneEnabled = false;
-  car.steeringAngle = 0;
-  car.yawRate = 0;
-  car.longitudinalAcceleration = 0;
-  car.lateralAcceleration = 0;
-  car.longitudinalG = 0;
-  car.lateralG = 0;
-  car.tractionLimited = false;
-  car.stabilityState = 'destroyed';
 }
 
 function resetStallTimer(car) {

package/src/simulation/raceSimulation.js

@@ -152,6 +152,7 @@ export class F1RaceSimulation {
       cars: this.cars,
       computeLap: (raceDistance) => this.computeLap(raceDistance),
       nearestDistanceOnRoute,
+      physicsMode: this.physicsMode,
       progressDelta,
       raceControl: this.raceControl,
       releaseRaceStart: () => this.releaseRaceStart(),

package/src/simulation/rules/rulesReview.js

@@ -11,6 +11,9 @@ function forwardVector(car) {
 }
 
 function velocityVector(car) {
+  if (Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)) {
+    return { x: car.velocityX, y: car.velocityY };
+  }
   const forward = forwardVector(car);
   return { x: forward.x * car.speed, y: forward.y * car.speed };
 }

package/src/simulation/snapshots/raceSnapshots.js

@@ -47,6 +47,7 @@ export function createVehicleSnapshotDependencies(sim) {
     simSpeedToKph,
     simUnitsToMeters,
     VEHICLE_LIMITS,
+    physicsMode: sim.physicsMode,
   };
 }
 

package/src/simulation/track/trackQueryGrid.js

@@ -0,0 +1,94 @@
+import { clamp } from '../simMath.js';
+import { ensureQueryScratch, ensureScratchArray, nextScratchEpoch } from './trackQueryScratch.js';
+
+export function createSpatialGrid(bounds, cellSize) {
+  const columns = Math.max(1, Math.ceil((bounds.maxX - bounds.minX) / cellSize));
+  const rows = Math.max(1, Math.ceil((bounds.maxY - bounds.minY) / cellSize));
+  return {
+    bounds,
+    cellSize,
+    columns,
+    rows,
+    cells: new Array(columns * rows),
+  };
+}
+
+export function insertIdIntoGridBounds(grid, id, bounds) {
+  const minCell = gridCellForPoint(grid, { x: bounds.minX, y: bounds.minY }, true);
+  const maxCell = gridCellForPoint(grid, { x: bounds.maxX, y: bounds.maxY }, true);
+  for (let row = minCell.row; row <= maxCell.row; row += 1) {
+    for (let column = minCell.column; column <= maxCell.column; column += 1) {
+      const cellIndex = row * grid.columns + column;
+      const cell = grid.cells[cellIndex];
+      if (cell) cell.push(id);
+      else grid.cells[cellIndex] = [id];
+    }
+  }
+}
+
+export function candidateIdsFromGrid(index, grid, position, neighborLimit) {
+  const center = gridCellForPoint(grid, position, false);
+  if (!center) return [];
+  const scratch = ensureQueryScratch(index);
+  const maxId = Math.max(index.centerline.segmentCount, index.pit?.roadSegments?.length ?? 0, index.pit?.boxCandidates?.length ?? 0);
+  const idMarks = ensureScratchArray(scratch, 'candidateMarks', maxId);
+  const ids = [];
+  for (let radius = 0; radius <= neighborLimit; radius += 1) {
+    const candidateEpoch = nextScratchEpoch(scratch, 'candidateEpoch', idMarks);
+    ids.length = 0;
+    for (let row = center.row - radius; row <= center.row + radius; row += 1) {
+      for (let column = center.column - radius; column <= center.column + radius; column += 1) {
+        if (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows) continue;
+        const cell = grid.cells[row * grid.columns + column];
+        if (!cell) continue;
+        for (const id of cell) {
+          if (idMarks[id] === candidateEpoch) continue;
+          idMarks[id] = candidateEpoch;
+          ids.push(id);
+        }
+      }
+    }
+    if (ids.length) return ids.slice();
+  }
+  return [];
+}
+
+export function candidateIdsFromGridBounds(index, grid, bounds) {
+  if (
+    bounds.maxX < grid.bounds.minX ||
+    bounds.minX > grid.bounds.maxX ||
+    bounds.maxY < grid.bounds.minY ||
+    bounds.minY > grid.bounds.maxY
+  ) return [];
+  const minPoint = { x: bounds.minX, y: bounds.minY };
+  const maxPoint = { x: bounds.maxX, y: bounds.maxY };
+  const minCell = gridCellForPoint(grid, minPoint, true);
+  const maxCell = gridCellForPoint(grid, maxPoint, true);
+  const scratch = ensureQueryScratch(index);
+  const maxId = Math.max(index.centerline.segmentCount, index.pit?.roadSegments?.length ?? 0, index.pit?.boxCandidates?.length ?? 0);
+  const idMarks = ensureScratchArray(scratch, 'candidateMarks', maxId);
+  const candidateEpoch = nextScratchEpoch(scratch, 'candidateEpoch', idMarks);
+  const ids = [];
+  for (let row = minCell.row; row <= maxCell.row; row += 1) {
+    for (let column = minCell.column; column <= maxCell.column; column += 1) {
+      const cell = grid.cells[row * grid.columns + column];
+      if (!cell) continue;
+      for (const id of cell) {
+        if (idMarks[id] === candidateEpoch) continue;
+        idMarks[id] = candidateEpoch;
+        ids.push(id);
+      }
+    }
+  }
+  return ids;
+}
+
+export function gridCellForPoint(grid, point, clampToGrid) {
+  const column = Math.floor((point.x - grid.bounds.minX) / grid.cellSize);
+  const row = Math.floor((point.y - grid.bounds.minY) / grid.cellSize);
+  if (!clampToGrid && (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows)) return null;
+  return {
+    column: clampToGrid ? clamp(column, 0, grid.columns - 1) : column,
+    row: clampToGrid ? clamp(row, 0, grid.rows - 1) : row,
+  };
+}