@inventure71/paddockjs 3.0.0 → 4.1.0

package/src/environment/observationVector.js

@@ -91,40 +91,36 @@ export function buildObservationVector(source, sensors, { includeSchema = true,
     );
     vector.push(sample.curvature ?? 0, (sample.headingDeltaRadians ?? 0) / Math.PI);
   });
-  source.rays.forEach((ray, index) => {
-    pushSchema(schema,
-      { 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' },
-      { name: `rays[${index}].car.targetTypeReplayGhost`, scale: 'boolean' },
-    );
-    vector.push(
-      ratio(ray.track.distanceMeters, ray.lengthMeters),
-      ray.track.hit ? 1 : 0,
-      ray.track.kind === 'exit' ? 1 : 0,
-      ray.track.kind === 'entry' ? 1 : 0,
-      ratio(ray.car.distanceMeters, ray.lengthMeters),
-      ray.car.hit ? 1 : 0,
-      ray.car.relativeSpeedKph / 200,
-      ray.car.targetType === 'replayGhost' ? 1 : 0,
-    );
-    MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
-      if (sensors.rays.channels?.includes?.(channel)) {
-        pushSchema(schema,
-          { name: `rays[${index}].${channel}.distanceRatio`, scale: '0..1' },
-          { name: `rays[${index}].${channel}.hit`, scale: 'boolean' },
-        );
-        vector.push(
-          ratio(ray[channel]?.distanceMeters ?? ray.lengthMeters, ray.lengthMeters),
-          ray[channel]?.hit ? 1 : 0,
-        );
-      }
+  if (typeof source.appendRayVectorValues === 'function') {
+    source.appendRayVectorValues(vector);
+  } else if (Array.isArray(source.rayVectorValues)) {
+    source.rayVectorValues.forEach((values, index) => {
+      pushRaySchema(schema, index, sensors);
+      vector.push(...values);
     });
-  });
+  } else {
+    source.rays.forEach((ray, index) => {
+      pushRaySchema(schema, index, sensors);
+      vector.push(
+        ratio(ray.track.distanceMeters, ray.lengthMeters),
+        ray.track.hit ? 1 : 0,
+        ray.track.kind === 'exit' ? 1 : 0,
+        ray.track.kind === 'entry' ? 1 : 0,
+        ratio(ray.car.distanceMeters, ray.lengthMeters),
+        ray.car.hit ? 1 : 0,
+        ray.car.relativeSpeedKph / 200,
+        ray.car.targetType === 'replayGhost' ? 1 : 0,
+      );
+      MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
+        if (sensors.rays.channels?.includes?.(channel)) {
+          vector.push(
+            ratio(ray[channel]?.distanceMeters ?? ray.lengthMeters, ray.lengthMeters),
+            ray[channel]?.hit ? 1 : 0,
+          );
+        }
+      });
+    });
+  }
   const nearbyLimit = sensors.nearbyCars.enabled ? (sensors.nearbyCars.maxCars ?? source.nearbyCars.length) : 0;
   const nearbyRadius = sensors.nearbyCars.radiusMeters ?? 150;
   for (let index = 0; index < nearbyLimit; index += 1) {
@@ -179,6 +175,27 @@ function pushSchema(schema, ...entries) {
   if (schema) schema.push(...entries);
 }
 
+function pushRaySchema(schema, index, sensors) {
+  pushSchema(schema,
+    { 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' },
+    { name: `rays[${index}].car.targetTypeReplayGhost`, scale: 'boolean' },
+  );
+  MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
+    if (sensors.rays.channels?.includes?.(channel)) {
+      pushSchema(schema,
+        { name: `rays[${index}].${channel}.distanceRatio`, scale: '0..1' },
+        { name: `rays[${index}].${channel}.hit`, scale: 'boolean' },
+      );
+    }
+  });
+}
+
 function normalizeLapProgress(source) {
   return ratio(source.self.lapProgressMeters, source.track.lengthMeters || 1);
 }

package/src/environment/observations.js

@@ -6,18 +6,37 @@ import { buildBodySenses } from './sensors/bodySenses.js';
 import { buildBoundarySenses } from './sensors/boundarySenses.js';
 import { buildContactPatchSenses } from './sensors/contactSenses.js';
 import { enrichOpponentRadar } from './sensors/opponentRadar.js';
-import { buildNearbyCars, buildRaySensors, createRayBatchContext, normalizeRayOptions } from './sensors.js';
+import {
+  buildNearbyCars,
+  appendRaySensorVectorValues,
+  buildRaySensors,
+  createRayBatchContext,
+  normalizeRayOptions,
+} from './sensors.js';
 import { buildObservationVector } from './observationVector.js';
 
 const EMPTY_EVENTS = Object.freeze([]);
 
