@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/simulation/driverController.js

@@ -1,253 +1,4 @@
-import { pointAt, offsetTrackPoint } from './trackModel.js';
-import { clamp, normalizeAngle, seededRange, TWO_PI } from './simMath.js';
-import { VEHICLE_LIMITS } from './vehiclePhysics.js';
-
-const LANE_OFFSETS = [-78, -52, -26, 0, 26, 52, 78];
-
-function angleToPoint(car, target) {
-  const angle = Math.atan2(target.y - car.y, target.x - car.x);
-  return normalizeAngle(angle - car.heading);
-}
-
-export function buildDriverPersonality(driver, index, racecraft, random) {
-  const numberSeed = Number(driver.driverNumber ?? index + 1);
-  const numberBias = (((Number.isFinite(numberSeed) ? numberSeed : index + 1) % 11) - 5) * 0.014;
-  const baseAggression = clamp(
-    driver.personality?.aggression ?? 0.36 + racecraft * 0.34 + numberBias + seededRange(random, -0.045, 0.045),
-    0.18,
-    0.88,
-  );
-
-  return {
-    baseAggression,
-    riskTolerance: clamp(
-      driver.personality?.riskTolerance ?? baseAggression * 0.72 + racecraft * 0.24 + seededRange(random, -0.04, 0.04),
-      0.12,
-      0.95,
-    ),
-    patience: clamp(
-      driver.personality?.patience ?? 0.72 - baseAggression * 0.36 + racecraft * 0.12 + seededRange(random, -0.05, 0.05),
-      0.18,
-      0.9,
-    ),
-  };
-}
-
-export function createDriverInput() {
-  const state = {
-    steering: 0,
-    throttle: 0,
-    brake: 0,
-  };
-
-  return {
-    steer(amount) {
-      state.steering = clamp(amount, -VEHICLE_LIMITS.maxSteer, VEHICLE_LIMITS.maxSteer);
-      return this;
-    },
-    accelerate(amount) {
-      state.throttle = clamp(amount, 0, 1);
-      return this;
-    },
-    brake(amount) {
-      state.brake = clamp(amount, 0, 1);
-      return this;
-    },
-    controls() {
-      return { ...state };
-    },
-  };
-}
-
-export function decideDriverControls({ car, orderIndex, race }) {
-  if (car.manualControls) return car.manualControls;
-
-  if (car.gridLocked) {
-    return createDriverInput().brake(1).controls();
-  }
-
-  if (race.safetyCar.deployed) {
-    return decideSafetyCarControls(car, orderIndex, race);
-  }
-
-  if (!car.trackState.onTrack) {
-    return decideRejoinControls(car, race);
-  }
-
-  return decideRacingControls(car, orderIndex, race);
-}
-
-function decideRacingControls(car, orderIndex, race) {
-  const aggression = car.aggression ?? car.personality?.baseAggression ?? 0.5;
-  const lookahead = clamp(car.speed * (1.12 - aggression * 0.08) + 160, 160, 360);
-  const targetBase = pointAt(race.track, car.progress + lookahead);
-  const lanePlan = planRacingLine(car, orderIndex, race);
-  const recoveryBias = car.trackState.crossTrackError > race.track.width * 0.46 ? 0 : 1;
-  const target = offsetTrackPoint(targetBase, lanePlan.offset * recoveryBias);
-  const angleError = angleToPoint(car, target);
-  const curvature = Math.max(car.trackState.curvature, targetBase.curvature);
-  const gripBudget = 54 + car.racecraft * 11 + (car.tireEnergy ?? 100) * 0.05 + aggression * 4.5;
-  const cornerTarget = clamp(
-    Math.sqrt(gripBudget / Math.max(curvature, 0.0001)) + (car.pace - 1) * 20 + aggression * 7,
-    72,
-    168,
-  );
-  const edgeTolerance = race.track.width * (0.36 + aggression * 0.1);
-  const edgePenalty = Math.max(0, car.trackState.crossTrackError - edgeTolerance) * (0.16 - aggression * 0.05);
-  const trafficPenalty = Math.max(
-    lanePlan.sameLaneAhead ? clamp((230 - lanePlan.sameLaneAhead.gap) * 0.16, 0, 32) : 0,
-    lanePlan.sideRisk ? clamp((44 - lanePlan.sideRisk.lateral) * 0.42, 0, 16) : 0,
-  ) * (1 - aggression * 0.28);
-  const desiredSpeed = clamp(
-    (car.drsActive ? cornerTarget + 22 : cornerTarget) - edgePenalty - trafficPenalty,
-    58,
-    VEHICLE_LIMITS.maxSpeed,
-  );
-  const speedError = desiredSpeed - car.speed;
-
-  return createDriverInput()
-    .steer(angleError * (0.82 + car.racecraft * 0.1))
-    .accelerate(speedError > 1 ? clamp(speedError / 16, 0.1 + aggression * 0.08, 1) : 0)
-    .brake(speedError < -2 ? clamp(Math.abs(speedError) / (22 + aggression * 8), 0, 1) : 0)
-    .controls();
-}
-
-function decideRejoinControls(car, race) {
-  const lookahead = clamp(car.speed * 0.72 + 118, 118, 220);
-  const targetBase = pointAt(race.track, car.progress + lookahead);
-  const target = offsetTrackPoint(targetBase, 0);
-  const angleError = angleToPoint(car, target);
-  const distanceFromRoad = Math.max(0, car.trackState.crossTrackError - race.track.width / 2);
-  const surfaceTargetSpeed = car.trackState.surface === 'gravel'
-    ? 54
-    : car.trackState.surface === 'grass'
-      ? 44
-      : 30;
-  const desiredSpeed = clamp(surfaceTargetSpeed - distanceFromRoad * 0.045, 20, surfaceTargetSpeed);
-  const speedError = desiredSpeed - car.speed;
-  const alignment = clamp(1 - Math.abs(angleError) / Math.PI, 0.28, 1);
-  const lowSpeedRecovery = car.speed < 18 ? 0.16 : 0;
-  const throttleLimit = car.trackState.surface === 'gravel' ? 0.62 : 0.48;
-
-  return createDriverInput()
-    .steer(angleError * 0.92)
-    .accelerate(speedError > 0 ? clamp((speedError / 24) * alignment + lowSpeedRecovery, 0.08, throttleLimit) : lowSpeedRecovery)
-    .brake(speedError < -5 ? clamp(Math.abs(speedError) / 30, 0.04, 0.74) : 0)
-    .controls();
-}
-
-function decideSafetyCarControls(car, orderIndex, race) {
-  const queueSlot = race.safetyCar.progress - race.rules.safetyCarLeadDistance - orderIndex * race.rules.safetyCarGap;
-  const lookahead = clamp(car.speed * 0.8 + 74, 84, 148);
-  const targetBase = pointAt(race.track, car.progress + lookahead);
-  const target = offsetTrackPoint(targetBase, 0);
-  const slotError = queueSlot - car.raceDistance;
-  const desiredSpeed = clamp(
-    race.rules.safetyCarSpeed + slotError * 0.24,
-    22,
-    race.rules.safetyCarSpeed + 32,
-  );
-  const speedError = desiredSpeed - car.speed;
-
-  return createDriverInput()
-    .steer(angleToPoint(car, target) * 1.04)
-    .accelerate(speedError > 1 ? clamp(speedError / 16, 0, 0.5) : 0)
-    .brake(speedError < -0.5 ? clamp(Math.abs(speedError) / 14, 0, 1) : 0)
-    .controls();
-}
-
-export function planRacingLine(car, orderIndex, race) {
-  const aggression = car.aggression ?? car.personality?.baseAggression ?? 0.5;
-  const riskTolerance = car.personality?.riskTolerance ?? aggression;
-  const trackLimit = race.track.width / 2 - VEHICLE_LIMITS.carWidth * clamp(1.22 - aggression * 0.34, 0.84, 1.22);
-  const preferred = Math.sin((car.index / Math.max(1, race.cars.length)) * TWO_PI) * 26;
-  const currentOffset = clamp(car.desiredOffset ?? preferred, -trackLimit, trackLimit);
-  const ahead = race.orderedCars[orderIndex - 1];
-  const traffic = scanNearbyTraffic(car, race);
-
-  let bestOffset = currentOffset;
-  let bestScore = -Infinity;
-
-  LANE_OFFSETS.forEach((rawOffset) => {
-    const offset = clamp(rawOffset, -trackLimit, trackLimit);
-    const edgeClearance = trackLimit - Math.abs(offset);
-    let score = 80;
-    score -= Math.abs(offset - preferred) * 0.18;
-    score -= Math.abs(offset - currentOffset) * (0.09 - aggression * 0.025);
-    score -= Math.max(0, 18 - edgeClearance) * (0.92 - aggression * 0.42);
-
-    traffic.forEach((entry) => {
-      const lateral = Math.abs(entry.signedOffset - offset);
-      if (entry.gap > 0 && entry.gap < 260) {
-        const overlapRisk = clamp(58 - lateral, 0, 58);
-        score -= overlapRisk * (260 - entry.gap) * 0.038 * (1 - riskTolerance * 0.34);
-        if (entry.gap < 190 + aggression * 70 && lateral > 34 - aggression * 8) {
-          score += Math.min(30 + aggression * 18, lateral - (28 - aggression * 6)) * (0.62 + aggression * 0.82);
-        }
-      } else if (entry.gap <= 0 && entry.gap > -74) {
-        const sideOverlapRisk = clamp(52 - lateral, 0, 52);
-        score -= sideOverlapRisk * (74 + entry.gap) * 0.052 * (1 - riskTolerance * 0.22);
-      }
-    });
-
-    if (ahead && car.gapAhead < 230) {
-      const side = car.index % 2 === 0 ? -1 : 1;
-      const passSide = clamp(
-        (ahead.trackState.signedOffset * -0.65) + side * (48 + aggression * 42),
-        -trackLimit,
-        trackLimit,
-      );
-      score -= Math.abs(offset - passSide) * (0.09 + aggression * 0.08);
-    }
-
-    if (score > bestScore) {
-      bestScore = score;
-      bestOffset = offset;
-    }
-  });
-
-  const laneChangeRate = 0.72 + car.racecraft * 0.3 + aggression * 0.58;
-  car.desiredOffset = currentOffset + clamp(bestOffset - currentOffset, -laneChangeRate, laneChangeRate);
-
-  return {
-    offset: car.desiredOffset,
-    sameLaneAhead: findLaneTrafficAhead(traffic, car.desiredOffset, 230),
-    sideRisk: findLaneTrafficBeside(traffic, car.desiredOffset),
-  };
-}
-
-function scanNearbyTraffic(car, race) {
-  return race.cars
-    .filter((other) => other !== car)
-    .map((other) => ({
-      car: other,
-      gap: other.raceDistance - car.raceDistance,
-      signedOffset: other.trackState?.signedOffset ?? 0,
-    }))
-    .filter((entry) => entry.gap > -82 && entry.gap < 280);
-}
-
-function findLaneTrafficAhead(traffic, offset, maxDistance) {
-  let closest = null;
-
-  traffic.forEach((entry) => {
-    if (entry.gap <= 0 || entry.gap > maxDistance) return;
-    if (Math.abs(entry.signedOffset - offset) > 42) return;
-    if (!closest || entry.gap < closest.gap) closest = entry;
-  });
-
-  return closest;
-}
-
-function findLaneTrafficBeside(traffic, offset) {
-  let closest = null;
-
-  traffic.forEach((entry) => {
-    const lateral = Math.abs(entry.signedOffset - offset);
-    if (Math.abs(entry.gap) > 58 || lateral > 44) return;
-    const risk = (58 - Math.abs(entry.gap)) + (44 - lateral);
-    if (!closest || risk > closest.risk) closest = { ...entry, lateral, risk };
-  });
-
-  return closest;
-}
+export { decideDriverControls } from './driver/driverController.js';
+export { createDriverInput } from './driver/driverInput.js';
+export { buildDriverPersonality } from './driver/driverPersonality.js';
+export { planRacingLine } from './driver/racingLinePlan.js';

