@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/environment/runtime.js

@@ -1,10 +1,20 @@
 import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.js';
+import { disableWarmupOptions, runWarmupWithGuard } from '../simulation/warmup/runtimeWarmup.js';
 import { handleActionError, resolveActionMap } from './actions.js';
 import { collectStepEvents } from './events.js';
-import { createEpisodeState, evaluateEpisode } from './episode.js';
+import {
+  advanceDriverEpisodes,
+  buildDriverEpisodeInfo,
+  createEpisodeState,
+  evaluateEpisode,
+  initializeDriverEpisodes,
+  markDestroyedDriverEpisodes,
+  resetDriverEpisodes,
+} from './episode.js';
+import { buildDriverMetrics } from './metrics.js';
 import { buildEnvironmentObservation } from './observations.js';
 import { resolveEnvironmentOptions } from './options.js';
-import { applyEnvironmentScenario } from './scenarios.js';
+import { applyEnvironmentPlacements, applyEnvironmentScenario, normalizeEnvironmentPlacements } from './scenarios.js';
 import { buildActionSpec, buildObservationSpec } from './specs.js';
 
 export function createPaddockEnvironment(options = {}) {
@@ -28,28 +38,55 @@ export function createPaddockEnvironment(options = {}) {
 }
 
 function createSimulationWithEnvironmentScenario(options) {
-  const sim = createRaceSimulation(options);
+  const simulationOptions = {
+    ...options,
+    trackQueryIndex: shouldUseTrackQueryIndex(options),
+  };
+  runWarmupWithGuard({
+    options: simulationOptions,
+    surface: 'environment',
+    execute: ({ warmup }) => {
+      const warmupSimulation = createRaceSimulation(disableWarmupOptions(simulationOptions, warmup.surface));
+      initializeControlledPitIntentForSimulation(warmupSimulation, options);
+      applyEnvironmentScenario(warmupSimulation, options);
+      applyControlledRunoffResponse(warmupSimulation, options);
+      for (let index = 0; index < warmup.steps; index += 1) warmupSimulation.step(FIXED_STEP);
+      const warmupSnapshot = warmupSimulation.snapshotObservation?.() ?? warmupSimulation.snapshot();
+      buildEnvironmentObservation({
+        snapshot: warmupSnapshot,
+        options,
+        events: [],
+      });
+    },
+  });
+  const sim = createRaceSimulation(disableWarmupOptions(simulationOptions, 'environment'));
+  initializeControlledPitIntentForSimulation(sim, options);
   applyEnvironmentScenario(sim, options);
+  applyControlledRunoffResponse(sim, options);
   return sim;
 }
 
+function shouldUseTrackQueryIndex(options) {
+  return options.trackQueryIndex !== false;
+}
+
 export function createEnvironmentRuntime(host) {
   const episodeState = createEpisodeState();
 
   initializeControlledPitIntent(host);
+  initializeDriverEpisodes(episodeState, host.getOptions().controlledDrivers);
 
   function reset(nextOptions = {}) {
-    const options = resolveEnvironmentOptions({
-      ...host.getOptions(),
-      ...nextOptions,
-    });
+    const options = resolveEnvironmentOptions(mergeEnvironmentResetOptions(host.getOptions(), nextOptions));
     host.setOptions(options);
     host.setSimulation(host.createSimulation(options));
     initializeControlledPitIntent(host);
     episodeState.step = 0;
     episodeState.previousSnapshot = null;
+    initializeDriverEpisodes(episodeState, options.controlledDrivers);
     const result = buildResult({ host, episodeState, events: [], actionErrors: [] });
     episodeState.lastResult = result;
+    emitExternalRenderFrame(host, result, { source: 'reset' });
     host.afterReset(result);
     return result;
   }
@@ -61,6 +98,11 @@ export function createEnvironmentRuntime(host) {
       policy: options.actionPolicy,
     });
 
+    if (options.actionPolicy === 'report') {
+      options.controlledDrivers.forEach((driverId) => {
+        if (!Object.hasOwn(controlsByDriver, driverId)) sim.clearCarControls?.(driverId);
+      });
+    }
     Object.entries(controlsByDriver).forEach(([driverId, controls]) => {
       sim.setCarControls(driverId, controls);
     });
@@ -71,7 +113,7 @@ export function createEnvironmentRuntime(host) {
       }
     });
 
