@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/simulation/pit/pitState.js

@@ -0,0 +1,113 @@
+import { metersToSimUnits } from '../units.js';
+import { firstDifferentCompound } from './pitIntent.js';
+
+const PIT_ENTRY_APPROACH_DISTANCE = metersToSimUnits(250);
+
+export function normalizePitCrewStats(value) {
+  const source = value && typeof value === 'object' ? value : {};
+  const rating = (entry) => {
+    const numeric = Number(entry);
+    return Number.isFinite(numeric) ? Math.max(0, Math.min(1, numeric)) : 0.5;
+  };
+  return {
+    speed: rating(source.speed ?? source.pace),
+    consistency: rating(source.consistency),
+    reliability: rating(source.reliability),
+  };
+}
+
+export function assignPitLaneTeams({ cars, pitLane }) {
+  if (!pitLane?.enabled || !Array.isArray(pitLane.boxes)) return;
+  const boxesPerTeam = pitLane.boxesPerTeam ?? 2;
+  const teamCount = pitLane.teamCount ?? Math.ceil(pitLane.boxes.length / boxesPerTeam);
+
+  pitLane.teams = Array.from({ length: teamCount }, (_, teamIndex) => {
+    const primary = cars[teamIndex * boxesPerTeam] ?? cars[teamIndex] ?? null;
+    const secondary = cars[teamIndex * boxesPerTeam + 1] ?? null;
+    const team = primary?.team ?? secondary?.team ?? null;
+    const id = team?.id ?? `team-${teamIndex + 1}`;
+    const name = team?.name ?? (primary ? `${primary.name} Team` : `Team ${teamIndex + 1}`);
+    const color = team?.color ?? primary?.color ?? secondary?.color ?? '#f8fafc';
+    const pitCrew = normalizePitCrewStats(
+      team?.pitCrew ?? team?.pitCrewStats ?? primary?.team?.pitCrew ?? secondary?.team?.pitCrew,
+    );
+    const boxIds = pitLane.boxes
+      .filter((box) => box.teamIndex === teamIndex)
+      .map((box) => box.id);
+
+    pitLane.boxes
+      .filter((box) => box.teamIndex === teamIndex)
+      .forEach((box) => {
+        box.teamId = id;
+        box.teamName = name;
+        box.teamColor = color;
+      });
+    const serviceArea = pitLane.serviceAreas?.[teamIndex] ?? null;
+    if (serviceArea) {
+      serviceArea.teamId = id;
+      serviceArea.teamName = name;
+      serviceArea.teamColor = color;
+      serviceArea.pitCrew = pitCrew;
+    }
+
+    return {
+      id,
+      name,
+      color,
+      index: teamIndex,
+      boxIds,
+      serviceAreaId: serviceArea?.id ?? null,
+      pitCrew,
+    };
+  });
+}
+
+export function initializePitStops({ cars, pitLane, pitStops, totalLaps, trackLength, tireCompounds, PIT_INTENT_NONE }) {
+  if (!pitStops?.enabled || !pitLane?.enabled || !Array.isArray(pitLane.boxes) || totalLaps < 2) return;
+  const boxesPerTeam = pitLane.boxesPerTeam ?? 2;
+  const maxConcurrentPitLaneCars = Math.max(1, Math.floor(pitStops.maxConcurrentPitLaneCars ?? 3));
+  const pitWindowLapCount = Math.max(1, Math.min(
+    totalLaps - 1,
+    Math.ceil(cars.length / maxConcurrentPitLaneCars),
+  ));
+
+  cars.forEach((car, index) => {
+    const stopLapBase = trackLength * (1 + (index % pitWindowLapCount));
+    const trainPosition = Math.floor(index / pitWindowLapCount);
+    const teamIndex = Math.floor(index / boxesPerTeam);
+    const teamBoxIndex = index % boxesPerTeam;
+    const garageBoxIndex = Math.min(pitLane.boxes.length - 1, teamIndex * boxesPerTeam + teamBoxIndex);
+    const garageBox = pitLane.boxes[garageBoxIndex] ?? pitLane.boxes[index % pitLane.boxes.length];
+    const serviceArea = pitLane.serviceAreas?.[teamIndex] ??
+      pitLane.serviceAreas?.[index % pitLane.serviceAreas.length] ??
+      garageBox;
+    car.pitStop = {
+      status: 'pending',
+      phase: null,
+      boxIndex: serviceArea.index,
+      boxId: serviceArea.id,
+      garageBoxIndex,
+      garageBoxId: garageBox.id,
+      teamId: serviceArea.teamId ?? garageBox.teamId ?? null,
+      teamColor: serviceArea.teamColor ?? garageBox.teamColor ?? null,
+      stopsCompleted: 0,
+      entryRaceDistance: stopLapBase + pitLane.entry.distanceFromStart,
+      plannedRaceDistance: stopLapBase + pitLane.entry.distanceFromStart -
+        PIT_ENTRY_APPROACH_DISTANCE,
+      trainPosition,
+      lapBase: stopLapBase,
+      serviceRemaining: 0,
+      penaltyServiceRemaining: 0,
+      penaltyServiceTotal: 0,
+      servingPenaltyIds: [],
+      serviceProfile: null,
+      queueingForService: false,
+      route: null,
+      routeProgress: 0,
+      routeStartRaceDistance: null,
+      routeEndRaceDistance: null,
+      targetTire: firstDifferentCompound(car.tire, tireCompounds),
+      intent: PIT_INTENT_NONE,
+    };
+  });
+}

