@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/simulation/vehicle/vehicleSnapshots.js

@@ -0,0 +1,327 @@
+import { serializeParticipantInteraction } from '../participants/participantInteractions.js';
+
+export function finiteOrNull(value) {
+  return Number.isFinite(value) ? value : null;
+}
+
+function serializeAppliedControls(car, dependencies) {
+  const { VEHICLE_LIMITS } = dependencies;
+  const controls = car.appliedControls ?? {};
+  const maxSteer = VEHICLE_LIMITS?.maxSteer ?? 1;
+  return {
+    steering: maxSteer > 0 ? (controls.steering ?? 0) / maxSteer : 0,
+    steeringRadians: controls.steering ?? 0,
+    throttle: controls.throttle ?? 0,
+    brake: controls.brake ?? 0,
+  };
+}
+
+function serializeVelocityComponent(car, component, dependencies) {
+  if (dependencies.physicsMode !== 'simulator') return null;
+  return finiteOrNull(car[component]);
+}
+
+export function serializeWheels(wheels = []) {
+  return wheels.map((wheel) => ({
+    id: wheel.id,
+    x: wheel.x,
+    y: wheel.y,
+    signedOffset: wheel.signedOffset,
+    crossTrackError: wheel.crossTrackError,
+    surface: wheel.surface,
+    onTrack: Boolean(wheel.onTrack),
+    inPitLane: Boolean(wheel.inPitLane),
+    fullyOutsideWhiteLine: Boolean(wheel.fullyOutsideWhiteLine),
+  }));
+}
+
+export function serializeCar(car, rank, penaltySeconds = 0, dependencies) {
+  const {
+    createLapTelemetry,
+    normalizePitIntent,
+    PIT_INTENT_NONE,
+    serializeLapTelemetry,
+    serializePitStop,
+    simSpeedToKph,
+    simUnitsToMeters,
+    VEHICLE_LIMITS,
+  } = dependencies;
+  const finishTime = car.finishTime ?? null;
+  const raceStatus = (car.destroyed || car.outOfRace) ? 'destroyed' : car.finished ? 'waved-flag' : 'racing';
+  return {
+    id: car.id,
+    code: car.code,
+    timingCode: car.timingCode,
+    driverNumber: car.driverNumber,
+    icon: car.icon,
+    raceName: car.raceName,
+    name: car.name,
+    color: car.color,
+    team: car.team ? { ...car.team } : null,
+    tire: car.tire,
+    personality: { ...car.personality },
+    aggression: car.aggression,
+    aggressionPercent: Math.round((car.aggression ?? 0) * 100),
+    setup: {
+      vehicleId: car.vehicleId,
+      vehicleName: car.vehicleName,
+      vehicleRatings: car.vehicleRatings ? { ...car.vehicleRatings } : null,
+      maxSpeedKph: simSpeedToKph(VEHICLE_LIMITS.maxSpeed),
+      powerUnitKn: car.powerNewtons / 1000,
+      brakeSystemKn: car.brakeNewtons / 1000,
+      dragCoefficient: car.dragCoefficient,
+      downforceCoefficient: car.downforceCoefficient,
+      tireGrip: car.tireGrip,
+      tireCare: car.tireCare,
+      massKg: car.mass,
+      pace: car.pace,
+      racecraft: car.racecraft,
+    },
+    interaction: serializeParticipantInteraction(car.interaction),
+    rank,
+    classifiedRank: car.classifiedRank ?? rank,
+    finishRank: car.finishRank ?? null,
+    status: raceStatus,
+    raceStatus,
+    wavedFlag: Boolean(car.finished),
+    finished: Boolean(car.finished),
+    destroyed: Boolean(car.destroyed),
+    destroyReason: car.destroyReason ?? null,
+    destroyedAt: car.destroyedAt ?? null,
+    dnf: Boolean(car.destroyed || car.outOfRace),
+    dnfReason: car.dnfReason ?? car.destroyReason ?? null,
+    dnfAt: car.dnfAt ?? car.destroyedAt ?? null,
+    dnfOrder: car.dnfOrder ?? null,
+    outOfRace: Boolean(car.outOfRace || car.destroyed),
+    finishTime,
+    penaltySeconds,
+    adjustedFinishTime: finishTime == null ? null : finishTime + penaltySeconds,
+    previousX: car.previousX ?? car.x,
+    previousY: car.previousY ?? car.y,
+    x: car.x,
+    y: car.y,
+    previousHeading: car.previousHeading ?? car.heading,
+    heading: car.heading,
+    steeringAngle: car.steeringAngle,
+    yawRate: car.yawRate,
+    velocityX: serializeVelocityComponent(car, 'velocityX', dependencies),
+    velocityY: serializeVelocityComponent(car, 'velocityY', dependencies),
+    turnRadius: car.turnRadius,
+    speed: car.speed,
+    speedKph: simSpeedToKph(car.speed),
+    throttle: car.throttle,
+    brake: car.brake,
+    appliedControls: serializeAppliedControls(car, dependencies),
+    lateralAcceleration: car.lateralAcceleration,
+    longitudinalAcceleration: car.longitudinalAcceleration ?? 0,
+    lateralG: car.lateralG ?? 0,
+    longitudinalG: car.longitudinalG ?? 0,
+    gripUsage: car.gripUsage ?? 0,
+    slipAngleRadians: car.slipAngleRadians ?? 0,
+    tractionLimited: Boolean(car.tractionLimited),
+    stabilityState: car.stabilityState ?? 'stable',
+    progress: car.progress,
+    raceDistance: car.raceDistance,
+    distanceMeters: simUnitsToMeters(car.raceDistance),
+    lap: car.lap,
+    lapTelemetry: serializeLapTelemetry(car.lapTelemetry ?? createLapTelemetry({ length: 1 }, 0, 0)),
+    gapAhead: car.gapAhead,
+    gapAheadMeters: Number.isFinite(car.gapAhead) ? simUnitsToMeters(car.gapAhead) : Infinity,
+    gapAheadSeconds: car.gapAheadSeconds,
+    intervalAheadSeconds: car.intervalAheadSeconds,
+    leaderGapSeconds: car.leaderGapSeconds,
+    gapAheadLaps: car.gapAheadLaps ?? 0,
+    intervalAheadLaps: car.intervalAheadLaps ?? car.gapAheadLaps ?? 0,
+    leaderGapLaps: car.leaderGapLaps ?? 0,
+    drsEligible: car.drsEligible,
+    drsActive: car.drsActive,
+    drsZoneId: car.drsZoneId,
+    drsZoneEnabled: car.drsZoneEnabled,
+    canAttack: car.canAttack,
+    signedOffset: car.trackState?.signedOffset ?? 0,
+    crossTrackError: car.trackState?.crossTrackError ?? 0,
+    surface: car.trackState?.surface ?? 'track',
+    wheels: serializeWheels(car.wheelStates),
+    inPitLane: Boolean(car.trackState?.inPitLane),
+    pitLanePart: car.trackState?.pitLanePart ?? null,
+    pitBoxId: car.trackState?.pitBoxId ?? null,
+    pitLaneCrossTrackError: car.trackState?.pitLaneCrossTrackError ?? null,
+    contactCooldown: car.contactCooldown,
+    tireEnergy: car.tireEnergy,
+    usedTireCompounds: [...(car.usedTireCompounds ?? [])],
+    pitIntent: normalizePitIntent(car.pitStop?.intent) ?? PIT_INTENT_NONE,
+    pitStop: serializePitStop(car.pitStop),
+    positionSource: 'integrated-vehicle',
+  };
+}
+
+export function serializeRenderCar(car, dependencies) {
+  const { serializeRenderPitStop } = dependencies;
+  return {
+    id: car.id,
+    color: car.color,
+    previousX: car.previousX ?? car.x,
+    previousY: car.previousY ?? car.y,
+    x: car.x,
+    y: car.y,
+    previousHeading: car.previousHeading ?? car.heading,
+    heading: car.heading,
+    drsActive: Boolean(car.drsActive),
+    destroyed: Boolean(car.destroyed),
+    destroyReason: car.destroyReason ?? null,
+    dnf: Boolean(car.destroyed || car.outOfRace),
+    dnfReason: car.dnfReason ?? car.destroyReason ?? null,
+    dnfAt: car.dnfAt ?? car.destroyedAt ?? null,
+    dnfOrder: car.dnfOrder ?? null,
+    outOfRace: Boolean(car.outOfRace || car.destroyed),
+    pitStop: serializeRenderPitStop(car.pitStop),
+    interaction: serializeParticipantInteraction(car.interaction),
+  };
+}
+
+export function serializeObservationCar(car, rank, dependencies) {
+  const {
+    createLapTelemetry,
+    normalizePitIntent,
+    PIT_INTENT_NONE,
+    serializeLapTelemetry,
+    serializeObservationPitStop,
+    serializeWheels: serializeWheelState = serializeWheels,
+    simSpeedToKph,
+  } = dependencies;
+  return {
+    id: car.id,
+    rank,
+    previousX: car.previousX ?? car.x,
+    previousY: car.previousY ?? car.y,
+    x: car.x,
+    y: car.y,
+    previousHeading: car.previousHeading ?? car.heading,
+    heading: car.heading,
+    steeringAngle: car.steeringAngle,
+    yawRate: car.yawRate,
+    velocityX: serializeVelocityComponent(car, 'velocityX', dependencies),
+    velocityY: serializeVelocityComponent(car, 'velocityY', dependencies),
+    speed: car.speed,
+    speedKph: simSpeedToKph(car.speed),
+    throttle: car.throttle,
+    brake: car.brake,
+    appliedControls: serializeAppliedControls(car, dependencies),
+    lateralG: car.lateralG ?? 0,
+    longitudinalG: car.longitudinalG ?? 0,
+    gripUsage: car.gripUsage ?? 0,
+    slipAngleRadians: car.slipAngleRadians ?? 0,
+    tractionLimited: Boolean(car.tractionLimited),
+    stabilityState: car.stabilityState ?? 'stable',
+    destroyed: Boolean(car.destroyed),
+    destroyReason: car.destroyReason ?? null,
+    destroyedAt: car.destroyedAt ?? null,
+    dnf: Boolean(car.destroyed || car.outOfRace),
+    dnfReason: car.dnfReason ?? car.destroyReason ?? null,
+    dnfAt: car.dnfAt ?? car.destroyedAt ?? null,
+    dnfOrder: car.dnfOrder ?? null,
+    outOfRace: Boolean(car.outOfRace || car.destroyed),
+    progress: car.progress,
+    raceDistance: car.raceDistance,
+    lap: car.lap,
+    lapTelemetry: serializeLapTelemetry(car.lapTelemetry ?? createLapTelemetry({ length: 1 }, 0, 0)),
+    signedOffset: car.trackState?.signedOffset ?? 0,
+    crossTrackError: car.trackState?.crossTrackError ?? 0,
+    surface: car.trackState?.surface ?? 'track',
+    trackHeadingError: car.trackHeadingError,
+    trackState: car.trackState ? {
+      distance: car.trackState.distance,
+      signedOffset: car.trackState.signedOffset,
+      crossTrackError: car.trackState.crossTrackError,
+      surface: car.trackState.surface,
+      inPitLane: Boolean(car.trackState.inPitLane),
+      pitLanePart: car.trackState.pitLanePart ?? null,
+      pitBoxId: car.trackState.pitBoxId ?? null,
+      curvature: car.trackState.curvature ?? 0,
+    } : null,
+    wheels: serializeWheelState(car.wheelStates),
+    inPitLane: Boolean(car.trackState?.inPitLane),
+    pitLanePart: car.trackState?.pitLanePart ?? null,
+    pitBoxId: car.trackState?.pitBoxId ?? null,
+    tireEnergy: car.tireEnergy ?? null,
+    pitIntent: normalizePitIntent(car.pitStop?.intent) ?? PIT_INTENT_NONE,
+    pitStop: serializeObservationPitStop(car.pitStop),
+    interaction: serializeParticipantInteraction(car.interaction),
+  };
+}
+
+export function serializeTrainingCar(car, rank, dependencies) {
+  const {
+    normalizePitIntent,
+    PIT_INTENT_NONE,
+    serializeObservationPitStop,
+    serializeWheels: serializeWheelState = serializeWheels,
+    simSpeedToKph,
+    simUnitsToMeters,
+  } = dependencies;
+  return {
+    id: car.id,
+    rank,
+    previousX: car.previousX ?? car.x,
+    previousY: car.previousY ?? car.y,
+    x: car.x,
+    y: car.y,
+    previousHeading: car.previousHeading ?? car.heading,
+    heading: car.heading,
+    steeringAngle: car.steeringAngle,
+    yawRate: car.yawRate,
+    velocityX: serializeVelocityComponent(car, 'velocityX', dependencies),
+    velocityY: serializeVelocityComponent(car, 'velocityY', dependencies),
+    speed: car.speed,
+    speedKph: simSpeedToKph(car.speed),
+    throttle: car.throttle,
+    brake: car.brake,
+    appliedControls: serializeAppliedControls(car, dependencies),
+    lateralG: car.lateralG ?? 0,
+    longitudinalG: car.longitudinalG ?? 0,
+    gripUsage: car.gripUsage ?? 0,
+    slipAngleRadians: car.slipAngleRadians ?? 0,
+    tractionLimited: Boolean(car.tractionLimited),
+    stabilityState: car.stabilityState ?? 'stable',
+    destroyed: Boolean(car.destroyed),
+    destroyReason: car.destroyReason ?? null,
+    destroyedAt: car.destroyedAt ?? null,
+    dnf: Boolean(car.destroyed || car.outOfRace),
+    dnfReason: car.dnfReason ?? car.destroyReason ?? null,
+    dnfAt: car.dnfAt ?? car.destroyedAt ?? null,
+    dnfOrder: car.dnfOrder ?? null,
+    outOfRace: Boolean(car.outOfRace || car.destroyed),
+    progress: car.progress,
+    raceDistance: car.raceDistance,
+    distanceMeters: simUnitsToMeters(car.raceDistance ?? car.progress ?? 0),
+    lap: car.lap,
+    lapTelemetry: {
+      completedLaps: car.lapTelemetry?.completedLaps ?? 0,
+      lastLapTime: car.lapTelemetry?.lastLapTime ?? null,
+      bestLapTime: car.lapTelemetry?.bestLapTime ?? null,
+    },
+    signedOffset: car.trackState?.signedOffset ?? 0,
+    crossTrackError: car.trackState?.crossTrackError ?? 0,
+    surface: car.trackState?.surface ?? 'track',
+    trackHeadingError: car.trackHeadingError,
+    trackState: car.trackState ? {
+      distance: car.trackState.distance,
+      signedOffset: car.trackState.signedOffset,
+      crossTrackError: car.trackState.crossTrackError,
+      surface: car.trackState.surface,
+      inPitLane: Boolean(car.trackState.inPitLane),
+      pitLanePart: car.trackState.pitLanePart ?? null,
+      pitBoxId: car.trackState.pitBoxId ?? null,
+      curvature: car.trackState.curvature ?? 0,
+      heading: car.trackState.heading,
+    } : null,
+    wheels: serializeWheelState(car.wheelStates),
+    inPitLane: Boolean(car.trackState?.inPitLane),
+    pitLanePart: car.trackState?.pitLanePart ?? null,
+    pitBoxId: car.trackState?.pitBoxId ?? null,
+    tireEnergy: car.tireEnergy ?? null,
+    pitIntent: normalizePitIntent(car.pitStop?.intent) ?? PIT_INTENT_NONE,
+    pitStop: serializeObservationPitStop(car.pitStop),
+    interaction: serializeParticipantInteraction(car.interaction),
+  };
+}

