@inventure71/paddockjs 1.0.0 → 2.0.0

package/src/environment/sensors.js

@@ -1,367 +1 @@
-import { nearestTrackState } from '../simulation/trackModel.js';
-import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
-import { VEHICLE_GEOMETRY } from '../simulation/vehicleGeometry.js';
-
-const TRACK_RAY_STEP_METERS = 1;
-const TRACK_RAY_REFINE_STEPS = 12;
-const ANALYTIC_TRACK_RAY_MAX_CURVATURE = 0.00005;
-const PIT_CONNECTOR_RAY_FALLBACK_METERS = 55;
-export const DEFAULT_RAY_ANGLES_DEGREES = [-135, -60, -20, 0, 20, 60, 135, 180];
-
-export function buildNearbyCars(car, snapshot, { maxCars = 6, radiusMeters = 150 } = {}) {
-  const limit = Math.max(0, Math.floor(maxCars));
-  if (limit === 0) return [];
-  const radius = metersToSimUnits(radiusMeters);
-  const radiusSquared = radius * radius;
-  const forwardX = Math.cos(car.heading);
-  const forwardY = Math.sin(car.heading);
-  const rightX = -Math.sin(car.heading);
-  const rightY = Math.cos(car.heading);
-  const nearest = [];
-
-  snapshot.cars.forEach((other, order) => {
-    if (other.id === car.id) return;
-    const dx = other.x - car.x;
-    const dy = other.y - car.y;
-    const distanceSquared = dx * dx + dy * dy;
-    if (distanceSquared > radiusSquared) return;
-
-    const forward = forwardX * dx + forwardY * dy;
-    const right = rightX * dx + rightY * dy;
-    const entry = {
-      id: other.id,
-      relativeForwardMeters: simUnitsToMeters(forward),
-      relativeRightMeters: simUnitsToMeters(right),
-      relativeDistanceMeters: simUnitsToMeters(Math.sqrt(distanceSquared)),
-      relativeSpeedKph: other.speedKph - car.speedKph,
-      relativeHeadingRadians: normalizeRelativeHeading(other.heading - car.heading),
-      ahead: forward > 0,
-      sameLap: other.lap === car.lap,
-      distanceSquared,
-      order,
-    };
-    insertNearestCar(nearest, entry, limit);
-  });
-
-  return nearest.map(({ distanceSquared, order, ...entry }) => entry);
-}
-
-export function buildRaySensors(car, snapshot, rayOptions = {}) {
-  const angles = rayOptions.anglesDegrees ?? DEFAULT_RAY_ANGLES_DEGREES;
-  const lengthMeters = rayOptions.lengthMeters ?? 120;
-  const origin = getCarRayOrigin(car);
-  const trackContext = rayOptions.detectTrack === false
-    ? null
-    : createTrackRayContext(car, snapshot, origin);
-
-  return angles.map((angleDegrees) => ({
-    angleDegrees,
-    angleRadians: degreesToRadians(angleDegrees),
-    lengthMeters,
-    track: rayOptions.detectTrack === false
-      ? createTrackMiss(lengthMeters)
-      : estimateTrackHit(car, snapshot, angleDegrees, lengthMeters, trackContext),
-    car: rayOptions.detectCars === false
-      ? { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 }
-      : estimateCarHit(car, snapshot, angleDegrees, lengthMeters, origin),
-  }));
-}
-
-function createTrackRayContext(car, snapshot, origin) {
-  if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
-    return { origin, originState: null };
-  }
-  return {
-    origin,
-    originState: nearestTrackState(snapshot.track, origin, car.progress),
-  };
-}
-
-function estimateTrackHit(car, snapshot, angleDegrees, lengthMeters, context = null) {
-  if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
-    return estimateLocalTrackHit(car, snapshot, angleDegrees, lengthMeters);
-  }
-
-  const origin = context?.origin ?? getCarRayOrigin(car);
-  const ray = getCarRayVector(car, angleDegrees);
-  const maxDistance = metersToSimUnits(lengthMeters);
-  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
-  const originState = context?.originState ?? nearestTrackState(snapshot.track, origin, car.progress);
-  const includePitLane = Boolean(car.inPitLane || car.pitLanePart || originState.inPitLane);
-  const analyticHit = estimateAnalyticMainTrackHit({
-    car,
-    track: snapshot.track,
-    originState,
-    ray,
-    lengthMeters,
-    includePitLane,
-  });
-  if (analyticHit) return analyticHit;
-  let previousDistance = 0;
-  let previousInside = null;
-
-  for (let distance = 0; distance <= maxDistance; distance += step) {
-    const state = nearestTrackState(snapshot.track, pointOnRay(origin, ray, distance), car.progress);
-    const inside = isInsideTrackBorder(state, snapshot.track, includePitLane);
-    if (previousInside == null) {
-      previousInside = inside;
-      previousDistance = distance;
-      continue;
-    }
-
-    if (inside !== previousInside) {
-      const kind = previousInside ? 'exit' : 'entry';
-      const hitDistance = refineTrackTransitionDistance(
-        snapshot.track,
-        origin,
-        ray,
-        car.progress,
-        previousDistance,
-        distance,
-        kind,
-        includePitLane,
-      );
-      return {
-        hit: true,
-        distanceMeters: simUnitsToMeters(hitDistance),
-        kind,
-      };
-    }
-    previousDistance = distance;
-    previousInside = inside;
-  }
-
-  return createTrackMiss(lengthMeters);
-}
-
-function insertNearestCar(nearest, entry, limit) {
-  let insertAt = nearest.findIndex((candidate) => (
-    entry.distanceSquared < candidate.distanceSquared ||
-    (entry.distanceSquared === candidate.distanceSquared && entry.order < candidate.order)
-  ));
-  if (insertAt < 0) insertAt = nearest.length;
-  if (insertAt >= limit) return;
-  nearest.splice(insertAt, 0, entry);
-  if (nearest.length > limit) nearest.pop();
-}
-
-function estimateAnalyticMainTrackHit({ car, track, originState, ray, lengthMeters, includePitLane }) {
-  if (includePitLane || isNearPitConnector(track, originState)) return null;
-  if (Math.abs(originState.curvature ?? 0) > ANALYTIC_TRACK_RAY_MAX_CURVATURE) return null;
-
-  const lateral = ray.x * originState.normalX + ray.y * originState.normalY;
-  if (Math.abs(lateral) < 0.08) return createTrackMiss(lengthMeters);
-
-  const trackHalfWidth = track.width / 2;
-  const offset = originState.signedOffset ?? car.signedOffset ?? 0;
-  const inside = Math.abs(offset) <= trackHalfWidth;
-  const targetEdge = getLocalTrackTransitionTarget({
-    inside,
-    offsetMeters: offset,
-    lateral,
-    trackHalfWidthMeters: trackHalfWidth,
-  });
-  if (targetEdge == null) return createTrackMiss(lengthMeters);
-
-  const distance = (targetEdge - offset) / lateral;
-  const maxDistance = metersToSimUnits(lengthMeters);
-  if (distance < 0 || distance > maxDistance) return createTrackMiss(lengthMeters);
-
-  return {
-    hit: true,
-    distanceMeters: simUnitsToMeters(distance),
-    kind: inside ? 'exit' : 'entry',
-  };
-}
-
-function isNearPitConnector(track, state) {
-  const pitLane = track.pitLane;
-  if (!pitLane?.enabled || !Number.isFinite(state?.distance)) return false;
-  const window = metersToSimUnits(PIT_CONNECTOR_RAY_FALLBACK_METERS);
-  const entryDistance = pitLane.entry?.trackDistance ?? pitLane.entry?.distanceFromStart;
-  const exitDistance = pitLane.exit?.trackDistance ?? pitLane.exit?.distanceFromStart;
-  return wrappedTrackDistance(state.distance, entryDistance, track.length) <= window ||
-    wrappedTrackDistance(state.distance, exitDistance, track.length) <= window;
-}
-
-function wrappedTrackDistance(first, second, totalLength) {
-  if (!Number.isFinite(first) || !Number.isFinite(second) || !Number.isFinite(totalLength) || totalLength <= 0) {
-    return Infinity;
-  }
-  const delta = Math.abs(first - second);
-  return Math.min(delta, totalLength - delta);
-}
-
-function estimateLocalTrackHit(car, snapshot, angleDegrees, lengthMeters) {
-  const trackHalfWidthMeters = simUnitsToMeters(snapshot.track.width / 2);
-  const offsetMeters = simUnitsToMeters(car.signedOffset ?? 0);
-  const lateral = Math.sin(degreesToRadians(angleDegrees));
-  if (Math.abs(lateral) < 0.08) {
-    return createTrackMiss(lengthMeters);
-  }
-
-  const inside = Math.abs(offsetMeters) <= trackHalfWidthMeters;
-  const targetEdge = getLocalTrackTransitionTarget({ inside, offsetMeters, lateral, trackHalfWidthMeters });
-  if (targetEdge == null) return createTrackMiss(lengthMeters);
-
-  const distanceMeters = (targetEdge - offsetMeters) / lateral;
-  if (distanceMeters < 0 || distanceMeters > lengthMeters) return createTrackMiss(lengthMeters);
-
-  return {
-    hit: true,
-    distanceMeters,
-    kind: inside ? 'exit' : 'entry',
-  };
-}
-
-function getLocalTrackTransitionTarget({ inside, offsetMeters, lateral, trackHalfWidthMeters }) {
-  if (inside) return lateral > 0 ? trackHalfWidthMeters : -trackHalfWidthMeters;
-  if (offsetMeters > trackHalfWidthMeters) return lateral < 0 ? trackHalfWidthMeters : null;
-  if (offsetMeters < -trackHalfWidthMeters) return lateral > 0 ? -trackHalfWidthMeters : null;
-  return null;
-}
-
-function refineTrackTransitionDistance(track, origin, ray, progressHint, lowDistance, highDistance, kind, includePitLane = true) {
-  let low = lowDistance;
-  let high = highDistance;
-  for (let index = 0; index < TRACK_RAY_REFINE_STEPS; index += 1) {
-    const middle = (low + high) / 2;
-    const state = nearestTrackState(track, pointOnRay(origin, ray, middle), progressHint);
-    const inside = isInsideTrackBorder(state, track, includePitLane);
-    if (kind === 'entry') {
-      if (inside) high = middle;
-      else low = middle;
-    } else if (inside) {
-      low = middle;
-    } else {
-      high = middle;
-    }
-  }
-  return high;
-}
-
-function isInsideTrackBorder(state, track, includePitLane = true) {
-  if (includePitLane && state.inPitLane) return true;
-  return state.crossTrackError <= track.width / 2;
-}
-
-function createTrackMiss(lengthMeters) {
-  return {
-    hit: false,
-    distanceMeters: lengthMeters,
-    kind: null,
-  };
-}
-
-function estimateCarHit(car, snapshot, angleDegrees, lengthMeters, origin = getCarRayOrigin(car)) {
-  const ray = getCarRayVector(car, angleDegrees);
-  const maxDistance = metersToSimUnits(lengthMeters);
-  let closest = null;
-  snapshot.cars.forEach((other) => {
-    if (other.id === car.id) return;
-    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,
-        relativeSpeedKph: other.speedKph - car.speedKph,
-      };
-    }
-  });
-  if (!closest) return { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 };
-  const { distanceSimUnits, ...publicHit } = closest;
-  return publicHit;
-}
-
-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;
-}
-
-export function getCarRayOrigin(car) {
-  return {
-    x: car.x,
-    y: car.y,
-  };
-}
-
-export function getCarRayVector(car, angleDegrees) {
-  const angle = car.heading + degreesToRadians(angleDegrees);
-  return {
-    x: Math.cos(angle),
-    y: Math.sin(angle),
-  };
-}
-
-function pointOnRay(origin, ray, distance) {
-  return {
-    x: origin.x + ray.x * distance,
-    y: origin.y + ray.y * distance,
-  };
-}
-
-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);
-}
-
-function intersectAxisAlignedBoxRay(origin, ray, halfLength, halfWidth) {
-  let tMin = -Infinity;
-  let tMax = Infinity;
-  const xRange = intersectSlab(origin.x, ray.x, -halfLength, halfLength);
-  const yRange = intersectSlab(origin.y, ray.y, -halfWidth, halfWidth);
-  if (!xRange || !yRange) return null;
-  tMin = Math.max(tMin, xRange.min, yRange.min);
-  tMax = Math.min(tMax, xRange.max, yRange.max);
-  if (tMax < 0 || tMin > tMax) return null;
-  return Math.max(0, tMin);
-}
-
-function intersectSlab(origin, direction, min, max) {
-  if (Math.abs(direction) < 1e-9) {
-    return origin >= min && origin <= max ? { min: -Infinity, max: Infinity } : null;
-  }
-  const first = (min - origin) / direction;
-  const second = (max - origin) / direction;
-  return {
-    min: Math.min(first, second),
-    max: Math.max(first, second),
-  };
-}
-
-function dot(a, b) {
-  return a.x * b.x + a.y * b.y;
-}
-
-function degreesToRadians(degrees) {
-  return (degrees * Math.PI) / 180;
-}
-
-function normalizeRelativeHeading(angle) {
-  let value = angle;
-  while (value > Math.PI) value -= Math.PI * 2;
-  while (value < -Math.PI) value += Math.PI * 2;
-  return value;
-}
+export * from './sensors/index.js';

