@inventure71/paddockjs 0.3.0 → 1.0.0

package/src/environment/sensors.js

@@ -1,39 +1,58 @@
 import { nearestTrackState } from '../simulation/trackModel.js';
 import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
-import { VEHICLE_LIMITS } from '../simulation/vehiclePhysics.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 } = {}) {
-  return snapshot.cars
-    .filter((other) => other.id !== car.id)
-    .map((other) => {
-      const dx = other.x - car.x;
-      const dy = other.y - car.y;
-      const distanceMeters = simUnitsToMeters(Math.hypot(dx, dy));
-      const forward = Math.cos(car.heading) * dx + Math.sin(car.heading) * dy;
-      const right = -Math.sin(car.heading) * dx + Math.cos(car.heading) * dy;
-      return {
-        id: other.id,
-        relativeForwardMeters: simUnitsToMeters(forward),
-        relativeRightMeters: simUnitsToMeters(right),
-        relativeDistanceMeters: distanceMeters,
-        relativeSpeedKph: other.speedKph - car.speedKph,
-        relativeHeadingRadians: normalizeRelativeHeading(other.heading - car.heading),
-        ahead: forward > 0,
-        sameLap: other.lap === car.lap,
-      };
-    })
-    .filter((entry) => entry.relativeDistanceMeters <= radiusMeters)
-    .sort((a, b) => a.relativeDistanceMeters - b.relativeDistanceMeters)
-    .slice(0, maxCars);
+  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,
@@ -41,28 +60,49 @@ export function buildRaySensors(car, snapshot, rayOptions = {}) {
     lengthMeters,
     track: rayOptions.detectTrack === false
       ? createTrackMiss(lengthMeters)
-      : estimateTrackHit(car, snapshot, angleDegrees, lengthMeters),
+      : estimateTrackHit(car, snapshot, angleDegrees, lengthMeters, trackContext),
     car: rayOptions.detectCars === false
       ? { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 }
-      : estimateCarHit(car, snapshot, angleDegrees, lengthMeters),
+      : estimateCarHit(car, snapshot, angleDegrees, lengthMeters, origin),
   }));
 }
 