package/src/simulation/vehicle/vehicleState.js

@@ -0,0 +1,220 @@
+import { buildDriverPersonality } from '../driverController.js';
+import { clamp, normalizeAngle, seededRange } from '../simMath.js';
+import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
+import { kphToSimSpeed, metersToSimUnits } from '../units.js';
+import { VEHICLE_LIMITS } from './vehiclePhysics.js';
+import { applyWheelSurfaceState } from './wheelSurface.js';
+import { nearestTrackStateForCar } from '../track/trackStatePolicy.js';
+import { clearCarDnf } from '../race/retirements.js';
+
+const GRID_SLOT_SPACING = metersToSimUnits(8);
+const ROLLING_START_SLOT_SPACING = metersToSimUnits(35);
+const GRID_FIRST_SLOT_DISTANCE = metersToSimUnits(-6);
+const ROLLING_START_FIRST_DISTANCE = metersToSimUnits(-30);
+const GRID_LATERAL_OFFSET = metersToSimUnits(3.2);
+
+export function getStartGridSlot(index, { standingStart = false } = {}) {
+  const gridDistance = standingStart
+    ? GRID_FIRST_SLOT_DISTANCE - index * GRID_SLOT_SPACING
+    : ROLLING_START_FIRST_DISTANCE - index * ROLLING_START_SLOT_SPACING;
+  const gridOffset = index % 2 === 0 ? -GRID_LATERAL_OFFSET : GRID_LATERAL_OFFSET;
+  return { gridDistance, gridOffset };
+}
+
+export function createCar(driver, index, random, track, { standingStart = false, createLapTelemetry } = {}) {
+  const { gridDistance, gridOffset } = getStartGridSlot(index, { standingStart });
+  const start = pointAt(track, gridDistance);
+  const position = offsetTrackPoint(start, gridOffset);
+  const pace = clamp(driver.pace ?? seededRange(random, 0.95, 1.05), 0.88, 1.12);
+  const racecraft = clamp(driver.racecraft ?? seededRange(random, 0.65, 0.92), 0.45, 1);
+  const personality = buildDriverPersonality(driver, index, racecraft, random);
+  const launchSpeed = kphToSimSpeed(Math.max(70, 84 - index * 0.55 + pace * 4));
+  const vehicle = driver.vehicle ?? {};
+
+  return {
+    id: driver.id ?? `car-${index + 1}`,
+    code: driver.code ?? `C${index + 1}`,
+    timingCode: driver.timingCode ?? driver.code ?? `C${index + 1}`,
+    driverNumber: driver.driverNumber ?? index + 1,
+    icon: driver.icon ?? String(index + 1).padStart(2, '0'),
+    raceName: driver.raceName ?? driver.code ?? `CAR${index + 1}`,
+    name: driver.name ?? `Car ${index + 1}`,
+    color: driver.color ?? '#e10600',
+    team: driver.team ? { ...driver.team } : null,
+    tire: driver.tire ?? ['M', 'H', 'S'][index % 3],
+    index,
+    x: position.x,
+    y: position.y,
+    previousX: position.x,
+    previousY: position.y,
+    heading: start.heading,
+    previousHeading: start.heading,
+    steeringAngle: 0,
+    yawRate: 0,
+    turnRadius: Infinity,
+    speed: standingStart ? 0 : launchSpeed,
+    longitudinalAcceleration: 0,
+    lateralAcceleration: 0,
+    lateralG: 0,
+    longitudinalG: 0,
+    gripUsage: 0,
+    slipAngleRadians: 0,
+    tractionLimited: false,
+    stabilityState: 'stable',
+    throttle: 0,
+    brake: 0,
+    vehicleId: vehicle.id ?? null,
+    vehicleName: vehicle.name ?? null,
+    vehicleRatings: vehicle.ratings ? { ...vehicle.ratings } : null,
+    mass: vehicle.mass ?? 798 + seededRange(random, -5, 5),
+    powerNewtons: vehicle.powerNewtons ?? 43000 * pace,
+    brakeNewtons: vehicle.brakeNewtons ?? 59000,
+    dragCoefficient: vehicle.dragCoefficient ?? 0.33 + seededRange(random, -0.026, 0.026),
+    downforceCoefficient: vehicle.downforceCoefficient ?? 6.1 + seededRange(random, -0.18, 0.18),
+    tireGrip: vehicle.tireGrip ?? 2.22 + racecraft * 0.28 + seededRange(random, -0.03, 0.03),
+    tireCare: vehicle.tireCare ?? 1,
+    pace,
+    racecraft,
+    personality,
+    aggression: personality.baseAggression,
+    gridLocked: standingStart,
+    gridDistance,
+    gridOffset,
+    desiredOffset: gridOffset,
+    progress: start.distance,
+    raceDistance: gridDistance,
+    lap: 1,
+    rank: index + 1,
+    gapAhead: Infinity,
+    gapAheadSeconds: Infinity,
+    leaderGapSeconds: 0,
+    intervalAheadSeconds: Infinity,
+    gapAheadLaps: 0,
+    intervalAheadLaps: 0,
+    leaderGapLaps: 0,
+    drsEligible: false,
+    drsActive: false,
+    drsZoneId: null,
+    drsZoneEnabled: false,
+    timingHistory: [],
+    lapTelemetry: createLapTelemetry?.(track, 0, gridDistance) ?? null,
+    drsDetection: {},
+    canAttack: true,
+    trackState: start,
+    contactCooldown: 0,
+    tireEnergy: 100,
+    usedTireCompounds: [driver.tire ?? ['M', 'H', 'S'][index % 3]],
+    automaticPitIntentEnabled: true,
+  };
+}
+
+export function clearCarDrsState(car) {
+  car.drsZoneId = null;
+  car.drsZoneEnabled = false;
+  car.drsActive = false;
+  car.drsEligible = false;
+  car.drsDetection = {};
+}
+
+export function applyExternalCarState(car, partial, context) {
+  const {
+    cars,
+    computeLap,
+    nearestDistanceOnRoute,
+    physicsMode,
+    progressDelta,
+    raceControl,
+    releaseRaceStart,
+    resetLapTelemetry,
+    resetTimingHistory,
+    resetTimingLineCrossings,
+    time,
+    totalLaps,
+    track,
+  } = context;
+  const hasExplicitRaceDistance = partial.raceDistance != null;
+  const nextPartial = { ...partial };
+  if (raceControl.finished && (car.destroyed || car.outOfRace)) {
+    if (partial.destroyed === false) nextPartial.destroyed = car.destroyed;
+    if (partial.outOfRace === false) nextPartial.outOfRace = car.outOfRace;
+  }
+  assertFiniteExternalCarState(nextPartial);
+  Object.assign(car, nextPartial);
+  if (
+    !raceControl.finished &&
+    nextPartial.destroyed === false &&
+    nextPartial.outOfRace === false
+  ) {
+    clearCarDnf(car);
+    car.destroyReason = null;
+    car.destroyedAt = null;
+    car.dnfReason = null;
+    car.dnfAt = null;
+  }
+  if (
+    nextPartial.x != null ||
+    nextPartial.y != null ||
+    nextPartial.progress != null ||
+    nextPartial.raceDistance != null
+  ) {
+    car.gridLocked = false;
+    if (raceControl.mode === 'pre-start' && cars.every((item) => !item.gridLocked)) {
+      releaseRaceStart();
+    }
+  }
+  car.speed = clamp(Number.isFinite(car.speed) ? car.speed : 0, 0, VEHICLE_LIMITS.maxSpeed);
+  car.heading = normalizeAngle(Number.isFinite(car.heading) ? car.heading : 0);
+  syncExternalVelocityState(car, nextPartial, physicsMode === 'simulator');
+  const centerState = nearestTrackStateForCar(track, car, car, car.progress ?? car.raceDistance);
+  applyWheelSurfaceState(car, track, { centerState });
+  if (
+    nextPartial.desiredOffset == null &&
+    (nextPartial.x != null || nextPartial.y != null || nextPartial.progress != null || nextPartial.raceDistance != null)
+  ) {
+    car.desiredOffset = centerState.signedOffset ?? 0;
+  }
+  if ((nextPartial.x != null || nextPartial.y != null) && car.pitStop?.route) {
+    car.pitStop.routeProgress = nearestDistanceOnRoute(car.pitStop.route, car, car.pitStop.routeProgress ?? 0);
+  }
+  if (!hasExplicitRaceDistance) {
+    const delta = progressDelta(car.trackState.distance, car.progress ?? car.trackState.distance, track.length);
+    car.raceDistance = (car.raceDistance ?? car.trackState.distance) + delta;
+  }
+  car.progress = car.trackState.distance;
+  car.lap = computeLap(car.raceDistance);
+  clearCarDrsState(car);
+  resetTimingHistory(car, time);
+  resetTimingLineCrossings(car, time);
+  resetLapTelemetry(car, time, track, totalLaps);
+}
+
+function assertFiniteExternalCarState(partial) {
+  Object.entries(partial ?? {}).forEach(([key, value]) => {
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+      throw new Error(`External car state ${key} must be a finite number.`);
+    }
+  });
+}
+
+function syncExternalVelocityState(car, partial, simulatorMode = false) {
+  const hasVelocityX = Object.hasOwn(partial, 'velocityX');
+  const hasVelocityY = Object.hasOwn(partial, 'velocityY');
+  const hasVelocity = hasVelocityX || hasVelocityY;
+  if (hasVelocity && (partial.velocityX == null || partial.velocityY == null)) {
+    car.velocityX = null;
+    car.velocityY = null;
+    return;
+  }
+  if (hasVelocity) {
+    const fallbackX = Math.cos(car.heading) * car.speed;
+    const fallbackY = Math.sin(car.heading) * car.speed;
+    car.velocityX = Number.isFinite(car.velocityX) ? car.velocityX : fallbackX;
+    car.velocityY = Number.isFinite(car.velocityY) ? car.velocityY : fallbackY;
+    car.speed = clamp(Math.hypot(car.velocityX, car.velocityY), 0, VEHICLE_LIMITS.maxSpeed);
+    return;
+  }
+  if (simulatorMode && (Object.hasOwn(partial, 'speed') || Object.hasOwn(partial, 'heading'))) {
+    car.velocityX = Math.cos(car.heading) * car.speed;
+    car.velocityY = Math.sin(car.heading) * car.speed;
+  }
+}

