@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/simulation/race/raceProgress.js

@@ -0,0 +1,129 @@
+import { pointAt } from '../track/trackModel.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import {
+  affectsRaceOrder,
+} from '../participants/participantInteractions.js';
+import {
+  estimateGapAheadSeconds,
+  recordTimingLineCrossings,
+  recordTimingSample,
+  resetLapTelemetry,
+  updateLapTelemetry,
+  updateSectorPerformance,
+  wholeLapGap,
+} 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);
+      freezeVehicleMotion(car, {
+        clearManualControls: true,
+        physicsMode: sim.physicsMode,
+        stabilityState: car.destroyed ? 'destroyed' : car.stabilityState,
+      });
+      car.canAttack = false;
+      car.drsEligible = false;
+      car.drsActive = false;
+      car.drsZoneId = null;
+      car.drsZoneEnabled = false;
+      return;
+    }
+    if (car.gridLocked) {
+      const gridPoint = pointAt(sim.track, car.gridDistance);
+      applyWheelSurfaceState(car, sim.track);
+      car.progress = gridPoint.distance;
+      car.raceDistance = car.gridDistance;
+      car.lap = 1;
+      resetLapTelemetry(car, sim.time, sim.track, sim.totalLaps);
+      return;
+    }
+
+    applyWheelSurfaceState(car, sim.track);
+    const previousProgress = car.progress ?? car.trackState.distance;
+    const delta = progressDelta(car.trackState.distance, previousProgress, sim.track.length);
+    car.raceDistance = (car.raceDistance ?? previousProgress) + delta;
+    car.progress = car.trackState.distance;
+    car.lap = sim.computeLap(car.raceDistance);
+    updateLapTelemetry(car, previousRaceDistance, sim.time, sim.track, sim.totalLaps);
+  });
+
+  updateSectorPerformance(sim.cars);
+  sim.cars.forEach((car) => {
+    recordTimingSample(car, sim.time);
+    recordTimingLineCrossings(car, car.previousRaceDistanceForTiming, sim.time, sim.track);
+    car.previousRaceDistanceForTiming = car.raceDistance;
+  });
+
+  const ordered = sim.orderedCars();
+  const orderedIds = new Set(ordered.map((car) => car.id));
+  sim.cars.forEach((car) => {
+    if (orderedIds.has(car.id) || affectsRaceOrder(car)) return;
+    car.rank = null;
+    car.classifiedRank = null;
+    car.gapAhead = Infinity;
+    car.gapAheadLaps = 0;
+    car.intervalAheadLaps = 0;
+    car.leaderGapLaps = 0;
+    car.gapAheadSeconds = Infinity;
+    car.intervalAheadSeconds = Infinity;
+    car.leaderGapSeconds = Infinity;
+    car.drsEligible = false;
+    car.drsActive = false;
+    car.drsZoneId = null;
+    car.drsZoneEnabled = false;
+    car.canAttack = false;
+  });
+  const leader = ordered[0];
+  ordered.forEach((car, index) => {
+    if (isRaceDnf(car)) {
+      car.rank = index + 1;
+      car.classifiedRank = null;
+      car.gapAhead = Infinity;
+      car.gapAheadLaps = 0;
+      car.intervalAheadLaps = 0;
+      car.leaderGapLaps = 0;
+      car.gapAheadSeconds = Infinity;
+      car.intervalAheadSeconds = Infinity;
+      car.leaderGapSeconds = Infinity;
+      car.drsEligible = false;
+      car.drsActive = false;
+      car.drsZoneId = null;
+      car.drsZoneEnabled = false;
+      car.canAttack = false;
+      return;
+    }
+    const ahead = ordered[index - 1];
+    const drsReference = sim.getDrsReferenceCar(car);
+    const gap = ahead ? ahead.raceDistance - car.raceDistance : Infinity;
+    const intervalAheadLaps = ahead ? wholeLapGap(ahead.raceDistance, car.raceDistance, sim.track.length) : 0;
+    const leaderGapLaps = leader ? wholeLapGap(leader.raceDistance, car.raceDistance, sim.track.length) : 0;
+    const activePitStop = sim.isCarInActivePitStop(car);
+    car.rank = index + 1;
+    car.gapAhead = gap;
+    car.gapAheadLaps = intervalAheadLaps;
+    car.intervalAheadLaps = intervalAheadLaps;
+    car.leaderGapLaps = leaderGapLaps;
+    car.gapAheadSeconds = Number.isFinite(gap) && intervalAheadLaps === 0
+      ? estimateGapAheadSeconds(ahead, car, sim.time, sim.track)
+      : Infinity;
+    car.intervalAheadSeconds = car.gapAheadSeconds;
+    car.leaderGapSeconds = leaderGapLaps > 0
+      ? Infinity
+      : (leader && leader !== car ? estimateGapAheadSeconds(leader, car, sim.time, sim.track) : 0);
+    car.canAttack = !sim.safetyCar.deployed && !car.finished && !activePitStop;
+    car.aggression = sim.computeAggression(car, index);
+    if (activePitStop) {
+      car.drsEligible = false;
+      car.drsActive = false;
+      car.drsZoneId = null;
+      car.drsZoneEnabled = false;
+    } else if (updateDrs) sim.updateDrsLatch(car, drsReference, Boolean(drsReference));
+  });
+  sim.evaluateRaceFinish();
+  return ordered;
+}

