@inventure71/paddockjs 4.0.0 → 4.2.0

package/src/simulation/track/trackModel.js

@@ -6,6 +6,7 @@ import { generateCenterlineControls, generateFallbackCenterlineControls, generat
 import { isValidProceduralTrackModel } from './trackValidation.js';
 import { recalculateSampleGeometry } from './sampleGeometry.js';
 import { rotateSamplesToStandingStart, straightenStandingStartSamples } from './startStraight.js';
+import { prepareSampleIndexLut } from './spatialQueries.js';
 import { createTrackSectors } from './trackSectors.js';
 import { deriveDrsZones, normalizeDrsZone } from './drsZones.js';
 import { createPitLaneModel } from './pitLaneLayout.js';
@@ -15,7 +16,14 @@ import { attachTrackSnapshotJsonSerializer } from './trackSnapshotJson.js';
 
 export { WORLD, TRACK } from './trackConstants.js';
 export { isInDrsZone } from './drsZones.js';
-export { nearestTrackState, offsetTrackPoint, pointAt } from './spatialQueries.js';
+export {
+  nearestTrackState,
+  offsetTrackPoint,
+  pointAt,
+  pointAtInto,
+  sampleHeadingAt,
+  sampleHeadingCurvatureAtInto,
+} from './spatialQueries.js';
 
 const PROCEDURAL_TRACK_CACHE = new Map();
 const TRACK_MODEL_CACHE = new WeakMap();
@@ -57,6 +65,7 @@ export function buildTrackModel(track = TRACK) {
     ? null
     : createPitLaneModel(model);
   attachTrackQueryIndex(model, createTrackQueryIndex(model));
+  prepareSampleIndexLut(model);
   attachTrackSnapshotJsonSerializer(model);
   if (canReuseCachedModel) {
     TRACK_MODEL_CACHE.set(track, freezeTrackModel(model));

package/src/simulation/vehicle/contactResolution.js

@@ -6,7 +6,7 @@ import {
 } from '../collisionGeometry.js';
 import { canCollide, isCollidable } from '../participants/participantInteractions.js';
 import { clamp, normalizeAngle } from '../simMath.js';
-import { VEHICLE_LIMITS } from './vehiclePhysics.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode } from './vehiclePhysics.js';
 import { shiftPreviousRenderPose } from '../pit/pitRouting.js';
 
 const MAX_COLLISION_CORRECTION = 4.5;
@@ -114,8 +114,8 @@ export function resolveCollisionsForSimulation(sim) {
       }
 
       if (oneCarFixed) {
-        if (!firstPitControlled) dampPitContactVelocity(first, 0.985, sim.physicsMode === 'advanced');
-        if (!secondPitControlled) dampPitContactVelocity(second, 0.985, sim.physicsMode === 'advanced');
+        if (!firstPitControlled) dampPitContactVelocity(first, 0.985, isSimulatorPhysicsMode(sim.physicsMode));
+        if (!secondPitControlled) dampPitContactVelocity(second, 0.985, isSimulatorPhysicsMode(sim.physicsMode));
       } else {
         applyContactVelocityResponse(sim, first, second, collision.axis);
       }
@@ -167,7 +167,7 @@ export function resolveCollisionsForSimulation(sim) {
 export function applyContactVelocityResponse(sim, first, second, axis, options = {}) {
   recordContactVelocityResponse(options.stats);
   if (
-    sim.physicsMode === 'advanced' ||
+    isSimulatorPhysicsMode(sim.physicsMode) ||
     Number.isFinite(first.velocityX) ||
     Number.isFinite(second.velocityX)
   ) {

package/src/simulation/vehicle/vehicleGeometry.js

@@ -274,33 +274,22 @@ function sweptPoseSignature(pose) {
   ].join(':');
 }
 
-function geometryPose(car) {
-  const { x, y, heading } = currentPoseState(car);
-  return {
-    x,
-    y,
-    heading,
-    previousX: finiteOr(car.previousX, x),
-    previousY: finiteOr(car.previousY, y),
-    previousHeading: normalizeAngle(finiteOr(car.previousHeading, heading)),
-  };
-}
-
 function currentGeometryStateMatches(car, state) {
   const pose = state?.pose;
   if (!pose) return false;
-  const currentPose = currentPoseState(car);
   return (
-    pose.x === currentPose.x &&
-    pose.y === currentPose.y &&
-    pose.heading === currentPose.heading
+    pose.x === finiteOr(car.x, 0) &&
+    pose.y === finiteOr(car.y, 0) &&
+    pose.heading === normalizeAngle(finiteOr(car.heading, 0))
   );
 }
 
 function geometryStateMatches(car, state) {
   const pose = state?.pose;
   if (!pose) return false;
-  const { x, y, heading } = currentPoseState(car);
+  const x = finiteOr(car.x, 0);
+  const y = finiteOr(car.y, 0);
+  const heading = normalizeAngle(finiteOr(car.heading, 0));
   return (
     pose.x === x &&
     pose.y === y &&
@@ -312,6 +301,10 @@ function geometryStateMatches(car, state) {
 }
 
 export function createVehicleShapeAabb(shape) {
+  return writeVehicleShapeAabb({}, shape);
+}
+
+function writeVehicleShapeAabb(target, shape) {
   let minX = Infinity;
   let maxX = -Infinity;
   let minY = Infinity;
@@ -323,12 +316,11 @@ export function createVehicleShapeAabb(shape) {
     if (corner.y < minY) minY = corner.y;
     if (corner.y > maxY) maxY = corner.y;
   }
-  return {
-    minX,
-    maxX,
-    minY,
-    maxY,
-  };
+  target.minX = minX;
+  target.maxX = maxX;
+  target.minY = minY;
+  target.maxY = maxY;
+  return target;
 }
 
 export function mergeAabbs(aabbs) {
@@ -346,32 +338,73 @@ export function mergeAabbs(aabbs) {
   return { minX, maxX, minY, maxY };
 }
 
-export function createVehicleGeometryState(car) {
-  const pose = geometryPose(car);
-  const current = writeVehicleGeometry(null, pose);
-  const previous = writeVehicleGeometry(null, {
-    x: pose.previousX,
-    y: pose.previousY,
-    heading: pose.previousHeading,
-  });
-  const bodyAabb = createVehicleShapeAabb(current.body);
-  const previousBodyAabb = createVehicleShapeAabb(previous.body);
-  const sweptBodyAabb = mergeAabbs([previousBodyAabb, bodyAabb]);
+function writeGeometryPose(target, car) {
+  const pose = target ?? {};
+  const x = finiteOr(car.x, 0);
+  const y = finiteOr(car.y, 0);
+  const heading = normalizeAngle(finiteOr(car.heading, 0));
+  pose.x = x;
+  pose.y = y;
+  pose.heading = heading;
+  pose.previousX = finiteOr(car.previousX, x);
+  pose.previousY = finiteOr(car.previousY, y);
+  pose.previousHeading = normalizeAngle(finiteOr(car.previousHeading, heading));
+  return pose;
+}
 
-  return {
-    pose,
-    currentSignature: currentPoseSignature(pose),
-    sweptSignature: sweptPoseSignature(pose),
-    signature: sweptPoseSignature(pose),
-    current,
-    previous,
-    body: current.body,
-    wheels: current.wheels,
-    contactPatches: current.contactPatches,
-    bodyAabb,
-    previousBodyAabb,
-    sweptBodyAabb,
+function createGeometryStateShell() {
+  const state = {
+    pose: null,
+    current: null,
+    previous: null,
+    body: null,
+    wheels: null,
+    contactPatches: null,
+    bodyAabb: {},
+    previousBodyAabb: {},
+    sweptBodyAabb: {},
   };
+  // Signatures are derived lazily from the pose: nothing on the hot path reads
+  // them, so the per-step string formatting cost must not be paid eagerly.
+  Object.defineProperties(state, {
+    currentSignature: {
+      get() { return currentPoseSignature(this.pose); },
+      enumerable: true,
+    },
+    sweptSignature: {
+      get() { return sweptPoseSignature(this.pose); },
+      enumerable: true,
+    },
+    signature: {
+      get() { return sweptPoseSignature(this.pose); },
+      enumerable: true,
+    },
+  });
+  return state;
+}
+
+const PREVIOUS_GEOMETRY_POSE_SCRATCH = { x: 0, y: 0, heading: 0 };
+
+export function createVehicleGeometryState(car, target = null) {
+  const state = target ?? createGeometryStateShell();
+  const pose = state.pose = writeGeometryPose(state.pose, car);
+  const current = state.current = writeVehicleGeometry(state.current, pose);
+  PREVIOUS_GEOMETRY_POSE_SCRATCH.x = pose.previousX;
+  PREVIOUS_GEOMETRY_POSE_SCRATCH.y = pose.previousY;
+  PREVIOUS_GEOMETRY_POSE_SCRATCH.heading = pose.previousHeading;
+  const previous = state.previous = writeVehicleGeometry(state.previous, PREVIOUS_GEOMETRY_POSE_SCRATCH);
+  const bodyAabb = writeVehicleShapeAabb(state.bodyAabb, current.body);
+  const previousBodyAabb = writeVehicleShapeAabb(state.previousBodyAabb, previous.body);
+  const sweptBodyAabb = state.sweptBodyAabb;
+  sweptBodyAabb.minX = Math.min(bodyAabb.minX, previousBodyAabb.minX);
+  sweptBodyAabb.maxX = Math.max(bodyAabb.maxX, previousBodyAabb.maxX);
+  sweptBodyAabb.minY = Math.min(bodyAabb.minY, previousBodyAabb.minY);
+  sweptBodyAabb.maxY = Math.max(bodyAabb.maxY, previousBodyAabb.maxY);
+
+  state.body = current.body;
+  state.wheels = current.wheels;
+  state.contactPatches = current.contactPatches;
+  return state;
 }
 
 export function createCurrentVehicleGeometryState(car, target = null) {
@@ -388,8 +421,13 @@ export function createCurrentVehicleGeometryState(car, target = null) {
 
 export function getVehicleGeometryState(car) {
   if (geometryStateMatches(car, car.geometryState)) return car.geometryState;
-  car.geometryState = createVehicleGeometryState(car);
-  return car.geometryState;
+  // Double-buffer pooled states: consumers may still hold the state returned
+  // for the previous pose within a step, so alternate between two reusable
+  // shells instead of allocating a fresh geometry tree on every pose change.
+  const next = createVehicleGeometryState(car, car._geometryStateSpare ?? null);
+  car._geometryStateSpare = car.geometryState ?? null;
+  car.geometryState = next;
+  return next;
 }
 
 export function getCurrentVehicleGeometryState(car) {

package/src/simulation/vehicle/vehiclePhysics.js

@@ -50,7 +50,11 @@ const SIMULATOR_SURFACE_MODEL = {
 };
 
 export function normalizePhysicsMode(value) {
-  return value === 'advanced' ? 'advanced' : DEFAULT_PHYSICS_MODE;
+  return PHYSICS_MODES.includes(value) ? value : DEFAULT_PHYSICS_MODE;
+}
+
+export function isSimulatorPhysicsMode(value) {
+  return value === 'advanced';
 }
 
 function accelerationLimit(speed, surfaceGrip) {
@@ -120,7 +124,8 @@ function setPhysicsTelemetry(car, {
 }
 
 export function integrateVehiclePhysics(car, controls, dt, options = {}) {
-  if (normalizePhysicsMode(options.physicsMode) === 'advanced') {
+  const mode = normalizePhysicsMode(options.physicsMode);
+  if (mode === 'advanced') {
     return integrateSimulatorVehiclePhysics(car, controls, dt, options);
   }
   return integrateArcadeVehiclePhysics(car, controls, dt, options);

package/src/simulation/vehicle/vehicleSnapshots.js

@@ -1,4 +1,7 @@
-import { serializeParticipantInteraction } from '../participants/participantInteractions.js';
+import {
+  serializeParticipantInteraction,
+  serializeParticipantInteractionCached,
+} from '../participants/participantInteractions.js';
 
 export function finiteOrNull(value) {
   return Number.isFinite(value) ? value : null;
@@ -185,7 +188,7 @@ export function serializeRenderCarInto(target, car, dependencies) {
   target.dnfOrder = car.dnfOrder ?? null;
   target.outOfRace = Boolean(car.outOfRace || car.destroyed);
   target.pitStop = serializeRenderPitStop(car.pitStop);
-  target.interaction = serializeParticipantInteraction(car.interaction);
+  target.interaction = serializeParticipantInteractionCached(car);
   return target;
 }
 

package/src/simulation/vehicle/vehicleState.js

@@ -2,7 +2,7 @@ import { buildDriverPersonality } from '../driverController.js';
 import { clamp, normalizeAngle, seededRange } from '../simMath.js';
 import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
 import { kphToSimSpeed, metersToSimUnits } from '../units.js';
-import { VEHICLE_LIMITS } from './vehiclePhysics.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode } from './vehiclePhysics.js';
 import { applyWheelSurfaceState } from './wheelSurface.js';
 import { nearestTrackStateForCar } from '../track/trackStatePolicy.js';
 import { clearCarDnf } from '../race/retirements.js';
@@ -73,6 +73,7 @@ export function createCar(driver, index, random, track, { standingStart = false,
     downforceCoefficient: vehicle.downforceCoefficient ?? 6.1 + seededRange(random, -0.18, 0.18),
     tireGrip: vehicle.tireGrip ?? 2.22 + racecraft * 0.28 + seededRange(random, -0.03, 0.03),
     tireCare: vehicle.tireCare ?? 1,
+    driverModel: driver.driverModel ?? vehicle.driverModel ?? null,
     pace,
     racecraft,
     personality,
@@ -170,7 +171,7 @@ export function applyExternalCarState(car, partial, context) {
   }
   car.speed = clamp(Number.isFinite(car.speed) ? car.speed : 0, 0, VEHICLE_LIMITS.maxSpeed);
   car.heading = normalizeAngle(Number.isFinite(car.heading) ? car.heading : 0);
-  syncExternalVelocityState(car, nextPartial, physicsMode === 'advanced');
+  syncExternalVelocityState(car, nextPartial, isSimulatorPhysicsMode(physicsMode));
   const centerState = nearestTrackStateForCar(track, car, car, car.progress ?? car.raceDistance);
   applyWheelSurfaceState(car, track, { centerState });
   if (

package/src/ui/raceCanvasTemplate.js

@@ -39,8 +39,9 @@ export function createRaceCanvasMarkup({
   }
   const timingPanelId = includeTimingTower ? createTimingPanelId() : '';
   const showPhysicsModeIndicator = debug.physicsModeIndicator === true;
-  const physicsModeLabel = physicsMode === 'advanced' ? 'Advanced physics mode' : 'Arcade physics mode';
-  const physicsModeClass = physicsMode === 'advanced' ? 'advanced' : 'arcade';
+  const simulatorPhysics = physicsMode === 'advanced';
+  const physicsModeLabel = `${simulatorPhysics ? 'Advanced' : 'Arcade'} physics mode`;
+  const physicsModeClass = simulatorPhysics ? 'advanced' : 'arcade';
 
   const body = `
       <div class="track-canvas" data-track-canvas></div>

package/src/ui/raceControlsTemplate.js

@@ -49,5 +49,6 @@ export function createSafetyCarControlMarkup({ compact = false } = {}) {
     ariaLabel: 'Safety car control',
     body,
     unsupportedLabel: 'Safety car control',
+    loadingLabel: 'Safety car control',
   });
 }

package/src/ui/telemetryDrawerTemplate.js

@@ -64,5 +64,6 @@ export function createRaceTelemetryDrawerMarkup(options, {
     attributes: 'data-race-telemetry-drawer',
     body,
     unsupportedLabel: 'Race telemetry drawer',
+    loadingLabel: 'Race telemetry drawer',
   });
 }

package/src/ui/telemetryTemplates.js

@@ -158,5 +158,6 @@ export function createTelemetryPanelMarkup(options, { includeOverview = options.
     ariaLabel: 'Selected car telemetry stack',
     body,
     unsupportedLabel: 'Telemetry stack',
+    loadingLabel: 'Telemetry stack',
   });
 }

package/examples/train-basic-policy.mjs

@@ -1,276 +0,0 @@
-#!/usr/bin/env node
-
-import { createPaddockEnvironment, createProgressReward } from '@inventure71/paddockjs/environment';
-import { TRAINING_DEMO_DRIVERS, TRAINING_DEMO_ENTRIES } from './trainingData.mjs';
-
-const DEFAULT_OPTIONS = Object.freeze({
-  generations: 4,
-  candidates: 5,
-  episodes: 1,
-  steps: 240,
-  frameSkip: 4,
-  seed: 71,
-  traffic: false,
-  evalOnly: false,
-});
-
-const INITIAL_POLICY = Object.freeze({
-  steeringHeading: -1.2,
-  steeringOffset: -0.35,
-  steeringRayBalance: 0.45,
-  throttleBias: 0.72,
-  throttleFrontClearance: 0.28,
-  throttleSpeedDamping: 0.18,
-  brakeBias: 0,
-  brakeFrontDanger: 0.65,
-  brakeOffTrack: 0.2,
-});
-
-const POLICY_KEYS = Object.keys(INITIAL_POLICY);
-
-main();
-
-function main() {
-  const options = parseCliArgs(process.argv.slice(2));
-  if (options.help) {
-    printHelp();
-    return;
-  }
-
-  const driverId = TRAINING_DEMO_DRIVERS[0].id;
-  const rng = createSeededRandom(options.seed);
-  const reward = createProgressReward();
-  const evaluate = (policy, seedOffset = 0) => evaluatePolicy({
-    policy,
-    driverId,
-    reward,
-    options,
-    seedOffset,
-  });
-
-  if (options.evalOnly) {
-    const baseline = evaluate(INITIAL_POLICY);
-    printSummary({ options, driverId, bestPolicy: INITIAL_POLICY, best: baseline });
-    return;
-  }
-
-  let bestPolicy = { ...INITIAL_POLICY };
-  let best = evaluate(bestPolicy);
-
-  console.log(formatGenerationLine(0, best));
-
-  for (let generation = 1; generation <= options.generations; generation += 1) {
-    const mutationScale = 0.45 / Math.sqrt(generation);
-    const candidates = [{ policy: bestPolicy, scoreSeedOffset: generation * 1000 }];
-
-    for (let index = 1; index < options.candidates; index += 1) {
-      candidates.push({
-        policy: mutatePolicy(bestPolicy, rng, mutationScale),
-        scoreSeedOffset: generation * 1000 + index * 100,
-      });
-    }
-
-    for (const candidate of candidates) {
-      const score = evaluate(candidate.policy, candidate.scoreSeedOffset);
-      if (score.averageReward > best.averageReward) {
-        best = score;
-        bestPolicy = candidate.policy;
-      }
-    }
-
-    console.log(formatGenerationLine(generation, best));
-  }
-
-  printSummary({ options, driverId, bestPolicy, best });
-}
-
-function evaluatePolicy({ policy, driverId, reward, options, seedOffset = 0 }) {
-  let totalReward = 0;
-  let totalDistanceMeters = 0;
-  let totalCollisions = 0;
-  let totalOffTrackSteps = 0;
-  let completedEpisodes = 0;
-
-  for (let episode = 0; episode < options.episodes; episode += 1) {
-    const env = createTrainingEnvironment({ driverId, reward, options, episode, seedOffset });
-    let result = env.reset();
-    let episodeReward = 0;
-
-    for (let step = 0; step < options.steps && !result.done; step += 1) {
-      const observation = result.observation[driverId];
-      const action = chooseAction(policy, observation);
-      result = env.step({ [driverId]: action });
-      episodeReward += result.reward?.[driverId] ?? 0;
-      totalCollisions += result.events.filter((event) => event.type === 'collision').length;
-      if (result.observation[driverId]?.object?.self?.onTrack === false) totalOffTrackSteps += 1;
-    }
-
-    const car = result.state.snapshot.cars.find((entry) => entry.id === driverId);
-    totalReward += episodeReward;
-    totalDistanceMeters += Number(car?.distanceMeters ?? 0);
-    completedEpisodes += 1;
-    env.destroy();
-  }
-
-  return {
-    averageReward: totalReward / Math.max(1, completedEpisodes),
-    averageDistanceMeters: totalDistanceMeters / Math.max(1, completedEpisodes),
-    collisions: totalCollisions,
-    offTrackSteps: totalOffTrackSteps,
-  };
-}
-
-function createTrainingEnvironment({ driverId, reward, options, episode, seedOffset }) {
-  const drivers = options.traffic ? TRAINING_DEMO_DRIVERS.slice(0, 8) : TRAINING_DEMO_DRIVERS.slice(0, 1);
-  return createPaddockEnvironment({
-    drivers,
-    entries: TRAINING_DEMO_ENTRIES,
-    controlledDrivers: [driverId],
-    seed: options.seed + seedOffset + episode,
-    trackSeed: options.seed + 2026 + seedOffset + episode,
-    totalLaps: 3,
-    frameSkip: options.frameSkip,
-    scenario: {
-      participants: options.traffic ? 'all' : 'controlled-only',
-      nonControlled: 'ai',
-    },
-    episode: {
-      maxSteps: options.steps,
-      endOnRaceFinish: true,
-    },
-    rules: {
-      standingStart: false,
-    },
-    reward,
-  });
-}
-
-function chooseAction(policy, observation) {
-  const self = observation.object.self;
-  const frontRay = getRayDistance(observation, 0);
-  const leftRay = getRayDistance(observation, -60);
-  const rightRay = getRayDistance(observation, 60);
-  const frontDanger = clamp01((35 - frontRay) / 35);
-  const rayBalanceMeters = rightRay - leftRay;
-
-  const steering = clamp(
-    policy.steeringHeading * self.trackHeadingErrorRadians +
-      policy.steeringOffset * (self.trackOffsetMeters / 12) +
-      policy.steeringRayBalance * (rayBalanceMeters / 120),
-    -1,
-    1,
-  );
-  const throttle = clamp01(
-    policy.throttleBias +
-      policy.throttleFrontClearance * (frontRay / 120) -
-      policy.throttleSpeedDamping * (self.speedKph / 320) -
-      (self.onTrack ? 0 : 0.35),
-  );
-  const brake = clamp01(
-    policy.brakeBias +
-      policy.brakeFrontDanger * frontDanger +
-      (self.onTrack ? 0 : policy.brakeOffTrack),
-  );
-
-  return { steering, throttle, brake };
-}
-
-function getRayDistance(observation, angleDegrees) {
-  const ray = observation.object.rays.find((entry) => entry.angleDegrees === angleDegrees);
-  return Number(ray?.track?.distanceMeters ?? ray?.lengthMeters ?? 120);
-}
-
-function mutatePolicy(policy, rng, scale) {
-  return Object.fromEntries(POLICY_KEYS.map((key) => [
-    key,
-    policy[key] + randomNormal(rng) * scale,
-  ]));
-}
-
-function parseCliArgs(argv) {
-  const options = { ...DEFAULT_OPTIONS };
-
-  for (const arg of argv) {
-    const [name, rawValue] = arg.split('=');
-    if (name === '--help' || name === '-h') options.help = true;
-    else if (name === '--eval-only') options.evalOnly = true;
-    else if (name === '--traffic') options.traffic = true;
-    else if (name === '--no-traffic') options.traffic = false;
-    else if (name === '--generations') options.generations = parsePositiveInt(rawValue, name);
-    else if (name === '--candidates') options.candidates = parsePositiveInt(rawValue, name);
-    else if (name === '--episodes') options.episodes = parsePositiveInt(rawValue, name);
-    else if (name === '--steps') options.steps = parsePositiveInt(rawValue, name);
-    else if (name === '--frame-skip') options.frameSkip = parsePositiveInt(rawValue, name);
-    else if (name === '--seed') options.seed = parsePositiveInt(rawValue, name);
-    else throw new Error(`Unknown option: ${name}`);
-  }
-
-  return options;
-}
-
-function parsePositiveInt(value, optionName) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`${optionName} requires a positive integer value.`);
-  }
-  return parsed;
-}
-
-function createSeededRandom(seed) {
-  let state = seed >>> 0;
-  return function random() {
-    state += 0x6D2B79F5;
-    let value = state;
-    value = Math.imul(value ^ (value >>> 15), value | 1);
-    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
-    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
-function randomNormal(rng) {
-  const a = Math.max(Number.EPSILON, rng());
-  const b = Math.max(Number.EPSILON, rng());
-  return Math.sqrt(-2 * Math.log(a)) * Math.cos(2 * Math.PI * b);
-}
-
-function clamp(value, min, max) {
-  return Math.min(max, Math.max(min, value));
-}
-
-function clamp01(value) {
-  return clamp(value, 0, 1);
-}
-
-function formatGenerationLine(generation, score) {
-  return [
-    `generation=${generation}`,
-    `reward=${score.averageReward.toFixed(2)}`,
-    `distanceMeters=${score.averageDistanceMeters.toFixed(1)}`,
-    `collisions=${score.collisions}`,
-    `offTrackSteps=${score.offTrackSteps}`,
-  ].join(' ');
-}
-
-function printSummary({ options, driverId, bestPolicy, best }) {
-  console.log(JSON.stringify({
-    driverId,
-    options,
-    best,
-    bestPolicy,
-  }, null, 2));
-}
-
-function printHelp() {
-  console.log(`Usage: node examples/train-basic-policy.mjs [options]
-
-Options:
-  --generations=N   Random-search generations. Default: ${DEFAULT_OPTIONS.generations}
-  --candidates=N    Candidate policies per generation. Default: ${DEFAULT_OPTIONS.candidates}
-  --episodes=N      Episodes per policy evaluation. Default: ${DEFAULT_OPTIONS.episodes}
-  --steps=N         Maximum manual environment steps per episode. Default: ${DEFAULT_OPTIONS.steps}
-  --frame-skip=N    Simulator frames advanced by each step(action). Default: ${DEFAULT_OPTIONS.frameSkip}
-  --seed=N          Deterministic random seed. Default: ${DEFAULT_OPTIONS.seed}
-  --traffic         Keep built-in AI traffic on track during training.
-  --eval-only       Evaluate the starter policy without training.
-`);
-}