@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/simulation/vehicle/contactResolution.js

@@ -0,0 +1,181 @@
+import { buildCollisionCandidatePairs, detectVehicleCollision } 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';
+
+const MAX_COLLISION_CORRECTION = 4.5;
+
+function isPitPositionControlledCar(car) {
+  const status = car?.pitStop?.status;
+  return status === 'entering' || status === 'queued' || status === 'servicing' || status === 'exiting';
+}
+
+function forwardVector(car) {
+  return { x: Math.cos(car.heading), y: Math.sin(car.heading) };
+}
+
+function velocityVector(car) {
+  if (Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)) {
+    return { x: car.velocityX, y: car.velocityY };
+  }
+  const forward = forwardVector(car);
+  return { x: forward.x * car.speed, y: forward.y * car.speed };
+}
+
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y;
+}
+
+function applyVelocityVector(car, velocity) {
+  const speed = clamp(Math.hypot(velocity.x, velocity.y), 0, VEHICLE_LIMITS.maxSpeed);
+  if (speed <= 0) {
+    car.velocityX = 0;
+    car.velocityY = 0;
+    car.speed = 0;
+    return;
+  }
+  const scale = speed / Math.max(1e-9, Math.hypot(velocity.x, velocity.y));
+  car.velocityX = velocity.x * scale;
+  car.velocityY = velocity.y * scale;
+  car.speed = speed;
+}
+
+export function resolveCollisionsForSimulation(sim) {
+  const collidableCars = sim.cars.filter(isCollidable);
+  if (collidableCars.length < 2) return;
+  const reportedContacts = new Set();
+
+  for (let pass = 0; pass < 3; pass += 1) {
+    const candidates = buildCollisionCandidatePairs(collidableCars, { trackLength: sim.track.length });
+    for (const [first, second] of candidates) {
+      if (!canCollide(first, second)) continue;
+      const collision = detectVehicleCollision(first, second);
+      if (!collision) continue;
+      const firstPitControlled = isPitPositionControlledCar(first);
+      const secondPitControlled = isPitPositionControlledCar(second);
+      if (firstPitControlled && secondPitControlled) continue;
+      const stewardCollision = {
+        ...collision,
+        trackLength: sim.track.length,
+      };
+      const oneCarFixed = firstPitControlled || secondPitControlled;
+
+      const correction = Math.min(
+        (oneCarFixed ? collision.depth : collision.depth / 2) + 0.65,
+        MAX_COLLISION_CORRECTION,
+      );
+      const firstCorrectionX = firstPitControlled ? 0 : -collision.axis.x * correction;
+      const firstCorrectionY = firstPitControlled ? 0 : -collision.axis.y * correction;
+      const secondCorrectionX = secondPitControlled ? 0 : collision.axis.x * correction;
+      const secondCorrectionY = secondPitControlled ? 0 : collision.axis.y * correction;
+      if (!firstPitControlled) {
+        first.x += firstCorrectionX;
+        first.y += firstCorrectionY;
+      }
+      if (!secondPitControlled) {
+        second.x += secondCorrectionX;
+        second.y += secondCorrectionY;
+      }
+
+      if (oneCarFixed) {
+        if (!firstPitControlled) dampPitContactVelocity(first, 0.985, sim.physicsMode === 'simulator');
+        if (!secondPitControlled) dampPitContactVelocity(second, 0.985, sim.physicsMode === 'simulator');
+      } else {
+        applyContactVelocityResponse(sim, first, second, collision.axis);
+      }
+
+      const yawNudge = 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);
+        shiftPreviousRenderPose(first, firstCorrectionX, firstCorrectionY, firstHeadingCorrection);
+      }
+      if (!secondPitControlled) {
+        second.heading = normalizeAngle(second.heading + secondHeadingCorrection);
+        shiftPreviousRenderPose(second, secondCorrectionX, secondCorrectionY, secondHeadingCorrection);
+      }
+      first.contactCooldown = 1;
+      second.contactCooldown = 1;
+
+      const contactKey = `${first.id}:${second.id}`;
+      if (freshContact && pass === 0 && !reportedContacts.has(contactKey)) {
+        reportedContacts.add(contactKey);
+        sim.events.unshift({
+          type: 'contact',
+          at: sim.time,
+          carId: first.id,
+          otherCarId: second.id,
+          firstShapeId: collision.firstShapeId,
+          secondShapeId: collision.secondShapeId,
+          contactType: collision.contactType,
+          depth: collision.depth,
+          timeOfImpact: collision.timeOfImpact,
+        });
+        sim.reviewCollision(first, second, stewardCollision);
+      }
+    }
+  }
+}
+
+export function applyContactVelocityResponse(sim, first, second, axis) {
+  if (
+    sim.physicsMode === 'simulator' ||
+    Number.isFinite(first.velocityX) ||
+    Number.isFinite(second.velocityX)
+  ) {
+    const firstVelocity = velocityVector(first);
+    const secondVelocity = velocityVector(second);
+    const relativeNormalVelocity = dot({
+      x: secondVelocity.x - firstVelocity.x,
+      y: secondVelocity.y - firstVelocity.y,
+    }, axis);
+
+    if (relativeNormalVelocity < 0) {
+      const impulse = clamp(-relativeNormalVelocity * (0.34 + sim.rules.collisionRestitution), 0, 16);
+      firstVelocity.x -= axis.x * impulse;
+      firstVelocity.y -= axis.y * impulse;
+      secondVelocity.x += axis.x * impulse;
+      secondVelocity.y += axis.y * impulse;
+    }
+
+    applyVelocityVector(first, {
+      x: firstVelocity.x * 0.997,
+      y: firstVelocity.y * 0.997,
+    });
+    applyVelocityVector(second, {
+      x: secondVelocity.x * 0.997,
+      y: secondVelocity.y * 0.997,
+    });
+    return;
+  }
+
+  const firstForward = forwardVector(first);
+  const secondForward = forwardVector(second);
+  const firstNormal = dot(firstForward, axis);
+  const secondNormal = dot(secondForward, axis);
+  const relativeNormalVelocity = second.speed * secondNormal - first.speed * firstNormal;
+
+  if (relativeNormalVelocity < 0) {
+    const impulse = clamp(-relativeNormalVelocity * (0.34 + sim.rules.collisionRestitution), 0, 16);
+    if (firstNormal > 0) first.speed = clamp(first.speed - impulse * firstNormal, 0, VEHICLE_LIMITS.maxSpeed);
+    if (secondNormal < 0) second.speed = clamp(second.speed + impulse * secondNormal, 0, VEHICLE_LIMITS.maxSpeed);
+  }
+
+  first.speed = clamp(first.speed * 0.997, 0, VEHICLE_LIMITS.maxSpeed);
+  second.speed = clamp(second.speed * 0.997, 0, VEHICLE_LIMITS.maxSpeed);
+}
+
+function dampPitContactVelocity(car, factor, syncVelocity = false) {
+  if (syncVelocity || Number.isFinite(car.velocityX) || Number.isFinite(car.velocityY)) {
+    const velocity = velocityVector(car);
+    applyVelocityVector(car, {
+      x: velocity.x * factor,
+      y: velocity.y * factor,
+    });
+    return;
+  }
+  car.speed = clamp(car.speed * factor, 0, VEHICLE_LIMITS.maxSpeed);
+}

