@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/simulation/pit/pitOccupancy.js

@@ -0,0 +1,47 @@
+import { blocksPitLane } from '../participants/participantInteractions.js';
+import { PIT_SERVICE_CLEAR_DISTANCE, pointDistance } from './pitServiceConstants.js';
+
+export function getPitStopBox(sim, stop) {
+  return sim.track.pitLane?.serviceAreas?.find((box) => box.id === stop?.boxId) ??
+    sim.track.pitLane?.boxes?.find((box) => box.id === stop?.boxId) ??
+    null;
+}
+
+export function isPitServiceAreaOccupied(sim, candidate, box, clearDistance) {
+  if (!blocksPitLane(candidate)) return false;
+  const status = candidate?.pitStop?.status;
+  const phase = candidate?.pitStop?.phase;
+  if (!status || !box) return false;
+  if (status === 'servicing') return true;
+  if (status === 'entering' && phase === 'queue-release') return true;
+  if (status === 'exiting') return pointDistance(candidate, box.center) < clearDistance;
+  return false;
+}
+
+export function isPitServiceBusy(sim, car, box, clearDistance = PIT_SERVICE_CLEAR_DISTANCE) {
+  return sim.cars.some((candidate) => (
+    candidate !== car &&
+    blocksPitLane(candidate) &&
+    candidate.pitStop?.boxId === box?.id &&
+    isPitServiceAreaOccupied(sim, candidate, box, clearDistance)
+  ));
+}
+
+export function isPitServiceQueueOccupied(sim, car, box) {
+  return sim.cars.some((candidate) => (
+    candidate !== car &&
+    blocksPitLane(candidate) &&
+    candidate.pitStop?.boxId === box?.id &&
+    (
+      candidate.pitStop?.status === 'queued' ||
+      Boolean(candidate.pitStop?.queueingForService)
+    )
+  ));
+}
+
+export function getPitBoxRaceDistance(sim, stop, box) {
+  const pitLane = sim.track.pitLane;
+  const amount = pitLane?.mainLane?.length > 0 ? box.distanceAlongLane / pitLane.mainLane.length : 0;
+  return stop.lapBase + pitLane.entry.distanceFromStart +
+    (pitLane.exit.distanceFromStart - pitLane.entry.distanceFromStart) * amount;
+}

package/src/simulation/pit/pitPenaltyService.js

@@ -0,0 +1,71 @@
+import {
+  getPitServicePenaltySeconds,
+  isPenaltyPitServiceable,
+  servePitPenaltyRecord,
+} from '../rules/penaltyLedger.js';
+import { beginTireService } from './pitTireService.js';
+
+export function beginPitPenaltyService(sim, car) {
+  const stop = car.pitStop;
+  const penalties = getPitServicePenalties(sim, car.id);
+  if (!stop || !penalties.length) return false;
+
+  const totalSeconds = penalties.reduce((total, penalty) => (
+    total + getPitServicePenaltySeconds(penalty)
+  ), 0);
+  stop.servingPenaltyIds = penalties.map((penalty) => penalty.id);
+  stop.penaltyServiceTotal = totalSeconds;
+  stop.penaltyServiceRemaining = totalSeconds;
+
+  if (totalSeconds <= 0) {
+    completePitPenaltyService(sim, car);
+    return true;
+  }
+
+  stop.phase = 'penalty';
+  stop.serviceRemaining = totalSeconds;
+  sim.events.unshift({
+    type: 'pit-penalty-service-start',
+    at: sim.time,
+    carId: car.id,
+    penaltyIds: [...stop.servingPenaltyIds],
+    penaltyServiceSeconds: totalSeconds,
+  });
+  return true;
+}
+
+export function completePitPenaltyService(sim, car) {
+  const stop = car.pitStop;
+  if (!stop) return;
+  const servedIds = [...(stop.servingPenaltyIds ?? [])];
+  servedIds.forEach((penaltyId) => {
+    const penalty = sim.penalties.find((entry) => entry.id === penaltyId);
+    const beforeStatus = penalty?.status;
+    const result = servePitPenaltyRecord(penalty, sim.time);
+    if (result && beforeStatus !== result.status) {
+      sim.events.unshift({
+        type: 'penalty-served',
+        at: sim.time,
+        penaltyId: result.id,
+        driverId: result.driverId,
+        serviceType: result.serviceType,
+        serviceContext: 'pit-stop',
+      });
+    }
+  });
+  stop.penaltyServiceRemaining = 0;
+  stop.serviceRemaining = 0;
+  sim.events.unshift({
+    type: 'pit-penalty-service-complete',
+    at: sim.time,
+    carId: car.id,
+    penaltyIds: servedIds,
+  });
+  beginTireService(sim, car);
+}
+
+export function getPitServicePenalties(sim, driverId) {
+  return sim.penalties.filter((penalty) => (
+    penalty.driverId === driverId && isPenaltyPitServiceable(penalty)
+  ));
+}

