@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/simulation/vehicle/advancedVehiclePhysics.js

@@ -0,0 +1,127 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { SIM_UNITS_PER_METER, TOP_SPEED_SIM_UNITS_PER_SECOND } from '../units.js';
+import { ADVANCED_VEHICLE_MODEL as MODEL, ADVANCED_WHEELS, advancedWheelSurface, advancedDriveForce, advancedDragFactor } from './advancedVehicleModel.js';
+import { advancedNormalLoads, advancedTireForce } from './advancedTireForces.js';
+
+export function integrateAdvancedVehiclePhysics(car, controls, dt, { tireFactor, tireDegradationEnabled, maxSteer, steerRate }) {
+  if (!(dt > 0) || !Number.isFinite(dt)) return car;
+  if (!Number.isFinite(car.velocityX) || !Number.isFinite(car.velocityY)) {
+    car.velocityX = Math.cos(car.heading) * car.speed;
+    car.velocityY = Math.sin(car.heading) * car.speed;
+  }
+  const throttle = clamp(controls.throttle ?? 0, 0, 1);
+  const brake = clamp(controls.brake ?? 0, 0, 1);
+  const steeringTarget = clamp(controls.steering ?? 0, -maxSteer, maxSteer);
+  const steps = Math.ceil(dt / MODEL.maxIntegrationStep);
+  const h = dt / steps;
+  const initialVelocityX = car.velocityX / SIM_UNITS_PER_METER;
+  const initialVelocityY = car.velocityY / SIM_UNITS_PER_METER;
+  const initialHeading = car.heading;
+  let frontUsage = 0;
+  let rearUsage = 0;
+  let resistanceYawAcceleration = 0;
+  for (let step = 0; step < steps; step += 1) {
+    car.steeringAngle += clamp(steeringTarget - car.steeringAngle, -steerRate * h, steerRate * h);
+    const cos = Math.cos(car.heading);
+    const sin = Math.sin(car.heading);
+    const vx = car.velocityX / SIM_UNITS_PER_METER;
+    const vy = car.velocityY / SIM_UNITS_PER_METER;
+    const u = vx * cos + vy * sin;
+    const v = -vx * sin + vy * cos;
+    const speed = Math.hypot(vx, vy);
+    const yaw = car.yawRate ?? 0;
+    const loads = advancedNormalLoads(car, speed, car.longitudinalAcceleration ?? 0, car.lateralAcceleration ?? 0);
+    // The existing newton-valued power rating defines launch force. Above the
+    // crossover speed, the envelope is constant power instead of constant force.
+    const drive = throttle * advancedDriveForce(car, u);
+    let fx = 0;
+    let fy = 0;
+    let moment = 0;
+    let resistanceMoment = 0;
+    frontUsage = 0;
+    rearUsage = 0;
+    for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) {
+      const wheel = ADVANCED_WHEELS[index];
+      const { x, y } = wheel;
+      const steer = wheel.front ? car.steeringAngle : 0;
+      const cs = Math.cos(steer);
+      const sn = Math.sin(steer);
+      const wheelU = (u - yaw * y) * cs + (v + yaw * x) * sn;
+      const wheelV = -(u - yaw * y) * sn + (v + yaw * x) * cs;
+      const surface = advancedWheelSurface(car, wheel.id);
+      const engine = wheel.front ? 0 : drive / 2;
+      const brakeDemand = brake * car.brakeNewtons * (wheel.front ? MODEL.frontBrakeFraction : 1 - MODEL.frontBrakeFraction) / 2;
+      // Brake/static resistance cannot manufacture a reverse launch at rest.
+      const brakingDirection = Math.sign(wheelU || engine);
+      const longitudinalLever = x * sn - y * cs;
+      const inverseContactMass = 1 / car.mass + longitudinalLever ** 2 / (car.mass * MODEL.yawInertiaPerMass);
+      // Four simultaneous contacts share the stopping impulse. Include yaw
+      // inertia and share the budget between braking and rolling resistance;
+      // independently spending it twice would create motion near rest.
+      const stoppingBudget = Math.abs(wheelU) / (4 * h * inverseContactMass);
+      const braking = brakingDirection * Math.min(brakeDemand, stoppingBudget + engine);
+      const remainingBudget = Math.max(0, stoppingBudget - Math.max(0, (braking - engine) * Math.sign(wheelU)));
+      const rolling = Math.sign(wheelU) * Math.min(surface.rolling * loads[index], remainingBudget);
+      const nominalLoad = car.mass * MODEL.gravity * (wheel.front ? MODEL.frontWeightFraction : 1 - MODEL.frontWeightFraction) / 2;
+      const tire = advancedTireForce({
+        normalLoad: loads[index], nominalLoad, grip: car.tireGrip, tireFactor, surface,
+        longitudinalDemand: engine - braking, forwardVelocity: wheelU, lateralVelocity: wheelV,
+      });
+      const wheelFx = tire.longitudinal - rolling;
+      const bodyFx = wheelFx * cs - tire.lateral * sn;
+      const bodyFy = wheelFx * sn + tire.lateral * cs;
+      fx += bodyFx;
+      fy += bodyFy;
+      moment += x * bodyFy - y * bodyFx;
+      resistanceMoment += x * (-rolling * sn) - y * (-rolling * cs);
+      if (wheel.front) frontUsage = Math.max(frontUsage, tire.usage);
+      else rearUsage = Math.max(rearUsage, tire.usage);
+    }
+    const dragFactor = advancedDragFactor(car);
+    fx -= dragFactor * speed * u;
+    fy -= dragFactor * speed * v;
+    car.longitudinalAcceleration = fx / car.mass;
+    car.lateralAcceleration = fy / car.mass;
+    const ax = (fx * cos - fy * sin) / car.mass;
+    const ay = (fx * sin + fy * cos) / car.mass;
+    car.velocityX += ax * h * SIM_UNITS_PER_METER;
+    car.velocityY += ay * h * SIM_UNITS_PER_METER;
+    car.yawRate = yaw + moment / (car.mass * MODEL.yawInertiaPerMass) * h;
+    resistanceYawAcceleration = resistanceMoment / (car.mass * MODEL.yawInertiaPerMass);
+    car.heading = normalizeAngle(car.heading + car.yawRate * h);
+    car.speed = Math.hypot(car.velocityX, car.velocityY);
+    // Retain the package's supported top-speed envelope, including externally
+    // placed cars. Engine/drag balance determines normal acceleration below it.
+    if (car.speed > TOP_SPEED_SIM_UNITS_PER_SECOND) {
+      const scale = TOP_SPEED_SIM_UNITS_PER_SECOND / car.speed;
+      car.velocityX *= scale;
+      car.velocityY *= scale;
+      car.speed = TOP_SPEED_SIM_UNITS_PER_SECOND;
+    }
+    car.x += car.velocityX * h;
+    car.y += car.velocityY * h;
+  }
+  const ax = (car.velocityX / SIM_UNITS_PER_METER - initialVelocityX) / dt;
+  const ay = (car.velocityY / SIM_UNITS_PER_METER - initialVelocityY) / dt;
+  car.longitudinalAcceleration = ax * Math.cos(initialHeading) + ay * Math.sin(initialHeading);
+  car.lateralAcceleration = -ax * Math.sin(initialHeading) + ay * Math.cos(initialHeading);
+  car.longitudinalG = car.longitudinalAcceleration / MODEL.gravity;
+  car.lateralG = car.lateralAcceleration / MODEL.gravity;
+  car.gripUsage = Math.max(frontUsage, rearUsage);
+  car.slipAngleRadians = car.speed > 0.01 ? normalizeAngle(Math.atan2(car.velocityY, car.velocityX) - car.heading) : 0;
+  car.tractionLimited = car.gripUsage > 1;
+  car.stabilityState = Math.abs(car.slipAngleRadians) > 0.35 ? 'spin-risk'
+    : rearUsage > 1 && rearUsage > frontUsage * 1.15 ? 'oversteer'
+      : frontUsage > 1 ? 'understeer' : 'stable';
+  car.wheelDragYawRate = resistanceYawAcceleration * dt;
+  car.steerSaturation = 1 / Math.max(1, frontUsage);
+  car.turnRadius = Math.abs(car.yawRate) < 0.001 ? Infinity : car.speed / Math.abs(car.yawRate);
+  car.throttle = throttle;
+  car.brake = brake;
+  if (tireDegradationEnabled !== false) {
+    const care = clamp(Number(car.tireCare) || 1, 0.45, 1.8);
+    const wear = (0.035 + Math.abs(car.lateralG) * 0.11 + brake * 0.07 + throttle * 0.025 + Math.max(0, car.gripUsage - 1) * 0.03) / care;
+    car.tireEnergy = clamp((car.tireEnergy ?? 100) - wear * dt, 1, 100);
+  }
+  return car;
+}

