@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/simulation/pit/pitServiceConstants.js

@@ -0,0 +1,21 @@
+import { kphToSimSpeed, metersToSimUnits } from '../units.js';
+import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+
+export const PIT_ROUTE_FINISH_DISTANCE = metersToSimUnits(8.5);
+export const PIT_QUEUE_RELEASE_FINISH_DISTANCE = metersToSimUnits(4);
+export const PIT_QUEUE_CAPTURE_DISTANCE = metersToSimUnits(2.5);
+export const PIT_ENTRY_BOX_CAPTURE_DISTANCE = metersToSimUnits(20);
+export const PIT_BOX_STOP_SPEED = kphToSimSpeed(35);
+export const PIT_QUEUE_CAPTURE_SPEED = kphToSimSpeed(140);
+export const PIT_QUEUE_RELEASE_SPEED = kphToSimSpeed(30);
+export const PIT_EXIT_RELEASE_SPEED_KPH = 95;
+export const PIT_BOX_APPROACH_DISTANCE = metersToSimUnits(34);
+export const PIT_LIMITER_BRAKE_DISTANCE = metersToSimUnits(295);
+export const PIT_LIMITER_APPROACH_SPEED_SLOPE = 0.045;
+export const PIT_ENTRY_CONNECTOR_OVERSPEED_KPH = 75;
+export const PIT_SERVICE_CLEAR_DISTANCE = VEHICLE_LIMITS.carLength * 0.9;
+
+export function pointDistance(first, second) {
+  if (!first || !second) return Infinity;
+  return Math.hypot(first.x - second.x, first.y - second.y);
+}

package/src/simulation/pit/pitServiceProfile.js

@@ -0,0 +1,45 @@
+import { clamp } from '../simMath.js';
+import { normalizePitCrewStats } from './pitState.js';
+import { getPitStopBox } from './pitOccupancy.js';
+
+export function calculatePitServiceProfile(sim, car) {
+  const pitStops = sim.rules.modules?.pitStops ?? {};
+  const variability = pitStops.variability ?? {};
+  const baseSeconds = Math.max(0, Number(pitStops.defaultStopSeconds) || 2.8);
+  const box = getPitStopBox(sim, car?.pitStop);
+  const team = sim.track.pitLane?.teams?.find((entry) => entry.id === car?.pitStop?.teamId);
+  const pitCrew = normalizePitCrewStats(
+    box?.pitCrew ?? team?.pitCrew ?? car?.team?.pitCrew ?? car?.team?.pitCrewStats,
+  );
+  const profile = {
+    baseSeconds,
+    seconds: baseSeconds,
+    perfect: Boolean(variability.perfect),
+    variabilityEnabled: Boolean(variability.enabled),
+    teamId: car?.pitStop?.teamId ?? box?.teamId ?? null,
+    pitCrew,
+    speedDeltaSeconds: 0,
+    consistencyDeltaSeconds: 0,
+    issueDelaySeconds: 0,
+    issue: null,
+  };
+
+  if (!variability.enabled || variability.perfect) return profile;
+
+  const speedImpact = Math.max(0, Number(variability.speedImpactSeconds) || 0);
+  const jitterImpact = Math.max(0, Number(variability.consistencyJitterSeconds) || 0);
+  const issueChance = clamp(Number(variability.issueChance) || 0, 0, 1);
+  const issueMaxDelay = Math.max(0, Number(variability.issueMaxDelaySeconds) || 0);
+  profile.speedDeltaSeconds = (0.5 - pitCrew.speed) * speedImpact;
+  profile.consistencyDeltaSeconds = (sim.random() - 0.5) * (1 - pitCrew.consistency) * jitterImpact;
+  const effectiveIssueChance = issueChance * (1 - pitCrew.reliability);
+  if (sim.random() < effectiveIssueChance) {
+    profile.issueDelaySeconds = 0.35 + sim.random() * issueMaxDelay * (1 - pitCrew.reliability);
+    profile.issue = 'slow-stop';
+  }
+  profile.seconds = Math.max(
+    Math.min(1.6, baseSeconds),
+    baseSeconds + profile.speedDeltaSeconds + profile.consistencyDeltaSeconds + profile.issueDelaySeconds,
+  );
+  return profile;
+}

