@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/environment/metrics.js

@@ -0,0 +1,159 @@
+import { normalizeAngle } from '../simulation/simMath.js';
+import { pointAt } from '../simulation/track/trackModel.js';
+import { simUnitsToMeters } from '../simulation/units.js';
+
+const LEGAL_SURFACES = new Set(['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box']);
+const ILLEGAL_SURFACES = new Set(['grass', 'gravel', 'runoff', 'barrier']);
+const UNSTABLE_STATES = new Set(['spun', 'backwards', 'spin-risk', 'understeer', 'oversteer', 'destroyed']);
+
+export function isEnvironmentCarOffTrack(car) {
+  if (!car) return false;
+  return isOffTrack(car, classifyWheels(car));
+}
+
+export function isEnvironmentContactEvent(event) {
+  return ['collision', 'contact', 'car-contact'].includes(event?.type);
+}
+
+export function buildDriverMetrics({ snapshot, previousSnapshot = null, options, events = [] }) {
+  const previousById = new Map((previousSnapshot?.cars ?? []).map((car) => [car.id, car]));
+  const currentById = new Map(snapshot.cars.map((car) => [car.id, car]));
+  const contactCounts = contactCountsByDriver(events);
+  const metrics = {};
+  options.controlledDrivers.forEach((driverId) => {
+    const car = currentById.get(driverId);
+    const previous = previousById.get(driverId);
+    metrics[driverId] = car ? buildMetricForDriver(car, previous, snapshot, contactCounts.get(driverId) ?? 0) : emptyMetrics();
+  });
+  return metrics;
+}
+
+function buildMetricForDriver(car, previous, snapshot, contactCount) {
+  const progressDeltaMeters = progressDelta(car, previous);
+  const wheelState = classifyWheels(car);
+  const offTrack = isOffTrack(car, wheelState);
+  const severeCut = isSevereCut(car, wheelState);
+  const completedLap = completedLaps(car) > completedLaps(previous);
+  const destroyed = Boolean(car.destroyed);
+  return {
+    progressDeltaMeters,
+    legalProgressDeltaMeters: destroyed || offTrack || severeCut ? 0 : Math.max(0, progressDeltaMeters),
+    offTrack,
+    kerb: wheelState.hasKerb,
+    fullyOutsideWhiteLine: wheelState.fullyOutsideWhiteLine,
+    severeCut,
+    destroyed,
+    destroyReason: car.destroyReason ?? null,
+    under30kph: (car.speedKph ?? 0) < 30,
+    spinOrBackwards: isSpinOrBackwards(car, snapshot),
+    completedLap,
+    lapTimeSeconds: completedLap ? lastLapTimeSeconds(car) : null,
+    contactCount,
+  };
+}
+
+function emptyMetrics() {
+  return {
+    progressDeltaMeters: 0,
+    legalProgressDeltaMeters: 0,
+    offTrack: true,
+    kerb: false,
+    fullyOutsideWhiteLine: true,
+    severeCut: true,
+    destroyed: true,
+    destroyReason: 'missing-car',
+    under30kph: true,
+    spinOrBackwards: false,
+    completedLap: false,
+    lapTimeSeconds: null,
+    contactCount: 0,
+  };
+}
+
+function progressDelta(car, previous) {
+  if (!previous) return 0;
+  if (Number.isFinite(car.distanceMeters) && Number.isFinite(previous.distanceMeters)) {
+    return car.distanceMeters - previous.distanceMeters;
+  }
+  return simUnitsToMeters((car.raceDistance ?? car.progress ?? 0) - (previous.raceDistance ?? previous.progress ?? 0));
+}
+
+function isOffTrack(car, wheelState) {
+  if (car.inPitLane) return false;
+  if (wheelState.fullyOutsideWhiteLine) return true;
+  if (wheelState.hasWheels) return wheelState.hasIllegalSurface;
+  return !LEGAL_SURFACES.has(car.surface ?? 'track');
+}
+
+function isSevereCut(car, wheelState) {
+  if (car.inPitLane) return false;
+  if (wheelState.fullyOutsideWhiteLine) return true;
+  if (wheelState.hasWheels) return wheelState.allIllegalSurface;
+  return ILLEGAL_SURFACES.has(car.surface ?? 'track');
+}
+
+function classifyWheels(car) {
+  const wheels = Array.isArray(car.wheels) ? car.wheels : [];
+  if (!wheels.length) {
+    return {
+      hasWheels: false,
+      hasKerb: car.surface === 'kerb',
+      fullyOutsideWhiteLine: false,
+      hasIllegalSurface: false,
+      allIllegalSurface: false,
+    };
+  }
+  let hasKerb = car.surface === 'kerb';
+  let fullyOutsideWhiteLine = true;
+  let hasIllegalSurface = false;
+  let allIllegalSurface = true;
+  wheels.forEach((wheel) => {
+    const surface = wheel.surface ?? 'track';
+    if (surface === 'kerb') hasKerb = true;
+    if (!wheel.fullyOutsideWhiteLine) fullyOutsideWhiteLine = false;
+    if (!LEGAL_SURFACES.has(surface)) hasIllegalSurface = true;
+    if (!ILLEGAL_SURFACES.has(surface)) allIllegalSurface = false;
+  });
+  return {
+    hasWheels: true,
+    hasKerb,
+    fullyOutsideWhiteLine,
+    hasIllegalSurface,
+    allIllegalSurface,
+  };
+}
+
+function isSpinOrBackwards(car, snapshot) {
+  if (UNSTABLE_STATES.has(car.stabilityState)) return true;
+  const trackHeading = car.trackState?.heading ?? pointAt(snapshot.track, car.progress ?? 0).heading;
+  const headingError = Number.isFinite(car.trackHeadingError)
+    ? car.trackHeadingError
+    : normalizeAngle((car.heading ?? trackHeading) - trackHeading);
+  return Math.abs(headingError) > Math.PI * 0.45;
+}
+
+function completedLaps(car) {
+  return car?.lapTelemetry?.completedLaps ?? 0;
+}
+
+function lastLapTimeSeconds(car) {
+  return car.lapTelemetry?.lastLapTime ?? car.lapTelemetry?.bestLapTime ?? null;
+}
+
+function contactCountsByDriver(events) {
+  const counts = new Map();
+  if (!events.length) return counts;
+  events.forEach((event) => {
+    if (!isEnvironmentContactEvent(event)) return;
+    const eventDriverIds = new Set([
+      event.driverId,
+      event.carId,
+      event.otherCarId,
+      ...(event.driverIds ?? []),
+    ].filter(Boolean));
+    eventDriverIds.forEach((driverId) => {
+      counts.set(driverId, (counts.get(driverId) ?? 0) + 1);
+    });
+  });
+  return counts;
+}