package/src/simulation/pit/pitTireService.js

@@ -0,0 +1,94 @@
+import { kphToSimSpeed } from '../units.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import {
+  createRoute,
+  pitDriveLaneOffset,
+  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';
+
+export function beginTireService(sim, car) {
+  const stop = car.pitStop;
+  if (!stop) return;
+  const serviceProfile = calculatePitServiceProfile(sim, car);
+  stop.phase = 'service';
+  stop.penaltyServiceRemaining = 0;
+  stop.serviceProfile = serviceProfile;
+  stop.serviceRemaining = serviceProfile.seconds;
+  sim.events.unshift({
+    type: 'pit-stop-start',
+    at: sim.time,
+    carId: car.id,
+    boxId: stop.boxId,
+    teamId: stop.teamId ?? null,
+    targetTire: stop.targetTire,
+    serviceSeconds: serviceProfile.seconds,
+    serviceIssue: serviceProfile.issue,
+  });
+}
+
+export function completePitService(sim, car) {
+  const stop = car.pitStop;
+  const box = getPitStopBox(sim, stop);
+  const pitLane = sim.track.pitLane;
+  if (!stop || !box || !pitLane?.enabled) return;
+
+  car.tire = stop.targetTire ?? car.tire;
+  car.tireEnergy = 100;
+  if (car.tire && !car.usedTireCompounds.includes(car.tire)) car.usedTireCompounds.push(car.tire);
+  sim.events.unshift({
+    type: 'pit-stop-complete',
+    at: sim.time,
+    carId: car.id,
+    boxId: box.id,
+    teamId: box.teamId ?? null,
+    tire: car.tire,
+  });
+
+  const driveLaneOffset = pitDriveLaneOffset(pitLane);
+  const boxReleaseDistance = Math.min(pitLane.mainLane.length, box.distanceAlongLane + PIT_BOX_APPROACH_DISTANCE);
+  const route = createRoute([
+    routePoint(box.center, pitLane.mainLane.heading, { limiterActive: true }),
+    routePoint(box.laneTarget, pitLane.mainLane.heading, { limiterActive: true }),
+    routePoint(pitMainLanePointAt(pitLane, boxReleaseDistance, driveLaneOffset), pitLane.mainLane.heading, { limiterActive: true }),
+    routePoint(pitMainLanePointAt(pitLane, pitLane.mainLane.length, driveLaneOffset), pitLane.mainLane.heading, { limiterActive: true }),
+    ...(pitLane.exit.roadCenterline ?? []).map((point) => routePoint(point)),
+  ]);
+  stop.status = 'exiting';
+  stop.phase = 'exit';
+  stop.route = route;
+  stop.routeProgress = 0;
+  stop.routeStartRaceDistance = getPitBoxRaceDistance(sim, stop, box);
+  stop.routeEndRaceDistance = stop.lapBase + pitLane.exit.distanceFromStart;
+}
+
+export function finishPitExit(sim, car) {
+  const stop = car.pitStop;
+  if (!stop) return;
+  stop.status = 'completed';
+  stop.phase = null;
+  stop.route = null;
+  stop.routeProgress = 0;
+  stop.serviceRemaining = 0;
+  stop.queueingForService = false;
+  stop.stopsCompleted = (stop.stopsCompleted ?? 0) + 1;
+  stop.intent = 0;
+  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);
+  sim.events.unshift({
+    type: 'pit-exit',
+    at: sim.time,
+    carId: car.id,
+    boxId: stop.boxId,
+    teamId: stop.teamId ?? null,
+  });
+}