package/src/simulation/pit/pitQueue.js

@@ -0,0 +1,55 @@
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import { createRoute, routePoint } from './pitRouting.js';
+import { PIT_QUEUE_RELEASE_SPEED } from './pitServiceConstants.js';
+import { getPitBoxRaceDistance } from './pitOccupancy.js';
+
+export function beginPitQueue(sim, car, box) {
+  const stop = car.pitStop;
+  if (!stop || !box?.queuePoint) return false;
+  stop.status = 'queued';
+  stop.phase = 'queue';
+  stop.route = null;
+  stop.routeProgress = 0;
+  stop.queueingForService = false;
+  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,
+  });
+  return true;
+}
+
+export function releasePitQueue(sim, car, box, { fromCurrent = false } = {}) {
+  const stop = car.pitStop;
+  if (!stop || !box?.center) return false;
+  const route = createRoute([
+    ...(fromCurrent ? [routePoint(car, car.heading, { limiterActive: true })] : []),
+    routePoint(box.queuePoint, sim.track.pitLane.mainLane.heading, { limiterActive: true }),
+    routePoint(box.center, sim.track.pitLane.mainLane.heading, { limiterActive: true }),
+  ]);
+  stop.status = 'entering';
+  stop.phase = 'queue-release';
+  stop.queueingForService = false;
+  stop.route = route;
+  stop.routeProgress = 0;
+  stop.routeStartRaceDistance = fromCurrent
+    ? car.raceDistance ?? getPitBoxRaceDistance(sim, stop, {
+        ...box,
+        distanceAlongLane: box.queueDistanceAlongLane ?? box.distanceAlongLane,
+      })
+    : getPitBoxRaceDistance(sim, stop, {
+        ...box,
+        distanceAlongLane: box.queueDistanceAlongLane ?? box.distanceAlongLane,
+      });
+  stop.routeEndRaceDistance = getPitBoxRaceDistance(sim, stop, box);
+  return true;
+}
+
+export { PIT_QUEUE_RELEASE_SPEED };

package/src/simulation/pit/pitRouteMovement.js