package/src/simulation/vehicle/mainTrackWheelSurface.js

@@ -0,0 +1,82 @@
+export function mainTrackSurface(track, crossTrackError) {
+  const trackEdge = track.width / 2;
+  const kerbEdge = trackEdge + (track.kerbWidth ?? 0);
+  const gravelEdge = kerbEdge + track.gravelWidth;
+  const runoffEdge = gravelEdge + track.runoffWidth;
+  if (crossTrackError <= trackEdge) return 'track';
+  if (crossTrackError <= kerbEdge) return 'kerb';
+  if (crossTrackError <= gravelEdge) return 'gravel';
+  if (crossTrackError <= runoffEdge) return 'grass';
+  return 'barrier';
+}
+
+export function wheelFullyOutside(samples, trackLimit) {
+  const rightOutside = samples.every((state) => !state.inPitLane && state.signedOffset > trackLimit);
+  const leftOutside = samples.every((state) => !state.inPitLane && state.signedOffset < -trackLimit);
+  return {
+    rightOutside,
+    leftOutside,
+    fullyOutsideWhiteLine: rightOutside || leftOutside,
+    outsideSide: rightOutside ? 1 : leftOutside ? -1 : 0,
+  };
+}
+
+export function wheelOutsideFromOffsets(minimumSignedOffset, maximumSignedOffset, trackLimit) {
+  const rightOutside = minimumSignedOffset > trackLimit;
+  const leftOutside = maximumSignedOffset < -trackLimit;
+  return {
+    rightOutside,
+    leftOutside,
+    fullyOutsideWhiteLine: rightOutside || leftOutside,
+    outsideSide: rightOutside ? 1 : leftOutside ? -1 : 0,
+  };
+}
+
+export function analyticWheelState(patch, centerState, track, trackLimit) {
+  const wheelCenterOffset =
+    (patch.center.x - centerState.x) * centerState.normalX +
+    (patch.center.y - centerState.y) * centerState.normalY;
+  const projectedHalfWidth =
+    Math.abs(patch.forward.x * centerState.normalX + patch.forward.y * centerState.normalY) * patch.halfLength +
+    Math.abs(patch.right.x * centerState.normalX + patch.right.y * centerState.normalY) * patch.halfWidth;
+  const minimumSignedOffset = wheelCenterOffset - projectedHalfWidth;
+  const maximumSignedOffset = wheelCenterOffset + projectedHalfWidth;
+  const signedOffset = Math.abs(minimumSignedOffset) > Math.abs(maximumSignedOffset)
+    ? minimumSignedOffset
+    : maximumSignedOffset;
+  const state = stateFromSignedOffset(centerState, track, signedOffset);
+  const outside = wheelOutsideFromOffsets(minimumSignedOffset, maximumSignedOffset, trackLimit);
+
+  return {
+    id: patch.id,
+    x: patch.center.x,
+    y: patch.center.y,
+    signedOffset: state.signedOffset,
+    crossTrackError: state.crossTrackError,
+    surface: state.surface,
+    onTrack: Boolean(state.onTrack),
+    inPitLane: false,
+    pitLanePart: null,
+    pitBoxId: null,
+    minimumSignedOffset,
+    maximumSignedOffset,
+    fullyOutsideWhiteLine: outside.fullyOutsideWhiteLine,
+    outsideSide: outside.outsideSide,
+    sampledStates: [state],
+  };
+}
+
+function stateFromSignedOffset(centerState, track, signedOffset) {
+  const crossTrackError = Math.abs(signedOffset);
+  const surface = mainTrackSurface(track, crossTrackError);
+  return {
+    ...centerState,
+    signedOffset,
+    crossTrackError,
+    surface,
+    onTrack: surface === 'track' || surface === 'kerb',
+    inPitLane: false,
+    pitLanePart: null,
+    pitBoxId: null,
+  };
+}