package/src/simulation/race/classification.js

@@ -0,0 +1,104 @@
+import { clamp } from '../simMath.js';
+import { simUnitsToMeters } from '../units.js';
+import { isRaceDnf, raceDnfCars } from './retirements.js';
+
+function getPenaltyStats(statsByDriver, driverId) {
+  return statsByDriver.get(driverId) ?? {
+    seconds: 0,
+    positionDrop: 0,
+    disqualified: false,
+  };
+}
+
+export function applyOutstandingServicePenalties(sim, applyUnservedServicePenalty) {
+  sim.penalties.forEach((penalty) => {
+    const beforeStatus = penalty.status;
+    applyUnservedServicePenalty(penalty, sim.time);
+    if (beforeStatus !== penalty.status && penalty.unserved) {
+      sim.events.unshift({
+        type: 'penalty-applied',
+        at: sim.time,
+        penaltyId: penalty.id,
+        driverId: penalty.driverId,
+        serviceType: penalty.serviceType,
+        penaltySeconds: penalty.penaltySeconds,
+      });
+    }
+  });
+}
+
+export function buildClassificationFromFinishOrder(sim) {
+  const byId = new Map(sim.cars.map((car) => [car.id, car]));
+  const penaltyStats = sim.getPenaltyStatsByDriver();
+  const finishOrderIds = new Set(sim.raceControl.finishOrder);
+  const orderedByAdjustedTime = sim.raceControl.finishOrder
+    .map((id, finishOrderIndex) => ({ car: byId.get(id), finishOrderIndex }))
+    .filter((entry) => Boolean(entry.car))
+    .sort((left, right) => {
+      const leftTime = (left.car.finishTime ?? Infinity) + getPenaltyStats(penaltyStats, left.car.id).seconds;
+      const rightTime = (right.car.finishTime ?? Infinity) + getPenaltyStats(penaltyStats, right.car.id).seconds;
+      return leftTime === rightTime ? left.finishOrderIndex - right.finishOrderIndex : leftTime - rightTime;
+    })
+    .map((entry) => entry.car);
+  const finishedOrder = applyClassificationConsequences(sim, orderedByAdjustedTime, penaltyStats);
+  const dnfOrder = raceDnfCars(sim.cars.filter((car) => (
+    !finishOrderIds.has(car.id) && car.interaction?.affectsRaceOrder !== false
+  )));
+  return buildClassification(sim, [...finishedOrder, ...dnfOrder], penaltyStats);
+}
+
+export function applyClassificationConsequences(sim, ordered, penaltyStats = sim.getPenaltyStatsByDriver()) {
+  const classified = ordered.filter((car) => !getPenaltyStats(penaltyStats, car.id).disqualified);
+  ordered.forEach((car) => {
+    const stats = getPenaltyStats(penaltyStats, car.id);
+    if (stats.disqualified) return;
+    const drop = stats.positionDrop;
+    if (drop <= 0) return;
+    const currentIndex = classified.findIndex((entry) => entry.id === car.id);
+    if (currentIndex < 0) return;
+    const [entry] = classified.splice(currentIndex, 1);
+    classified.splice(Math.min(classified.length, currentIndex + drop), 0, entry);
+  });
+  return [
+    ...classified,
+    ...ordered.filter((car) => getPenaltyStats(penaltyStats, car.id).disqualified),
+  ];
+}
+
+export function buildClassification(sim, ordered = sim.orderedCars(), penaltyStats = sim.getPenaltyStatsByDriver()) {
+  const leaderDistance = ordered[0]?.raceDistance ?? 0;
+  return ordered.map((car, index) => {
+    const dnf = isRaceDnf(car);
+    const finishTime = dnf ? null : (car.finishTime ?? (car.raceDistance >= sim.finishDistance ? sim.time : null));
+    const stats = getPenaltyStats(penaltyStats, car.id);
+    const penaltySeconds = stats.seconds;
+    const positionDrop = stats.positionDrop;
+    const disqualified = stats.disqualified;
+    return {
+      id: car.id,
+      code: car.code,
+      timingCode: car.timingCode,
+      name: car.name,
+      rank: index + 1,
+      raceDistance: car.raceDistance,
+      distanceMeters: simUnitsToMeters(car.raceDistance),
+      lap: sim.computeLap(car.raceDistance),
+      lapsCompleted: clamp(Math.floor(Math.max(0, car.raceDistance) / sim.track.length), 0, sim.totalLaps),
+      gapMeters: simUnitsToMeters(Math.max(0, leaderDistance - car.raceDistance)),
+      gapSeconds: index === 0 ? 0 : car.leaderGapSeconds,
+      intervalSeconds: index === 0 ? 0 : car.intervalAheadSeconds,
+      gapLaps: index === 0 ? 0 : car.leaderGapLaps,
+      intervalLaps: index === 0 ? 0 : car.intervalAheadLaps,
+      finished: !dnf && Boolean(car.finished || car.raceDistance >= sim.finishDistance),
+      finishTime,
+      dnf,
+      dnfReason: car.dnfReason ?? car.destroyReason ?? null,
+      dnfAt: car.dnfAt ?? car.destroyedAt ?? null,
+      dnfOrder: car.dnfOrder ?? null,
+      penaltySeconds,
+      adjustedFinishTime: finishTime == null ? null : finishTime + penaltySeconds,
+      positionDrop,
+      disqualified,
+    };
+  });
+}