package/src/environment/specs.js

@@ -1,4 +1,7 @@
 import { normalizeLookaheadMeters } from './observationOptions.js';
+import { normalizeRayOptions } from './sensors.js';
+
+const PHYSICAL_RAY_SURFACE_CHANNELS = Object.freeze(['kerb', 'illegalSurface']);
 
 export function buildActionSpec(options) {
   const compounds = Array.isArray(options.rules?.modules?.tireStrategy?.compounds) &&
@@ -22,21 +25,32 @@ export function buildActionSpec(options) {
 }
 
 export function buildObservationSpec(options) {
-  const rayOptions = options.sensors.rays;
+  const rayOptions = normalizeRayOptions(options.sensors.rays);
   const nearbyOptions = options.sensors.nearbyCars;
-  const lookaheadMeters = normalizeLookaheadMeters(options.observation?.lookaheadMeters);
+  const lookaheadMeters = Array.isArray(options.observation?.lookaheadMeters)
+    ? options.observation.lookaheadMeters
+    : normalizeLookaheadMeters(options.observation?.lookaheadMeters);
+  const profile = options.observation?.profile ?? 'default';
   return {
-    version: 2,
+    version: profile === 'physical-driver' ? 4 : 2,
     controlledDrivers: [...options.controlledDrivers],
     object: {
+      profile,
       self: [
         { name: 'id', unit: 'id' },
         { name: 'speedKph', unit: 'kph' },
         { name: 'speedMetersPerSecond', unit: 'm/s' },
         { name: 'headingRadians', unit: 'rad' },
+        { name: 'yawRateRadiansPerSecond', unit: 'rad/s' },
         { name: 'steeringAngleRadians', unit: 'rad' },
         { name: 'throttle', unit: 'normalized' },
         { name: 'brake', unit: 'normalized' },
+        { name: 'lateralG', unit: 'g' },
+        { name: 'longitudinalG', unit: 'g' },
+        { name: 'gripUsage', unit: 'ratio' },
+        { name: 'slipAngleRadians', unit: 'rad' },
+        { name: 'tractionLimited', unit: 'boolean' },
+        { name: 'stabilityState', unit: 'label' },
         { name: 'lap', unit: 'count' },
         { name: 'completedLaps', unit: 'count' },
         { name: 'lapProgressMeters', unit: 'm' },
@@ -56,6 +70,27 @@ export function buildObservationSpec(options) {
         { name: 'pitStopPenaltyServiceRemainingSeconds', unit: 'nullable:seconds' },
         { name: 'pitStopsCompleted', unit: 'count' },
       ],
+      trackRelation: [
+        { name: 'lateralOffsetMeters', unit: 'm' },
+        { name: 'headingErrorRadians', unit: 'rad' },
+        { name: 'legalWidthMeters', unit: 'm' },
+        { name: 'leftBoundaryMeters', unit: 'm' },
+        { name: 'rightBoundaryMeters', unit: 'm' },
+        { name: 'onLegalSurface', unit: 'boolean' },
+        { name: 'surface', unit: 'label' },
+      ],
+      contactPatches: {
+        ids: ['front-left', 'front-right', 'rear-left', 'rear-right'],
+        fields: [
+          { name: 'present', unit: 'boolean' },
+          { name: 'signedOffsetMeters', unit: 'm' },
+          { name: 'crossTrackErrorMeters', unit: 'm' },
+          { name: 'surface', unit: 'label' },
+          { name: 'surfaceCode', unit: 'number' },
+          { name: 'onLegalSurface', unit: 'boolean' },
+          { name: 'inPitLane', unit: 'boolean' },
+        ],
+      },
       race: [
         { name: 'position', unit: 'rank' },
         { name: 'totalCars', unit: 'count' },
@@ -68,15 +103,28 @@ export function buildObservationSpec(options) {
         enabled: Boolean(rayOptions.enabled),
         anglesDegrees: [...rayOptions.anglesDegrees],
         lengthMeters: rayOptions.lengthMeters,
+        defaultLengthMeters: rayOptions.defaultLengthMeters,
+        rays: rayOptions.rays.map((ray) => ({ ...ray })),
+        channels: [...rayOptions.channels],
+        precision: rayOptions.precision,
         track: {
           distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
           hit: { unit: 'boolean' },
           kind: { values: ['exit', 'entry', null] },
         },
+        roadEdge: {
+          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+          hit: { unit: 'boolean' },
+          kind: { values: ['exit', 'entry', null] },
+        },
+        kerb: surfaceRaySpec(rayOptions.lengthMeters),
+        illegalSurface: surfaceRaySpec(rayOptions.lengthMeters),
         car: {
           distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
           hit: { unit: 'boolean' },
           driverId: { nullable: true },
+          targetId: { nullable: true },
+          targetType: { values: ['car', 'replayGhost', null] },
           relativeSpeedKph: { unit: 'kph' },
         },
       },
@@ -99,18 +147,24 @@ export function buildObservationSpec(options) {
       events: { type: 'array' },
     },
     vector: {
-      schema: buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }),
+      schema: buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters, profile }),
     },
   };
 }
 