package/src/simulation/vehicle/wheelSurface.js

@@ -0,0 +1,152 @@
+import { getVehicleGeometryState } from './vehicleGeometry.js';
+import { analyticWheelState, wheelFullyOutside } from './mainTrackWheelSurface.js';
+import { analyticPitWheelState, canUseAnalyticPitWheels, isNearPitConnector, patchSamples } from './pitWheelSurface.js';
+import { getEffectiveSurface, worstState } from './surfacePriority.js';
+import { nearestTrackStateForCar, pitOverrideAllowedForCar } from '../track/trackStatePolicy.js';
+
+function finiteSignatureValue(value) {
+  return Number.isFinite(value) ? Number(value).toFixed(4) : '';
+}
+
+function centerStateSignature(centerState) {
+  if (!centerState) return 'auto';
+  return [
+    finiteSignatureValue(centerState.distance),
+    finiteSignatureValue(centerState.signedOffset),
+    finiteSignatureValue(centerState.crossTrackError),
+    centerState.surface ?? '',
+    centerState.inPitLane ? 1 : 0,
+    centerState.pitLanePart ?? '',
+    centerState.pitBoxId ?? '',
+  ].join(':');
+}
+
+export { getEffectiveSurface } from './surfacePriority.js';
+
+export function isWholeCarOutsideTrackLimits(wheels = [], track, relaxedMargin = 0) {
+  if (!wheels.length || !track) {
+    return {
+      violating: false,
+      side: 0,
+      outsideBy: 0,
+    };
+  }
+  const trackLimit = track.width / 2 + relaxedMargin;
+  const right = wheels.every((wheel) => wheel.outsideSide === 1);
+  const left = wheels.every((wheel) => wheel.outsideSide === -1);
+  if (!right && !left) {
+    return {
+      violating: false,
+      side: 0,
+      outsideBy: 0,
+    };
+  }
+  const side = right ? 1 : -1;
+  const outsideBy = right
+    ? Math.min(...wheels.map((wheel) => wheel.minimumSignedOffset)) - trackLimit
+    : -trackLimit - Math.max(...wheels.map((wheel) => wheel.maximumSignedOffset));
+
+  return {
+    violating: outsideBy > 0,
+    side,
+    outsideBy: Math.max(0, outsideBy),
+  };
+}
+
+export function calculateWheelSurfaceState({ car, track, centerState: providedCenterState = null }) {
+  const geometry = getVehicleGeometryState(car);
+  const trackLimit = track.width / 2;
+  const allowPitOverride = pitOverrideAllowedForCar(car);
+  const centerState = providedCenterState == null
+    ? nearestTrackStateForCar(track, car)
+    : !allowPitOverride && providedCenterState.inPitLane
+      ? nearestTrackStateForCar(track, car, car, car.progress, { allowPitOverride: false })
+      : providedCenterState;
+  const useAnalyticPitSampling = canUseAnalyticPitWheels(geometry, centerState);
+  const useFullSampling = !useAnalyticPitSampling && Boolean(centerState.inPitLane || isNearPitConnector(track, centerState));
+  const wheels = useAnalyticPitSampling
+    ? geometry.contactPatches.map((patch) => analyticPitWheelState(patch, centerState))
+    : useFullSampling
+    ? geometry.contactPatches.map((patch) => {
+        const sampleState = (point) => nearestTrackStateForCar(track, car, point, car.progress);
+        const sampledStates = patchSamples(patch).map(sampleState);
+        const state = worstState(sampledStates);
+        const offsets = sampledStates.map((sample) => sample.signedOffset);
+        const outside = wheelFullyOutside(sampledStates, 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: Boolean(state.inPitLane),
+          pitLanePart: state.pitLanePart ?? null,
+          pitBoxId: state.pitBoxId ?? null,
+          minimumSignedOffset: Math.min(...offsets),
+          maximumSignedOffset: Math.max(...offsets),
+          fullyOutsideWhiteLine: outside.fullyOutsideWhiteLine,
+          outsideSide: outside.outsideSide,
+          sampledStates,
+        };
+      })
+    : geometry.contactPatches.map((patch) => analyticWheelState(patch, centerState, track, trackLimit));
+  const effectiveSurface = getEffectiveSurface(wheels);
+  const representative = wheels.reduce((best, wheel) => (
+    Math.abs(wheel.signedOffset) > Math.abs(best.signedOffset) ? wheel : best
+  ), wheels[0]);
+  const trackLimits = isWholeCarOutsideTrackLimits(wheels, track);
+
+  return {
+    wheels,
+    effectiveSurface,
+    trackLimits,
+    sampleMode: useAnalyticPitSampling ? 'pit-analytic' : useFullSampling ? 'full' : 'analytic',
+    representativeState: representative ? {
+      ...centerState,
+      surface: effectiveSurface,
+      onTrack: wheels.every((wheel) => wheel.onTrack || wheel.inPitLane),
+      inPitLane: wheels.every((wheel) => wheel.inPitLane),
+      signedOffset: representative.signedOffset,
+      crossTrackError: representative.crossTrackError,
+    } : nearestTrackStateForCar(track, car),
+  };
+}
+
+export function applyWheelSurfaceState(car, track, options = {}) {
+  const geometry = getVehicleGeometryState(car);
+  const cacheKey = {
+    track,
+    geometrySignature: geometry.signature,
+    centerSignature: centerStateSignature(options.centerState),
+    pitOverrideAllowed: pitOverrideAllowedForCar(car),
+  };
+  const cached = car.wheelSurfaceCache;
+  if (
+    cached?.track === cacheKey.track &&
+    cached.geometrySignature === cacheKey.geometrySignature &&
+    cached.centerSignature === cacheKey.centerSignature &&
+    cached.pitOverrideAllowed === cacheKey.pitOverrideAllowed
+  ) {
+    car.wheelStates = cached.result.wheels;
+    car.trackLimitState = cached.result.trackLimits;
+    car.trackState = cached.trackState;
+    return cached.result;
+  }
+
+  const result = calculateWheelSurfaceState({ car, track, centerState: options.centerState });
+  car.wheelStates = result.wheels;
+  car.trackLimitState = result.trackLimits;
+  car.trackState = {
+    ...result.representativeState,
+    wheelSurface: result.effectiveSurface,
+  };
+  car.wheelSurfaceCache = {
+    ...cacheKey,
+    result,
+    trackState: car.trackState,
+  };
+  return result;
+}