package/src/simulation/race/gridPenalties.js

@@ -0,0 +1,37 @@
+import { pointAt, offsetTrackPoint } from '../track/trackModel.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import { getStartGridSlot } from '../vehicle/vehicleState.js';
+
+export function applyGridDropForSimulation(simulation, driverId, positions) {
+  const drop = Math.max(0, Math.floor(Number(positions) || 0));
+  if (drop <= 0) return;
+
+  const ordered = [...simulation.cars].sort((left, right) => {
+    const delta = right.gridDistance - left.gridDistance;
+    return delta === 0 ? left.index - right.index : delta;
+  });
+  const currentIndex = ordered.findIndex((car) => car.id === driverId);
+  if (currentIndex < 0) return;
+  const [car] = ordered.splice(currentIndex, 1);
+  ordered.splice(Math.min(ordered.length, currentIndex + drop), 0, car);
+
+  ordered.forEach((entry, index) => {
+    const { gridDistance, gridOffset } = getStartGridSlot(index, { standingStart: true });
+    const gridPoint = pointAt(simulation.track, gridDistance);
+    const position = offsetTrackPoint(gridPoint, gridOffset);
+    entry.gridDistance = gridDistance;
+    entry.gridOffset = gridOffset;
+    entry.rank = index + 1;
+    if (entry.gridLocked) {
+      entry.x = position.x;
+      entry.y = position.y;
+      entry.previousX = position.x;
+      entry.previousY = position.y;
+      entry.heading = gridPoint.heading;
+      entry.previousHeading = gridPoint.heading;
+      entry.progress = gridPoint.distance;
+      entry.raceDistance = gridDistance;
+      applyWheelSurfaceState(entry, simulation.track);
+    }
+  });
+}

package/src/simulation/race/raceControlState.js