package/src/simulation/race/raceSetup.js

@@ -0,0 +1,93 @@
+import { buildTrackModel, createProceduralTrack, TRACK } from '../track/trackModel.js';
+import { attachTrackQueryIndex, createTrackQueryIndex, forkTrackQueryIndex } from '../track/trackQueryIndex.js';
+import { createMulberry32 } from '../simMath.js';
+import { createCar } from '../vehicle/vehicleState.js';
+import { normalizePhysicsMode } from '../vehicle/vehiclePhysics.js';
+import {
+  createLapTelemetry,
+  createTimingLines,
+  resetLapTelemetry,
+  resetTimingHistory,
+  resetTimingLineCrossings,
+} from '../timing/raceTiming.js';
+import { normalizePitIntent, PIT_INTENT_NONE } from '../pit/pitIntent.js';
+import { assignPitLaneTeams, initializePitStops } from '../pit/pitState.js';
+import { clonePitLaneModel } from '../pit/pitRouting.js';
+import { createRaceControlState, createSafetyCarState } from './raceControlState.js';
+import { normalizeTotalLaps } from './raceDistance.js';
+import { normalizeRaceRules } from '../rulesConfig.js';
+import { attachParticipantInteractions } from '../participants/participantInteractions.js';
+import { normalizeReplayGhosts, updateReplayGhosts } from '../replay/replayGhosts.js';
+
+export const DEFAULT_TOTAL_LAPS = 10;
+
+export function initializeRaceSimulation(simulation, {
+  seed = 1,
+  drivers = [],
+  totalLaps = DEFAULT_TOTAL_LAPS,
+  rules = {},
+  track = null,
+  trackSeed = null,
+  trackGeneration = {},
+  trackQueryIndex = true,
+  physicsMode = 'arcade',
+  participantInteractions = {},
+  replayGhosts = [],
+} = {}) {
+  simulation.seed = seed;
+  simulation.random = createMulberry32(seed);
+  simulation.physicsMode = normalizePhysicsMode(physicsMode);
+  const trackDefinition = track ?? (trackSeed == null ? TRACK : createProceduralTrack(trackSeed, trackGeneration));
+  const builtTrack = buildTrackModel(trackDefinition);
+  simulation.track = {
+    ...builtTrack,
+    pitLane: clonePitLaneModel(builtTrack.pitLane),
+  };
+  const useTrackQueryIndex = trackQueryIndex !== false;
+  if (useTrackQueryIndex) {
+    const forkedCachedIndex = forkTrackQueryIndex(builtTrack.queryIndex);
+    attachTrackQueryIndex(simulation.track, forkedCachedIndex ?? createTrackQueryIndex(simulation.track));
+  }
+  simulation.track.timingLines = createTimingLines(simulation.track);
+  simulation.trackSeed = simulation.track.seed ?? trackSeed;
+  simulation.rules = normalizeRaceRules(rules);
+  simulation.startLightsOutAt = simulation.rules.startLightCount * simulation.rules.startLightInterval +
+    simulation.rules.startLightsOutHold;
+  simulation.totalLaps = normalizeTotalLaps(totalLaps);
+  simulation.time = 0;
+  simulation.events = [];
+  simulation.penalties = [];
+  simulation.nextPenaltyId = 1;
+  simulation.stewardState = {
+    trackLimits: Object.create(null),
+    pitLaneSpeeding: Object.create(null),
+    tireRequirement: Object.create(null),
+  };
+  simulation.raceControl = createRaceControlState(simulation.rules, simulation.startLightsOutAt);
+  simulation.safetyCar = createSafetyCarState(simulation.track, simulation.rules);
+  simulation.cars = drivers.map((driver, index) => createCar(driver, index, simulation.random, simulation.track, {
+    standingStart: simulation.raceControl.mode === 'pre-start',
+    createLapTelemetry,
+  }));
+  simulation.participantInteractions = attachParticipantInteractions(simulation.cars, participantInteractions);
+  simulation.replayGhosts = normalizeReplayGhosts(replayGhosts);
+  updateReplayGhosts(simulation.replayGhosts, simulation.time);
+  assignPitLaneTeams({ cars: simulation.cars, pitLane: simulation.track.pitLane });
+  initializePitStops({
+    cars: simulation.cars,
+    pitLane: simulation.track.pitLane,
+    pitStops: simulation.rules.modules?.pitStops,
+    totalLaps: simulation.totalLaps,
+    trackLength: simulation.track.length,
+    tireCompounds: simulation.rules.modules?.tireStrategy?.compounds,
+    PIT_INTENT_NONE,
+  });
+  simulation.recalculateRaceState({ updateDrs: false });
+  simulation.cars.forEach((car) => resetTimingHistory(car, simulation.time));
+  simulation.cars.forEach((car) => resetTimingLineCrossings(car, simulation.time));
+  simulation.cars.forEach((car) => resetLapTelemetry(car, simulation.time, simulation.track, simulation.totalLaps));
+}
+
+export function normalizePitIntentForRace(car) {
+  return normalizePitIntent(car?.pitStop?.intent) ?? PIT_INTENT_NONE;
+}

