@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/simulation/pit/pitRouteMovement.js

@@ -0,0 +1,167 @@
+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 { syncPitCarKinematics } from './pitKinematics.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);
+    syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
+    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);
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
+  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;
+  car.steeringAngle = 0;
+  car.yawRate = 0;
+  car.turnRadius = Infinity;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
+  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,43 @@
+import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
+import { normalizePitCrewStats } from './pitState.js';
+import { beginPitPenaltyService } from './pitPenaltyService.js';
+import { beginTireService } from './pitTireService.js';
+import { syncPitCarKinematics } from './pitKinematics.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;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
+  applyWheelSurfaceState(car, sim.track);
+  car.progress = car.trackState.distance;
+  car.raceDistance = getPitBoxRaceDistance(sim, stop, box);
+
+  if (beginPitPenaltyService(sim, car)) return;
+  beginTireService(sim, car);
+}

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,
+  };
+}