package/src/simulation/pit/pitSnapshots.js

@@ -0,0 +1,61 @@
+import { finiteOrNull } from '../vehicle/vehicleSnapshots.js';
+
+export function pitLaneStatusSnapshot(raceControl, pitLane, pitStops) {
+  const enabled = Boolean(pitLane?.enabled && pitStops?.enabled);
+  const redFlag = Boolean(raceControl.redFlag);
+  const open = enabled && Boolean(raceControl.pitLaneOpen) && !redFlag;
+  return {
+    enabled,
+    open,
+    reason: !enabled ? 'unavailable' : redFlag ? 'red-flag' : open ? 'open' : 'closed',
+    color: open ? 'green' : redFlag ? 'yellow' : 'red',
+    light: open ? '#22c55e' : redFlag ? '#facc15' : '#ef4444',
+  };
+}
+
+export function serializePitStop(pitStop, normalizePitIntent, PIT_INTENT_NONE) {
+  if (!pitStop) return null;
+  return {
+    status: pitStop.status,
+    intent: normalizePitIntent(pitStop.intent) ?? PIT_INTENT_NONE,
+    phase: pitStop.phase ?? null,
+    boxIndex: pitStop.boxIndex,
+    boxId: pitStop.boxId,
+    garageBoxIndex: pitStop.garageBoxIndex ?? null,
+    garageBoxId: pitStop.garageBoxId ?? null,
+    teamId: pitStop.teamId ?? null,
+    teamColor: pitStop.teamColor ?? null,
+    stopsCompleted: pitStop.stopsCompleted ?? 0,
+    queueingForService: Boolean(pitStop.queueingForService),
+    plannedRaceDistance: finiteOrNull(pitStop.plannedRaceDistance),
+    entryRaceDistance: finiteOrNull(pitStop.entryRaceDistance),
+    serviceRemainingSeconds: finiteOrNull(pitStop.serviceRemaining),
+    penaltyServiceRemainingSeconds: finiteOrNull(pitStop.penaltyServiceRemaining),
+    penaltyServiceTotalSeconds: finiteOrNull(pitStop.penaltyServiceTotal),
+    servingPenaltyIds: [...(pitStop.servingPenaltyIds ?? [])],
+    targetTire: pitStop.targetTire ?? null,
+    serviceProfile: pitStop.serviceProfile ? { ...pitStop.serviceProfile } : null,
+  };
+}
+
+export function serializeRenderPitStop(pitStop) {
+  if (!pitStop) return null;
+  return {
+    phase: pitStop.phase ?? null,
+    serviceRemainingSeconds: finiteOrNull(pitStop.serviceRemaining),
+    penaltyServiceRemainingSeconds: finiteOrNull(pitStop.penaltyServiceRemaining),
+  };
+}
+
+export function serializeObservationPitStop(pitStop, normalizePitIntent, PIT_INTENT_NONE) {
+  if (!pitStop) return null;
+  return {
+    status: pitStop.status,
+    intent: normalizePitIntent(pitStop.intent) ?? PIT_INTENT_NONE,
+    phase: pitStop.phase ?? null,
+    targetTire: pitStop.targetTire ?? null,
+    serviceRemainingSeconds: finiteOrNull(pitStop.serviceRemaining),
+    penaltyServiceRemainingSeconds: finiteOrNull(pitStop.penaltyServiceRemaining),
+    stopsCompleted: pitStop.stopsCompleted ?? 0,
+  };
+}

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,92 @@
+import { kphToSimSpeed } from '../units.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import {
+  createRoute,
+  pitDriveLaneOffset,
+  pitMainLanePointAt,
+  routePoint,
+} from './pitRouting.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;
+  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,71 @@
+import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import { clamp } from '../simMath.js';
+import { nearestTrackStateForCar } from '../track/trackStatePolicy.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;
+    car.speed = 0;
+    car.throttle = 0;
+    car.brake = 1;
+    car.steeringAngle = 0;
+    car.yawRate = 0;
+    car.turnRadius = Infinity;
+    car.progress = gridPoint.distance;
+    car.raceDistance = car.gridDistance;
+    applyWheelSurfaceState(car, sim.track);
+  });
+}