package/src/environment/observationOptions.js

@@ -1,6 +1,26 @@
 export const DEFAULT_VECTOR_LOOKAHEAD_METERS = Object.freeze([20, 50, 100, 150]);
+export const OBSERVATION_PROFILES = Object.freeze(['default', 'physical-driver', 'debug-map']);
+export const OBSERVATION_OUTPUTS = Object.freeze(['full', 'vector', 'object']);
+export const OBSERVATION_VECTOR_TYPES = Object.freeze(['array', 'float32']);
 
-export function normalizeLookaheadMeters(value) {
+export function normalizeObservationOptions(value = {}) {
+  const profile = OBSERVATION_PROFILES.includes(value.profile) ? value.profile : 'default';
+  const output = OBSERVATION_OUTPUTS.includes(value.output) ? value.output : 'full';
+  const vectorType = OBSERVATION_VECTOR_TYPES.includes(value.vectorType) ? value.vectorType : 'array';
+  const physicalDriverDefault = profile === 'physical-driver' && value.lookaheadMeters == null;
+  return {
+    ...value,
+    profile,
+    output,
+    vectorType,
+    includeSchema: value.includeSchema !== false,
+    lookaheadMeters: physicalDriverDefault
+      ? []
+      : normalizeLookaheadMeters(value.lookaheadMeters, { allowEmpty: profile === 'physical-driver' }),
+  };
+}
+
+export function normalizeLookaheadMeters(value, { allowEmpty = false } = {}) {
   if (value == null) return [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
   if (!Array.isArray(value)) return [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
 
@@ -8,5 +28,6 @@ export function normalizeLookaheadMeters(value) {
     .map((item) => Number(item))
     .filter((item) => Number.isFinite(item));
 
+  if (allowEmpty && distances.length === 0) return [];
   return distances.length ? distances : [...DEFAULT_VECTOR_LOOKAHEAD_METERS];
 }

package/src/environment/observationVector.js

@@ -0,0 +1,200 @@
+const MODEL_RAY_SURFACE_CHANNELS = Object.freeze(['kerb', 'illegalSurface']);
+
+export function buildObservationVector(source, sensors, { includeSchema = true, vectorType = 'array' } = {}) {
+  const includePhysicalDriverSenses = source.profile === 'physical-driver';
+  const schema = includeSchema ? [
+    { 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' },
+    { 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' },
+  ] : null;
+  const vector = [
+    source.self.speedKph / 400,
+    source.self.speedMetersPerSecond / 120,
+    source.self.steeringAngleRadians / Math.PI,
+    source.self.throttle,
+    source.self.brake,
+    source.self.lateralG / 8,
+    source.self.longitudinalG / 6,
+    source.self.gripUsage / 2,
+    source.self.slipAngleRadians / Math.PI,
+    source.self.tractionLimited ? 1 : 0,
+    normalizeLapProgress(source),
+    source.self.trackOffsetMeters,
+    source.self.trackHeadingErrorRadians / Math.PI,
+    source.self.onTrack ? 1 : 0,
+    source.self.inPitLane ? 1 : 0,
+    (source.self.tireEnergy ?? 0) / 100,
+    (source.self.pitIntent ?? 0) / 2,
+    source.self.pitStopStatus && source.self.pitStopStatus !== 'pending' && source.self.pitStopStatus !== 'completed' ? 1 : 0,
+    normalizeRacePosition(source),
+    source.race.raceMode === 'green' ? 1 : 0,
+    source.race.raceMode === 'safety-car' ? 1 : 0,
+    source.race.redFlag ? 1 : 0,
+    source.race.pitLaneOpen ? 1 : 0,
+    source.track.curvature ?? 0,
+  ];
+  if (includePhysicalDriverSenses) {
+    pushSchema(schema,
+      { 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' },
+    );
+    vector.push(
+      source.self.yawRateRadiansPerSecond / Math.PI,
+      source.trackRelation.leftBoundaryMeters,
+      source.trackRelation.rightBoundaryMeters,
+      source.trackRelation.legalWidthMeters,
+    );
+    source.contactPatches.forEach((patch, index) => {
+      pushSchema(schema,
+        { 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' },
+        { name: `contactPatches[${index}].crossTrackErrorMeters`, unit: 'm', scale: 'fixed:meters' },
+      );
+      vector.push(
+        patch.present ? 1 : 0,
+        patch.surfaceCode / 5,
+        patch.onLegalSurface ? 1 : 0,
+        patch.signedOffsetMeters,
+        patch.crossTrackErrorMeters,
+      );
+    });
+  }
+  source.track.lookahead.forEach((sample, index) => {
+    pushSchema(schema,
+      { name: `track.lookahead[${index}].curvature`, scale: 'track-curvature' },
+      { name: `track.lookahead[${index}].headingDeltaRadians`, unit: 'rad', scale: 'fixed:pi' },
+    );
+    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,
+        );
+      }
+    });
+  });
+  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) {
+    const nearby = source.nearbyCars[index] ?? null;
+    pushSchema(schema,
+      { 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' },
+      { name: `nearbyCars[${index}].entityTypeReplayGhost`, scale: 'boolean' },
+    );
+    vector.push(
+      nearby ? 1 : 0,
+      clampRatio((nearby?.relativeForwardMeters ?? 0) / nearbyRadius),
+      clampRatio((nearby?.relativeRightMeters ?? 0) / nearbyRadius),
+      ratio(nearby?.relativeDistanceMeters ?? nearbyRadius, nearbyRadius),
+      (nearby?.relativeSpeedKph ?? 0) / 200,
+      (nearby?.relativeHeadingRadians ?? 0) / Math.PI,
+      nearby?.ahead ? 1 : 0,
+      nearby?.sameLap ? 1 : 0,
+      nearby?.entityType === 'replayGhost' ? 1 : 0,
+    );
+    if (includePhysicalDriverSenses) {
+      pushSchema(schema,
+        { 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' },
+      );
+      vector.push(
+        nearby?.behind ? 1 : 0,
+        (nearby?.closingRateMetersPerSecond ?? 0) / 100,
+        ratio(nearby?.timeToContactSeconds ?? 10, 10),
+        nearby?.leftOverlap ? 1 : 0,
+        nearby?.rightOverlap ? 1 : 0,
+      );
+    }
+  }
+  return { vector: finalizeVector(vector, vectorType), schema: schema ?? [] };
+}
+
+function finalizeVector(vector, vectorType = 'array') {
+  return vectorType === 'float32' ? Float32Array.from(vector) : vector;
+}
+
+function pushSchema(schema, ...entries) {
+  if (schema) schema.push(...entries);
+}
+
+function normalizeLapProgress(source) {
+  return ratio(source.self.lapProgressMeters, source.track.lengthMeters || 1);
+}
+
+function normalizeRacePosition(source) {
+  const totalCars = Number(source.race.totalCars);
+  const position = Number(source.race.position);
+  if (!Number.isFinite(totalCars) || totalCars <= 1 || !Number.isFinite(position)) return 0;
+  return ratio(position - 1, totalCars - 1);
+}
+
+function ratio(value, max) {
+  const finite = Number.isFinite(value) ? value : max;
+  return Math.max(0, Math.min(1, finite / Math.max(1e-9, max)));
+}
+
+function clampRatio(value) {
+  return Math.max(-1, Math.min(1, Number.isFinite(value) ? value : 0));
+}