package/src/simulation/race/raceStep.js

@@ -0,0 +1,80 @@
+import { decideDriverControls } from '../driverController.js';
+import { clamp } from '../simMath.js';
+import { updateReplayGhosts } from '../replay/replayGhosts.js';
+import { integrateVehiclePhysics } from '../vehicle/vehiclePhysics.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import { applyRedFlagHoldForSimulation } from './redFlag.js';
+import { freezeRetiredCar, updateStalledDnfForSimulation } from './stalledDnf.js';
+
+export function runRaceStep(simulation, dt) {
+  const delta = clamp(dt, 0, 1 / 20);
+  if (!Number.isFinite(delta) || delta <= 0) return;
+
+  simulation.time += delta;
+  simulation.events = [];
+  updateReplayGhosts(simulation.replayGhosts, simulation.time);
+  simulation.updateStartSequence();
+  const orderedCars = simulation.recalculateRaceState({ updateDrs: false }) ?? simulation.orderedCars();
+
+  if (simulation.raceControl.mode === 'pre-start' && simulation.cars.every((car) => car.gridLocked)) {
+    simulation.holdGridCars();
+    simulation.recalculateRaceState({ updateDrs: false });
+    return;
+  }
+
+  if (simulation.raceControl.redFlag) {
+    applyRedFlagHoldForSimulation(simulation);
+    simulation.recalculateRaceState({ updateDrs: false });
+    return;
+  }
+
+  simulation.updateSafetyCar(delta);
+
+  const raceContext = simulation.driverRaceContext(orderedCars);
+  const orderedIndexById = new Map(orderedCars.map((car, index) => [car.id, index]));
+  const driveCars = orderedCars.length === simulation.cars.length
+    ? orderedCars
+    : [
+      ...orderedCars,
+      ...simulation.cars.filter((car) => !orderedIndexById.has(car.id)),
+    ];
+  driveCars.forEach((car) => {
+    if (car.destroyed || car.outOfRace) {
+      freezeRetiredCar(car, { physicsMode: simulation.physicsMode });
+      return;
+    }
+    const orderIndex = orderedIndexById.get(car.id);
+    car.previousX = car.x;
+    car.previousY = car.y;
+    car.previousHeading = car.heading;
+    car.previousProgress = car.progress;
+    if (simulation.advancePitStopCar(car, delta)) return;
+    const controls = decideDriverControls({
+      car,
+      orderIndex: orderIndex ?? Math.max(0, car.index ?? 0),
+      race: raceContext,
+    });
+    car.appliedControls = {
+      steering: controls.steering ?? 0,
+      throttle: controls.throttle ?? 0,
+      brake: controls.brake ?? 0,
+    };
+    if (simulation.physicsMode === 'simulator') {
+      applyWheelSurfaceState(car, simulation.track);
+    }
+    integrateVehiclePhysics(car, controls, delta, {
+      physicsMode: simulation.physicsMode,
+      tireDegradationEnabled: simulation.rules.modules?.tireDegradation?.enabled !== false,
+    });
+    simulation.applyRunoffResponse(car);
+    car.contactCooldown = Math.max(0, car.contactCooldown - delta);
+  });
+
+  simulation.resolveCollisions();
+  simulation.recalculateRaceState();
+  if (updateStalledDnfForSimulation(simulation, delta)) {
+    simulation.recalculateRaceState();
+  }
+  simulation.reviewTrackLimits();
+  simulation.reviewPitLaneSpeeding();
+}

