@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/environment/scenarios.js

@@ -0,0 +1,249 @@
+import { normalizeAngle } from '../simulation/simMath.js';
+import { offsetTrackPoint, pointAt } from '../simulation/track/trackModel.js';
+import { kphToSimSpeed, metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+
+export const ENVIRONMENT_SCENARIO_PRESETS = Object.freeze([
+  'cornering',
+  'off-track-recovery',
+  'overtaking-pack',
+  'pit-entry',
+]);
+
+export function resolveScenarioPlacementConfig(scenario = {}, driverIds = new Set()) {
+  const preset = scenario.preset == null ? null : String(scenario.preset);
+  if (preset && !ENVIRONMENT_SCENARIO_PRESETS.includes(preset)) {
+    throw new Error(`PaddockJS environment scenario.preset must be one of: ${ENVIRONMENT_SCENARIO_PRESETS.join(', ')}.`);
+  }
+
+  const placements = normalizePlacementMap(scenario.placements, driverIds);
+  const traffic = normalizeTrafficLayout(scenario.traffic, driverIds);
+
+  return {
+    preset,
+    placements,
+    traffic,
+  };
+}
+
+export function applyEnvironmentScenario(sim, options) {
+  const scenario = options.scenario ?? {};
+  if (!scenario.preset && Object.keys(scenario.placements ?? {}).length === 0 && (scenario.traffic ?? []).length === 0) {
+    return;
+  }
+
+  const snapshot = sim.snapshot();
+  const carsById = new Map(snapshot.cars.map((car) => [car.id, car]));
+  const placements = {
+    ...buildPresetPlacements(snapshot, options),
+    ...(scenario.placements ?? {}),
+  };
+
+  applyEnvironmentPlacements(sim, snapshot.track, carsById, placements);
+
+  const nextSnapshot = sim.snapshot();
+  const nextCarsById = new Map(nextSnapshot.cars.map((car) => [car.id, car]));
+  scenario.traffic?.forEach((trafficPlacement) => {
+    const reference = nextCarsById.get(trafficPlacement.relativeTo);
+    const car = nextCarsById.get(trafficPlacement.driverId);
+    if (!reference || !car) return;
+    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)) {
+    throw new Error('PaddockJS environment scenario.placements must be an object keyed by driver id.');
+  }
+  return Object.fromEntries(Object.entries(value).map(([driverId, placement]) => {
+    assertKnownDriver(driverId, driverIds, 'scenario placement');
+    return [driverId, normalizePlacement(placement, `scenario.placements.${driverId}`)];
+  }));
+}
+
+function normalizeTrafficLayout(value, driverIds) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error('PaddockJS environment scenario.traffic must be an array.');
+  }
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== 'object') {
+      throw new Error(`PaddockJS environment scenario.traffic[${index}] must be an object.`);
+    }
+    assertKnownDriver(entry.driverId, driverIds, `scenario.traffic[${index}].driverId`);
+    assertKnownDriver(entry.relativeTo, driverIds, `scenario.traffic[${index}].relativeTo`);
+    return {
+      driverId: entry.driverId,
+      relativeTo: entry.relativeTo,
+      deltaDistanceMeters: finiteNumber(entry.deltaDistanceMeters, 0, `scenario.traffic[${index}].deltaDistanceMeters`),
+      offsetMeters: finiteNumber(entry.offsetMeters, 0, `scenario.traffic[${index}].offsetMeters`),
+      speedKph: optionalFiniteNumber(entry.speedKph, `scenario.traffic[${index}].speedKph`),
+      headingErrorRadians: finiteNumber(entry.headingErrorRadians, 0, `scenario.traffic[${index}].headingErrorRadians`),
+    };
+  });
+}
+
+function normalizePlacement(placement, label) {
+  if (!placement || typeof placement !== 'object') {
+    throw new Error(`PaddockJS environment ${label} must be an object.`);
+  }
+  const distanceMeters = placement.distanceMeters ?? placement.startDistanceMeters;
+  return {
+    distanceMeters: optionalFiniteNumber(distanceMeters, `${label}.distanceMeters`),
+    offsetMeters: finiteNumber(placement.offsetMeters, 0, `${label}.offsetMeters`),
+    speedKph: optionalFiniteNumber(placement.speedKph, `${label}.speedKph`),
+    headingErrorRadians: finiteNumber(placement.headingErrorRadians, 0, `${label}.headingErrorRadians`),
+  };
+}
+
+function buildPresetPlacements(snapshot, options) {
+  const preset = options.scenario?.preset;
+  if (!preset) return {};
+  const controlledDriverId = options.controlledDrivers[0];
+  const cars = snapshot.cars;
+  const track = snapshot.track;
+  const primaryDistance = presetBaseDistance(track, preset);
+  const placements = {};
+
+  if (preset === 'cornering') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: 0,
+      speedKph: 135,
+      headingErrorRadians: 0,
+    };
+  } else if (preset === 'off-track-recovery') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: simUnitsToMeters(track.width / 2) + 7,
+      speedKph: 52,
+      headingErrorRadians: -0.45,
+    };
+  } else if (preset === 'pit-entry') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: 0,
+      speedKph: 120,
+      headingErrorRadians: 0,
+    };
+  } else if (preset === 'overtaking-pack') {
+    const baseMeters = simUnitsToMeters(primaryDistance);
+    cars.slice(0, 4).forEach((car, index) => {
+      placements[car.id] = {
+        distanceMeters: baseMeters + (index - 1) * 18,
+        offsetMeters: index % 2 === 0 ? -2.2 : 2.2,
+        speedKph: 135 - index * 3,
+        headingErrorRadians: 0,
+      };
+    });
+  }
+
+  return placements;
+}
+
+function presetBaseDistance(track, preset) {
+  if (preset === 'cornering') return findHighCurvatureDistance(track) - metersToSimUnits(70);
+  if (preset === 'off-track-recovery') return track.length * 0.42;
+  if (preset === 'overtaking-pack') return track.length * 0.35;
+  if (preset === 'pit-entry') {
+    const pitDistance = track.pitLane?.entry?.trackDistance ??
+      track.pitLane?.entry?.distanceFromStart ??
+      track.length * 0.92;
+    return pitDistance - metersToSimUnits(170);
+  }
+  return 0;
+}
+
+function findHighCurvatureDistance(track) {
+  const samples = Array.isArray(track.samples) ? track.samples : [];
+  const fallback = track.length * 0.25;
+  const best = samples
+    .filter((sample) => sample.distance > metersToSimUnits(350))
+    .reduce((selected, sample) => {
+      if (!selected || (sample.curvature ?? 0) > (selected.curvature ?? 0)) return sample;
+      return selected;
+    }, null);
+  return best?.distance ?? fallback;
+}
+
+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);
+  });
+  if (typeof sim.setCarStates === 'function') {
+    sim.setCarStates(states);
+    return;
+  }
+  Object.entries(states).forEach(([driverId, partial]) => {
+    sim.setCarState(driverId, partial);
+  });
+}
+
+function placementToCarState(track, currentCar, placement) {
+  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 partial = {
+    x: position.x,
+    y: position.y,
+    previousX: position.x,
+    previousY: position.y,
+    progress: base.distance,
+    raceDistance,
+    desiredOffset: offset,
+    heading,
+    previousHeading: heading,
+    destroyed: false,
+    destroyReason: null,
+    destroyedAt: null,
+    outOfRace: false,
+    canAttack: true,
+    throttle: 0,
+    brake: 0,
+    steeringAngle: 0,
+    yawRate: 0,
+    stabilityState: 'stable',
+  };
+  if (placement.speedKph != null) partial.speed = kphToSimSpeed(placement.speedKph);
+  return partial;
+}
+
+function assertKnownDriver(driverId, driverIds, label) {
+  if (typeof driverId !== 'string' || driverId.length === 0) {
+    throw new Error(`PaddockJS environment ${label} must be a driver id.`);
+  }
+  if (!driverIds.has(driverId)) {
+    throw new Error(`PaddockJS environment ${label} does not exist: ${driverId}`);
+  }
+}
+
+function finiteNumber(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number)) {
+    throw new Error(`PaddockJS environment ${label} must be a finite number.`);
+  }
+  return number;
+}
+
+function optionalFiniteNumber(value, label) {
+  if (value == null) return undefined;
+  return finiteNumber(value, undefined, 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),
+    };
+  });
+}