-function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }) {
+function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters, profile = 'default' }) {
+  const includePhysicalDriverSenses = profile === 'physical-driver';
   const schema = [
     { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
     { name: 'self.speedMetersPerSecond', unit: 'm/s', scale: 'fixed:120' },
     { name: 'self.steeringAngleRadians', unit: 'rad', scale: 'fixed:pi' },
     { name: 'self.throttle', scale: '0..1' },
     { name: 'self.brake', scale: '0..1' },
+    { name: 'self.lateralG', scale: 'fixed:8g' },
+    { name: 'self.longitudinalG', scale: 'fixed:6g' },
+    { name: 'self.gripUsage', scale: '0..2' },
+    { name: 'self.slipAngleRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.tractionLimited', scale: 'boolean' },
     { name: 'self.lapProgressRatio', scale: '0..1' },
     { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
     { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
@@ -126,6 +180,22 @@ function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }) {
     { name: 'race.pitLaneOpen', scale: 'boolean' },
     { name: 'track.curvature', scale: 'track-curvature' },
   ];
+  if (includePhysicalDriverSenses) {
+    schema.push(
+      { name: 'self.yawRateRadiansPerSecond', unit: 'rad/s', scale: 'fixed:pi' },
+      { name: 'trackRelation.leftBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
+      { name: 'trackRelation.rightBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
+      { name: 'trackRelation.legalWidthMeters', unit: 'm', scale: 'fixed:meters' },
+    );
+    for (let index = 0; index < 4; index += 1) {
+      schema.push(
+        { name: `contactPatches[${index}].present`, scale: 'boolean' },
+        { name: `contactPatches[${index}].surfaceCode`, scale: 'surface-code' },
+        { name: `contactPatches[${index}].onLegalSurface`, scale: 'boolean' },
+        { name: `contactPatches[${index}].signedOffsetMeters`, unit: 'm', scale: 'fixed:meters' },
+      );
+    }
+  }
   lookaheadMeters.forEach((_, index) => {
     schema.push(
       { name: `track.lookahead[${index}].curvature`, scale: 'track-curvature' },
@@ -143,6 +213,14 @@ function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }) {
         { name: `rays[${index}].car.hit`, scale: 'boolean' },
         { name: `rays[${index}].car.relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
       );
+      if (includePhysicalDriverSenses) {
+        PHYSICAL_RAY_SURFACE_CHANNELS.forEach((channel) => {
+          schema.push(
+            { name: `rays[${index}].${channel}.distanceRatio`, scale: '0..1' },
+            { name: `rays[${index}].${channel}.hit`, scale: 'boolean' },
+          );
+        });
+      }
     });
   }
   if (nearbyOptions.enabled) {
@@ -157,7 +235,24 @@ function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }) {
         { name: `nearbyCars[${index}].ahead`, scale: 'boolean' },
         { name: `nearbyCars[${index}].sameLap`, scale: 'boolean' },
       );
+      if (includePhysicalDriverSenses) {
+        schema.push(
+          { name: `nearbyCars[${index}].behind`, scale: 'boolean' },
+          { name: `nearbyCars[${index}].closingRateMetersPerSecond`, unit: 'm/s', scale: 'fixed:100' },
+          { name: `nearbyCars[${index}].timeToContactSeconds`, unit: 's', scale: 'fixed:10' },
+          { name: `nearbyCars[${index}].leftOverlap`, scale: 'boolean' },
+          { name: `nearbyCars[${index}].rightOverlap`, scale: 'boolean' },
+        );
+      }
     }
   }
   return schema;
 }
+
+function surfaceRaySpec(lengthMeters) {
+  return {
+    distanceMeters: { unit: 'm', noHitValue: lengthMeters },
+    hit: { unit: 'boolean' },
+    surface: { values: ['kerb', 'grass', 'gravel', null] },
+  };
+}

package/src/environment/workerProtocol.js

@@ -15,6 +15,8 @@ export function handleEnvironmentMessage(env, message = {}) {
   switch (message.type) {
     case 'reset':
       return createSuccessResponse(id, 'reset:result', env.reset(message.options ?? {}));
+    case 'resetDrivers':
+      return createSuccessResponse(id, 'resetDrivers:result', env.resetDrivers(message.placements ?? {}, message.resultOptions ?? {}));
     case 'step':
       return createSuccessResponse(id, 'step:result', env.step(message.actions ?? {}));
     case 'getActionSpec':
@@ -24,7 +26,7 @@ export function handleEnvironmentMessage(env, message = {}) {
     case 'getObservation':
       return createSuccessResponse(id, 'getObservation:result', env.getObservation());
     case 'getState':
-      return createSuccessResponse(id, 'getState:result', env.getState());
+      return createSuccessResponse(id, 'getState:result', env.getState(resolveStateOptions(message)));
     case 'destroy':
       env.destroy();
       return createSuccessResponse(id, 'destroy:result', null);
@@ -33,6 +35,16 @@ export function handleEnvironmentMessage(env, message = {}) {
   }
 }
 
+function resolveStateOptions(message) {
+  if (message.stateOptions && typeof message.stateOptions === 'object') {
+    return message.stateOptions;
+  }
+  if (message.resultOptions?.stateOutput) {
+    return { output: message.resultOptions.stateOutput };
+  }
+  return undefined;
+}
+
 function createSuccessResponse(id, type, result) {
   return {
     id,