@@ -0,0 +1,160 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { kphToSimSpeed, metersToSimUnits } from '../units.js';
+import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import {
+  distanceToNextLimiterSegment,
+  nearestDistanceOnRoute,
+  routeLimiterActiveAt,
+  sampleRoute,
+} from './pitRouting.js';
+import { completePitPenaltyService } from './pitPenaltyService.js';
+import { completePitService } from './pitTireService.js';
+import { getPitBoxRaceDistance, getPitStopBox } from './pitOccupancy.js';
+import {
+  PIT_BOX_STOP_SPEED,
+  PIT_ENTRY_BOX_CAPTURE_DISTANCE,
+  PIT_ENTRY_CONNECTOR_OVERSPEED_KPH,
+  PIT_LIMITER_APPROACH_SPEED_SLOPE,
+  PIT_LIMITER_BRAKE_DISTANCE,
+  PIT_QUEUE_CAPTURE_DISTANCE,
+  PIT_QUEUE_CAPTURE_SPEED,
+  PIT_QUEUE_RELEASE_FINISH_DISTANCE,
+  PIT_QUEUE_RELEASE_SPEED,
+  PIT_ROUTE_FINISH_DISTANCE,
+  pointDistance,
+} from './pitServiceConstants.js';
+
+export function applyPitRoutePosition(sim, car, delta) {
+  const stop = car.pitStop;
+  if (!stop?.route) return false;
+  const speedLimit = kphToSimSpeed(sim.rules.modules?.pitStops?.pitLaneSpeedLimitKph ?? 80);
+  const route = stop.route;
+  if (stop.phase === 'queue-release') {
+    const nextProgress = Math.min(route.length, (stop.routeProgress ?? 0) + PIT_QUEUE_RELEASE_SPEED * delta);
+    const point = sampleRoute(route, nextProgress);
+    if (!point) return false;
+    const previousHeading = car.heading;
+    car.previousX = car.x;
+    car.previousY = car.y;
+    car.previousHeading = car.heading;
+    car.x = point.x;
+    car.y = point.y;
+    car.heading = point.heading ?? sim.track.pitLane.mainLane.heading;
+    car.speed = PIT_QUEUE_RELEASE_SPEED;
+    car.throttle = 0.32;
+    car.brake = 0;
+    car.yawRate = normalizeAngle(car.heading - previousHeading) / Math.max(delta, 1e-6);
+    car.steeringAngle = clamp(
+      Math.atan((car.yawRate * VEHICLE_LIMITS.wheelbase) / Math.max(car.speed, 1)),
+      -VEHICLE_LIMITS.maxSteer,
+      VEHICLE_LIMITS.maxSteer,
+    );
+    car.turnRadius = Math.abs(car.yawRate) < 0.001 ? Infinity : car.speed / Math.abs(car.yawRate);
+    stop.routeProgress = nextProgress;
+    const routeAmount = route.length > 0 ? stop.routeProgress / route.length : 1;
+    car.raceDistance = stop.routeStartRaceDistance +
+      (stop.routeEndRaceDistance - stop.routeStartRaceDistance) * routeAmount;
+    applyWheelSurfaceState(car, sim.track);
+    car.progress = car.trackState.distance;
+    car.lap = sim.computeLap(car.raceDistance);
+    return route.length - stop.routeProgress <= PIT_QUEUE_RELEASE_FINISH_DISTANCE;
+  }
+  stop.routeProgress = clamp(nearestDistanceOnRoute(route, car, stop.routeProgress ?? 0), 0, route.length);
+  const routeEnd = route.points.at(-1);
+  const limiterActive = routeLimiterActiveAt(route, stop.routeProgress);
+  let targetSpeed = limiterActive
+    ? Math.min(speedLimit, VEHICLE_LIMITS.maxSpeed)
+    : Math.min(kphToSimSpeed(150), VEHICLE_LIMITS.maxSpeed);
+  if (!limiterActive && stop.status === 'entering') {
+    targetSpeed = Math.min(targetSpeed, speedLimit + kphToSimSpeed(PIT_ENTRY_CONNECTOR_OVERSPEED_KPH));
+    const distanceToLimiter = distanceToNextLimiterSegment(route, stop.routeProgress);
+    if (distanceToLimiter < PIT_LIMITER_BRAKE_DISTANCE) {
+      targetSpeed = Math.min(
+        targetSpeed,
+        speedLimit + Math.max(0, distanceToLimiter * PIT_LIMITER_APPROACH_SPEED_SLOPE),
+      );
+    }
+  }
+  if (stop.status === 'entering') {
+    const remainingBefore = Math.max(0, route.length - stop.routeProgress);
+    const captureDistance = stop.queueingForService ? PIT_QUEUE_CAPTURE_DISTANCE : PIT_ENTRY_BOX_CAPTURE_DISTANCE;
+    const brakeZone = stop.queueingForService ? metersToSimUnits(25) : metersToSimUnits(80);
+    if (remainingBefore < brakeZone) {
+      const brakingSlope = stop.queueingForService ? kphToSimSpeed(62) / metersToSimUnits(100) : kphToSimSpeed(24) / metersToSimUnits(100);
+      const captureSpeedFloor = stop.queueingForService ? kphToSimSpeed(42) : kphToSimSpeed(28);
+      const approachSpeed = remainingBefore > captureDistance
+        ? Math.max(captureSpeedFloor, remainingBefore * brakingSlope)
+        : remainingBefore * brakingSlope;
+      targetSpeed = Math.min(targetSpeed, clamp(approachSpeed, 0, speedLimit * 0.78));
+    }
+  }
+
+  const nextProgress = Math.min(route.length, stop.routeProgress + Math.max(0, targetSpeed) * delta);
+  const point = sampleRoute(route, nextProgress);
+  if (!point) return false;
+  const previousSpeed = car.speed;
+  const previousHeading = car.heading;
+  car.previousX = car.x;
+  car.previousY = car.y;
+  car.previousHeading = car.heading;
+  car.x = point.x;
+  car.y = point.y;
+  car.heading = point.heading ?? car.heading;
+  car.speed = targetSpeed;
+  car.throttle = limiterActive ? 0.28 : 0.46;
+  car.brake = targetSpeed < previousSpeed ? 0.4 : 0;
+  car.yawRate = normalizeAngle(car.heading - previousHeading) / Math.max(delta, 1e-6);
+  car.steeringAngle = clamp(
+    Math.atan((car.yawRate * VEHICLE_LIMITS.wheelbase) / Math.max(car.speed, 1)),
+    -VEHICLE_LIMITS.maxSteer,
+    VEHICLE_LIMITS.maxSteer,
+  );
+  car.turnRadius = Math.abs(car.yawRate) < 0.001 ? Infinity : car.speed / Math.abs(car.yawRate);
+  applyWheelSurfaceState(car, sim.track);
+  stop.routeProgress = nextProgress;
+  const routeAmount = route.length > 0 ? stop.routeProgress / route.length : 1;
+  car.raceDistance = stop.routeStartRaceDistance +
+    (stop.routeEndRaceDistance - stop.routeStartRaceDistance) * routeAmount;
+  car.progress = car.trackState.distance;
+  car.lap = sim.computeLap(car.raceDistance);
+  const remainingAfter = Math.max(0, route.length - stop.routeProgress);
+  if (stop.status === 'entering') {
+    const captureDistance = stop.queueingForService ? PIT_QUEUE_CAPTURE_DISTANCE : PIT_ENTRY_BOX_CAPTURE_DISTANCE;
+    const captureSpeed = stop.queueingForService ? PIT_QUEUE_CAPTURE_SPEED : PIT_BOX_STOP_SPEED;
+    return remainingAfter <= captureDistance &&
+      pointDistance(car, routeEnd) <= captureDistance &&
+      car.speed <= captureSpeed;
+  }
+  return remainingAfter <= PIT_ROUTE_FINISH_DISTANCE;
+}
+
+export function advancePitService(sim, car, delta) {
+  const stop = car.pitStop;
+  const box = getPitStopBox(sim, stop);
+  if (!box) return true;
+  if (stop.phase === 'penalty') {
+    stop.penaltyServiceRemaining = Math.max(0, (stop.penaltyServiceRemaining ?? 0) - delta);
+    stop.serviceRemaining = stop.penaltyServiceRemaining;
+  } else {
+    stop.serviceRemaining = Math.max(0, (stop.serviceRemaining ?? 0) - delta);
+  }
+  car.previousX = car.x;
+  car.previousY = car.y;
+  car.previousHeading = car.heading;
+  car.x = box.center.x;
+  car.y = box.center.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);
+  if (stop.phase === 'penalty' && stop.penaltyServiceRemaining <= 0) {
+    completePitPenaltyService(sim, car);
+  } else if (stop.serviceRemaining <= 0) {
+    completePitService(sim, car);
+  }
+  return true;
+}

