@inventure71/paddockjs 0.1.0 → 0.3.0

package/src/environment/options.js

@@ -0,0 +1,150 @@
+import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
+import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
+
+const DEFAULT_SEED = 1971;
+const DEFAULT_FRAME_SKIP = 1;
+const DEFAULT_MAX_STEPS = 10000;
+
+const DEFAULT_SENSOR_OPTIONS = {
+  rays: {
+    enabled: true,
+    anglesDegrees: [-135, -60, -20, 0, 20, 60, 135, 180],
+    lengthMeters: 120,
+    detectTrack: true,
+    detectCars: true,
+  },
+  nearbyCars: {
+    enabled: true,
+    maxCars: 6,
+    radiusMeters: 150,
+  },
+};
+
+export function resolveEnvironmentOptions(options = {}) {
+  if (!Array.isArray(options.controlledDrivers) || options.controlledDrivers.length === 0) {
+    throw new Error('PaddockJS environment controlledDrivers is required.');
+  }
+
+  const seed = normalizeSeed(options.seed, createGeneratedSeed);
+  const trackSeed = normalizeSeed(options.trackSeed, createGeneratedSeed);
+  const normalizedDrivers = normalizeSimulatorDrivers(options.drivers, {
+    entries: options.entries ?? CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+    caller: 'createPaddockEnvironment',
+  });
+  const resolved = {
+    ...options,
+    seed,
+    trackSeed,
+    totalLaps: options.totalLaps,
+    drivers: normalizedDrivers,
+  };
+  const driverIds = new Set(resolved.drivers.map((driver) => driver.id));
+  const controlledDrivers = [...new Set(options.controlledDrivers)];
+
+  controlledDrivers.forEach((driverId) => {
+    if (!driverIds.has(driverId)) {
+      throw new Error(`PaddockJS environment controlled driver does not exist: ${driverId}`);
+    }
+  });
+
+  const scenario = resolveScenario(options.scenario, controlledDrivers, driverIds);
+  const participants = resolveParticipants(scenario.participants, controlledDrivers, resolved.drivers);
+  const participantDrivers = resolved.drivers.filter((driver) => participants.has(driver.id));
+  const participantIds = new Set(participantDrivers.map((driver) => driver.id));
+
+  controlledDrivers.forEach((driverId) => {
+    if (!participantIds.has(driverId)) {
+      throw new Error(`PaddockJS environment controlled driver must be included in scenario participants: ${driverId}`);
+    }
+  });
+
+  return {
+    ...resolved,
+    drivers: participantDrivers,
+    controlledDrivers,
+    frameSkip: normalizePositiveInteger(options.frameSkip, DEFAULT_FRAME_SKIP, 'frameSkip'),
+    actionPolicy: options.actionPolicy === 'report' ? 'report' : 'strict',
+    scenario,
+    sensors: mergeSensorOptions(options.sensors),
+    sensorsByDriver: options.sensorsByDriver ?? {},
+    episode: {
+      maxSteps: normalizePositiveInteger(options.episode?.maxSteps, DEFAULT_MAX_STEPS, 'episode.maxSteps'),
+      endOnRaceFinish: options.episode?.endOnRaceFinish !== false,
+    },
+    reward: typeof options.reward === 'function' ? options.reward : null,
+  };
+}
+
+function normalizeSeed(value, fallbackFactory) {
+  if (value == null) return fallbackFactory();
+  const number = Number(value);
+  return Number.isFinite(number) ? number : DEFAULT_SEED;
+}
+
+function createGeneratedSeed() {
+  const values = new Uint32Array(1);
+  try {
+    globalThis.crypto?.getRandomValues?.(values);
+  } catch {
+    values[0] = 0;
+  }
+  return (values[0] || Math.floor(Date.now() + performance.now() * 1000)) >>> 0;
+}
+
+function resolveScenario(scenario = {}, controlledDrivers, driverIds) {
+  const participants = scenario.participants ?? 'all';
+  if (
+    participants !== 'all' &&
+    participants !== 'controlled-only' &&
+    !Array.isArray(participants)
+  ) {
+    throw new Error('PaddockJS environment scenario.participants must be "all", "controlled-only", or an array of driver ids.');
+  }
+  if (scenario.nonControlled != null && scenario.nonControlled !== 'ai') {
+    throw new Error('PaddockJS environment first slice only supports scenario.nonControlled: "ai".');
+  }
+  if (Array.isArray(participants)) {
+    participants.forEach((driverId) => {
+      if (!driverIds.has(driverId)) {
+        throw new Error(`PaddockJS environment scenario participant does not exist: ${driverId}`);
+      }
+    });
+    controlledDrivers.forEach((driverId) => {
+      if (!participants.includes(driverId)) {
+        throw new Error(`PaddockJS environment controlled driver must be included in scenario participants: ${driverId}`);
+      }
+    });
+  }
+  return {
+    participants,
+    nonControlled: 'ai',
+  };
+}
+
+function resolveParticipants(participants, controlledDrivers, drivers) {
+  if (participants === 'controlled-only') return new Set(controlledDrivers);
+  if (Array.isArray(participants)) return new Set(participants);
+  return new Set(drivers.map((driver) => driver.id));
+}
+
+function normalizePositiveInteger(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Math.floor(Number(value));
+  if (!Number.isFinite(number) || number < 1) {
+    throw new Error(`PaddockJS environment ${label} must be a positive integer.`);
+  }
+  return number;
+}
+
+function mergeSensorOptions(sensors = {}) {
+  return {
+    rays: {
+      ...DEFAULT_SENSOR_OPTIONS.rays,
+      ...(sensors.rays ?? {}),
+    },
+    nearbyCars: {
+      ...DEFAULT_SENSOR_OPTIONS.nearbyCars,
+      ...(sensors.nearbyCars ?? {}),
+    },
+  };
+}