@@ -0,0 +1,38 @@
+import { pointAt } from '../track/trackModel.js';
+
+export function createRaceControlState(rules, startLightsOutAt) {
+  return {
+    mode: rules.standingStart === false ? 'green' : 'pre-start',
+    frozenOrder: null,
+    redFlag: false,
+    pitLaneOpen: true,
+    finished: false,
+    finishedAt: null,
+    winnerId: null,
+    classification: [],
+    finishOrder: [],
+    nextDnfOrder: 1,
+    start: {
+      lightCount: rules.startLightCount,
+      lightsLit: 0,
+      lightsOutAt: startLightsOutAt,
+      released: rules.standingStart === false,
+      releasedAt: rules.standingStart === false ? 0 : null,
+    },
+  };
+}
+
+export function createSafetyCarState(track, rules) {
+  const safetyCarStart = pointAt(track, rules.safetyCarLeadDistance);
+  return {
+    deployed: false,
+    progress: rules.safetyCarLeadDistance,
+    speed: rules.safetyCarSpeed,
+    previousX: safetyCarStart.x,
+    previousY: safetyCarStart.y,
+    previousHeading: safetyCarStart.heading,
+    x: safetyCarStart.x,
+    y: safetyCarStart.y,
+    heading: safetyCarStart.heading,
+  };
+}

package/src/simulation/race/raceDistance.js

@@ -0,0 +1,32 @@
+import { clamp, wrapDistance } from '../simMath.js';
+
+const MIN_TOTAL_LAPS = 1;
+
+export function normalizeTotalLaps(value, { minimum = MIN_TOTAL_LAPS } = {}) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return minimum;
+  return Math.max(minimum, Math.floor(numeric));
+}
+
+export function wrapProgress(value, length) {
+  return wrapDistance(value, length);
+}
+
+export function distanceForward(from, to, length) {
+  return wrapProgress(to - from, length);
+}
+
+export function progressDelta(a, b, trackLength) {
+  let delta = a - b;
+  if (delta < -trackLength / 2) delta += trackLength;
+  if (delta > trackLength / 2) delta -= trackLength;
+  return delta;
+}
+
+export function computeLapForDistance(raceDistance, trackLength, totalLaps) {
+  return clamp(Math.floor(Math.max(0, raceDistance) / trackLength) + 1, 1, totalLaps);
+}
+
+export function finishDistanceForRace(trackLength, totalLaps) {
+  return trackLength * totalLaps;
+}

package/src/simulation/race/raceFinish.js

@@ -0,0 +1,65 @@
+import { isRaceDnf } from './retirements.js';
+
+export function evaluateRaceFinishForSimulation(sim) {
+  if (sim.raceControl.finished) return;
+  if (sim.raceControl.mode === 'pre-start') return;
+
+  const ordered = sim.orderedCars();
+  const newlyFinished = ordered.filter((car) => !isRaceDnf(car) && !car.finished && car.raceDistance >= sim.finishDistance);
+
+  newlyFinished.forEach((car) => {
+    car.finished = true;
+    car.finishTime = sim.time;
+    car.finishRank = sim.raceControl.finishOrder.length + 1;
+    car.classifiedRank = car.finishRank;
+    sim.raceControl.finishOrder.push(car.id);
+    if (!sim.raceControl.winnerId) sim.raceControl.winnerId = car.id;
+    car.drsActive = false;
+    car.drsEligible = false;
+    car.drsZoneId = null;
+    car.drsZoneEnabled = false;
+    car.canAttack = false;
+    sim.events.unshift({
+      type: 'car-finish',
+      at: sim.time,
+      carId: car.id,
+      rank: car.finishRank,
+      winnerId: sim.raceControl.winnerId,
+    });
+    sim.reviewTireRequirement(car);
+  });
+
+  if (!ordered.length || !ordered.every((car) => car.finished || isRaceDnf(car))) return;
+
+  sim.applyOutstandingServicePenalties();
+  const classification = sim.buildClassificationFromFinishOrder();
+  const winningClassification = classification.find((entry) => !entry.dnf && entry.finished);
+  sim.raceControl.winnerId = winningClassification?.id ?? null;
+  sim.raceControl.mode = 'safety-car';
+  sim.raceControl.finished = true;
+  sim.raceControl.finishedAt = sim.time;
+  sim.raceControl.classification = classification;
+  sim.raceControl.frozenOrder = classification.map((entry) => entry.id);
+  sim.safetyCar.deployed = true;
+  const leader = sim.cars.find((car) => car.id === sim.raceControl.winnerId) ?? ordered[0];
+  const safetyCarProgress = (leader?.raceDistance ?? 0) + sim.rules.safetyCarLeadDistance;
+  if (sim.safetyCar.progress < safetyCarProgress) {
+    sim.moveSafetyCarTo(safetyCarProgress);
+  }
+  sim.cars.forEach((car) => {
+    const classified = classification.find((entry) => entry.id === car.id);
+    car.classifiedRank = classified?.rank ?? null;
+    car.desiredOffset = 0;
+    car.drsActive = false;
+    car.drsEligible = false;
+    car.drsZoneId = null;
+    car.drsZoneEnabled = false;
+    car.canAttack = false;
+  });
+  sim.events.unshift({
+    type: 'race-finish',
+    at: sim.time,
+    winnerId: sim.raceControl.winnerId,
+    classification: classification.map((entry) => ({ id: entry.id, rank: entry.rank })),
+  });
+}