package/src/simulation/participants/participantInteractions.js

@@ -0,0 +1,120 @@
+export const PARTICIPANT_INTERACTION_PROFILES = Object.freeze({
+  normal: Object.freeze({
+    profile: 'normal',
+    collidable: true,
+    detectableByRays: true,
+    detectableAsNearby: true,
+    blocksPitLane: true,
+    affectsRaceOrder: true,
+  }),
+  'isolated-training': Object.freeze({
+    profile: 'isolated-training',
+    collidable: false,
+    detectableByRays: false,
+    detectableAsNearby: false,
+    blocksPitLane: false,
+    affectsRaceOrder: true,
+  }),
+  'batch-training': Object.freeze({
+    profile: 'batch-training',
+    collidable: false,
+    detectableByRays: false,
+    detectableAsNearby: false,
+    blocksPitLane: false,
+    affectsRaceOrder: false,
+  }),
+  'phantom-race': Object.freeze({
+    profile: 'phantom-race',
+    collidable: false,
+    detectableByRays: true,
+    detectableAsNearby: true,
+    blocksPitLane: false,
+    affectsRaceOrder: true,
+  }),
+  'time-trial-overlay': Object.freeze({
+    profile: 'time-trial-overlay',
+    collidable: false,
+    detectableByRays: false,
+    detectableAsNearby: false,
+    blocksPitLane: false,
+    affectsRaceOrder: false,
+  }),
+});
+
+const INTERACTION_FLAGS = Object.freeze([
+  'collidable',
+  'detectableByRays',
+  'detectableAsNearby',
+  'blocksPitLane',
+  'affectsRaceOrder',
+]);
+
+export function normalizeParticipantInteractions(options = {}) {
+  const defaultProfile = resolveProfileName(options.defaultProfile);
+  const defaultInteraction = { ...PARTICIPANT_INTERACTION_PROFILES[defaultProfile] };
+  const drivers = {};
+  Object.entries(options.drivers ?? {}).forEach(([driverId, override]) => {
+    drivers[driverId] = resolveInteraction(override, defaultProfile);
+  });
+  return {
+    defaultProfile,
+    defaultInteraction,
+    drivers,
+  };
+}
+
+export function attachParticipantInteractions(cars = [], options = {}) {
+  const normalized = normalizeParticipantInteractions(options);
+  cars.forEach((car) => {
+    car.interaction = normalized.drivers[car.id] ?? { ...normalized.defaultInteraction };
+  });
+  return normalized;
+}
+
+export function resolveInteraction(override = {}, fallbackProfile = 'normal') {
+  const profile = resolveProfileName(override?.profile ?? fallbackProfile);
+  const resolved = { ...PARTICIPANT_INTERACTION_PROFILES[profile] };
+  INTERACTION_FLAGS.forEach((flag) => {
+    if (override?.[flag] != null) resolved[flag] = Boolean(override[flag]);
+  });
+  return resolved;
+}
+
+export function canCollide(first, second) {
+  return isCollidable(first) && isCollidable(second);
+}
+
+export function isCollidable(car) {
+  if (car?.destroyed || car?.outOfRace) return false;
+  return car?.interaction?.collidable !== false;
+}
+
+export function isRayDetectable(car) {
+  if (car?.destroyed || car?.outOfRace) return false;
+  return car?.interaction?.detectableByRays !== false;
+}
+
+export function isNearbyDetectable(car) {
+  if (car?.destroyed || car?.outOfRace) return false;
+  return car?.interaction?.detectableAsNearby !== false;
+}
+
+export function blocksPitLane(car) {
+  if (car?.destroyed || car?.outOfRace) return false;
+  return car?.interaction?.blocksPitLane !== false;
+}
+
+export function affectsRaceOrder(car) {
+  if (car?.destroyed || car?.outOfRace) return false;
+  return car?.interaction?.affectsRaceOrder !== false;
+}
+
+export function serializeParticipantInteraction(interaction) {
+  const normalized = resolveInteraction(interaction ?? {}, interaction?.profile ?? 'normal');
+  return { ...normalized };
+}
+
+function resolveProfileName(profile) {
+  const key = String(profile ?? 'normal');
+  return PARTICIPANT_INTERACTION_PROFILES[key] ? key : 'normal';
+}