package/src/simulation/vehicle/contactResolution.js

@@ -6,8 +6,9 @@ import {
 } from '../collisionGeometry.js';
 import { canCollide, isCollidable } from '../participants/participantInteractions.js';
 import { clamp, normalizeAngle } from '../simMath.js';
-import { VEHICLE_LIMITS } from './vehiclePhysics.js';
-import { shiftPreviousRenderPose } from '../pit/pitRouting.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode } from './vehiclePhysics.js';
+import { shiftPreviousRenderPose } from './vehicleKinematics.js';
+import { applyAdvancedContactResponse } from './advancedContactResponse.js';
 
 const MAX_COLLISION_CORRECTION = 4.5;
 
@@ -113,23 +114,29 @@ export function resolveCollisionsForSimulation(sim) {
         second.y += secondCorrectionY;
       }
 
-      if (oneCarFixed) {
-        if (!firstPitControlled) dampPitContactVelocity(first, 0.985, sim.physicsMode === 'advanced');
-        if (!secondPitControlled) dampPitContactVelocity(second, 0.985, sim.physicsMode === 'advanced');
+      const advancedPhysics = isSimulatorPhysicsMode(sim.physicsMode);
+      if (advancedPhysics) {
+        applyContactVelocityResponse(sim, first, second, collision.axis, {
+          firstFixed: firstPitControlled,
+          secondFixed: secondPitControlled,
+        });
+      } else if (oneCarFixed) {
+        if (!firstPitControlled) dampPitContactVelocity(first, 0.985, isSimulatorPhysicsMode(sim.physicsMode));
+        if (!secondPitControlled) dampPitContactVelocity(second, 0.985, isSimulatorPhysicsMode(sim.physicsMode));
       } else {
         applyContactVelocityResponse(sim, first, second, collision.axis);
       }
 
-      const yawNudge = clamp(collision.depth * 0.0025, 0.008, 0.035);
+      const yawNudge = advancedPhysics ? 0 : clamp(collision.depth * 0.0025, 0.008, 0.035);
       const freshContact = first.contactCooldown <= 0 && second.contactCooldown <= 0;
       const firstHeadingCorrection = firstPitControlled ? 0 : -collision.axis.y * yawNudge;
       const secondHeadingCorrection = secondPitControlled ? 0 : collision.axis.y * yawNudge;
       if (!firstPitControlled) {
-        first.heading = normalizeAngle(first.heading + firstHeadingCorrection);
+        if (!advancedPhysics) first.heading = normalizeAngle(first.heading + firstHeadingCorrection);
         shiftPreviousRenderPose(first, firstCorrectionX, firstCorrectionY, firstHeadingCorrection);
       }
       if (!secondPitControlled) {
-        second.heading = normalizeAngle(second.heading + secondHeadingCorrection);
+        if (!advancedPhysics) second.heading = normalizeAngle(second.heading + secondHeadingCorrection);
         shiftPreviousRenderPose(second, secondCorrectionX, secondCorrectionY, secondHeadingCorrection);
       }
       first.contactCooldown = 1;
@@ -166,8 +173,15 @@ export function resolveCollisionsForSimulation(sim) {
 
 export function applyContactVelocityResponse(sim, first, second, axis, options = {}) {
   recordContactVelocityResponse(options.stats);
+  if (isSimulatorPhysicsMode(sim.physicsMode)) {
+    applyAdvancedContactResponse(first, second, axis, {
+      restitution: sim.rules.collisionRestitution,
+      firstFixed: options.firstFixed,
+      secondFixed: options.secondFixed,
+    });
+    return;
+  }
   if (
-    sim.physicsMode === 'advanced' ||
     Number.isFinite(first.velocityX) ||
     Number.isFinite(second.velocityX)
   ) {

package/src/simulation/vehicle/mainTrackWheelSurface.js

@@ -37,17 +37,6 @@ export function wheelOutsideFromOffsets(minimumSignedOffset, maximumSignedOffset
   };
 }
 
-export function analyticWheelState(patch, centerState, track, trackLimit) {
-  return writeAnalyticWheelStateWithProjectedHalfWidth(
-    {},
-    patch,
-    centerState,
-    track,
-    trackLimit,
-    analyticWheelProjectedHalfWidth(patch, centerState),
-  );
-}
-
 export function writeAnalyticWheelState(target, patch, centerState, track, trackLimit) {
   return writeAnalyticWheelStateWithProjectedHalfWidth(
     target,
@@ -87,7 +76,7 @@ export function writeAnalyticWheelStateWithProjectedHalfWidth(
   const state = sampledStates.length === 1 ? (sampledStates[0] ?? {}) : {};
   sampledStates.length = 1;
   sampledStates[0] = state;
-  writeStateFromSignedOffset(state, centerState, track, signedOffset);
+  writeStateFromSignedOffset(state, track, signedOffset);
 
   target.id = patch.id;
   target.x = patch.center.x;
@@ -107,7 +96,7 @@ export function writeAnalyticWheelStateWithProjectedHalfWidth(
   return target;
 }
 
-function writeStateFromSignedOffset(target, centerState, track, signedOffset) {
+function writeStateFromSignedOffset(target, track, signedOffset) {
   const crossTrackError = Math.abs(signedOffset);
   const surface = mainTrackSurface(track, crossTrackError);
   target.signedOffset = signedOffset;

package/src/simulation/vehicle/pitWheelSurface.js

@@ -38,10 +38,6 @@ export function canSkipConnectorPitChecks(track, geometry, centerState, epsilon
   return true;
 }
 
-export function pitPatchOffsetRange(patch, centerState) {
-  return patchPitOffsetRange(patch, centerState);
-}
-
 export function pitPatchInsideRoad(patch, centerState, epsilon = 0.001) {
   const roadWidth = Number(centerState?.pitLaneRoadWidth);
   if (!centerState?.inPitLane || !Number.isFinite(roadWidth) || roadWidth <= 0) return false;
@@ -50,14 +46,6 @@ export function pitPatchInsideRoad(patch, centerState, epsilon = 0.001) {
   return range.minimum >= -halfRoadWidth - epsilon && range.maximum <= halfRoadWidth + epsilon;
 }
 
-export function pitPatchOverlapsRoad(patch, centerState, epsilon = 0.001) {
-  const roadWidth = Number(centerState?.pitLaneRoadWidth);
-  if (!centerState?.inPitLane || !Number.isFinite(roadWidth) || roadWidth <= 0) return false;
-  const halfRoadWidth = roadWidth / 2;
-  const range = patchPitOffsetRange(patch, centerState);
-  return range.minimum <= halfRoadWidth + epsilon && range.maximum >= -halfRoadWidth - epsilon;
-}
-
 export function writeAnalyticPitWheelState(target, patch, centerState) {
   const range = patchPitOffsetRange(patch, centerState);
   const signedOffset = centerState.mainTrackSignedOffset ?? centerState.signedOffset;

package/src/simulation/vehicle/runoffResponse.js

@@ -1,3 +1,4 @@
+import { clearCurrentDrsState } from '../timing/drsState.js';
 import {
   VEHICLE_GEOMETRY,
   vehicleAxes,
@@ -89,10 +90,7 @@ function destroyCarOnBarrier(sim, car) {
   car.outOfRace = true;
   markCarDnf(sim, car, { reason: 'barrier' });
   car.canAttack = false;
-  car.drsActive = false;
-  car.drsEligible = false;
-  car.drsZoneId = null;
-  car.drsZoneEnabled = false;
+  clearCurrentDrsState(car);
   freezeBarrierMotion(car, sim.physicsMode);
   sim.events.unshift({
     type: 'car-destroyed',

package/src/simulation/vehicle/sampledWheelSurface.js

@@ -0,0 +1,266 @@
+import { ensureOrientedRectCorners } from './vehicleGeometry.js';
+import { analyticWheelProjectedHalfWidth, wheelFullyOutside, writeAnalyticWheelState } from './mainTrackWheelSurface.js';
+import { pitPatchInsideRoad, writeAnalyticPitWheelState } from './pitWheelSurface.js';
+import { worstState } from './surfacePriority.js';
+import { resetWheelSummary, recordWheelSummary, finishWheelSummary } from './wheelSurfaceSummary.js';
+import {
+  nearestTrackStateForCar,
+  queryHintedTrackStateForCar,
+  queryLocalSegmentTrackProjectionsForCar,
+  queryLocalSegmentTrackStateForCar,
+  queryLocalSegmentTrackStatesForCar,
+} from '../track/trackStatePolicy.js';
+
+const STRAIGHT_CONNECTOR_CURVATURE_EPSILON = 1e-8;
+const MAIN_TRACK_PATCH_MARGIN = 0.001;
+
+function writeFullWheelState(target, patch, sampledStates, trackLimit) {
+  const state = worstState(sampledStates);
+  let minimumSignedOffset = Infinity;
+  let maximumSignedOffset = -Infinity;
+  for (let index = 0; index < sampledStates.length; index += 1) {
+    const signedOffset = sampledStates[index].signedOffset;
+    if (signedOffset < minimumSignedOffset) minimumSignedOffset = signedOffset;
+    if (signedOffset > maximumSignedOffset) maximumSignedOffset = signedOffset;
+  }
+  const outside = wheelFullyOutside(sampledStates, trackLimit);
+
+  target.id = patch.id;
+  target.x = patch.center.x;
+  target.y = patch.center.y;
+  target.signedOffset = state.signedOffset;
+  target.crossTrackError = state.crossTrackError;
+  target.surface = state.surface;
+  target.onTrack = Boolean(state.onTrack);
+  target.inPitLane = Boolean(state.inPitLane);
+  target.pitLanePart = state.pitLanePart ?? null;
+  target.pitBoxId = state.pitBoxId ?? null;
+  target.minimumSignedOffset = minimumSignedOffset;
+  target.maximumSignedOffset = maximumSignedOffset;
+  target.fullyOutsideWhiteLine = outside.fullyOutsideWhiteLine;
+  target.outsideSide = outside.outsideSide;
+  target.sampledStates = sampledStates;
+  return target;
+}
+
+function queryConnectorSampleState(track, car, point, progressHint, centerState) {
+  const baseSegmentId = Number.isInteger(centerState?.segmentId) ? centerState.segmentId : null;
+  if (baseSegmentId == null) return queryHintedTrackStateForCar(track, car, point, progressHint);
+  return queryLocalSegmentTrackStateForCar(
+    track,
+    car,
+    point,
+    baseSegmentId,
+    progressHint,
+    { skipPitOverrideInsideMainRoad: true },
+  );
+}
+
+function sampleFullConnectorPatchInto(sampledStates, patch, track, car, progressHint, centerState) {
+  const corners = ensureOrientedRectCorners(patch);
+  sampledStates.length = 1 + corners.length;
+  sampledStates[0] = queryConnectorSampleState(track, car, patch.center, progressHint, centerState);
+  for (let index = 0; index < corners.length; index += 1) {
+    sampledStates[index + 1] = queryConnectorSampleState(track, car, corners[index], progressHint, centerState);
+  }
+  return sampledStates;
+}
+
+function sampleFullNearestPatchInto(sampledStates, patch, track, car) {
+  const corners = ensureOrientedRectCorners(patch);
+  sampledStates.length = 1 + corners.length;
+  sampledStates[0] = nearestTrackStateForCar(track, car, patch.center, car.progress);
+  for (let index = 0; index < corners.length; index += 1) {
+    sampledStates[index + 1] = nearestTrackStateForCar(track, car, corners[index], car.progress);
+  }
+  return sampledStates;
+}
+
+function writeConnectorWheelState(target, {
+  patch,
+  wheelCenterState,
+  centerState,
+  car,
+  track,
+  trackLimit,
+  progressHint,
+  sampledStates,
+}) {
+  if (!wheelCenterState) {
+    return writeAnalyticWheelState(target, patch, centerState, track, trackLimit);
+  }
+  if (!wheelCenterState.inPitLane) {
+    return writeAnalyticWheelState(target, patch, wheelCenterState, track, trackLimit);
+  }
+  if (pitPatchInsideRoad(patch, wheelCenterState)) {
+    return writeAnalyticPitWheelState(target, patch, wheelCenterState);
+  }
+  sampleFullConnectorPatchInto(sampledStates, patch, track, car, progressHint, centerState);
+  return writeFullWheelState(target, patch, sampledStates, trackLimit);
+}
+
+function collectPatchCenters(target, patches) {
+  target.length = patches.length;
+  for (let index = 0; index < patches.length; index += 1) {
+    target[index] = patches[index].center;
+  }
+  return target;
+}
+
+export function connectorWheelCenterStates(
+  track,
+  car,
+  patches,
+  centerState,
+  progressHint,
+  scratchStates = null,
+  scratchProjections = null,
+  scratchPositions = null,
+) {
+  const baseSegmentId = Number.isInteger(centerState?.segmentId) ? centerState.segmentId : null;
+  const states = scratchStates ?? new Array(patches.length);
+  states.length = patches.length;
+  if (baseSegmentId == null) {
+    for (let index = 0; index < patches.length; index += 1) {
+      states[index] = queryHintedTrackStateForCar(track, car, patches[index].center, progressHint);
+    }
+    return states;
+  }
+  const positions = collectPatchCenters(scratchPositions ?? new Array(patches.length), patches);
+  return queryLocalSegmentTrackStatesForCar(
+    track,
+    car,
+    positions,
+    baseSegmentId,
+    progressHint,
+    {
+      radius: 2,
+      skipPitOverrideInsideMainRoad: true,
+      target: states,
+      projections: scratchProjections,
+    },
+  );
+}
+
+export function connectorWheelCenterProjections(
+  track,
+  car,
+  patches,
+  centerState,
+  progressHint,
+  scratchProjections = null,
+  scratchPositions = null,
+) {
+  const baseSegmentId = Number.isInteger(centerState?.segmentId) ? centerState.segmentId : null;
+  if (baseSegmentId == null) return null;
+  const positions = collectPatchCenters(scratchPositions ?? new Array(patches.length), patches);
+  return queryLocalSegmentTrackProjectionsForCar(
+    track,
+    car,
+    positions,
+    baseSegmentId,
+    progressHint,
+    {
+      radius: 2,
+      projections: scratchProjections,
+    },
+  );
+}
+
+export function canUseStraightConnectorMainTrackAnalytic(track, geometry, centerState, trackLimit) {
+  if (
+    !track ||
+    !geometry?.contactPatches?.length ||
+    !centerState ||
+    centerState.inPitLane ||
+    !centerState.onTrack ||
+    Math.abs(centerState.curvature ?? 0) > STRAIGHT_CONNECTOR_CURVATURE_EPSILON
+  ) {
+    return false;
+  }
+
+  for (let index = 0; index < geometry.contactPatches.length; index += 1) {
+    const patch = geometry.contactPatches[index];
+    const wheelCenterOffset =
+      (patch.center.x - centerState.x) * centerState.normalX +
+      (patch.center.y - centerState.y) * centerState.normalY;
+    const projectedHalfWidth = analyticWheelProjectedHalfWidth(patch, centerState);
+    if (
+      wheelCenterOffset - projectedHalfWidth < -trackLimit - MAIN_TRACK_PATCH_MARGIN ||
+      wheelCenterOffset + projectedHalfWidth > trackLimit + MAIN_TRACK_PATCH_MARGIN
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function writeConnectorWheelStatesWithSummary({
+  targetWheels,
+  patches,
+  wheelCenterStates,
+  centerState,
+  car,
+  track,
+  trackLimit,
+  progressHint,
+  sampledStatePools,
+  summaryTarget = null,
+}) {
+  const summary = resetWheelSummary(summaryTarget ?? {});
+  for (let index = 0; index < patches.length; index += 1) {
+    const sampledStates = sampledStatePools[index] ?? [];
+    sampledStatePools[index] = sampledStates;
+    const wheel = writeConnectorWheelState(targetWheels[index], {
+      patch: patches[index],
+      wheelCenterState: wheelCenterStates[index],
+      centerState,
+      car,
+      track,
+      trackLimit,
+      progressHint,
+      sampledStates,
+    });
+    recordWheelSummary(summary, wheel);
+  }
+  finishWheelSummary(summary, track, trackLimit);
+
+  return {
+    wheels: targetWheels,
+    effectiveSurface: summary.effectiveSurface,
+    representative: summary.representative,
+    trackLimits: summary.trackLimits,
+    allOnTrackOrPit: summary.allOnTrackOrPit,
+    allInPitLane: summary.allInPitLane,
+  };
+}
+
+export function writeNearestSampledWheelStatesWithSummary({
+  targetWheels,
+  patches,
+  car,
+  track,
+  trackLimit,
+  sampledStatePools,
+  summaryTarget = null,
+}) {
+  const summary = resetWheelSummary(summaryTarget ?? {});
+  for (let index = 0; index < patches.length; index += 1) {
+    const patch = patches[index];
+    const sampledStates = sampledStatePools[index] ?? [];
+    sampledStatePools[index] = sampledStates;
+    sampleFullNearestPatchInto(sampledStates, patch, track, car);
+    const wheel = writeFullWheelState(targetWheels[index], patch, sampledStates, trackLimit);
+    recordWheelSummary(summary, wheel);
+  }
+  finishWheelSummary(summary, track, trackLimit);
+
+  return {
+    wheels: targetWheels,
+    effectiveSurface: summary.effectiveSurface,
+    representative: summary.representative,
+    trackLimits: summary.trackLimits,
+    allOnTrackOrPit: summary.allOnTrackOrPit,
+    allInPitLane: summary.allInPitLane,
+  };
+}