package/src/simulation/race/raceLifecycle.js

@@ -0,0 +1,67 @@
+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);
+  if (next === Boolean(sim.raceControl.pitLaneOpen)) return;
+  sim.raceControl.pitLaneOpen = next;
+  sim.events.unshift({ type: next ? 'pit-lane-open' : 'pit-lane-closed', at: sim.time });
+}
+
+export function updateStartSequence(sim) {
+  const start = sim.raceControl.start;
+  if (sim.raceControl.mode !== 'pre-start' || !start || start.released) return;
+
+  if (sim.time >= start.lightsOutAt) {
+    releaseRaceStart(sim);
+    sim.events.unshift({ type: 'start-lights-out', at: sim.time });
+    return;
+  }
+
+  start.lightsLit = clamp(
+    Math.floor((sim.time + Number.EPSILON) / sim.rules.startLightInterval),
+    0,
+    start.lightCount,
+  );
+}
+
+export function releaseRaceStart(sim) {
+  const start = sim.raceControl.start;
+  sim.raceControl.mode = 'green';
+  start.lightsLit = 0;
+  start.released = true;
+  start.releasedAt = sim.time;
+  sim.cars.forEach((car) => {
+    const wasGridLocked = car.gridLocked;
+    car.gridLocked = false;
+    const state = nearestTrackStateForCar(sim.track, car, car, car.gridDistance);
+    car.progress = state.distance;
+    applyWheelSurfaceState(car, sim.track);
+    if (wasGridLocked) car.raceDistance = car.gridDistance;
+    if (wasGridLocked) car.desiredOffset = 0;
+    car.previousX = car.x;
+    car.previousY = car.y;
+    car.previousHeading = car.heading;
+  });
+}
+
+export function holdGridCars(sim) {
+  sim.cars.forEach((car) => {
+    if (!car.gridLocked) return;
+    const gridPoint = pointAt(sim.track, car.gridDistance);
+    const position = offsetTrackPoint(gridPoint, car.gridOffset);
+    car.previousX = position.x;
+    car.previousY = position.y;
+    car.previousHeading = gridPoint.heading;
+    car.x = position.x;
+    car.y = position.y;
+    car.heading = gridPoint.heading;
+    freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
+    car.progress = gridPoint.distance;
+    car.raceDistance = car.gridDistance;
+    applyWheelSurfaceState(car, sim.track);
+  });
+}

package/src/simulation/race/raceOrder.js