package/src/simulation/pit/pitRouting.js

@@ -0,0 +1,319 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { metersToSimUnits } from '../units.js';
+import { nearestTrackState, offsetTrackPoint, pointAt } from '../track/trackModel.js';
+
+const PIT_ENTRY_APPROACH_DISTANCE = metersToSimUnits(250);
+
+function clonePointLike(point) {
+  if (!point) return point;
+  return { ...point };
+}
+
+function clonePointArray(points) {
+  return Array.isArray(points) ? points.map(clonePointLike) : points;
+}
+
+export function clonePitLaneModel(pitLane) {
+  if (!pitLane) return pitLane;
+  return {
+    ...pitLane,
+    entry: pitLane.entry ? {
+      ...pitLane.entry,
+      trackPoint: clonePointLike(pitLane.entry.trackPoint),
+      edgePoint: clonePointLike(pitLane.entry.edgePoint),
+      trackConnectPoint: clonePointLike(pitLane.entry.trackConnectPoint),
+      lanePoint: clonePointLike(pitLane.entry.lanePoint),
+      roadCenterline: clonePointArray(pitLane.entry.roadCenterline),
+      connector: clonePointArray(pitLane.entry.connector),
+    } : pitLane.entry,
+    exit: pitLane.exit ? {
+      ...pitLane.exit,
+      trackPoint: clonePointLike(pitLane.exit.trackPoint),
+      edgePoint: clonePointLike(pitLane.exit.edgePoint),
+      trackConnectPoint: clonePointLike(pitLane.exit.trackConnectPoint),
+      lanePoint: clonePointLike(pitLane.exit.lanePoint),
+      roadCenterline: clonePointArray(pitLane.exit.roadCenterline),
+      connector: clonePointArray(pitLane.exit.connector),
+    } : pitLane.exit,
+    mainLane: pitLane.mainLane ? {
+      ...pitLane.mainLane,
+      start: clonePointLike(pitLane.mainLane.start),
+      end: clonePointLike(pitLane.mainLane.end),
+      points: clonePointArray(pitLane.mainLane.points),
+    } : pitLane.mainLane,
+    workingLane: pitLane.workingLane ? {
+      ...pitLane.workingLane,
+      start: clonePointLike(pitLane.workingLane.start),
+      end: clonePointLike(pitLane.workingLane.end),
+      points: clonePointArray(pitLane.workingLane.points),
+    } : pitLane.workingLane,
+    fastLane: pitLane.fastLane ? { ...pitLane.fastLane } : pitLane.fastLane,
+    serviceNormal: clonePointLike(pitLane.serviceNormal),
+    boxes: Array.isArray(pitLane.boxes)
+      ? pitLane.boxes.map((box) => ({
+        ...box,
+        laneTarget: clonePointLike(box.laneTarget),
+        center: clonePointLike(box.center),
+        corners: clonePointArray(box.corners),
+      }))
+      : pitLane.boxes,
+    serviceAreas: Array.isArray(pitLane.serviceAreas)
+      ? pitLane.serviceAreas.map((area) => ({
+        ...area,
+        laneTarget: clonePointLike(area.laneTarget),
+        center: clonePointLike(area.center),
+        queuePoint: clonePointLike(area.queuePoint),
+        corners: clonePointArray(area.corners),
+        queueCorners: clonePointArray(area.queueCorners),
+        garageBoxIds: [...(area.garageBoxIds ?? [])],
+        pitCrew: area.pitCrew ? { ...area.pitCrew } : area.pitCrew,
+      }))
+      : pitLane.serviceAreas,
+    teams: Array.isArray(pitLane.teams)
+      ? pitLane.teams.map((team) => ({ ...team, boxIds: [...(team.boxIds ?? [])], pitCrew: team.pitCrew ? { ...team.pitCrew } : team.pitCrew }))
+      : pitLane.teams,
+  };
+}
+
+export function routePoint(point, heading = point?.heading, options = {}) {
+  if (!point) return null;
+  return {
+    x: point.x,
+    y: point.y,
+    heading,
+    limiterActive: Boolean(options.limiterActive ?? point.limiterActive),
+  };
+}
+
+export function offsetPitLanePoint(pitLane, point, lateralOffset) {
+  return {
+    ...point,
+    x: point.x + pitLane.serviceNormal.x * lateralOffset,
+    y: point.y + pitLane.serviceNormal.y * lateralOffset,
+    heading: pitLane.mainLane.heading,
+  };
+}
+
+export function pitMainLanePointAt(pitLane, distanceAlongLane, lateralOffset = 0) {
+  const amount = pitLane.mainLane.length > 0
+    ? clamp(distanceAlongLane / pitLane.mainLane.length, 0, 1)
+    : 0;
+  const point = {
+    x: pitLane.mainLane.start.x + (pitLane.mainLane.end.x - pitLane.mainLane.start.x) * amount,
+    y: pitLane.mainLane.start.y + (pitLane.mainLane.end.y - pitLane.mainLane.start.y) * amount,
+    heading: pitLane.mainLane.heading,
+  };
+  return offsetPitLanePoint(pitLane, point, lateralOffset);
+}
+
+export function pitDriveLaneOffset(pitLane) {
+  return pitLane.fastLane?.offset ?? 0;
+}
+
+function sameRoutePoint(first, second) {
+  return first && second && Math.hypot(first.x - second.x, first.y - second.y) < 0.001;
+}
+
+export function shiftPreviousRenderPose(car, dx, dy, dheading = 0) {
+  car.previousX = Number.isFinite(car.previousX) ? car.previousX + dx : car.x + dx;
+  car.previousY = Number.isFinite(car.previousY) ? car.previousY + dy : car.y + dy;
+  car.previousHeading = normalizeAngle(
+    (Number.isFinite(car.previousHeading) ? car.previousHeading : car.heading) + dheading,
+  );
+}
+
+export function pointDistance(first, second) {
+  if (!first || !second) return Infinity;
+  return Math.hypot(first.x - second.x, first.y - second.y);
+}
+
+export function createRoute(points) {
+  const routePoints = points
+    .filter(Boolean)
+    .map((point) => routePoint(point))
+    .filter(Boolean)
+    .reduce((deduped, point) => {
+      if (!sameRoutePoint(deduped.at(-1), point)) {
+        deduped.push(point);
+      } else if (point.limiterActive) {
+        deduped.at(-1).limiterActive = true;
+      }
+      return deduped;
+    }, []);
+  const segments = [];
+  let totalLength = 0;
+
+  for (let index = 0; index < routePoints.length - 1; index += 1) {
+    const start = routePoints[index];
+    const end = routePoints[index + 1];
+    const length = Math.hypot(end.x - start.x, end.y - start.y);
+    if (length <= 0.001) continue;
+    const heading = Math.atan2(end.y - start.y, end.x - start.x);
+    segments.push({
+      start,
+      end,
+      length,
+      heading,
+      startDistance: totalLength,
+      endDistance: totalLength + length,
+      limiterActive: Boolean(start.limiterActive && end.limiterActive),
+    });
+    totalLength += length;
+  }
+
+  let nextLimiterStartDistance = Infinity;
+  for (let index = segments.length - 1; index >= 0; index -= 1) {
+    const segment = segments[index];
+    if (segment.limiterActive) nextLimiterStartDistance = segment.startDistance;
+    segment.nextLimiterStartDistance = nextLimiterStartDistance;
+  }
+
+  return {
+    points: routePoints,
+    segments,
+    length: totalLength,
+    segmentCursor: 0,
+  };
+}
+
+function findRouteSegment(route, distanceAlong, endPadding = 0) {
+  if (!route?.segments?.length) return null;
+  const clampedDistance = clamp(distanceAlong, 0, route.length);
+  const segments = route.segments;
+  let index = clamp(Math.floor(route.segmentCursor ?? 0), 0, segments.length - 1);
+  let segment = segments[index];
+
+  if (
+    clampedDistance >= segment.startDistance - 0.001 &&
+    clampedDistance <= segment.endDistance - endPadding
+  ) {
+    return segment;
+  }
+
+  if (clampedDistance > segment.endDistance - endPadding) {
+    while (index < segments.length - 1 && clampedDistance > segments[index].endDistance - endPadding) {
+      index += 1;
+    }
+  } else {
+    while (index > 0 && clampedDistance < segments[index].startDistance - 0.001) {
+      index -= 1;
+    }
+  }
+
+  segment = segments[index];
+  if (
+    clampedDistance < segment.startDistance - 0.001 ||
+    clampedDistance > segment.endDistance - endPadding
+  ) {
+    segment = segments.find((candidate) => (
+      clampedDistance >= candidate.startDistance - 0.001 &&
+      clampedDistance <= candidate.endDistance - endPadding
+    )) ?? segments.at(-1);
+    index = segments.indexOf(segment);
+  }
+
+  route.segmentCursor = Math.max(0, index);
+  return segment;
+}
+
+export function sampleRoute(route, distanceAlong) {
+  if (!route?.segments?.length) return route?.points?.[0] ?? null;
+  const clampedDistance = clamp(distanceAlong, 0, route.length);
+  const segment = findRouteSegment(route, clampedDistance) ?? route.segments.at(-1);
+  const amount = clamp((clampedDistance - segment.startDistance) / segment.length, 0, 1);
+
+  return {
+    x: segment.start.x + (segment.end.x - segment.start.x) * amount,
+    y: segment.start.y + (segment.end.y - segment.start.y) * amount,
+    heading: segment.heading,
+    limiterActive: segment.limiterActive,
+  };
+}
+
+export function routeLimiterActiveAt(route, distanceAlong) {
+  if (!route?.segments?.length) return false;
+  const clampedDistance = clamp(distanceAlong, 0, route.length);
+  const segment = findRouteSegment(route, clampedDistance, 0.001) ?? route.segments.at(-1);
+  return Boolean(segment?.limiterActive);
+}
+
+export function distanceToNextLimiterSegment(route, distanceAlong) {
+  if (!route?.segments?.length) return Infinity;
+  const clampedDistance = clamp(distanceAlong, 0, route.length);
+  const segment = findRouteSegment(route, clampedDistance, 0.001);
+  if (!segment) return Infinity;
+  if (segment.limiterActive && segment.endDistance > clampedDistance + 0.001) return 0;
+  return Math.max(0, segment.nextLimiterStartDistance - clampedDistance);
+}
+
+function easeInOut(value) {
+  const amount = clamp(value, 0, 1);
+  return amount * amount * (3 - 2 * amount);
+}
+
+function projectPositionToSegment(position, segment) {
+  const dx = segment.end.x - segment.start.x;
+  const dy = segment.end.y - segment.start.y;
+  const lengthSquared = dx * dx + dy * dy;
+  const amount = lengthSquared > 0
+    ? clamp(((position.x - segment.start.x) * dx + (position.y - segment.start.y) * dy) / lengthSquared, 0, 1)
+    : 0;
+  const x = segment.start.x + dx * amount;
+  const y = segment.start.y + dy * amount;
+  const distanceSquared = (position.x - x) ** 2 + (position.y - y) ** 2;
+
+  return {
+    distanceAlong: segment.startDistance + segment.length * amount,
+    distanceSquared,
+  };
+}
+
+export function nearestDistanceOnRoute(route, position, previousDistance = 0) {
+  if (!route?.segments?.length) return 0;
+  let best = null;
+  const backtrackAllowance = metersToSimUnits(90);
+
+  route.segments.forEach((segment) => {
+    if (segment.endDistance < previousDistance - backtrackAllowance) return;
+    const projected = projectPositionToSegment(position, segment);
+    if (!best || projected.distanceSquared < best.distanceSquared) best = projected;
+  });
+
+  return clamp(best?.distanceAlong ?? previousDistance, 0, route.length);
+}
+
+export function createPitApproachPoints(track, car, pitLane, entryRaceDistance) {
+  const currentDistance = car.raceDistance ?? entryRaceDistance - PIT_ENTRY_APPROACH_DISTANCE;
+  const remaining = Math.max(0, entryRaceDistance - currentDistance);
+  const currentState = nearestTrackState(track, car, car.progress, { indexMode: 'legacy' });
+  const startOffset = currentState.inPitLane ? 0 : currentState.signedOffset ?? 0;
+  const entryConnectState = nearestTrackState(track, pitLane.entry.trackConnectPoint, pitLane.entry.trackDistance, {
+    indexMode: 'legacy',
+  });
+  const targetOffset = entryConnectState.signedOffset ?? 0;
+  const points = [routePoint(car, car.heading)];
+  const straightDistance = remaining > metersToSimUnits(14)
+    ? Math.min(remaining * 0.22, metersToSimUnits(42))
+    : 0;
+  if (straightDistance > metersToSimUnits(1)) {
+    points.push(routePoint({
+      x: car.x + Math.cos(car.heading) * straightDistance,
+      y: car.y + Math.sin(car.heading) * straightDistance,
+    }, car.heading));
+  }
+
+  const transitionDistance = Math.max(0, remaining - straightDistance);
+  const steps = Math.max(4, Math.ceil(Math.max(transitionDistance, PIT_ENTRY_APPROACH_DISTANCE * 0.45) / metersToSimUnits(74)));
+  for (let index = 1; index <= steps; index += 1) {
+    const amount = index / steps;
+    const distance = currentDistance + straightDistance + transitionDistance * amount;
+    const trackPoint = pointAt(track, distance);
+    const lateralAmount = easeInOut(amount);
+    const offset = startOffset + (targetOffset - startOffset) * lateralAmount;
+    const point = offsetTrackPoint(trackPoint, offset);
+    points.push(routePoint(point, trackPoint.heading));
+  }
+
+  points.push(routePoint(pitLane.entry.trackConnectPoint, pitLane.entry.trackPoint?.heading));
+  return points;
+}