package/src/simulation/vehicle/pitWheelSurface.js

@@ -0,0 +1,69 @@
+import { metersToSimUnits } from '../units.js';
+
+const PIT_CONNECTOR_FULL_SAMPLE_WINDOW = metersToSimUnits(35);
+
+export function patchSamples(patch) {
+  return [patch.center, ...patch.corners];
+}
+
+export function isNearPitConnector(track, centerState) {
+  const pitLane = track.pitLane;
+  if (!pitLane?.enabled) return false;
+  const distance = centerState.distance;
+  const entryDistance = pitLane.entry?.trackDistance ?? pitLane.entry?.distanceFromStart;
+  const exitDistance = pitLane.exit?.trackDistance ?? pitLane.exit?.distanceFromStart;
+  return wrappedDistanceDelta(distance, entryDistance, track.length) <= PIT_CONNECTOR_FULL_SAMPLE_WINDOW ||
+    wrappedDistanceDelta(distance, exitDistance, track.length) <= PIT_CONNECTOR_FULL_SAMPLE_WINDOW;
+}
+
+export function canUseAnalyticPitWheels(geometry, centerState) {
+  const roadWidth = Number(centerState?.pitLaneRoadWidth);
+  if (!centerState?.inPitLane || !Number.isFinite(roadWidth) || roadWidth <= 0) return false;
+  const halfRoadWidth = roadWidth / 2;
+  return geometry.contactPatches.every((patch) => {
+    const range = patchPitOffsetRange(patch, centerState);
+    return range.minimum >= -halfRoadWidth - 0.001 && range.maximum <= halfRoadWidth + 0.001;
+  });
+}
+
+export function analyticPitWheelState(patch, centerState) {
+  const range = patchPitOffsetRange(patch, centerState);
+  return {
+    id: patch.id,
+    x: patch.center.x,
+    y: patch.center.y,
+    signedOffset: centerState.mainTrackSignedOffset ?? centerState.signedOffset,
+    crossTrackError: centerState.mainTrackCrossTrackError ?? centerState.crossTrackError,
+    surface: centerState.surface,
+    onTrack: true,
+    inPitLane: true,
+    pitLanePart: centerState.pitLanePart ?? null,
+    pitBoxId: centerState.pitBoxId ?? null,
+    minimumSignedOffset: centerState.mainTrackSignedOffset ?? centerState.signedOffset,
+    maximumSignedOffset: centerState.mainTrackSignedOffset ?? centerState.signedOffset,
+    pitLaneMinimumSignedOffset: range.minimum,
+    pitLaneMaximumSignedOffset: range.maximum,
+    fullyOutsideWhiteLine: false,
+    outsideSide: 0,
+    sampledStates: [centerState],
+  };
+}
+
+function patchPitOffsetRange(patch, centerState) {
+  const wheelCenterOffset =
+    (patch.center.x - centerState.x) * centerState.normalX +
+    (patch.center.y - centerState.y) * centerState.normalY;
+  const projectedHalfWidth =
+    Math.abs(patch.forward.x * centerState.normalX + patch.forward.y * centerState.normalY) * patch.halfLength +
+    Math.abs(patch.right.x * centerState.normalX + patch.right.y * centerState.normalY) * patch.halfWidth;
+  return {
+    minimum: wheelCenterOffset - projectedHalfWidth,
+    maximum: wheelCenterOffset + projectedHalfWidth,
+  };
+}
+
+function wrappedDistanceDelta(first, second, length) {
+  if (!Number.isFinite(first) || !Number.isFinite(second) || !Number.isFinite(length) || length <= 0) return Infinity;
+  const delta = Math.abs(first - second);
+  return Math.min(delta, length - delta);
+}