package/src/environment/rewards.js

@@ -0,0 +1,69 @@
+const DEFAULT_PROGRESS_REWARD_WEIGHTS = Object.freeze({
+  progress: 1,
+  speed: 0.01,
+  offTrack: -2,
+  collision: -10,
+  steering: -0.03,
+  brake: -0.02,
+});
+
+export function createProgressReward(options = {}) {
+  const weights = {
+    ...DEFAULT_PROGRESS_REWARD_WEIGHTS,
+    ...(options.weights ?? {}),
+  };
+
+  return function progressReward(context = {}) {
+    const driverId = context.driverId;
+    const previousCar = findSnapshotCar(context.previous, driverId);
+    const currentCar = findSnapshotCar(context.state?.snapshot, driverId);
+    const progressMeters = getProgressMeters(previousCar, currentCar);
+    const self = context.current?.object?.self ?? {};
+    const speedKph = Number(self.speedKph ?? 0);
+    const isOnTrack = self.onTrack !== false;
+    const collisionCount = countDriverCollisions(context.events, driverId);
+    const steering = Math.abs(Number(context.action?.steering ?? 0));
+    const brake = Math.abs(Number(context.action?.brake ?? 0));
+
+    return (
+      progressMeters * weights.progress +
+      (isOnTrack ? speedKph * weights.speed : 0) +
+      (isOnTrack ? 0 : weights.offTrack) +
+      collisionCount * weights.collision +
+      steering * weights.steering +
+      brake * weights.brake
+    );
+  };
+}
+
+function findSnapshotCar(snapshot, driverId) {
+  if (!snapshot || !driverId || !Array.isArray(snapshot.cars)) return null;
+  return snapshot.cars.find((car) => car?.id === driverId) ?? null;
+}
+
+function getProgressMeters(previousCar, currentCar) {
+  if (!previousCar || !currentCar) return 0;
+  const previous = Number(previousCar.distanceMeters ?? previousCar.raceDistanceMeters ?? 0);
+  const current = Number(currentCar.distanceMeters ?? currentCar.raceDistanceMeters ?? 0);
+  if (!Number.isFinite(previous) || !Number.isFinite(current)) return 0;
+  return current - previous;
+}
+
+function countDriverCollisions(events = [], driverId) {
+  if (!driverId || !Array.isArray(events)) return 0;
+  return events.filter((event) => isCollisionEvent(event) && eventIncludesDriver(event, driverId)).length;
+}
+
+function isCollisionEvent(event) {
+  return event?.type === 'collision' || event?.type === 'contact';
+}
+
+function eventIncludesDriver(event, driverId) {
+  if (event.driverId === driverId ||
+      event.carId === driverId ||
+      event.primaryDriverId === driverId ||
+      event.otherDriverId === driverId) {
+    return true;
+  }
+  return Array.isArray(event.driverIds) && event.driverIds.includes(driverId);
+}

package/src/environment/runtime.js