-    episodeState.previousSnapshot = episodeState.lastResult?.state?.snapshot ?? sim.snapshot();
+    episodeState.previousSnapshot = episodeState.lastRewardSnapshot ?? snapshotForResult(sim, options, options.result.stateOutput);
     const stepEvents = [];
     for (let index = 0; index < options.frameSkip; index += 1) {
       sim.step(FIXED_STEP);
@@ -81,8 +123,17 @@ export function createEnvironmentRuntime(host) {
       stepEvents.push(...collectStepEvents(events));
     }
     episodeState.step += 1;
-    const result = buildResult({ host, episodeState, events: stepEvents, actionErrors: errors, actions });
+    advanceDriverEpisodes(episodeState, options.controlledDrivers);
+    const result = buildResult({
+      host,
+      episodeState,
+      events: stepEvents,
+      actionErrors: errors,
+      actions,
+      rewardEnabled: true,
+    });
     episodeState.lastResult = result;
+    emitExternalRenderFrame(host, result, { source: 'step', actions });
     host.afterStep(result);
     return result;
   }
@@ -92,8 +143,50 @@ export function createEnvironmentRuntime(host) {
       buildResult({ host, episodeState, events: [], actionErrors: [] }).observation;
   }
 
-  function getState() {
-    return { snapshot: host.getSimulation().snapshot() };
+  function getState({ output = 'full' } = {}) {
+    const sim = host.getSimulation();
+    if (output === 'none') return null;
+    if (output === 'minimal') return { snapshot: sim.snapshotObservation?.() ?? sim.snapshot() };
+    return { snapshot: sim.snapshot() };
+  }
+
+  function resetDrivers(placements = {}, resultOptions = {}) {
+    const options = host.getOptions();
+    const sim = host.getSimulation();
+    const driverIds = new Set(options.controlledDrivers);
+    const normalizedPlacements = normalizeEnvironmentPlacements(placements, driverIds);
+    const snapshot = sim.snapshotObservation?.() ?? sim.snapshot();
+    const carsById = new Map(snapshot.cars.map((car) => [car.id, car]));
+    applyEnvironmentPlacements(sim, snapshot.track, carsById, normalizedPlacements);
+    Object.keys(normalizedPlacements).forEach((driverId) => {
+      sim.clearCarControls?.(driverId);
+      sim.setAutomaticPitIntentEnabled?.(driverId, false);
+      const car = sim.cars?.find?.((item) => item.id === driverId);
+      resetEnvironmentPitStop(car);
+      sim.setPitIntent?.(driverId, 0);
+      if (car) sim.applyRunoffResponse?.(car);
+    });
+    resetDriverEpisodes(episodeState, Object.keys(normalizedPlacements));
+    episodeState.previousSnapshot = null;
+    const resetDriverIds = Object.keys(normalizedPlacements);
+    const observationScope = resultOptions.observationScope ??
+      resultOptions.resetDriversObservationScope ??
+      options.result.resetDriversObservationScope;
+    const result = buildResult({
+      host,
+      episodeState,
+      events: [],
+      actionErrors: [],
+      controlledDrivers: observationScope === 'reset' ? resetDriverIds : options.controlledDrivers,
+      stateOutput: resultOptions.stateOutput,
+    });
+    episodeState.lastResult = result;
+    emitExternalRenderFrame(host, result, {
+      source: 'resetDrivers',
+      resetDriverIds,
+      observationScope,
+    });
+    return result;
   }
 
   function getActionSpec() {
@@ -107,9 +200,42 @@ export function createEnvironmentRuntime(host) {
   function destroy() {
     episodeState.lastResult = null;
     episodeState.previousSnapshot = null;
+    episodeState.lastObservationSnapshot = null;
+    episodeState.lastRewardSnapshot = null;
+    episodeState.drivers?.clear?.();
   }
 
-  return { reset, step, getObservation, getState, getActionSpec, getObservationSpec, destroy };
+  return { reset, step, resetDrivers, getObservation, getState, getActionSpec, getObservationSpec, destroy };
+}
+
+function mergeEnvironmentResetOptions(currentOptions, nextOptions = {}) {
+  return mergePlainObjects(currentOptions, nextOptions);
+}
+
+const REPLACE_OBJECT_PATHS = new Set([
+  'scenario.placements',
+]);
+
+function mergePlainObjects(base, overrides, path = []) {
+  if (!isPlainObject(base) || !isPlainObject(overrides)) return overrides;
+  const merged = { ...base };
+  Object.entries(overrides).forEach(([key, value]) => {
+    if (value === undefined) return;
+    const nextPath = [...path, key];
+    merged[key] = isPlainObject(value) &&
+      isPlainObject(base[key]) &&
+      !REPLACE_OBJECT_PATHS.has(nextPath.join('.'))
+      ? mergePlainObjects(base[key], value, nextPath)
+      : value;
+  });
+  return merged;
+}
+
+function isPlainObject(value) {
+  return value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
 }
 
 function isNoopPitIntent(pitIntent) {
@@ -122,54 +248,177 @@ function isNoopPitIntent(pitIntent) {
 function initializeControlledPitIntent(host) {
   const sim = host.getSimulation?.();
   const options = host.getOptions?.();
+  initializeControlledPitIntentForSimulation(sim, options);
+}
+
+function initializeControlledPitIntentForSimulation(sim, options) {
   options?.controlledDrivers?.forEach?.((driverId) => {
     sim?.setAutomaticPitIntentEnabled?.(driverId, false);
     sim?.setPitIntent?.(driverId, 0);
+    const car = sim?.cars?.find?.((item) => item.id === driverId);
+    if (car) car.environmentControlled = true;
   });
 }
 
-function buildResult({ host, episodeState, events, actionErrors, actions = {} }) {
+function resetEnvironmentPitStop(car) {
+  const stop = car?.pitStop;
+  if (!stop) return;
+  stop.status = 'pending';
+  stop.phase = null;
+  stop.intent = 0;
+  stop.queueingForService = false;
+  stop.route = null;
+  stop.routeProgress = 0;
+  stop.routeStartRaceDistance = null;
+  stop.routeEndRaceDistance = null;
+  stop.serviceRemaining = 0;
+  stop.penaltyServiceRemaining = 0;
+  stop.penaltyServiceTotal = 0;
+  stop.servingPenaltyIds = [];
+  stop.serviceProfile = null;
+}
+
+function buildResult({
+  host,
+  episodeState,
+  events,
+  actionErrors,
+  actions = {},
+  controlledDrivers = null,
+  stateOutput = null,
+  rewardEnabled = false,
+}) {
   const options = host.getOptions();
-  const snapshot = host.getSimulation().snapshot();
+  const sim = host.getSimulation();
+  const resultDrivers = controlledDrivers ?? options.controlledDrivers;
+  const resolvedStateOutput = stateOutput ?? options.result.stateOutput;
+  const observationSnapshot = snapshotForResult(sim, options, resolvedStateOutput);
+  markDestroyedDriverEpisodes(episodeState, options.controlledDrivers, observationSnapshot);
   const observation = buildEnvironmentObservation({
-    snapshot,
+    snapshot: observationSnapshot,
     previousSnapshot: episodeState.previousSnapshot,
     options,
     events,
+    controlledDrivers: resultDrivers,
   });
-  const episode = evaluateEpisode(snapshot, options, episodeState);
-  const reward = computeReward({ options, observation, events, snapshot, actions, previousSnapshot: episodeState.previousSnapshot });
+  const episode = evaluateEpisode(observationSnapshot, options, episodeState, resultDrivers);
+  const metrics = buildDriverMetrics({
+    snapshot: observationSnapshot,
+    previousSnapshot: episodeState.previousSnapshot,
+    options: { ...options, controlledDrivers: resultDrivers },
+    events,
+  });
+  const rewardEpisodeInfo = buildDriverEpisodeInfo(episodeState, {
+    ...options,
+    controlledDrivers: resultDrivers,
+  }, episode);
+  const driverEpisode = resultDrivers === options.controlledDrivers
+    ? episode
+    : evaluateEpisode(observationSnapshot, options, episodeState, options.controlledDrivers);
+  const driverEpisodeInfo = buildDriverEpisodeInfo(episodeState, options, driverEpisode);
+  const { state, rewardSnapshot } = buildResultState(sim, observationSnapshot, resolvedStateOutput);
+  const reward = rewardEnabled
+    ? computeReward({
+      options: { ...options, controlledDrivers: resultDrivers },
+      observation,
+      events,
+      snapshot: rewardSnapshot,
+      actions,
+      previousSnapshot: episodeState.previousSnapshot,
+      metrics,
+      driverEpisodeInfo: rewardEpisodeInfo,
+    })
+    : null;
+  episodeState.lastObservationSnapshot = observationSnapshot;
+  episodeState.lastRewardSnapshot = rewardSnapshot;
   return {
     observation,
     reward,
+    metrics,
     terminated: episode.terminated,
     truncated: episode.truncated,
     done: episode.terminated || episode.truncated,
     events,
-    state: { snapshot },
+    state,
     info: {
       step: episodeState.step,
-      elapsedSeconds: snapshot.time,
+      elapsedSeconds: observationSnapshot.time,
       seed: options.seed,
       trackSeed: options.trackSeed,
-      controlledDrivers: [...options.controlledDrivers],
+      controlledDrivers: [...resultDrivers],
       actionErrors,
       endReason: episode.endReason,
+      drivers: driverEpisodeInfo,
     },
   };
 }
 
-function computeReward({ options, observation, events, snapshot, actions, previousSnapshot }) {
+function applyControlledRunoffResponse(sim, options) {
+  options?.controlledDrivers?.forEach?.((driverId) => {
+    const car = sim?.cars?.find?.((item) => item.id === driverId);
+    if (car) sim?.applyRunoffResponse?.(car);
+  });
+}
+
+function buildResultState(sim, observationSnapshot, stateOutput) {
+  if (stateOutput === 'none') return { state: null, rewardSnapshot: observationSnapshot };
+  if (stateOutput === 'minimal') return { state: { snapshot: observationSnapshot }, rewardSnapshot: observationSnapshot };
+  const snapshot = sim.snapshot();
+  return { state: { snapshot }, rewardSnapshot: snapshot };
+}
+
+function snapshotForResult(sim, options, stateOutput) {
+  if (canUseTrainingSnapshot(options, stateOutput)) {
+    return sim.snapshotTraining?.() ?? sim.snapshotObservation?.() ?? sim.snapshot();
+  }
+  return sim.snapshotObservation?.() ?? sim.snapshot();
+}
+
+function canUseTrainingSnapshot(options, stateOutput) {
+  return stateOutput === 'none' &&
+    options.observation?.output === 'vector' &&
+    options.observation?.includeSchema === false;
+}
+
+function computeReward({ options, observation, events, snapshot, actions, previousSnapshot, metrics, driverEpisodeInfo }) {
   if (!options.reward) return null;
   return Object.fromEntries(options.controlledDrivers.map((driverId) => [
     driverId,
-    Number(options.reward({
+    normalizeRewardValue(options.reward({
       driverId,
       previous: previousSnapshot,
       current: observation[driverId],
       action: actions?.[driverId],
       events: observation[driverId]?.events ?? events,
       state: { snapshot },
-    }) ?? 0),
+      metrics: metrics?.[driverId] ?? null,
+      episode: driverEpisodeInfo?.[driverId] ?? null,
+    })),
   ]));
 }
+
+function emitExternalRenderFrame(host, result, meta = {}) {
+  const options = host.getOptions?.();
+  const onFrame = options?.externalRenderer?.onFrame;
+  if (typeof onFrame !== 'function') return;
+  try {
+    onFrame({
+      snapshot: result?.state?.snapshot ??
+        host.getSimulation?.()?.snapshotObservation?.() ??
+        host.getSimulation?.()?.snapshot?.(),
+      observation: result?.observation ?? {},
+      meta: {
+        ...meta,
+        step: result?.info?.step ?? null,
+        elapsedSeconds: result?.info?.elapsedSeconds ?? null,
+      },
+    });
+  } catch {
+    // External rendering hooks are observer-only and must not break stepping.
+  }
+}
+
+function normalizeRewardValue(value) {
+  const reward = Number(value ?? 0);
+  return Number.isFinite(reward) ? reward : 0;
+}

package/src/environment/scenarios.js

@@ -1,5 +1,5 @@
 import { normalizeAngle } from '../simulation/simMath.js';
-import { offsetTrackPoint, pointAt } from '../simulation/trackModel.js';
+import { offsetTrackPoint, pointAt } from '../simulation/track/trackModel.js';
 import { kphToSimSpeed, metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
 
 export const ENVIRONMENT_SCENARIO_PRESETS = Object.freeze([
@@ -38,10 +38,7 @@ export function applyEnvironmentScenario(sim, options) {
     ...(scenario.placements ?? {}),
   };
 
-  Object.entries(placements).forEach(([driverId, placement]) => {
-    if (!carsById.has(driverId)) return;
-    applyPlacement(sim, snapshot.track, carsById.get(driverId), driverId, placement);
-  });
+  applyEnvironmentPlacements(sim, snapshot.track, carsById, placements);
 
   const nextSnapshot = sim.snapshot();
   const nextCarsById = new Map(nextSnapshot.cars.map((car) => [car.id, car]));
@@ -49,15 +46,21 @@ export function applyEnvironmentScenario(sim, options) {
     const reference = nextCarsById.get(trafficPlacement.relativeTo);
     const car = nextCarsById.get(trafficPlacement.driverId);
     if (!reference || !car) return;
-    applyPlacement(sim, nextSnapshot.track, car, trafficPlacement.driverId, {
+    applyEnvironmentPlacements(sim, nextSnapshot.track, nextCarsById, {
+      [trafficPlacement.driverId]: {
       distanceMeters: reference.distanceMeters + trafficPlacement.deltaDistanceMeters,
       offsetMeters: trafficPlacement.offsetMeters,
       speedKph: trafficPlacement.speedKph ?? reference.speedKph,
       headingErrorRadians: trafficPlacement.headingErrorRadians ?? 0,
+      },
     });
   });
 }
 
+export function normalizeEnvironmentPlacements(placements = {}, driverIds = new Set()) {
+  return normalizePlacementMap(placements, driverIds);
+}
+
 function normalizePlacementMap(value, driverIds) {
   if (value == null) return {};
   if (typeof value !== 'object' || Array.isArray(value)) {
@@ -174,13 +177,32 @@ function findHighCurvatureDistance(track) {
   return best?.distance ?? fallback;
 }
 
-function applyPlacement(sim, track, currentCar, driverId, placement) {
+export function applyEnvironmentPlacements(sim, track, carsById, placements = {}) {
+  const states = {};
+  Object.entries(placements).forEach(([driverId, placement]) => {
+    const currentCar = carsById.get(driverId);
+    if (!currentCar) return;
+    states[driverId] = placementToCarState(track, currentCar, placement, {
+      physicsMode: sim.physicsMode,
+    });
+  });
+  if (typeof sim.setCarStates === 'function') {
+    sim.setCarStates(states);
+    return;
+  }
+  Object.entries(states).forEach(([driverId, partial]) => {
+    sim.setCarState(driverId, partial);
+  });
+}
+
+function placementToCarState(track, currentCar, placement, { physicsMode = 'arcade' } = {}) {
   const currentDistanceMeters = currentCar.distanceMeters ?? simUnitsToMeters(currentCar.raceDistance ?? currentCar.progress ?? 0);
   const raceDistance = metersToSimUnits(Math.max(0, placement.distanceMeters ?? currentDistanceMeters));
   const offset = metersToSimUnits(placement.offsetMeters ?? 0);
   const base = pointAt(track, raceDistance);
   const position = offsetTrackPoint(base, offset);
   const heading = normalizeAngle(base.heading + (placement.headingErrorRadians ?? 0));
+  const speed = placement.speedKph == null ? null : kphToSimSpeed(placement.speedKph);
   const partial = {
     x: position.x,
     y: position.y,
@@ -191,9 +213,35 @@ function applyPlacement(sim, track, currentCar, driverId, placement) {
     desiredOffset: offset,
     heading,
     previousHeading: heading,
+    destroyed: false,
+    destroyReason: null,
+    destroyedAt: null,
+    outOfRace: false,
+    canAttack: true,
+    throttle: 0,
+    brake: 0,
+    longitudinalAcceleration: 0,
+    lateralAcceleration: 0,
+    lateralG: 0,
+    longitudinalG: 0,
+    gripUsage: 0,
+    slipAngleRadians: 0,
+    tractionLimited: false,
+    steeringAngle: 0,
+    yawRate: 0,
+    stabilityState: 'stable',
   };
-  if (placement.speedKph != null) partial.speed = kphToSimSpeed(placement.speedKph);
-  sim.setCarState(driverId, partial);
+  if (speed != null) {
+    partial.speed = speed;
+    if (physicsMode === 'simulator') {
+      partial.velocityX = Math.cos(heading) * speed;
+      partial.velocityY = Math.sin(heading) * speed;
+    } else {
+      partial.velocityX = null;
+      partial.velocityY = null;
+    }
+  }
+  return partial;
 }
 
 function assertKnownDriver(driverId, driverIds, label) {

package/src/environment/sensors/bodySenses.js

@@ -0,0 +1,23 @@
+import { simSpeedToMetersPerSecond } from '../../simulation/units.js';
+
+export function buildBodySenses(car) {
+  return {
+    id: car.id,
+    speedKph: car.speedKph,
+    speedMetersPerSecond: simSpeedToMetersPerSecond(car.speed ?? 0),
+    headingRadians: car.heading,
+    yawRateRadiansPerSecond: car.yawRate ?? 0,
+    steeringAngleRadians: car.steeringAngle ?? 0,
+    throttle: car.throttle ?? 0,
+    brake: car.brake ?? 0,
+    appliedControls: car.appliedControls ?? null,
+    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,
+  };
+}

package/src/environment/sensors/boundarySenses.js

@@ -0,0 +1,17 @@
+import { simUnitsToMeters } from '../../simulation/units.js';
+
+export function buildBoundarySenses(car, snapshot, onLegalSurface) {
+  const widthMeters = simUnitsToMeters(snapshot.track?.width ?? 0);
+  const halfWidthMeters = widthMeters / 2;
+  const lateralOffsetMeters = simUnitsToMeters(car.signedOffset ?? 0);
+
+  return {
+    lateralOffsetMeters,
+    headingErrorRadians: car.trackHeadingError ?? 0,
+    legalWidthMeters: widthMeters,
+    leftBoundaryMeters: halfWidthMeters + lateralOffsetMeters,
+    rightBoundaryMeters: halfWidthMeters - lateralOffsetMeters,
+    onLegalSurface,
+    surface: car.surface ?? 'track',
+  };
+}

package/src/environment/sensors/carRays.js

@@ -0,0 +1,75 @@
+import { metersToSimUnits, simUnitsToMeters } from '../../simulation/units.js';
+import { VEHICLE_GEOMETRY } from '../../simulation/vehicle/vehicleGeometry.js';
+import { dot, getCarRayOrigin, getCarRayVector, intersectAxisAlignedBoxRay } from './rayGeometry.js';
+import { rayDetectableTargets } from './sensorTargets.js';
+
+export function estimateCarHit(
+  car,
+  snapshot,
+  angleDegrees,
+  lengthMeters,
+  origin = getCarRayOrigin(car),
+  targets = rayDetectableTargets(car, snapshot),
+) {
+  const ray = getCarRayVector(car, angleDegrees);
+  const maxDistance = metersToSimUnits(lengthMeters);
+  let closest = null;
+  targets.forEach((other) => {
+    if (!carRayBroadphaseHit(origin, ray, maxDistance, other)) return;
+    const hitDistance = intersectCarFootprint(origin, ray, other);
+    if (hitDistance == null || hitDistance > maxDistance) return;
+    const distanceMeters = simUnitsToMeters(hitDistance);
+    if (!closest || hitDistance < closest.distanceSimUnits) {
+      closest = {
+        hit: true,
+        distanceSimUnits: hitDistance,
+        distanceMeters,
+        driverId: other.id,
+        targetId: other.id,
+        targetType: other.entityType,
+        relativeSpeedKph: other.speedKph - car.speedKph,
+      };
+    }
+  });
+  if (!closest) return createCarRayMiss(lengthMeters);
+  const { distanceSimUnits, ...publicHit } = closest;
+  return publicHit;
+}
+
+export function createCarRayMiss(lengthMeters) {
+  return {
+    hit: false,
+    distanceMeters: lengthMeters,
+    driverId: null,
+    targetId: null,
+    targetType: null,
+    relativeSpeedKph: 0,
+  };
+}
+
+function carRayBroadphaseHit(origin, ray, maxDistance, other) {
+  const dx = other.x - origin.x;
+  const dy = other.y - origin.y;
+  const projection = dx * ray.x + dy * ray.y;
+  const radius = Math.hypot(VEHICLE_GEOMETRY.bodyLength, VEHICLE_GEOMETRY.bodyWidth) / 2;
+  if (projection < -radius || projection > maxDistance + radius) return false;
+  const perpendicularSquared = Math.max(0, dx * dx + dy * dy - projection * projection);
+  return perpendicularSquared <= radius * radius;
+}
+
+function intersectCarFootprint(origin, ray, other) {
+  const forward = { x: Math.cos(other.heading), y: Math.sin(other.heading) };
+  const right = { x: -Math.sin(other.heading), y: Math.cos(other.heading) };
+  const delta = { x: origin.x - other.x, y: origin.y - other.y };
+  const localOrigin = {
+    x: dot(delta, forward),
+    y: dot(delta, right),
+  };
+  const localRay = {
+    x: dot(ray, forward),
+    y: dot(ray, right),
+  };
+  const halfLength = VEHICLE_GEOMETRY.bodyLength / 2;
+  const halfWidth = VEHICLE_GEOMETRY.bodyWidth / 2;
+  return intersectAxisAlignedBoxRay(localOrigin, localRay, halfLength, halfWidth);
+}

package/src/environment/sensors/contactSenses.js

@@ -0,0 +1,32 @@
+import { simUnitsToMeters } from '../../simulation/units.js';
+
+const SURFACE_CODES = {
+  track: 0,
+  kerb: 1,
+  'pit-entry': 2,
+  'pit-lane': 2,
+  'pit-exit': 2,
+  'pit-box': 2,
+  grass: 3,
+  gravel: 4,
+  barrier: 5,
+};
+
+export const CONTACT_PATCH_IDS = Object.freeze(['front-left', 'front-right', 'rear-left', 'rear-right']);
+
+export function buildContactPatchSenses(car) {
+  const wheelsById = new Map((car.wheels ?? []).map((wheel) => [wheel.id, wheel]));
+  return CONTACT_PATCH_IDS.map((id) => {
+    const wheel = wheelsById.get(id);
+    return {
+      id,
+      present: Boolean(wheel),
+      signedOffsetMeters: simUnitsToMeters(wheel?.signedOffset ?? 0),
+      crossTrackErrorMeters: simUnitsToMeters(wheel?.crossTrackError ?? 0),
+      surface: wheel?.surface ?? 'track',
+      surfaceCode: SURFACE_CODES[wheel?.surface ?? 'track'] ?? SURFACE_CODES.barrier,
+      onLegalSurface: Boolean(wheel?.onTrack || wheel?.inPitLane),
+      inPitLane: Boolean(wheel?.inPitLane),
+    };
+  });
+}