package/src/environment/sensors/index.js

@@ -0,0 +1,157 @@
+import { createCarRayMiss, estimateCarHit } from './carRays.js';
+import { normalizeRayOptions } from './rayConfig.js';
+import { degreesToRadians, getCarRayOrigin } from './rayGeometry.js';
+import { rayDetectableTargetsForSnapshot } from './sensorTargets.js';
+import { createTrackMiss, createTrackRayContext, estimateTrackHit } from './trackRays.js';
+import { createSurfaceMiss, estimateSurfaceHits, requestedSurfaceChannels } from './surfaceRays.js';
+import { canUseBatchTrainingRayApproximation } from './rayGuards.js';
+
+export { buildNearbyCars } from './nearbyCars.js';
+export { DEFAULT_RAY_ANGLES_DEGREES } from './rayDefaults.js';
+export { normalizeRayOptions, RAY_CHANNELS, RAY_LAYOUT_PRESETS } from './rayConfig.js';
+export { getCarRayOrigin, getCarRayVector } from './rayGeometry.js';
+
+export function createRayBatchContext(snapshot) {
+  return {
+    rayTargets: rayDetectableTargetsForSnapshot(snapshot),
+  };
+}
+
+export function buildRaySensors(car, snapshot, rayOptions = {}, batchContext = null) {
+  const normalized = normalizeRayOptions(rayOptions);
+  if (!normalized.enabled) return [];
+  if (car?.destroyed || car?.outOfRace) {
+    return buildInactiveCarRays(normalized);
+  }
+  const origin = getCarRayOrigin(car);
+  const usesTrackContext = normalized.channels.includes('roadEdge') ||
+    requestedSurfaceChannels(normalized.channels).length > 0;
+  const trackContext = !usesTrackContext
+    ? null
+    : createTrackRayContext(car, snapshot, origin);
+  const carTargets = normalized.channels.includes('car')
+    ? (batchContext?.rayTargets ?? rayDetectableTargetsForSnapshot(snapshot)).filter((target) => target.id !== car.id)
+    : [];
+
+  if (canUseFastBatchTrainingRays(car, snapshot, trackContext)) {
+    return buildFastBatchTrainingRays(car, snapshot, normalized, origin, carTargets, trackContext);
+  }
+
+  return normalized.rays.map((ray) => {
+    const angleDegrees = ray.angleDegrees;
+    const vector = {
+      x: Math.cos((car.heading ?? 0) + degreesToRadians(angleDegrees)),
+      y: Math.sin((car.heading ?? 0) + degreesToRadians(angleDegrees)),
+    };
+    const sharedRayQuery = {};
+    const roadEdge = normalized.channels.includes('roadEdge')
+      ? estimateTrackHit(
+        car,
+        snapshot,
+        angleDegrees,
+        ray.lengthMeters,
+        trackContext,
+        { precision: normalized.precision, sharedRayQuery },
+      )
+      : createTrackMiss(ray.lengthMeters);
+    const carHit = normalized.channels.includes('car')
+      ? estimateCarHit(car, snapshot, angleDegrees, ray.lengthMeters, origin, carTargets)
+      : createCarRayMiss(ray.lengthMeters);
+    const surfaceHits = estimateSurfaceHits(
+      car,
+      snapshot,
+      ray,
+      origin,
+      vector,
+      normalized.channels,
+      trackContext,
+      { precision: normalized.precision, sharedRayQuery },
+    );
+
+    return {
+      id: ray.id,
+      angleDegrees,
+      angleRadians: degreesToRadians(angleDegrees),
+      lengthMeters: ray.lengthMeters,
+      roadEdge,
+      track: roadEdge,
+      kerb: surfaceHits.kerb ?? createSurfaceMiss(ray.lengthMeters),
+      illegalSurface: surfaceHits.illegalSurface ?? createSurfaceMiss(ray.lengthMeters),
+      car: carHit,
+    };
+  });
+}
+
+function buildInactiveCarRays(normalized) {
+  return normalized.rays.map((ray) => ({
+    id: ray.id,
+    angleDegrees: ray.angleDegrees,
+    angleRadians: degreesToRadians(ray.angleDegrees),
+    lengthMeters: ray.lengthMeters,
+    roadEdge: createTrackMiss(ray.lengthMeters),
+    track: createTrackMiss(ray.lengthMeters),
+    kerb: createSurfaceMiss(ray.lengthMeters),
+    illegalSurface: createSurfaceMiss(ray.lengthMeters),
+    car: createCarRayMiss(ray.lengthMeters),
+  }));
+}
+
+function canUseFastBatchTrainingRays(car, snapshot, trackContext) {
+  return car?.interaction?.profile === 'batch-training' &&
+    !car.inPitLane &&
+    !trackContext?.originState?.inPitLane &&
+    Array.isArray(snapshot.track?.samples) &&
+    snapshot.track.samples.length > 0 &&
+    trackContext?.originState &&
+    canUseBatchTrainingRayApproximation(snapshot.track, trackContext.originState);
+}
+
+function buildFastBatchTrainingRays(car, snapshot, normalized, origin, carTargets, trackContext) {
+  const channels = new Set(normalized.channels);
+
+  return normalized.rays.map((ray) => {
+    const angleRadians = degreesToRadians(ray.angleDegrees);
+    const heading = (car.heading ?? 0) + angleRadians;
+    const vector = { x: Math.cos(heading), y: Math.sin(heading) };
+    const sharedRayQuery = {};
+    const roadEdge = channels.has('roadEdge')
+      ? estimateTrackHit(
+        car,
+        snapshot,
+        ray.angleDegrees,
+        ray.lengthMeters,
+        trackContext,
+        { precision: normalized.precision, sharedRayQuery },
+      )
+      : createTrackMiss(ray.lengthMeters);
+    const carHit = channels.has('car') && carTargets.length > 0
+      ? estimateCarHit(car, snapshot, ray.angleDegrees, ray.lengthMeters, origin, carTargets)
+      : createCarRayMiss(ray.lengthMeters);
+    const surfaceHits = estimateSurfaceHits(
+      car,
+      snapshot,
+      ray,
+      origin,
+      vector,
+      normalized.channels,
+      trackContext,
+      { precision: normalized.precision, sharedRayQuery },
+    );
+
+    return {
+      id: ray.id,
+      angleDegrees: ray.angleDegrees,
+      angleRadians,
+      lengthMeters: ray.lengthMeters,
+      roadEdge,
+      track: roadEdge,
+      kerb: channels.has('kerb')
+        ? (surfaceHits.kerb ?? createSurfaceMiss(ray.lengthMeters))
+        : createSurfaceMiss(ray.lengthMeters),
+      illegalSurface: channels.has('illegalSurface')
+        ? (surfaceHits.illegalSurface ?? createSurfaceMiss(ray.lengthMeters))
+        : createSurfaceMiss(ray.lengthMeters),
+      car: carHit,
+    };
+  });
+}