package/src/simulation/pit/pitFlow.js

@@ -0,0 +1,234 @@
+import { pitLaneStatusSnapshot } from './pitSnapshots.js';
+import {
+  firstDifferentCompound,
+  normalizePitIntent,
+  shouldStartPitStopForSimulation,
+  updateAutomaticPitIntentForSimulation,
+} from './pitIntent.js';
+import {
+  advancePitService,
+  applyPitRoutePosition,
+  beginPitQueue,
+  beginPitService,
+  finishPitExit,
+  getPitBoxRaceDistance,
+  getPitStopBox,
+  isPitServiceBusy,
+  isPitServiceQueueOccupied,
+  releasePitQueue,
+} from './pitService.js';
+import {
+  createPitApproachPoints,
+  createRoute,
+  pitDriveLaneOffset,
+  pitMainLanePointAt,
+  routePoint,
+} from './pitRouting.js';
+import { metersToSimUnits } from '../units.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+
+const PIT_ENTRY_APPROACH_DISTANCE = metersToSimUnits(250);
+const PIT_BOX_APPROACH_DISTANCE = metersToSimUnits(34);
+const PIT_SERVICE_QUEUE_FALLBACK_GAP = metersToSimUnits(48);
+const PIT_ENTRY_LATE_THRESHOLD_DISTANCE = metersToSimUnits(90);
+
+export function isCarInActivePitStop(sim, car) {
+  return Boolean(car?.pitStop && car.pitStop.status !== 'pending' && car.pitStop.status !== 'completed');
+}
+
+export function schedulePitStopAtNextEntry(sim, car, stop) {
+  const pitLane = sim.track.pitLane;
+  if (!stop || !pitLane?.entry || !Number.isFinite(sim.track.length) || sim.track.length <= 0) return false;
+  const raceDistance = car.raceDistance ?? 0;
+  const entryOffset = pitLane.entry.distanceFromStart ?? 0;
+  let lapBase = Math.floor((raceDistance - entryOffset) / sim.track.length) * sim.track.length;
+  let entryRaceDistance = lapBase + entryOffset;
+
+  while (raceDistance > entryRaceDistance + PIT_ENTRY_LATE_THRESHOLD_DISTANCE) {
+    lapBase += sim.track.length;
+    entryRaceDistance = lapBase + entryOffset;
+  }
+
+  stop.lapBase = lapBase;
+  stop.entryRaceDistance = entryRaceDistance;
+  stop.plannedRaceDistance = entryRaceDistance - PIT_ENTRY_APPROACH_DISTANCE;
+  return true;
+}
+
+export function rearmCompletedPitStop(sim, car, stop) {
+  if (!stop || stop.status !== 'completed') return false;
+  stop.status = 'pending';
+  stop.phase = null;
+  stop.route = null;
+  stop.routeProgress = 0;
+  stop.routeStartRaceDistance = null;
+  stop.routeEndRaceDistance = null;
+  stop.serviceRemaining = 0;
+  stop.penaltyServiceRemaining = 0;
+  stop.penaltyServiceTotal = 0;
+  stop.servingPenaltyIds = [];
+  stop.queueingForService = false;
+  stop.serviceProfile = null;
+  stop.targetTire = stop.targetTire ?? firstDifferentCompound(car.tire, sim.rules.modules?.tireStrategy?.compounds);
+  return schedulePitStopAtNextEntry(sim, car, stop);
+}
+
+export function canStartPitStop(sim, car) {
+  const stop = car.pitStop;
+  const pitStops = sim.rules.modules?.pitStops;
+  if (!stop || !pitStops?.enabled) return false;
+  const active = sim.cars.filter((candidate) => candidate !== car && isCarInActivePitStop(sim, candidate));
+  const maxConcurrentPitLaneCars = Math.max(1, Math.floor(pitStops.maxConcurrentPitLaneCars ?? 3));
+  if (active.length >= maxConcurrentPitLaneCars) return false;
+
+  if (!pitStops.doubleStacking && stop.teamId) {
+    const box = getPitStopBox(sim, stop);
+    if (isPitServiceQueueOccupied(sim, car, box)) return false;
+  }
+
+  const minimumGap = Math.max(0, pitStops.minimumPitLaneGap ?? 0);
+  const candidateDistance = car.raceDistance ?? 0;
+  return active.every((candidate) => {
+    const gap = (candidate.raceDistance ?? 0) - candidateDistance;
+    return gap < 0 || gap >= minimumGap;
+  });
+}
+
+export function shouldStartPitStop(sim, car) {
+  return shouldStartPitStopForSimulation(sim, car);
+}
+
+export function updateAutomaticPitIntent(sim, car) {
+  updateAutomaticPitIntentForSimulation(sim, car);
+}
+
+export function isPitLaneOpenForStops(sim) {
+  return pitLaneStatusSnapshot(sim.raceControl, sim.track.pitLane, sim.rules.modules?.pitStops).open;
+}
+
+export function pitEntryLateThresholdDistance() {
+  return PIT_ENTRY_LATE_THRESHOLD_DISTANCE;
+}
+
+export function startPitStop(sim, car) {
+  const stop = car.pitStop;
+  const box = getPitStopBox(sim, stop);
+  const pitLane = sim.track.pitLane;
+  if (!stop || !box || !pitLane?.enabled) return false;
+
+  car.gridLocked = false;
+  car.drsActive = false;
+  car.drsEligible = false;
+  car.drsZoneId = null;
+  car.drsZoneEnabled = false;
+  car.canAttack = false;
+  stop.targetTire = stop.targetTire ?? firstDifferentCompound(car.tire, sim.rules.modules?.tireStrategy?.compounds);
+
+  const currentState = applyWheelSurfaceState(car, sim.track).representativeState;
+  sim.events.unshift({
+    type: 'pit-entry',
+    at: sim.time,
+    carId: car.id,
+    boxId: box.id,
+    teamId: box.teamId ?? null,
+  });
+
+  if (currentState.surface === 'pit-box' && currentState.pitBoxId === box.id) {
+    beginPitService(sim, car, box);
+    return true;
+  }
+
+  const hasServiceQueue = Boolean(box.queuePoint);
+  const shouldStageForService = hasServiceQueue;
+  const queueDistanceAlongLane = box.queueDistanceAlongLane ??
+    Math.max(0, box.distanceAlongLane - PIT_SERVICE_QUEUE_FALLBACK_GAP);
+  const stopDistanceAlongLane = shouldStageForService
+    ? queueDistanceAlongLane
+    : box.distanceAlongLane;
+  const serviceTarget = shouldStageForService ? box.queuePoint : box.center;
+  const driveLaneOffset = pitDriveLaneOffset(pitLane);
+  const boxApproachDistance = Math.max(
+    0,
+    (hasServiceQueue ? queueDistanceAlongLane : stopDistanceAlongLane) - PIT_BOX_APPROACH_DISTANCE,
+  );
+  const route = createRoute([
+    ...createPitApproachPoints(sim.track, car, pitLane, stop.entryRaceDistance),
+    ...(pitLane.entry.roadCenterline ?? []).map((point) => routePoint(point)),
+    routePoint(pitMainLanePointAt(pitLane, 0, driveLaneOffset), pitLane.mainLane.heading, { limiterActive: true }),
+    routePoint(pitMainLanePointAt(pitLane, boxApproachDistance, driveLaneOffset), pitLane.mainLane.heading, { limiterActive: true }),
+    routePoint(serviceTarget, pitLane.mainLane.heading, { limiterActive: true }),
+  ]);
+  stop.status = 'entering';
+  stop.phase = 'entry';
+  stop.queueingForService = shouldStageForService;
+  stop.route = route;
+  stop.routeProgress = 0;
+  stop.routeStartRaceDistance = car.raceDistance ?? stop.plannedRaceDistance;
+  stop.routeEndRaceDistance = getPitBoxRaceDistance(sim, stop, {
+    ...box,
+    distanceAlongLane: stopDistanceAlongLane,
+  });
+  return true;
+}
+
+export function advancePitStopCar(sim, car, delta) {
+  const pitStops = sim.rules.modules?.pitStops;
+  const stop = car.pitStop;
+  if (!pitStops?.enabled || !stop) return false;
+  if (stop.status === 'pending' || stop.status === 'completed') updateAutomaticPitIntent(sim, car);
+  if (stop.status === 'completed') return false;
+  if (stop.status === 'pending' && !shouldStartPitStop(sim, car)) return false;
+  if (stop.status === 'pending') startPitStop(sim, car);
+
+  if (stop.status === 'entering') {
+    const finishedRoute = applyPitRoutePosition(sim, car, delta);
+    const box = getPitStopBox(sim, stop);
+    if (finishedRoute && box) {
+      if (stop.queueingForService) {
+        if (!isPitServiceBusy(sim, car, box) && !isPitServiceQueueOccupied(sim, car, box)) {
+          releasePitQueue(sim, car, box, { fromCurrent: true });
+        } else {
+          beginPitQueue(sim, car, box);
+        }
+      }
+      else beginPitService(sim, car, box);
+    }
+    car.contactCooldown = Math.max(0, car.contactCooldown - delta);
+    return true;
+  }
+
+  if (stop.status === 'queued') {
+    const box = getPitStopBox(sim, stop);
+    if (!box) return true;
+    car.previousX = car.x;
+    car.previousY = car.y;
+    car.previousHeading = car.heading;
+    car.x = box.queuePoint.x;
+    car.y = box.queuePoint.y;
+    car.heading = sim.track.pitLane.mainLane.heading;
+    car.speed = 0;
+    car.throttle = 0;
+    car.brake = 1;
+    applyWheelSurfaceState(car, sim.track);
+    car.progress = car.trackState.distance;
+    car.raceDistance = getPitBoxRaceDistance(sim, stop, {
+      ...box,
+      distanceAlongLane: box.queueDistanceAlongLane ?? box.distanceAlongLane,
+    });
+    if (!isPitServiceBusy(sim, car, box)) releasePitQueue(sim, car, box);
+    return true;
+  }
+
+  if (stop.status === 'servicing') {
+    return advancePitService(sim, car, delta);
+  }
+
+  if (stop.status === 'exiting') {
+    const finishedRoute = applyPitRoutePosition(sim, car, delta);
+    if (finishedRoute) finishPitExit(sim, car);
+    car.contactCooldown = Math.max(0, car.contactCooldown - delta);
+    return true;
+  }
+
+  return false;
+}