package/src/simulation/pit/pitService.js

@@ -0,0 +1,41 @@
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import { normalizePitCrewStats } from './pitState.js';
+import { beginPitPenaltyService } from './pitPenaltyService.js';
+import { beginTireService } from './pitTireService.js';
+import { getPitBoxRaceDistance } from './pitOccupancy.js';
+
+export { normalizePitCrewStats };
+export {
+  getPitBoxRaceDistance,
+  getPitStopBox,
+  isPitServiceAreaOccupied,
+  isPitServiceBusy,
+  isPitServiceQueueOccupied,
+} from './pitOccupancy.js';
+export { beginPitQueue, releasePitQueue } from './pitQueue.js';
+export { calculatePitServiceProfile } from './pitServiceProfile.js';
+export { beginPitPenaltyService, completePitPenaltyService, getPitServicePenalties } from './pitPenaltyService.js';
+export { beginTireService, completePitService, finishPitExit } from './pitTireService.js';
+export { advancePitService, applyPitRoutePosition } from './pitRouteMovement.js';
+
+export function beginPitService(sim, car, box) {
+  const stop = car.pitStop;
+  stop.status = 'servicing';
+  stop.route = null;
+  stop.routeProgress = 0;
+  car.x = box.center.x;
+  car.y = box.center.y;
+  car.heading = sim.track.pitLane.mainLane.heading;
+  car.speed = 0;
+  car.throttle = 0;
+  car.brake = 1;
+  car.steeringAngle = 0;
+  car.yawRate = 0;
+  car.turnRadius = Infinity;
+  applyWheelSurfaceState(car, sim.track);
+  car.progress = car.trackState.distance;
+  car.raceDistance = getPitBoxRaceDistance(sim, stop, box);
+
+  if (beginPitPenaltyService(sim, car)) return;
+  beginTireService(sim, car);
+}