@@ -0,0 +1,113 @@
+import { clamp } from '../simMath.js';
+import { affectsRaceOrder } from '../participants/participantInteractions.js';
+import { distanceForward } from './raceDistance.js';
+import { isRaceDnf, raceDnfCars } from './retirements.js';
+
+function canAppearInRaceOrder(car) {
+  return car?.interaction?.affectsRaceOrder !== false;
+}
+
+export function orderedCarsForSimulation(sim) {
+  const raceCars = raceOrderCarsForSimulation(sim);
+  const dnfCars = raceDnfCars(sim.cars.filter(canAppearInRaceOrder));
+  const sortLive = (cars) => [...cars].sort((a, b) => {
+    const delta = b.raceDistance - a.raceDistance;
+    return delta === 0 ? a.index - b.index : delta;
+  });
+  const byId = new Map(sim.cars.map((car) => [car.id, car]));
+
+  if (sim.raceControl.finished && sim.raceControl.classification?.length) {
+    const classified = sim.raceControl.classification.map((entry) => byId.get(entry.id)).filter(Boolean);
+    const classifiedIds = new Set(classified.map((car) => car.id));
+    return [
+      ...classified,
+      ...sortLive(raceCars.filter((car) => !classifiedIds.has(car.id))),
+      ...dnfCars.filter((car) => !classifiedIds.has(car.id)),
+    ];
+  }
+
+  if (sim.raceControl.finishOrder?.length) {
+    const finished = sim.raceControl.finishOrder.map((id) => byId.get(id)).filter(Boolean);
+    const finishedIds = new Set(finished.map((car) => car.id));
+    const missedFinished = sim.cars
+      .filter((car) => canAppearInRaceOrder(car) && !isRaceDnf(car) && car.finished && !finishedIds.has(car.id))
+      .sort((a, b) => {
+        const delta = (a.finishRank ?? Infinity) - (b.finishRank ?? Infinity);
+        return delta === 0 ? a.index - b.index : delta;
+      });
+    const running = sortLive(raceCars.filter((car) => !finishedIds.has(car.id) && !car.finished && !isRaceDnf(car)));
+    return [...finished, ...missedFinished, ...running, ...dnfCars.filter((car) => !finishedIds.has(car.id))];
+  }
+
+  if (sim.safetyCar.deployed && sim.raceControl.frozenOrder?.length) {
+    const frozen = sim.raceControl.frozenOrder.map((id) => byId.get(id)).filter(Boolean);
+    const activeFrozen = frozen.filter((car) => !isRaceDnf(car));
+    const activeFrozenIds = new Set(activeFrozen.map((car) => car.id));
+    return [
+      ...activeFrozen,
+      ...dnfCars.filter((car) => !activeFrozenIds.has(car.id)),
+    ];
+  }
+
+  return [...sortLive(raceCars.filter((car) => !isRaceDnf(car))), ...dnfCars];
+}
+
+export function raceOrderCarsForSimulation(sim) {
+  return sim.cars.filter((car) => affectsRaceOrder(car) && !isRaceDnf(car));
+}
+
+export function driverRaceContextForSimulation(sim, orderedCars = orderedCarsForSimulation(sim)) {
+  const raceCars = raceOrderCarsForSimulation(sim);
+  return {
+    physicsMode: sim.physicsMode,
+    track: sim.track,
+    cars: raceCars,
+    orderedCars,
+    safetyCar: sim.safetyCar,
+    rules: sim.rules,
+  };
+}
+
+export function computeAggressionForSimulation(sim, car, orderIndex = Math.max(0, (car.rank ?? 1) - 1)) {
+  const personality = car.personality ?? { baseAggression: 0.5, riskTolerance: 0.5, patience: 0.5 };
+  if (sim.safetyCar.deployed || car.canAttack === false) {
+    return clamp(personality.baseAggression * 0.62, 0.08, 0.62);
+  }
+
+  const fieldDepth = Math.max(1, raceOrderCarsForSimulation(sim).length - 1);
+  const positionPressure = clamp(orderIndex / fieldDepth, 0, 1);
+  const gapPressure = Number.isFinite(car.gapAhead) ? clamp((230 - car.gapAhead) / 230, 0, 1) : 0;
+  const tireConfidence = clamp(((car.tireEnergy ?? 100) - 42) / 58, 0, 1);
+  const patienceDamping = (1 - gapPressure) * personality.patience * 0.08;
+
+  return clamp(
+    personality.baseAggression
+      + positionPressure * 0.26
+      + gapPressure * (0.1 + personality.riskTolerance * 0.08)
+      - (1 - tireConfidence) * 0.1
+      - patienceDamping,
+    0.08,
+    1,
+  );
+}
+
+export function getDrsReferenceCarForSimulation(sim, car) {
+  let closest = null;
+  sim.cars.forEach((candidate) => {
+    if (
+      candidate === car ||
+      !affectsRaceOrder(candidate) ||
+      isRaceDnf(candidate) ||
+      candidate.finished ||
+      sim.isCarInActivePitStop(candidate)
+    ) return;
+    const delta = distanceForward(
+      car.progress ?? car.raceDistance ?? 0,
+      candidate.progress ?? candidate.raceDistance ?? 0,
+      sim.track.length,
+    );
+    if (delta <= 0 || delta > sim.track.length / 2) return;
+    if (!closest || delta < closest.delta) closest = { car: candidate, delta };
+  });
+  return closest?.car ?? null;
+}