-function estimateTrackHit(car, snapshot, angleDegrees, lengthMeters) {
+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 = getCarRayOrigin(car);
+  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);
+    const inside = isInsideTrackBorder(state, snapshot.track, includePitLane);
     if (previousInside == null) {
       previousInside = inside;
       previousDistance = distance;
@@ -79,6 +119,7 @@ function estimateTrackHit(car, snapshot, angleDegrees, lengthMeters) {
         previousDistance,
         distance,
         kind,
+        includePitLane,
       );
       return {
         hit: true,
@@ -93,6 +134,64 @@ function estimateTrackHit(car, snapshot, angleDegrees, lengthMeters) {
   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);
@@ -122,13 +221,13 @@ function getLocalTrackTransitionTarget({ inside, offsetMeters, lateral, trackHal
   return null;
 }
 
-function refineTrackTransitionDistance(track, origin, ray, progressHint, lowDistance, highDistance, kind) {
+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);
+    const inside = isInsideTrackBorder(state, track, includePitLane);
     if (kind === 'entry') {
       if (inside) high = middle;
       else low = middle;
@@ -141,7 +240,8 @@ function refineTrackTransitionDistance(track, origin, ray, progressHint, lowDist
   return high;
 }
 
-function isInsideTrackBorder(state, track) {
+function isInsideTrackBorder(state, track, includePitLane = true) {
+  if (includePitLane && state.inPitLane) return true;
   return state.crossTrackError <= track.width / 2;
 }
 
@@ -153,13 +253,13 @@ function createTrackMiss(lengthMeters) {
   };
 }
 
-function estimateCarHit(car, snapshot, angleDegrees, lengthMeters) {
-  const origin = getCarRayOrigin(car);
+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);
@@ -178,6 +278,16 @@ function estimateCarHit(car, snapshot, angleDegrees, lengthMeters) {
   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,
@@ -212,8 +322,8 @@ function intersectCarFootprint(origin, ray, other) {
     x: dot(ray, forward),
     y: dot(ray, right),
   };
-  const halfLength = VEHICLE_LIMITS.carLength / 2;
-  const halfWidth = VEHICLE_LIMITS.carWidth / 2;
+  const halfLength = VEHICLE_GEOMETRY.bodyLength / 2;
+  const halfWidth = VEHICLE_GEOMETRY.bodyWidth / 2;
   return intersectAxisAlignedBoxRay(localOrigin, localRay, halfLength, halfWidth);
 }
 

package/src/environment/specs.js

@@ -1,4 +1,10 @@
+import { normalizeLookaheadMeters } from './observationOptions.js';
+
 export function buildActionSpec(options) {
+  const compounds = Array.isArray(options.rules?.modules?.tireStrategy?.compounds) &&
+    options.rules.modules.tireStrategy.compounds.length
+    ? [...options.rules.modules.tireStrategy.compounds]
+    : ['S', 'M', 'H'];
   return {
     version: 1,
     controlledDrivers: [...options.controlledDrivers],
@@ -8,6 +14,8 @@ export function buildActionSpec(options) {
         steering: { min: -1, max: 1, unit: 'normalized' },
         throttle: { min: 0, max: 1, unit: 'normalized' },
         brake: { min: 0, max: 1, unit: 'normalized' },
+        pitIntent: { values: [0, 1, 2], unit: 'request', optional: true },
+        pitCompound: { values: compounds, unit: 'compound', optional: true },
       },
     },
   };
@@ -16,8 +24,9 @@ export function buildActionSpec(options) {
 export function buildObservationSpec(options) {
   const rayOptions = options.sensors.rays;
   const nearbyOptions = options.sensors.nearbyCars;
+  const lookaheadMeters = normalizeLookaheadMeters(options.observation?.lookaheadMeters);
   return {
-    version: 1,
+    version: 2,
     controlledDrivers: [...options.controlledDrivers],
     object: {
       self: [
@@ -35,12 +44,24 @@ export function buildObservationSpec(options) {
         { name: 'trackHeadingErrorRadians', unit: 'rad' },
         { name: 'onTrack', unit: 'boolean' },
         { name: 'surface', unit: 'label' },
+        { name: 'inPitLane', unit: 'boolean' },
+        { name: 'pitLanePart', unit: 'nullable:label' },
+        { name: 'pitBoxId', unit: 'nullable:id' },
         { name: 'tireEnergy', unit: 'nullable:number' },
+        { name: 'pitIntent', unit: '0:none|1:if-free|2:committed' },
+        { name: 'pitTargetCompound', unit: 'nullable:compound' },
+        { name: 'pitStopStatus', unit: 'nullable:label' },
+        { name: 'pitStopPhase', unit: 'nullable:label' },
+        { name: 'pitStopServiceRemainingSeconds', unit: 'nullable:seconds' },
+        { name: 'pitStopPenaltyServiceRemainingSeconds', unit: 'nullable:seconds' },
+        { name: 'pitStopsCompleted', unit: 'count' },
       ],
       race: [
         { name: 'position', unit: 'rank' },
         { name: 'totalCars', unit: 'count' },
         { name: 'raceMode', unit: 'label' },
+        { name: 'pitLaneOpen', unit: 'boolean' },
+        { name: 'redFlag', unit: 'boolean' },
         { name: 'totalLaps', unit: 'count' },
       ],
       rays: {
@@ -64,16 +85,79 @@ export function buildObservationSpec(options) {
         maxCars: nearbyOptions.maxCars,
         radiusMeters: nearbyOptions.radiusMeters,
       },
+      track: {
+        lengthMeters: { unit: 'm' },
+        widthMeters: { unit: 'm' },
+        curvature: { unit: '1/sim-unit' },
+        lookaheadMeters: [...lookaheadMeters],
+        lookahead: {
+          distanceMeters: { unit: 'm' },
+          curvature: { unit: '1/sim-unit' },
+          headingDeltaRadians: { unit: 'rad' },
+        },
+      },
       events: { type: 'array' },
     },
     vector: {
-      schema: [
-        { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
-        { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
-        { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
-        { name: 'self.onTrack', scale: 'boolean' },
-        { name: 'race.position', scale: 'fixed:field-position' },
-      ],
+      schema: buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }),
     },
   };
 }
+
+function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }) {
+  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.lapProgressRatio', scale: '0..1' },
+    { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
+    { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.onTrack', scale: 'boolean' },
+    { name: 'self.inPitLane', scale: 'boolean' },
+    { name: 'self.tireEnergy', scale: '0..100' },
+    { name: 'self.pitIntent', scale: '0..2' },
+    { name: 'self.pitStopActive', scale: 'boolean' },
+    { name: 'race.positionNormalized', scale: '0..1' },
+    { name: 'race.raceModeGreen', scale: 'boolean' },
+    { name: 'race.raceModeSafetyCar', scale: 'boolean' },
+    { name: 'race.redFlag', scale: 'boolean' },
+    { name: 'race.pitLaneOpen', scale: 'boolean' },
+    { name: 'track.curvature', scale: 'track-curvature' },
+  ];
+  lookaheadMeters.forEach((_, index) => {
+    schema.push(
+      { name: `track.lookahead[${index}].curvature`, scale: 'track-curvature' },
+      { name: `track.lookahead[${index}].headingDeltaRadians`, unit: 'rad', scale: 'fixed:pi' },
+    );
+  });
+  if (rayOptions.enabled) {
+    rayOptions.anglesDegrees.forEach((_, index) => {
+      schema.push(
+        { name: `rays[${index}].track.distanceRatio`, scale: '0..1' },
+        { name: `rays[${index}].track.hit`, scale: 'boolean' },
+        { name: `rays[${index}].track.kindExit`, scale: 'boolean' },
+        { name: `rays[${index}].track.kindEntry`, scale: 'boolean' },
+        { name: `rays[${index}].car.distanceRatio`, scale: '0..1' },
+        { name: `rays[${index}].car.hit`, scale: 'boolean' },
+        { name: `rays[${index}].car.relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
+      );
+    });
+  }
+  if (nearbyOptions.enabled) {
+    for (let index = 0; index < nearbyOptions.maxCars; index += 1) {
+      schema.push(
+        { name: `nearbyCars[${index}].present`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].relativeForwardRatio`, scale: '-1..1' },
+        { name: `nearbyCars[${index}].relativeRightRatio`, scale: '-1..1' },
+        { name: `nearbyCars[${index}].relativeDistanceRatio`, scale: '0..1' },
+        { name: `nearbyCars[${index}].relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
+        { name: `nearbyCars[${index}].relativeHeadingRadians`, unit: 'rad', scale: 'fixed:pi' },
+        { name: `nearbyCars[${index}].ahead`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].sameLap`, scale: 'boolean' },
+      );
+    }
+  }
+  return schema;
+}

package/src/environment/workerProtocol.js

@@ -0,0 +1,52 @@
+export function createEnvironmentWorkerProtocol(env) {
+  return {
+    handle(message = {}) {
+      try {
+        return handleEnvironmentMessage(env, message);
+      } catch (error) {
+        return createErrorResponse(message, error);
+      }
+    },
+  };
+}
+
+export function handleEnvironmentMessage(env, message = {}) {
+  const id = message.id ?? null;
+  switch (message.type) {
+    case 'reset':
+      return createSuccessResponse(id, 'reset:result', env.reset(message.options ?? {}));
+    case 'step':
+      return createSuccessResponse(id, 'step:result', env.step(message.actions ?? {}));
+    case 'getActionSpec':
+      return createSuccessResponse(id, 'getActionSpec:result', env.getActionSpec());
+    case 'getObservationSpec':
+      return createSuccessResponse(id, 'getObservationSpec:result', env.getObservationSpec());
+    case 'getObservation':
+      return createSuccessResponse(id, 'getObservation:result', env.getObservation());
+    case 'getState':
+      return createSuccessResponse(id, 'getState:result', env.getState());
+    case 'destroy':
+      env.destroy();
+      return createSuccessResponse(id, 'destroy:result', null);
+    default:
+      throw new Error(`Unsupported PaddockJS environment worker message type: ${message.type}`);
+  }
+}
+
+function createSuccessResponse(id, type, result) {
+  return {
+    id,
+    ok: true,
+    type,
+    result,
+  };
+}
+
+function createErrorResponse(message, error) {
+  return {
+    id: message?.id ?? null,
+    ok: false,
+    type: 'error',
+    error: error instanceof Error ? error.message : String(error),
+  };
+}