package/src/simulation/race/redFlag.js

@@ -0,0 +1,15 @@
+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;
+    freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
+    car.drsActive = false;
+    car.drsEligible = false;
+    car.drsZoneId = null;
+    car.drsZoneEnabled = false;
+    car.canAttack = false;
+  });
+}

package/src/simulation/race/retirements.js

@@ -0,0 +1,44 @@
+export function isRaceDnf(car) {
+  return Boolean(car?.destroyed || car?.outOfRace);
+}
+
+export function getDnfOrder(car) {
+  const order = Number(car?.dnfOrder);
+  if (Number.isFinite(order)) return order;
+  const retiredAt = Number(car?.dnfAt ?? car?.destroyedAt);
+  if (Number.isFinite(retiredAt)) return retiredAt;
+  return Infinity;
+}
+
+export function compareDnfOrder(left, right) {
+  const orderDelta = getDnfOrder(left) - getDnfOrder(right);
+  if (orderDelta !== 0) return orderDelta;
+  const timeDelta = (left.dnfAt ?? left.destroyedAt ?? Infinity) - (right.dnfAt ?? right.destroyedAt ?? Infinity);
+  if (timeDelta !== 0) return timeDelta;
+  return (left.index ?? 0) - (right.index ?? 0);
+}
+
+export function nextDnfOrder(sim) {
+  const current = Number(sim.raceControl?.nextDnfOrder);
+  const next = Number.isFinite(current) ? current : 1;
+  sim.raceControl.nextDnfOrder = next + 1;
+  return next;
+}
+
+export function markCarDnf(sim, car, { reason = null } = {}) {
+  if (!car || car.dnfOrder != null) return;
+  car.dnfOrder = nextDnfOrder(sim);
+  car.dnfAt = sim.time;
+  car.dnfReason = reason ?? car.destroyReason ?? null;
+}
+
+export function clearCarDnf(car) {
+  delete car.dnfOrder;
+  delete car.dnfAt;
+  delete car.dnfReason;
+  delete car.stalledOffTrackSeconds;
+}
+
+export function raceDnfCars(cars = []) {
+  return cars.filter(isRaceDnf).sort(compareDnfOrder);
+}

package/src/simulation/race/safetyCar.js

