@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/environment/controllerLoop.js

@@ -0,0 +1,246 @@
+export function createPaddockDriverControllerLoop({
+  runtime,
+  controller,
+  actionRepeat = 4,
+  mode = 'manual',
+  scheduler = null,
+} = {}) {
+  if (!runtime || typeof runtime.step !== 'function' || typeof runtime.reset !== 'function') {
+    throw new Error('createPaddockDriverControllerLoop requires a runtime with reset() and step(actions).');
+  }
+  if (!controller || typeof controller.decideBatch !== 'function') {
+    throw new Error('createPaddockDriverControllerLoop requires a controller with decideBatch(context).');
+  }
+
+  const repeat = Math.max(1, Math.floor(Number(actionRepeat) || 1));
+  let actionSpec = null;
+  let observationSpec = null;
+  let initialized = false;
+  let result = null;
+  let previousResult = null;
+  let heldActions = null;
+  let heldFramesRemaining = 0;
+  let policyStep = 0;
+  let runtimeStep = 0;
+  let running = false;
+  let scheduled = null;
+  let previousActions = {};
+  let lastDecisionMs = 0;
+  let lastError = null;
+
+  async function ensureSpecs() {
+    if (!actionSpec) actionSpec = runtime.getActionSpec();
+    if (!observationSpec) observationSpec = runtime.getObservationSpec();
+  }
+
+  async function ensureInitialized(context) {
+    if (initialized) return;
+    await controller.init?.(context);
+    initialized = true;
+  }
+
+  async function resetRuntime(options = {}, { stopPlayback = true } = {}) {
+    if (stopPlayback) stop();
+    result = runtime.reset(options);
+    previousResult = null;
+    heldActions = null;
+    heldFramesRemaining = 0;
+    policyStep = 0;
+    runtimeStep = Number(result?.info?.step ?? 0);
+    previousActions = {};
+    lastError = null;
+    await ensureSpecs();
+    const context = buildContext({ resetDriverIds: controlledDrivers() });
+    await ensureInitialized(context);
+    await controller.reset?.(context);
+    return result;
+  }
+
+  async function reset(options = {}) {
+    return resetRuntime(options, { stopPlayback: true });
+  }
+
+  async function ensureResult() {
+    if (!result) await resetRuntime({}, { stopPlayback: false });
+  }
+
+  async function resetDrivers(placements = {}, resultOptions = {}) {
+    if (typeof runtime.resetDrivers !== 'function') {
+      throw new Error('The supplied Paddock runtime does not support resetDrivers().');
+    }
+    const resetDriverIds = Object.keys(placements);
+    previousResult = result;
+    result = runtime.resetDrivers(placements, resultOptions);
+    heldActions = null;
+    heldFramesRemaining = 0;
+    lastError = null;
+    resetDriverIds.forEach((driverId) => {
+      delete previousActions[driverId];
+    });
+    await ensureSpecs();
+    const context = buildContext({ resetDriverIds });
+    await ensureInitialized(context);
+    await controller.reset?.(context);
+    return result;
+  }
+
+  async function beginDecision() {
+    await ensureResult();
+    const context = buildContext();
+    await ensureInitialized(context);
+    const startedAt = now();
+    const actions = await controller.decideBatch(context);
+    lastDecisionMs = now() - startedAt;
+    heldActions = actions && typeof actions === 'object' ? actions : {};
+    heldFramesRemaining = repeat;
+    policyStep += 1;
+  }
+
+  async function stepFrame() {
+    await ensureResult();
+    if (!heldActions || heldFramesRemaining <= 0) {
+      await beginDecision();
+    }
+    const actionIndex = repeat - heldFramesRemaining;
+    const actions = heldActions;
+    const previousActionsForStep = previousActions;
+    previousResult = result;
+    result = runtime.step(actions);
+    heldFramesRemaining -= 1;
+    runtimeStep = Number(result?.info?.step ?? runtimeStep + 1);
+    previousActions = actions;
+    await controller.onStep?.(buildContext({
+      actionIndex,
+      actions,
+      previousActions: previousActionsForStep,
+      previousResult,
+    }));
+    return result;
+  }
+
+  async function step() {
+    let latest = result;
+    const targetPolicyStep = policyStep + 1;
+    while (policyStep < targetPolicyStep || heldFramesRemaining > 0) {
+      latest = await stepFrame();
+      if (latest?.done) break;
+      if (policyStep >= targetPolicyStep && heldFramesRemaining <= 0) break;
+    }
+    return latest;
+  }
+
+  function start() {
+    if (running) return;
+    lastError = null;
+    running = true;
+    const schedule = scheduler ?? defaultScheduler();
+    const tick = async () => {
+      if (!running) return;
+      scheduled = null;
+      try {
+        await stepFrame();
+      } catch (error) {
+        lastError = error;
+        running = false;
+        scheduled = null;
+        return;
+      }
+      if (!running || result?.done) {
+        running = false;
+        return;
+      }
+      scheduled = schedule(tick);
+    };
+    scheduled = schedule(tick);
+  }
+
+  function stop() {
+    running = false;
+    if (scheduled && typeof scheduled.cancel === 'function') scheduled.cancel();
+    else if (typeof scheduled === 'number' && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(scheduled);
+    scheduled = null;
+  }
+
+  function controlledDrivers() {
+    return actionSpec?.controlledDrivers ?? result?.info?.controlledDrivers ?? [];
+  }
+
+  function buildContext(extra = {}) {
+    const drivers = controlledDrivers();
+    const observation = result?.observation ?? runtime.getObservation?.() ?? {};
+    return {
+      runtime,
+      mode,
+      actionRepeat: repeat,
+      controlledDrivers: drivers,
+      actionSpec,
+      observationSpec,
+      result,
+      previousResult: extra.previousResult ?? previousResult,
+      observation,
+      orderedObservations: drivers.map((driverId, index) => ({
+        driverId,
+        index,
+        observation: observation?.[driverId] ?? null,
+        vector: observation?.[driverId]?.vector ?? null,
+      })),
+      metrics: result?.metrics ?? {},
+      events: result?.events ?? [],
+      info: result?.info ?? null,
+      previousActions: extra.previousActions ?? previousActions,
+      orderedPreviousActions: drivers.map((driverId) => (extra.previousActions ?? previousActions)?.[driverId] ?? null),
+      actions: extra.actions ?? heldActions,
+      policyStep,
+      runtimeStep,
+      heldFramesRemaining,
+      actionIndex: extra.actionIndex ?? 0,
+      resetDriverIds: extra.resetDriverIds ?? [],
+    };
+  }
+
+  return {
+    reset,
+    resetDrivers,
+    step,
+    stepFrame,
+    start,
+    stop,
+    get result() {
+      return result;
+    },
+    get actionSpec() {
+      return actionSpec;
+    },
+    get observationSpec() {
+      return observationSpec;
+    },
+    get stats() {
+      return {
+        policyStep,
+        runtimeStep,
+        heldFramesRemaining,
+        actions: heldActions,
+        actionRepeat: repeat,
+        lastDecisionMs,
+        running,
+        lastError,
+      };
+    },
+  };
+}
+
+function now() {
+  return typeof performance !== 'undefined' && typeof performance.now === 'function'
+    ? performance.now()
+    : Date.now();
+}
+
+function defaultScheduler() {
+  if (typeof requestAnimationFrame === 'function') {
+    return (callback) => requestAnimationFrame(callback);
+  }
+  return (callback) => {
+    const id = setTimeout(callback, 0);
+    return { cancel: () => clearTimeout(id) };
+  };
+}

package/src/environment/episode.js

@@ -1,17 +1,101 @@
 export function createEpisodeState() {
   return {
     step: 0,
+    drivers: new Map(),
     previousSnapshot: null,
     lastResult: null,
   };
 }
 
-export function evaluateEpisode(snapshot, options, episodeState) {
+export function initializeDriverEpisodes(episodeState, driverIds = []) {
+  episodeState.drivers = new Map(driverIds.map((driverId) => [driverId, createDriverEpisodeState()]));
+}
+
+export function advanceDriverEpisodes(episodeState, driverIds = []) {
+  driverIds.forEach((driverId) => {
+    const state = ensureDriverEpisodeState(episodeState, driverId);
+    if (!state.terminated && !state.truncated) state.episodeStep += 1;
+  });
+}
+
+export function resetDriverEpisodes(episodeState, driverIds = []) {
+  driverIds.forEach((driverId) => {
+    const state = ensureDriverEpisodeState(episodeState, driverId);
+    state.episodeId += 1;
+    state.episodeStep = 0;
+    state.terminated = false;
+    state.truncated = false;
+    state.endReason = null;
+  });
+}
+
+export function markDestroyedDriverEpisodes(episodeState, driverIds = [], snapshot = null) {
+  const carsById = new Map((snapshot?.cars ?? []).map((car) => [car.id, car]));
+  driverIds.forEach((driverId) => {
+    const car = carsById.get(driverId);
+    if (!car?.destroyed && !car?.dnf && !car?.outOfRace) return;
+    const state = ensureDriverEpisodeState(episodeState, driverId);
+    state.terminated = true;
+    state.truncated = false;
+    state.endReason = car.destroyed ? 'destroyed' : (car.dnfReason ?? car.destroyReason ?? 'destroyed');
+  });
+}
+
+export function buildDriverEpisodeInfo(episodeState, options, episode) {
+  return Object.fromEntries(options.controlledDrivers.map((driverId) => {
+    const state = ensureDriverEpisodeState(episodeState, driverId);
+    const maxStepTruncated = state.episodeStep >= options.episode.maxSteps;
+    const terminated = Boolean(state.terminated || episode.terminated);
+    const truncated = Boolean(state.truncated || maxStepTruncated || episode.truncated);
+    const endReason = state.endReason ??
+      (terminated ? episode.endReason : null) ??
+      (maxStepTruncated ? 'max-steps' : null) ??
+      (truncated ? episode.endReason : null);
+    return [driverId, {
+      terminated,
+      truncated,
+      endReason,
+      episodeStep: state.episodeStep,
+      episodeId: state.episodeId,
+    }];
+  }));
+}
+
+export function evaluateEpisode(snapshot, options, episodeState, controlledDrivers = options.controlledDrivers) {
   if (snapshot.raceControl.finished && options.episode.endOnRaceFinish) {
     return { terminated: true, truncated: false, endReason: 'race-finish' };
   }
-  if (episodeState.step >= options.episode.maxSteps) {
+  let allTerminated = controlledDrivers.length > 0;
+  let allTruncated = controlledDrivers.length > 0;
+  let firstTerminatedReason = null;
+  for (const driverId of controlledDrivers) {
+    const state = ensureDriverEpisodeState(episodeState, driverId);
+    if (!state.terminated) allTerminated = false;
+    else firstTerminatedReason ??= state.endReason;
+    if (!state.truncated && state.episodeStep < options.episode.maxSteps) allTruncated = false;
+    if (!allTerminated && !allTruncated) break;
+  }
+  if (allTerminated) {
+    return { terminated: true, truncated: false, endReason: controlledDrivers.length === 1 ? firstTerminatedReason : 'all-drivers-terminated' };
+  }
+  if (allTruncated) {
     return { terminated: false, truncated: true, endReason: 'max-steps' };
   }
   return { terminated: false, truncated: false, endReason: null };
 }
+
+function createDriverEpisodeState() {
+  return {
+    episodeStep: 0,
+    episodeId: 0,
+    terminated: false,
+    truncated: false,
+    endReason: null,
+  };
+}
+
+function ensureDriverEpisodeState(episodeState, driverId) {
+  if (!episodeState.drivers) episodeState.drivers = new Map();
+  if (!episodeState.drivers.has(driverId)) episodeState.drivers.set(driverId, createDriverEpisodeState());
+  return episodeState.drivers.get(driverId);
+}

package/src/environment/evaluation.js

@@ -0,0 +1,206 @@
+import { simUnitsToMeters } from '../simulation/units.js';
+import { isEnvironmentCarOffTrack, isEnvironmentContactEvent } from './metrics.js';
+import { createPaddockEnvironment } from './runtime.js';
+
+export const DEFAULT_EVALUATION_CASES = Object.freeze([
+  {
+    name: 'cornering',
+    seed: 7101,
+    trackSeed: 2601,
+    maxSteps: 420,
+    scenario: { preset: 'cornering' },
+  },
+  {
+    name: 'off-track-recovery',
+    seed: 7102,
+    trackSeed: 2602,
+    maxSteps: 360,
+    scenario: { preset: 'off-track-recovery' },
+  },
+  {
+    name: 'overtaking-pack',
+    seed: 7103,
+    trackSeed: 2603,
+    maxSteps: 600,
+    scenario: { preset: 'overtaking-pack' },
+  },
+  {
+    name: 'pit-entry',
+    seed: 7104,
+    trackSeed: 2604,
+    maxSteps: 480,
+    scenario: { preset: 'pit-entry' },
+  },
+]);
+
+export function runEnvironmentEvaluation({
+  baseOptions,
+  policy,
+  cases = DEFAULT_EVALUATION_CASES,
+  createEnvironment = createPaddockEnvironment,
+} = {}) {
+  if (!baseOptions || typeof baseOptions !== 'object') {
+    throw new Error('PaddockJS environment evaluation requires baseOptions.');
+  }
+  if (!isEvaluationPolicy(policy)) {
+    throw new Error('PaddockJS environment evaluation requires a policy function or object with predict().');
+  }
+
+  return {
+    cases: cases.map((evaluationCase) => runEvaluationCase({
+      baseOptions,
+      policy,
+      evaluationCase,
+      createEnvironment,
+    })),
+  };
+}
+
+function isEvaluationPolicy(policy) {
+  return typeof policy === 'function' ||
+    (policy != null && typeof policy.predict === 'function');
+}
+
+export function createEvaluationTracker(initialResult) {
+  if (!initialResult?.state?.snapshot) {
+    throw new Error('PaddockJS environment evaluation tracker requires result.state.snapshot; use result.stateOutput "minimal" or "full".');
+  }
+  const initialCars = carsById(initialResult.state.snapshot);
+  const metrics = Object.fromEntries(initialResult.info.controlledDrivers.map((driverId) => {
+    const car = initialCars.get(driverId);
+    const offTrack = isEnvironmentCarOffTrack(car);
+    return [driverId, {
+      distanceMeters: 0,
+      lapProgressMeters: lapProgressMetersFromSnapshotCar(car),
+      offTrackSteps: offTrack ? 1 : 0,
+      contactCount: 0,
+      recoverySuccess: false,
+      passCount: 0,
+      lapTimeSeconds: null,
+      startedOffTrack: offTrack,
+      startPosition: car?.rank ?? null,
+      bestPosition: car?.rank ?? null,
+      startDistanceMeters: cumulativeDistanceMetersFromSnapshotCar(car),
+    }];
+  }));
+
+  return {
+    update(result) {
+      const currentCars = carsById(result.state.snapshot);
+      result.info.controlledDrivers.forEach((driverId) => {
+        const car = currentCars.get(driverId);
+        const entry = metrics[driverId];
+        if (!car || !entry) return;
+        entry.distanceMeters = Math.max(0, cumulativeDistanceMetersFromSnapshotCar(car) - entry.startDistanceMeters);
+        entry.lapProgressMeters = lapProgressMetersFromSnapshotCar(car);
+        const offTrack = isEnvironmentCarOffTrack(car);
+        if (offTrack) entry.offTrackSteps += 1;
+        if (entry.startedOffTrack && !offTrack) entry.recoverySuccess = true;
+        if (Number.isFinite(car.rank)) {
+          entry.bestPosition = entry.bestPosition == null ? car.rank : Math.min(entry.bestPosition, car.rank);
+          entry.passCount = entry.startPosition == null ? 0 : Math.max(0, entry.startPosition - entry.bestPosition);
+        }
+        const completedLaps = car.lapTelemetry?.completedLaps ?? 0;
+        if (completedLaps > 0 && entry.lapTimeSeconds == null) {
+          entry.lapTimeSeconds = result.info.elapsedSeconds;
+        }
+      });
+      result.events.forEach((event) => {
+        if (!isEnvironmentContactEvent(event)) return;
+        Object.keys(metrics).forEach((driverId) => {
+          if (event.driverId === driverId || event.carId === driverId || event.otherCarId === driverId || event.driverIds?.includes?.(driverId)) {
+            metrics[driverId].contactCount += 1;
+          }
+        });
+      });
+    },
+    finish() {
+      return Object.fromEntries(Object.entries(metrics).map(([driverId, entry]) => [
+        driverId,
+        {
+          distanceMeters: entry.distanceMeters,
+          lapProgressMeters: entry.lapProgressMeters,
+          offTrackSteps: entry.offTrackSteps,
+          contactCount: entry.contactCount,
+          recoverySuccess: entry.recoverySuccess,
+          passCount: entry.passCount,
+          lapTimeSeconds: entry.lapTimeSeconds,
+        },
+      ]));
+    },
+  };
+}
+
+function cumulativeDistanceMetersFromSnapshotCar(car) {
+  const distance = Number(car?.distanceMeters ?? car?.raceDistanceMeters);
+  if (Number.isFinite(distance)) return distance;
+  return simUnitsToMeters(car?.raceDistance ?? 0);
+}
+
+function lapProgressMetersFromSnapshotCar(car) {
+  const progressMeters = Number(car?.lapProgressMeters ?? car?.progressMeters);
+  if (Number.isFinite(progressMeters)) return progressMeters;
+  return simUnitsToMeters(car?.progress ?? 0);
+}
+
+function runEvaluationCase({ baseOptions, policy, evaluationCase, createEnvironment }) {
+  const env = createEnvironment({
+    ...baseOptions,
+    result: {
+      ...(baseOptions.result ?? {}),
+      stateOutput: normalizeEvaluationStateOutput(baseOptions.result?.stateOutput),
+    },
+    seed: evaluationCase.seed ?? baseOptions.seed,
+    trackSeed: evaluationCase.trackSeed ?? baseOptions.trackSeed,
+    scenario: {
+      ...(baseOptions.scenario ?? {}),
+      ...(evaluationCase.scenario ?? {}),
+    },
+  });
+  try {
+    let result = env.reset();
+    const tracker = createEvaluationTracker(result);
+    const maxSteps = Math.max(1, Math.floor(evaluationCase.maxSteps ?? baseOptions.episode?.maxSteps ?? 1000));
+    let steps = 0;
+    while (!result.done && steps < maxSteps) {
+      const actions = Object.fromEntries(result.info.controlledDrivers.map((driverId) => [
+        driverId,
+        predictAction(policy, result.observation[driverId], {
+          driverId,
+          caseName: evaluationCase.name,
+          step: steps,
+          result,
+        }),
+      ]));
+      result = env.step(actions);
+      tracker.update(result);
+      steps += 1;
+    }
+    return {
+      name: evaluationCase.name,
+      seed: evaluationCase.seed ?? baseOptions.seed,
+      trackSeed: evaluationCase.trackSeed ?? baseOptions.trackSeed,
+      steps,
+      done: result.done,
+      endReason: result.info.endReason,
+      metrics: tracker.finish(),
+    };
+  } finally {
+    env.destroy?.();
+  }
+}
+
+function normalizeEvaluationStateOutput(stateOutput) {
+  return stateOutput === 'none' ? 'minimal' : stateOutput;
+}
+
+function predictAction(policy, observation, context) {
+  const action = typeof policy === 'function'
+    ? policy(observation, context)
+    : policy.predict(observation, context);
+  return action ?? { steering: 0, throttle: 0, brake: 1 };
+}
+
+function carsById(snapshot) {
+  return new Map(snapshot.cars.map((car) => [car.id, car]));
+}