package/src/simulation/vehicle/runoffResponse.js

@@ -0,0 +1,87 @@
+import { VEHICLE_GEOMETRY, getVehicleGeometryState, vehicleAxes } from './vehicleGeometry.js';
+import { applyWheelSurfaceState } from './wheelSurface.js';
+import { freezeVehicleMotion } from './vehicleKinematics.js';
+import { nearestTrackStateForCar, pitOverrideAllowedForCar } from '../track/trackStatePolicy.js';
+import { markCarDnf } from '../race/retirements.js';
+
+export function applyRunoffResponseForSimulation(sim, car) {
+  if (car.destroyed) {
+    freezeBarrierMotion(car, sim.physicsMode);
+    applyWheelSurfaceState(car, sim.track);
+    return;
+  }
+  const allowPitOverride = pitOverrideAllowedForCar(car);
+  const state = nearestTrackStateForCar(sim.track, car, car, car.progress, { allowPitOverride });
+  const mainTrackState = state.inPitLane
+    ? nearestTrackStateForCar(sim.track, car, car, car.progress, { allowPitOverride: false })
+    : state;
+  const barrierCenter = sim.track.width / 2 + (sim.track.kerbWidth ?? 0) + sim.track.gravelWidth + sim.track.runoffWidth;
+  const signedLimit = barrierCenter - (sim.track.barrierWidth ?? 0) / 2;
+  const side = Math.sign(mainTrackState.signedOffset) || 1;
+  const outwardReach = getOutwardVehicleReach(car, mainTrackState, side);
+  const overshoot = Math.abs(mainTrackState.signedOffset) + outwardReach - signedLimit;
+  if (overshoot <= 0) {
+    if (state.inPitLane) {
+      applyWheelSurfaceState(car, sim.track, { centerState: state });
+      return;
+    }
+    applyWheelSurfaceState(car, sim.track, { centerState: state });
+    return;
+  }
+
+  destroyCarOnBarrier(sim, car);
+  applyWheelSurfaceState(car, sim.track, { centerState: mainTrackState });
+}
+
+function getOutwardVehicleReach(car, state, side) {
+  const visualReach = getVisualFootprintOutwardReach(car, state);
+  const geometry = getVehicleGeometryState(car);
+  let reach = visualReach;
+  geometry.current.shapes.forEach((shape) => {
+    shape.corners.forEach((corner) => {
+      const lateral =
+        (corner.x - car.x) * state.normalX +
+        (corner.y - car.y) * state.normalY;
+      reach = Math.max(reach, lateral * side);
+    });
+  });
+  return reach;
+}
+
+function getVisualFootprintOutwardReach(car, state) {
+  const axes = vehicleAxes(car.heading ?? 0);
+  return (
+    Math.abs(axes.forward.x * state.normalX + axes.forward.y * state.normalY) * VEHICLE_GEOMETRY.visualLength / 2 +
+    Math.abs(axes.right.x * state.normalX + axes.right.y * state.normalY) * VEHICLE_GEOMETRY.visualWidth / 2
+  );
+}
+
+function destroyCarOnBarrier(sim, car) {
+  if (car.destroyed || car.finished) return;
+  car.destroyed = true;
+  car.destroyReason = 'barrier';
+  car.destroyedAt = sim.time;
+  car.outOfRace = true;
+  markCarDnf(sim, car, { reason: 'barrier' });
+  car.canAttack = false;
+  car.drsActive = false;
+  car.drsEligible = false;
+  car.drsZoneId = null;
+  car.drsZoneEnabled = false;
+  freezeBarrierMotion(car, sim.physicsMode);
+  sim.events.unshift({
+    type: 'car-destroyed',
+    at: sim.time,
+    carId: car.id,
+    driverId: car.id,
+    reason: 'barrier',
+  });
+}
+
+function freezeBarrierMotion(car, physicsMode) {
+  freezeVehicleMotion(car, {
+    clearManualControls: true,
+    physicsMode,
+    stabilityState: 'destroyed',
+  });
+}