package/src/simulation/pit/pitIntent.js

@@ -0,0 +1,92 @@
+export const PIT_INTENT_NONE = 0;
+export const PIT_INTENT_IF_FREE = 1;
+export const PIT_INTENT_COMMITTED = 2;
+
+export function firstDifferentCompound(currentTire, compounds) {
+  const available = Array.isArray(compounds) && compounds.length ? compounds : ['S', 'M', 'H'];
+  return available.find((compound) => compound !== currentTire) ?? currentTire;
+}
+
+export function normalizePitCompound(value, compounds) {
+  if (value == null || value === '') return null;
+  const available = Array.isArray(compounds) && compounds.length ? compounds : ['S', 'M', 'H'];
+  return available.includes(value) ? value : null;
+}
+
+export function normalizePitIntent(value) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0 || number > 2) return null;
+  return number;
+}
+
+export function setPitIntentForSimulation(sim, id, intent, targetCompound = undefined) {
+  const request = intent && typeof intent === 'object'
+    ? intent
+    : { intent, targetCompound };
+  const nextIntent = normalizePitIntent(request.intent ?? request.pitIntent);
+  if (nextIntent == null) return false;
+  const car = sim.cars.find((item) => item.id === id);
+  const stop = car?.pitStop;
+  const pitStops = sim.rules.modules?.pitStops;
+  if (!car || !stop || !pitStops?.enabled || !sim.track.pitLane?.enabled) return false;
+  if (sim.isCarInActivePitStop(car)) return false;
+
+  const compoundRequest = request.targetCompound ??
+    request.compound ??
+    request.pitCompound ??
+    request.pitTargetCompound ??
+    request.targetTire;
+  const hasCompoundRequest = compoundRequest != null && compoundRequest !== '';
+  if (hasCompoundRequest) {
+    const targetTire = normalizePitCompound(compoundRequest, sim.rules.modules?.tireStrategy?.compounds);
+    if (!targetTire) return false;
+    stop.targetTire = targetTire;
+  } else if (nextIntent !== 0 && (!stop.targetTire || stop.status === 'completed')) {
+    stop.targetTire = firstDifferentCompound(car.tire, sim.rules.modules?.tireStrategy?.compounds);
+  } else if (nextIntent === 0) {
+    stop.targetTire = firstDifferentCompound(car.tire, sim.rules.modules?.tireStrategy?.compounds);
+  }
+
+  stop.intent = nextIntent;
+  if (stop.status === 'pending' && nextIntent !== 0) {
+    sim.schedulePitStopAtNextEntry(car, stop);
+  } else if (stop.status === 'completed' && nextIntent !== 0) {
+    sim.rearmCompletedPitStop(car, stop);
+  }
+  return true;
+}
+
+export function shouldStartPitStopForSimulation(sim, car) {
+  const stop = car.pitStop;
+  if (!stop || stop.status !== 'pending' || car.finished) return false;
+  if (!sim.isPitLaneOpenForStops()) return false;
+  const intent = normalizePitIntent(stop.intent) ?? 0;
+  if (intent === 0) return false;
+  const raceDistance = car.raceDistance ?? 0;
+  if (raceDistance > stop.entryRaceDistance + sim.pitEntryLateThresholdDistance()) {
+    sim.schedulePitStopAtNextEntry(car, stop);
+    return false;
+  }
+  return raceDistance >= stop.plannedRaceDistance &&
+    (intent === 2 || sim.canStartPitStop(car));
+}
+
+export function updateAutomaticPitIntentForSimulation(sim, car) {
+  const stop = car.pitStop;
+  const pitStops = sim.rules.modules?.pitStops;
+  if (!stop || !['pending', 'completed'].includes(stop.status) || !pitStops?.enabled || car.finished) return;
+  if (car.automaticPitIntentEnabled === false) return;
+  const tireEnergy = Number(car.tireEnergy ?? 100);
+  const requestThreshold = Number(pitStops.tirePitRequestThresholdPercent ?? 50);
+  const commitThreshold = Number(pitStops.tirePitCommitThresholdPercent ?? 30);
+  if (!Number.isFinite(tireEnergy)) return;
+
+  let nextIntent = 0;
+  if (tireEnergy < commitThreshold) nextIntent = 2;
+  else if (tireEnergy < requestThreshold) nextIntent = 1;
+  if (nextIntent === 0 || nextIntent <= (normalizePitIntent(stop.intent) ?? 0)) return;
+
+  stop.intent = nextIntent;
+  if (stop.status === 'completed') sim.rearmCompletedPitStop(car, stop);
+  else sim.schedulePitStopAtNextEntry(car, stop);
+}