@@ -0,0 +1,92 @@
+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);
+  if (sim.raceControl.finished) return;
+  if (next && sim.raceControl.mode === 'pre-start') return;
+  if (sim.raceControl.redFlag) return;
+  if (next === sim.safetyCar.deployed) return;
+  const ordered = sim.orderedCars();
+  sim.safetyCar.deployed = next;
+  sim.raceControl.mode = next ? 'safety-car' : 'green';
+  sim.raceControl.frozenOrder = next ? ordered.map((car) => car.id) : null;
+  if (next) {
+    const leader = ordered[0];
+    const safetyCarProgress = (leader?.raceDistance ?? 0) + sim.rules.safetyCarLeadDistance;
+    if (sim.safetyCar.progress < safetyCarProgress) {
+      moveSafetyCarTo(sim, safetyCarProgress);
+    }
+    sim.cars.forEach((car) => {
+      car.desiredOffset = 0;
+      car.drsActive = false;
+      car.drsEligible = false;
+      car.drsZoneId = null;
+      car.drsZoneEnabled = false;
+    });
+  }
+  sim.events.unshift({ type: next ? 'safety-car' : 'green-flag', at: sim.time });
+}
+
+export function updateSafetyCarState(sim, dt) {
+  if (!sim.safetyCar.deployed) return;
+  const leader = sim.orderedCars()[0];
+  const targetProgress = (leader?.raceDistance ?? 0) + sim.rules.safetyCarLeadDistance;
+  const progress = sim.safetyCar.progress < targetProgress
+    ? Math.min(sim.safetyCar.progress + sim.safetyCar.speed * dt, targetProgress)
+    : targetProgress;
+  moveSafetyCarTo(sim, progress);
+}
+
+export function moveSafetyCarTo(sim, progress) {
+  const point = pointAt(sim.track, progress);
+  sim.safetyCar.previousX = sim.safetyCar.x;
+  sim.safetyCar.previousY = sim.safetyCar.y;
+  sim.safetyCar.previousHeading = sim.safetyCar.heading;
+  sim.safetyCar.progress = progress;
+  sim.safetyCar.x = point.x;
+  sim.safetyCar.y = point.y;
+  sim.safetyCar.heading = point.heading;
+}
+
+export function setRedFlagState(sim, deployed) {
+  const next = Boolean(deployed);
+  if (sim.raceControl.finished) return;
+  if (next && sim.raceControl.mode === 'pre-start') return;
+  if (next === Boolean(sim.raceControl.redFlag)) return;
+  sim.raceControl.redFlag = next;
+  if (next) {
+    sim.safetyCar.deployed = false;
+    sim.raceControl.mode = 'red-flag';
+    sim.raceControl.frozenOrder = sim.orderedCars().map((car) => car.id);
+    sim.cars.forEach((car) => {
+      freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
+      car.drsActive = false;
+      car.drsEligible = false;
+      car.drsZoneId = null;
+      car.drsZoneEnabled = false;
+      car.canAttack = false;
+    });
+  } else {
+    sim.raceControl.mode = sim.safetyCar.deployed ? 'safety-car' : 'green';
+    sim.raceControl.frozenOrder = sim.safetyCar.deployed
+      ? sim.orderedCars().map((car) => car.id)
+      : null;
+    sim.cars.forEach((car) => {
+      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);
+      }
+    });
+  }
+  sim.events.unshift({ type: next ? 'red-flag' : 'green-flag', at: sim.time });
+}

package/src/simulation/race/stalledDnf.js

@@ -0,0 +1,77 @@
+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']);
+
+export function updateStalledDnfForSimulation(sim, dt) {
+  const config = sim.rules.modules?.stalledDnf;
+  if (!config?.enabled) {
+    sim.cars.forEach(resetStallTimer);
+    return false;
+  }
+  if (sim.raceControl.mode === 'pre-start' || sim.raceControl.redFlag || sim.raceControl.finished) {
+    sim.cars.forEach(resetStallTimer);
+    return false;
+  }
+
+  let retired = false;
+  sim.cars.forEach((car) => {
+    if (!isEligibleForStalledDnf(sim, car, config)) {
+      resetStallTimer(car);
+      return;
+    }
+    car.stalledOffTrackSeconds = (car.stalledOffTrackSeconds ?? 0) + dt;
+    if (car.stalledOffTrackSeconds + Number.EPSILON < config.maxStoppedSeconds) return;
+    retireStalledCar(sim, car);
+    retired = true;
+  });
+  return retired;
+}
+
+function isEligibleForStalledDnf(sim, car, config) {
+  if (!car || car.finished || car.destroyed || car.outOfRace) return false;
+  if (sim.isCarInActivePitStop(car)) return false;
+  if (car.trackState?.inPitLane) return false;
+  if (simSpeedToKph(car.speed ?? 0) > config.speedThresholdKph) return false;
+  return isOffTrackForStalledDnf(car);
+}
+
+function isOffTrackForStalledDnf(car) {
+  const wheels = Array.isArray(car.wheelStates) ? car.wheelStates : [];
+  if (wheels.length) {
+    return wheels.some((wheel) => !wheel.onTrack && !LEGAL_STALL_SURFACES.has(wheel.surface));
+  }
+  return !LEGAL_STALL_SURFACES.has(car.trackState?.surface ?? 'track');
+}
+
+function retireStalledCar(sim, car) {
+  if (car.finished || car.destroyed || car.outOfRace) return;
+  car.outOfRace = true;
+  markCarDnf(sim, car, { reason: 'stalled-off-track' });
+  freezeRetiredCar(car, { physicsMode: sim.physicsMode });
+  sim.events.unshift({
+    type: 'car-dnf',
+    at: sim.time,
+    carId: car.id,
+    driverId: car.id,
+    reason: 'stalled-off-track',
+  });
+}
+
+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;
+}
+
+function resetStallTimer(car) {
+  if (car) car.stalledOffTrackSeconds = 0;
+}