package/src/simulation/vehicle/surfacePriority.js

@@ -0,0 +1,28 @@
+const SURFACE_PRIORITY = {
+  track: 0,
+  'pit-entry': 1,
+  'pit-exit': 1,
+  'pit-lane': 2,
+  'pit-box': 3,
+  kerb: 4,
+  grass: 5,
+  gravel: 6,
+  barrier: 7,
+};
+
+export function priority(surface) {
+  return SURFACE_PRIORITY[surface] ?? SURFACE_PRIORITY.barrier;
+}
+
+export function worstState(states) {
+  return states.reduce((worst, state) => (
+    priority(state.surface) > priority(worst.surface) ? state : worst
+  ), states[0]);
+}
+
+export function getEffectiveSurface(wheels = []) {
+  if (!wheels.length) return 'track';
+  return wheels.reduce((surface, wheel) => (
+    priority(wheel.surface) > priority(surface) ? wheel.surface : surface
+  ), 'track');
+}

package/src/simulation/vehicle/vehicleGeometry.js

@@ -0,0 +1,247 @@
+import { normalizeAngle } from '../simMath.js';
+import {
+  REAL_F1_CAR_LENGTH_METERS,
+  REAL_F1_CAR_WIDTH_METERS,
+  REAL_F1_WHEELBASE_METERS,
+  metersToSimUnits,
+} from '../units.js';
+
+export const VEHICLE_GEOMETRY = {
+  visualLength: metersToSimUnits(REAL_F1_CAR_LENGTH_METERS),
+  visualWidth: metersToSimUnits(REAL_F1_CAR_WIDTH_METERS),
+  bodyLength: metersToSimUnits(4.65),
+  bodyWidth: metersToSimUnits(1.24),
+  wheelLength: metersToSimUnits(0.72),
+  wheelWidth: metersToSimUnits(0.38),
+  wheelLongitudinalOffset: metersToSimUnits(REAL_F1_WHEELBASE_METERS / 2),
+  wheelLateralOffset: metersToSimUnits((REAL_F1_CAR_WIDTH_METERS - 0.38) / 2),
+};
+
+const WHEEL_SPECS = [
+  { id: 'front-left', longitudinal: 1, lateral: -1 },
+  { id: 'front-right', longitudinal: 1, lateral: 1 },
+  { id: 'rear-left', longitudinal: -1, lateral: -1 },
+  { id: 'rear-right', longitudinal: -1, lateral: 1 },
+];
+
+function finiteOr(value, fallback) {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function vehiclePose(car, { previous = false } = {}) {
+  const x = previous ? finiteOr(car.previousX, car.x) : car.x;
+  const y = previous ? finiteOr(car.previousY, car.y) : car.y;
+  const heading = previous ? finiteOr(car.previousHeading, car.heading) : car.heading;
+
+  return {
+    x: finiteOr(x, 0),
+    y: finiteOr(y, 0),
+    heading: normalizeAngle(finiteOr(heading, 0)),
+  };
+}
+
+export function vehicleAxes(heading) {
+  const cos = Math.cos(heading);
+  const sin = Math.sin(heading);
+  return {
+    forward: { x: cos, y: sin },
+    right: { x: -sin, y: cos },
+  };
+}
+
+function offsetPoint(center, axes, longitudinal, lateral) {
+  return {
+    x: center.x + axes.forward.x * longitudinal + axes.right.x * lateral,
+    y: center.y + axes.forward.y * longitudinal + axes.right.y * lateral,
+  };
+}
+
+export function createOrientedRect({ id, type, center, heading, length, width }) {
+  const axes = vehicleAxes(heading);
+  const halfLength = length / 2;
+  const halfWidth = width / 2;
+  const corners = [
+    offsetPoint(center, axes, halfLength, halfWidth),
+    offsetPoint(center, axes, halfLength, -halfWidth),
+    offsetPoint(center, axes, -halfLength, -halfWidth),
+    offsetPoint(center, axes, -halfLength, halfWidth),
+  ];
+
+  return {
+    id,
+    type,
+    center,
+    heading,
+    length,
+    width,
+    halfLength,
+    halfWidth,
+    forward: axes.forward,
+    right: axes.right,
+    corners,
+  };
+}
+
+export function createVehicleGeometry(car, options = {}) {
+  const pose = vehiclePose(car, options);
+  const axes = vehicleAxes(pose.heading);
+  const center = { x: pose.x, y: pose.y };
+  const body = createOrientedRect({
+    id: 'body',
+    type: 'body',
+    center,
+    heading: pose.heading,
+    length: VEHICLE_GEOMETRY.bodyLength,
+    width: VEHICLE_GEOMETRY.bodyWidth,
+  });
+  const wheels = WHEEL_SPECS.map((spec) => {
+    const wheelCenter = offsetPoint(
+      center,
+      axes,
+      spec.longitudinal * VEHICLE_GEOMETRY.wheelLongitudinalOffset,
+      spec.lateral * VEHICLE_GEOMETRY.wheelLateralOffset,
+    );
+    return createOrientedRect({
+      id: spec.id,
+      type: 'wheel',
+      center: wheelCenter,
+      heading: pose.heading,
+      length: VEHICLE_GEOMETRY.wheelLength,
+      width: VEHICLE_GEOMETRY.wheelWidth,
+    });
+  });
+
+  return {
+    body,
+    wheels,
+    contactPatches: wheels,
+    shapes: [body, ...wheels],
+  };
+}
+
+function geometryPoseSignature(pose) {
+  return [
+    pose.x,
+    pose.y,
+    pose.heading,
+    pose.previousX,
+    pose.previousY,
+    pose.previousHeading,
+  ].join(':');
+}
+
+function geometryPose(car) {
+  const x = finiteOr(car.x, 0);
+  const y = finiteOr(car.y, 0);
+  const heading = normalizeAngle(finiteOr(car.heading, 0));
+  return {
+    x,
+    y,
+    heading,
+    previousX: finiteOr(car.previousX, x),
+    previousY: finiteOr(car.previousY, y),
+    previousHeading: normalizeAngle(finiteOr(car.previousHeading, heading)),
+  };
+}
+
+function geometryStateMatches(car, state) {
+  const pose = state?.pose;
+  if (!pose) return false;
+  const x = finiteOr(car.x, 0);
+  const y = finiteOr(car.y, 0);
+  const heading = normalizeAngle(finiteOr(car.heading, 0));
+  return (
+    pose.x === x &&
+    pose.y === y &&
+    pose.heading === heading &&
+    pose.previousX === finiteOr(car.previousX, x) &&
+    pose.previousY === finiteOr(car.previousY, y) &&
+    pose.previousHeading === normalizeAngle(finiteOr(car.previousHeading, heading))
+  );
+}
+
+export function createVehicleShapeAabb(shape) {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let index = 0; index < shape.corners.length; index += 1) {
+    const corner = shape.corners[index];
+    if (corner.x < minX) minX = corner.x;
+    if (corner.x > maxX) maxX = corner.x;
+    if (corner.y < minY) minY = corner.y;
+    if (corner.y > maxY) maxY = corner.y;
+  }
+  return {
+    minX,
+    maxX,
+    minY,
+    maxY,
+  };
+}
+
+export function mergeAabbs(aabbs) {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let index = 0; index < aabbs.length; index += 1) {
+    const aabb = aabbs[index];
+    if (aabb.minX < minX) minX = aabb.minX;
+    if (aabb.maxX > maxX) maxX = aabb.maxX;
+    if (aabb.minY < minY) minY = aabb.minY;
+    if (aabb.maxY > maxY) maxY = aabb.maxY;
+  }
+  return { minX, maxX, minY, maxY };
+}
+
+export function createVehicleGeometryState(car) {
+  const pose = geometryPose(car);
+  const current = createVehicleGeometry(car);
+  const previous = createVehicleGeometry(car, { previous: true });
+  const bodyAabb = createVehicleShapeAabb(current.body);
+  const previousBodyAabb = createVehicleShapeAabb(previous.body);
+  const sweptBodyAabb = mergeAabbs([previousBodyAabb, bodyAabb]);
+
+  return {
+    pose,
+    signature: geometryPoseSignature(pose),
+    current,
+    previous,
+    body: current.body,
+    wheels: current.wheels,
+    contactPatches: current.contactPatches,
+    bodyAabb,
+    previousBodyAabb,
+    sweptBodyAabb,
+  };
+}
+
+export function getVehicleGeometryState(car) {
+  if (geometryStateMatches(car, car.geometryState)) return car.geometryState;
+  car.geometryState = createVehicleGeometryState(car);
+  return car.geometryState;
+}
+
+export function createVehicleAabb(car, options = {}) {
+  const geometry = createVehicleGeometry(car, options);
+  return mergeAabbs(geometry.shapes.map(createVehicleShapeAabb));
+}
+
+export function interpolateVehiclePose(car, amount) {
+  const previousX = finiteOr(car.previousX, car.x);
+  const previousY = finiteOr(car.previousY, car.y);
+  const previousHeading = finiteOr(car.previousHeading, car.heading);
+  const headingDelta = normalizeAngle(finiteOr(car.heading, 0) - previousHeading);
+
+  return {
+    ...car,
+    x: previousX + (finiteOr(car.x, previousX) - previousX) * amount,
+    y: previousY + (finiteOr(car.y, previousY) - previousY) * amount,
+    heading: normalizeAngle(previousHeading + headingDelta * amount),
+  };
+}
+
+export function getCarCorners(car) {
+  return createVehicleGeometry(car).body.corners;
+}