@@ -0,0 +1,140 @@
+import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.js';
+import { resolveActionMap } from './actions.js';
+import { collectStepEvents } from './events.js';
+import { createEpisodeState, evaluateEpisode } from './episode.js';
+import { buildEnvironmentObservation } from './observations.js';
+import { resolveEnvironmentOptions } from './options.js';
+import { buildActionSpec, buildObservationSpec } from './specs.js';
+
+export function createPaddockEnvironment(options = {}) {
+  let resolvedOptions = resolveEnvironmentOptions(options);
+  let sim = createRaceSimulation(resolvedOptions);
+  return createEnvironmentRuntime({
+    getSimulation: () => sim,
+    setSimulation(nextSim) {
+      sim = nextSim;
+    },
+    createSimulation(nextOptions) {
+      return createRaceSimulation(nextOptions);
+    },
+    getOptions: () => resolvedOptions,
+    setOptions(nextOptions) {
+      resolvedOptions = nextOptions;
+    },
+    afterReset() {},
+    afterStep() {},
+  });
+}
+
+export function createEnvironmentRuntime(host) {
+  const episodeState = createEpisodeState();
+
+  function reset(nextOptions = {}) {
+    const options = resolveEnvironmentOptions({
+      ...host.getOptions(),
+      ...nextOptions,
+    });
+    host.setOptions(options);
+    host.setSimulation(host.createSimulation(options));
+    episodeState.step = 0;
+    episodeState.previousSnapshot = null;
+    const result = buildResult({ host, episodeState, events: [], actionErrors: [] });
+    episodeState.lastResult = result;
+    host.afterReset(result);
+    return result;
+  }
+
+  function step(actions = {}) {
+    const options = host.getOptions();
+    const sim = host.getSimulation();
+    const { controlsByDriver, errors } = resolveActionMap(actions, options.controlledDrivers, {
+      policy: options.actionPolicy,
+    });
+
+    Object.entries(controlsByDriver).forEach(([driverId, controls]) => {
+      sim.setCarControls(driverId, controls);
+    });
+
+    episodeState.previousSnapshot = sim.snapshot();
+    const stepEvents = [];
+    for (let index = 0; index < options.frameSkip; index += 1) {
+      sim.step(FIXED_STEP);
+      stepEvents.push(...collectStepEvents(sim.snapshot().events));
+    }
+    episodeState.step += 1;
+    const result = buildResult({ host, episodeState, events: stepEvents, actionErrors: errors, actions });
+    episodeState.lastResult = result;
+    host.afterStep(result);
+    return result;
+  }
+
+  function getObservation() {
+    return episodeState.lastResult?.observation ??
+      buildResult({ host, episodeState, events: [], actionErrors: [] }).observation;
+  }
+
+  function getState() {
+    return { snapshot: host.getSimulation().snapshot() };
+  }
+
+  function getActionSpec() {
+    return buildActionSpec(host.getOptions());
+  }
+
+  function getObservationSpec() {
+    return buildObservationSpec(host.getOptions());
+  }
+
+  function destroy() {
+    episodeState.lastResult = null;
+    episodeState.previousSnapshot = null;
+  }
+
+  return { reset, step, getObservation, getState, getActionSpec, getObservationSpec, destroy };
+}
+
+function buildResult({ host, episodeState, events, actionErrors, actions = {} }) {
+  const options = host.getOptions();
+  const snapshot = host.getSimulation().snapshot();
+  const observation = buildEnvironmentObservation({
+    snapshot,
+    previousSnapshot: episodeState.previousSnapshot,
+    options,
+    events,
+  });
+  const episode = evaluateEpisode(snapshot, options, episodeState);
+  const reward = computeReward({ options, observation, events, snapshot, actions, previousSnapshot: episodeState.previousSnapshot });
+  return {
+    observation,
+    reward,
+    terminated: episode.terminated,
+    truncated: episode.truncated,
+    done: episode.terminated || episode.truncated,
+    events,
+    state: { snapshot },
+    info: {
+      step: episodeState.step,
+      elapsedSeconds: snapshot.time,
+      seed: options.seed,
+      trackSeed: options.trackSeed,
+      controlledDrivers: [...options.controlledDrivers],
+      actionErrors,
+      endReason: episode.endReason,
+    },
+  };
+}
+
+function computeReward({ options, observation, events, snapshot, actions, previousSnapshot }) {
+  if (!options.reward) return null;
+  return Object.fromEntries(options.controlledDrivers.map((driverId) => [
+    driverId,
+    Number(options.reward({
+      driverId,
+      previous: previousSnapshot,
+      current: observation[driverId],
+      action: actions?.[driverId],
+      events: observation[driverId]?.events ?? events,
+      state: { snapshot },
+    }) ?? 0),
+  ]));
+}

package/src/environment/sensors.js