package/src/environment/sensors/indexedRayBands.js

@@ -0,0 +1,103 @@
+import { queryTrackSegmentsAlongRay } from '../../simulation/track/trackQueryIndex.js';
+import { metersToSimUnits } from '../../simulation/units.js';
+
+const RAY_BOUND_QUERY_MARGIN_METERS = 18;
+
+export function findIndexedRayBoundaryHit(track, origin, vector, lengthMeters, offsets) {
+  const boundaries = findIndexedRayBoundaryDistances(track, origin, vector, lengthMeters, offsets);
+  if (!boundaries.available) return { available: false, distance: null };
+  return {
+    available: true,
+    distance: minFinite(...boundaries.distances),
+  };
+}
+
+export function findIndexedRayBoundaryDistances(track, origin, vector, lengthMeters, offsets) {
+  const finiteOffsets = offsets.filter(Number.isFinite);
+  if (finiteOffsets.length === 0) return { available: true, distances: [] };
+  const maxDistance = metersToSimUnits(lengthMeters);
+  const maxOffset = Math.max(0, ...finiteOffsets.map((offset) => Math.abs(offset)));
+  const margin = maxOffset + metersToSimUnits(RAY_BOUND_QUERY_MARGIN_METERS);
+  const segments = queryTrackSegmentsAlongRay(track, origin, vector, maxDistance, margin);
+  if (!segments) return { available: false, distances: [] };
+  const distances = finiteOffsets.map(() => Infinity);
+
+  for (const segment of segments) {
+    finiteOffsets.forEach((offset, offsetIndex) => {
+      const start = offsetSegmentStart(segment, offset);
+      const finish = offsetSegmentEnd(segment, offset);
+      const distance = raySegmentIntersectionDistance(origin, vector, start, finish, maxDistance);
+      if (distance != null && distance < distances[offsetIndex]) distances[offsetIndex] = distance;
+    });
+  }
+
+  return {
+    available: true,
+    distances: distances.map((distance) => (Number.isFinite(distance) ? distance : null)),
+  };
+}
+
+export function findIndexedTrackBandBoundaries(
+  track,
+  origin,
+  vector,
+  lengthMeters,
+  trackHalfWidth,
+  kerbOuterWidth,
+  cache = null,
+) {
+  if (cache?.trackBandBoundaries) return cache.trackBandBoundaries;
+  const boundaries = findIndexedRayBoundaryDistances(
+    track,
+    origin,
+    vector,
+    lengthMeters,
+    [trackHalfWidth, -trackHalfWidth, kerbOuterWidth, -kerbOuterWidth],
+  );
+  const result = {
+    available: boundaries.available,
+    trackEdgeDistance: minFinite(boundaries.distances[0], boundaries.distances[1]),
+    kerbOuterDistance: minFinite(boundaries.distances[2], boundaries.distances[3]),
+  };
+  if (cache) cache.trackBandBoundaries = result;
+  return result;
+}
+
+function offsetSegmentStart(segment, offset) {
+  return {
+    x: segment.startX + segment.normalX * offset,
+    y: segment.startY + segment.normalY * offset,
+  };
+}
+
+function offsetSegmentEnd(segment, offset) {
+  return {
+    x: segment.endX + segment.endNormalX * offset,
+    y: segment.endY + segment.endNormalY * offset,
+  };
+}
+
+function raySegmentIntersectionDistance(origin, ray, start, end, maxDistance) {
+  const sx = end.x - start.x;
+  const sy = end.y - start.y;
+  const denominator = cross(ray.x, ray.y, sx, sy);
+  if (Math.abs(denominator) < 1e-9) return null;
+
+  const ox = start.x - origin.x;
+  const oy = start.y - origin.y;
+  const rayDistance = cross(ox, oy, sx, sy) / denominator;
+  const segmentAmount = cross(ox, oy, ray.x, ray.y) / denominator;
+
+  if (rayDistance < 0 || rayDistance > maxDistance) return null;
+  if (segmentAmount < -1e-6 || segmentAmount > 1 + 1e-6) return null;
+  return rayDistance;
+}
+
+function cross(ax, ay, bx, by) {
+  return ax * by - ay * bx;
+}
+
+function minFinite(...values) {
+  const minimum = Math.min(...values.filter((value) => Number.isFinite(value)));
+  return Number.isFinite(minimum) ? minimum : null;
+}