-export function buildEnvironmentObservation({ snapshot, options, events = [], controlledDrivers = options.controlledDrivers }) {
-  const carsById = new Map(snapshot.cars.map((entry) => [entry.id, entry]));
-  const eventsByDriver = groupEventsByDriver(events, controlledDrivers);
+export function buildEnvironmentObservation({
+  snapshot,
+  options,
+  events = [],
+  controlledDrivers = options.controlledDrivers,
+  scratch = null,
+}) {
+  const carsById = carsByIdForObservation(snapshot, scratch);
+  const eventsByDriver = groupEventsByDriver(events, controlledDrivers, scratch);
   const defaultSensors = defaultSensorOptions(options);
   const hasSensorOverrides = Object.keys(options.sensorsByDriver ?? {}).length > 0;
   let rayBatchContext = null;
-  const getRayBatchContext = () => {
+  let rayScratchBatchContext = null;
+  const getRayBatchContext = ({ scratch: useScratch = false } = {}) => {
+    if (useScratch) {
+      rayScratchBatchContext ??= createRayBatchContext(snapshot, {
+        scratch: rayBatchContextScratchForObservation(scratch),
+      });
+      return rayScratchBatchContext;
+    }
     rayBatchContext ??= createRayBatchContext(snapshot);
     return rayBatchContext;
   };
@@ -66,24 +85,65 @@ function formatObservation(observation, options = {}) {
   return formatted;
 }
 
-function groupEventsByDriver(events, controlledDrivers) {
+function carsByIdForObservation(snapshot, scratch) {
+  if (!scratch) return new Map(snapshot.cars.map((entry) => [entry.id, entry]));
+  const carsById = scratch.carsById ?? new Map();
+  scratch.carsById = carsById;
+  carsById.clear();
+  for (let index = 0; index < snapshot.cars.length; index += 1) {
+    const entry = snapshot.cars[index];
+    carsById.set(entry.id, entry);
+  }
+  return carsById;
+}
+
+function groupEventsByDriver(events, controlledDrivers, scratch = null) {
   if (!events.length) return null;
-  const byDriver = new Map(controlledDrivers.map((driverId) => [driverId, []]));
-  const controlledSet = new Set(controlledDrivers);
+  const byDriver = scratch ? (scratch.eventsByDriver ?? new Map()) : new Map();
+  const controlledSet = scratch ? (scratch.controlledEventDrivers ?? new Set()) : new Set();
+  const eventDriverIds = scratch ? (scratch.eventDriverIds ?? []) : [];
+  if (scratch) {
+    scratch.eventsByDriver = byDriver;
+    scratch.controlledEventDrivers = controlledSet;
+    scratch.eventDriverIds = eventDriverIds;
+  }
+  byDriver.clear();
+  controlledSet.clear();
+  for (let index = 0; index < controlledDrivers.length; index += 1) {
+    const driverId = controlledDrivers[index];
+    byDriver.set(driverId, []);
+    controlledSet.add(driverId);
+  }
   events.forEach((event) => {
-    const driverIds = new Set([
-      event.driverId,
-      event.carId,
-      event.otherCarId,
-      ...(event.driverIds ?? []),
-    ].filter(Boolean));
-    driverIds.forEach((driverId) => {
+    eventDriverIds.length = 0;
+    pushEventDriverId(eventDriverIds, event.driverId);
+    pushEventDriverId(eventDriverIds, event.carId);
+    pushEventDriverId(eventDriverIds, event.otherCarId);
+    const extraDriverIds = event.driverIds ?? [];
+    for (let index = 0; index < extraDriverIds.length; index += 1) {
+      pushEventDriverId(eventDriverIds, extraDriverIds[index]);
+    }
+    for (let index = 0; index < eventDriverIds.length; index += 1) {
+      const driverId = eventDriverIds[index];
       if (controlledSet.has(driverId)) byDriver.get(driverId)?.push(event);
-    });
+    }
   });
+  eventDriverIds.length = 0;
   return byDriver;
 }
 
+function pushEventDriverId(target, driverId) {
+  if (!driverId || target.includes(driverId)) return;
+  target.push(driverId);
+}
+
+function rayBatchContextScratchForObservation(scratch) {
+  if (!scratch) return true;
+  const rayScratch = scratch.rayBatchContextScratch ?? {};
+  scratch.rayBatchContextScratch = rayScratch;
+  return rayScratch;
+}
+
 function buildDriverObservationObject(car, snapshot, options, events, sensors, getRayBatchContext = null) {
   const sensorCar = withEnvironmentControlFlag(car, options);
   const onTrack = isCarLegallyOnTrack(car);
@@ -186,7 +246,15 @@ function buildDriverVectorDirect(car, snapshot, options, events, sensors, getRay
     headingErrorRadians: trackHeadingError,
   };
   const contactPatches = includePhysicalDriverSenses ? buildContactPatchSenses(car) : [];
-  const rays = sensors.rays.enabled ? buildRaySensors(sensorCar, snapshot, sensors.rays, rayBatchContextForSensors(sensors, getRayBatchContext)) : [];
+  const appendRayVectorValues = sensors.rays.enabled
+    ? (vector) => appendRaySensorVectorValues(
+      vector,
+      sensorCar,
+      snapshot,
+      sensors.rays,
+      rayBatchContextForSensors(sensors, getRayBatchContext, { scratch: true }),
+    )
+    : null;
   const nearbyCars = sensors.nearbyCars.enabled
     ? enrichOpponentRadar(car, buildNearbyCars(car, snapshot, sensors.nearbyCars), snapshot)
     : [];
@@ -219,7 +287,8 @@ function buildDriverVectorDirect(car, snapshot, options, events, sensors, getRay
       curvature: trackCurvature,
       lookahead: buildTrackLookahead(car, snapshot, options),
     },
-    rays,
+    rays: [],
+    appendRayVectorValues,
     nearbyCars,
   };
   return buildObservationVector(source, sensors, {
@@ -228,9 +297,9 @@ function buildDriverVectorDirect(car, snapshot, options, events, sensors, getRay
   });
 }
 
-function rayBatchContextForSensors(sensors, getRayBatchContext) {
+function rayBatchContextForSensors(sensors, getRayBatchContext, { scratch = false } = {}) {
   if (!getRayBatchContext || !sensors.rays?.channels?.includes('car')) return null;
-  return getRayBatchContext();
+  return getRayBatchContext({ scratch });
 }
 
 export function defaultSensorOptions(options) {

package/src/environment/runtime.js

@@ -195,6 +195,9 @@ export function createEnvironmentRuntime(host) {
     episodeState.lastObservationSnapshot = null;
     episodeState.lastRewardSnapshot = null;
     episodeState.drivers?.clear?.();
+    episodeState.destroyedCarsById?.clear?.();
+    clearObservationScratch(episodeState.observationScratch);
+    clearMetricScratch(episodeState.metricScratch);
   }
 
   return { reset, step, resetDrivers, getObservation, getState, getActionSpec, getObservationSpec, destroy };
@@ -292,6 +295,7 @@ function buildResult({
     options,
     events,
     controlledDrivers: resultDrivers,
+    scratch: episodeState.observationScratch,
   });
   const episode = evaluateEpisode(observationSnapshot, options, episodeState, resultDrivers);
   const metrics = buildDriverMetrics({
@@ -299,6 +303,7 @@ function buildResult({
     previousSnapshot: episodeState.previousSnapshot,
     options: { ...options, controlledDrivers: resultDrivers },
     events,
+    scratch: episodeState.metricScratch,
   });
   const rewardEpisodeInfo = buildDriverEpisodeInfo(episodeState, {
     ...options,
@@ -345,6 +350,42 @@ function buildResult({
   };
 }
 
+function clearObservationScratch(scratch) {
+  if (!scratch) return;
+  scratch.carsById?.clear?.();
+  scratch.eventsByDriver?.clear?.();
+  scratch.controlledEventDrivers?.clear?.();
+  clearRayBatchContextScratch(scratch.rayBatchContextScratch);
+  if (Array.isArray(scratch.eventDriverIds)) scratch.eventDriverIds.length = 0;
+}
+
+function clearRayBatchContextScratch(scratch) {
+  if (!scratch) return;
+  const arrayKeys = [
+    'rayTargets',
+    'rayTargetPool',
+    'carTargets',
+    'rayVectors',
+    'sharedRayQueries',
+    'rays',
+    'rayPool',
+    'rayVectorValues',
+    'rayVectorValuePool',
+  ];
+  for (let index = 0; index < arrayKeys.length; index += 1) {
+    const value = scratch[arrayKeys[index]];
+    if (Array.isArray(value)) value.length = 0;
+  }
+}
+
+function clearMetricScratch(scratch) {
+  if (!scratch) return;
+  scratch.previousCarsById?.clear?.();
+  scratch.currentCarsById?.clear?.();
+  scratch.contactCounts?.clear?.();
+  if (Array.isArray(scratch.eventDriverIds)) scratch.eventDriverIds.length = 0;
+}
+
 function applyControlledRunoffResponse(sim, options) {
   options?.controlledDrivers?.forEach?.((driverId) => {
     const car = sim?.cars?.find?.((item) => item.id === driverId);

package/src/environment/sensors/carRays.js

@@ -1,6 +1,6 @@
 import { metersToSimUnits, simUnitsToMeters } from '../../simulation/units.js';
 import { VEHICLE_GEOMETRY } from '../../simulation/vehicle/vehicleGeometry.js';
-import { dot, getCarRayOrigin, getCarRayVector, intersectAxisAlignedBoxRay } from './rayGeometry.js';
+import { getCarRayOrigin, getCarRayVector, intersectAxisAlignedBoxRayScalars } from './rayGeometry.js';
 import { rayDetectableTargets } from './sensorTargets.js';
 
 export function estimateCarHit(
@@ -10,41 +10,53 @@ export function estimateCarHit(
   lengthMeters,
   origin = getCarRayOrigin(car),
   targets = rayDetectableTargets(car, snapshot),
+  options = {},
 ) {
-  const ray = getCarRayVector(car, angleDegrees);
+  const ray = options.rayVector ?? getCarRayVector(car, angleDegrees);
+  if (options.stats) {
+    if (options.rayVector) options.stats.callerVectorCount += 1;
+    else options.stats.computedVectorCount += 1;
+  }
   const maxDistance = metersToSimUnits(lengthMeters);
-  let closest = null;
+  let closestTarget = null;
+  let closestDistance = Infinity;
   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 (hitDistance < closestDistance) {
+      closestDistance = hitDistance;
+      closestTarget = other;
     }
   });
-  if (!closest) return createCarRayMiss(lengthMeters);
-  const { distanceSimUnits, ...publicHit } = closest;
-  return publicHit;
+  const resultTarget = options.resultTarget ?? null;
+  if (resultTarget && options.stats) options.stats.resultTargetCount += 1;
+  if (!closestTarget) return writeCarRayMiss(resultTarget ?? {}, lengthMeters);
+  return writeCarRayResult(resultTarget ?? {}, car, closestTarget, closestDistance);
 }
 
 export function createCarRayMiss(lengthMeters) {
-  return {
-    hit: false,
-    distanceMeters: lengthMeters,
-    driverId: null,
-    targetId: null,
-    targetType: null,
-    relativeSpeedKph: 0,
-  };
+  return writeCarRayMiss({}, lengthMeters);
+}
+
+function writeCarRayMiss(target, lengthMeters) {
+  target.hit = false;
+  target.distanceMeters = lengthMeters;
+  target.driverId = null;
+  target.targetId = null;
+  target.targetType = null;
+  target.relativeSpeedKph = 0;
+  return target;
+}
+
+function writeCarRayResult(target, car, other, distanceSimUnits) {
+  target.hit = true;
+  target.distanceMeters = simUnitsToMeters(distanceSimUnits);
+  target.driverId = other.id;
+  target.targetId = other.id;
+  target.targetType = other.entityType;
+  target.relativeSpeedKph = other.speedKph - car.speedKph;
+  return target;
 }
 
 function carRayBroadphaseHit(origin, ray, maxDistance, other) {
@@ -58,18 +70,17 @@ function carRayBroadphaseHit(origin, ray, maxDistance, other) {
 }
 
 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 forwardX = Math.cos(other.heading);
+  const forwardY = Math.sin(other.heading);
+  const rightX = -forwardY;
+  const rightY = forwardX;
+  const deltaX = origin.x - other.x;
+  const deltaY = origin.y - other.y;
+  const localOriginX = deltaX * forwardX + deltaY * forwardY;
+  const localOriginY = deltaX * rightX + deltaY * rightY;
+  const localRayX = ray.x * forwardX + ray.y * forwardY;
+  const localRayY = ray.x * rightX + ray.y * rightY;
   const halfLength = VEHICLE_GEOMETRY.bodyLength / 2;
   const halfWidth = VEHICLE_GEOMETRY.bodyWidth / 2;
-  return intersectAxisAlignedBoxRay(localOrigin, localRay, halfLength, halfWidth);
+  return intersectAxisAlignedBoxRayScalars(localOriginX, localOriginY, localRayX, localRayY, halfLength, halfWidth);
 }