@@ -0,0 +1,257 @@
+import { nearestTrackState } from '../simulation/trackModel.js';
+import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+import { VEHICLE_LIMITS } from '../simulation/vehiclePhysics.js';
+
+const TRACK_RAY_STEP_METERS = 1;
+const TRACK_RAY_REFINE_STEPS = 12;
+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);
+}
+
+export function buildRaySensors(car, snapshot, rayOptions = {}) {
+  const angles = rayOptions.anglesDegrees ?? DEFAULT_RAY_ANGLES_DEGREES;
+  const lengthMeters = rayOptions.lengthMeters ?? 120;
+
+  return angles.map((angleDegrees) => ({
+    angleDegrees,
+    angleRadians: degreesToRadians(angleDegrees),
+    lengthMeters,
+    track: rayOptions.detectTrack === false
+      ? createTrackMiss(lengthMeters)
+      : estimateTrackHit(car, snapshot, angleDegrees, lengthMeters),
+    car: rayOptions.detectCars === false
+      ? { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 }
+      : estimateCarHit(car, snapshot, angleDegrees, lengthMeters),
+  }));
+}
+
+function estimateTrackHit(car, snapshot, angleDegrees, lengthMeters) {
+  if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
+    return estimateLocalTrackHit(car, snapshot, angleDegrees, lengthMeters);
+  }
+
+  const origin = getCarRayOrigin(car);
+  const ray = getCarRayVector(car, angleDegrees);
+  const maxDistance = metersToSimUnits(lengthMeters);
+  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
+  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);
+    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,
+      );
+      return {
+        hit: true,
+        distanceMeters: simUnitsToMeters(hitDistance),
+        kind,
+      };
+    }
+    previousDistance = distance;
+    previousInside = inside;
+  }
+
+  return createTrackMiss(lengthMeters);
+}
+
+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) {
+  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);
+    if (kind === 'entry') {
+      if (inside) high = middle;
+      else low = middle;
+    } else if (inside) {
+      low = middle;
+    } else {
+      high = middle;
+    }
+  }
+  return high;
+}
+
+function isInsideTrackBorder(state, track) {
+  return state.crossTrackError <= track.width / 2;
+}
+
+function createTrackMiss(lengthMeters) {
+  return {
+    hit: false,
+    distanceMeters: lengthMeters,
+    kind: null,
+  };
+}
+
+function estimateCarHit(car, snapshot, angleDegrees, lengthMeters) {
+  const 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;
+    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;
+}
+
+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_LIMITS.carLength / 2;
+  const halfWidth = VEHICLE_LIMITS.carWidth / 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;
+}

package/src/environment/specs.js

@@ -0,0 +1,79 @@
+export function buildActionSpec(options) {
+  return {
+    version: 1,
+    controlledDrivers: [...options.controlledDrivers],
+    action: {
+      type: 'continuous',
+      perDriver: {
+        steering: { min: -1, max: 1, unit: 'normalized' },
+        throttle: { min: 0, max: 1, unit: 'normalized' },
+        brake: { min: 0, max: 1, unit: 'normalized' },
+      },
+    },
+  };
+}
+
+export function buildObservationSpec(options) {
+  const rayOptions = options.sensors.rays;
+  const nearbyOptions = options.sensors.nearbyCars;
+  return {
+    version: 1,
+    controlledDrivers: [...options.controlledDrivers],
+    object: {
+      self: [
+        { name: 'id', unit: 'id' },
+        { name: 'speedKph', unit: 'kph' },
+        { name: 'speedMetersPerSecond', unit: 'm/s' },
+        { name: 'headingRadians', unit: 'rad' },
+        { name: 'steeringAngleRadians', unit: 'rad' },
+        { name: 'throttle', unit: 'normalized' },
+        { name: 'brake', unit: 'normalized' },
+        { name: 'lap', unit: 'count' },
+        { name: 'completedLaps', unit: 'count' },
+        { name: 'lapProgressMeters', unit: 'm' },
+        { name: 'trackOffsetMeters', unit: 'm' },
+        { name: 'trackHeadingErrorRadians', unit: 'rad' },
+        { name: 'onTrack', unit: 'boolean' },
+        { name: 'surface', unit: 'label' },
+        { name: 'tireEnergy', unit: 'nullable:number' },
+      ],
+      race: [
+        { name: 'position', unit: 'rank' },
+        { name: 'totalCars', unit: 'count' },
+        { name: 'raceMode', unit: 'label' },
+        { name: 'totalLaps', unit: 'count' },
+      ],
+      rays: {
+        enabled: Boolean(rayOptions.enabled),
+        anglesDegrees: [...rayOptions.anglesDegrees],
+        lengthMeters: rayOptions.lengthMeters,
+        track: {
+          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+          hit: { unit: 'boolean' },
+          kind: { values: ['exit', 'entry', null] },
+        },
+        car: {
+          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+          hit: { unit: 'boolean' },
+          driverId: { nullable: true },
+          relativeSpeedKph: { unit: 'kph' },
+        },
+      },
+      nearbyCars: {
+        enabled: Boolean(nearbyOptions.enabled),
+        maxCars: nearbyOptions.maxCars,
+        radiusMeters: nearbyOptions.radiusMeters,
+      },
+      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' },
+      ],
+    },
+  };
+}