@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/environment/controllerLoop.js

@@ -0,0 +1,261 @@
+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 observationCache = {};
+  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 refreshSpecs() {
+    actionSpec = runtime.getActionSpec();
+    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);
+    observationCache = { ...(result?.observation ?? {}) };
+    previousActions = {};
+    lastError = null;
+    await refreshSpecs();
+    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);
+    observationCache = {
+      ...observationCache,
+      ...(result?.observation ?? {}),
+    };
+    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);
+    observationCache = { ...(result?.observation ?? {}) };
+    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 = {
+      ...observationCache,
+      ...(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,113 @@
 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 aggregateTruncated = episode.truncated && episode.endReason !== 'all-drivers-ended';
+    const terminated = Boolean(state.terminated || episode.terminated);
+    const truncated = Boolean(state.truncated || maxStepTruncated || aggregateTruncated);
+    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 allEnded = controlledDrivers.length > 0;
+  let anyTruncated = false;
+  let firstTerminatedReason = null;
+  for (const driverId of controlledDrivers) {
+    const state = ensureDriverEpisodeState(episodeState, driverId);
+    if (!state.terminated && state.episodeStep >= options.episode.maxSteps) {
+      state.truncated = true;
+      state.endReason ??= 'max-steps';
+    }
+    if (!state.terminated) allTerminated = false;
+    else firstTerminatedReason ??= state.endReason;
+    if (!state.truncated && state.episodeStep < options.episode.maxSteps) allTruncated = false;
+    if (state.truncated || state.episodeStep >= options.episode.maxSteps) anyTruncated = true;
+    if (!state.terminated && !state.truncated && state.episodeStep < options.episode.maxSteps) allEnded = false;
+    if (!allTerminated && !allTruncated && !allEnded) 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' };
   }
+  if (allEnded) {
+    return { terminated: false, truncated: anyTruncated, endReason: 'all-drivers-ended' };
+  }
   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

@@ -1,4 +1,5 @@
 import { simUnitsToMeters } from '../simulation/units.js';
+import { isEnvironmentCarOffTrack, isEnvironmentContactEvent } from './metrics.js';
 import { createPaddockEnvironment } from './runtime.js';
 
 export const DEFAULT_EVALUATION_CASES = Object.freeze([
@@ -41,7 +42,7 @@ export function runEnvironmentEvaluation({
   if (!baseOptions || typeof baseOptions !== 'object') {
     throw new Error('PaddockJS environment evaluation requires baseOptions.');
   }
-  if (!policy) {
+  if (!isEvaluationPolicy(policy)) {
     throw new Error('PaddockJS environment evaluation requires a policy function or object with predict().');
   }
 
@@ -55,19 +56,28 @@ export function runEnvironmentEvaluation({
   };
 }
 
+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: car && car.surface !== 'track' ? 1 : 0,
+      offTrackSteps: offTrack ? 1 : 0,
       contactCount: 0,
       recoverySuccess: false,
       passCount: 0,
       lapTimeSeconds: null,
-      startedOffTrack: Boolean(car && car.surface !== 'track'),
+      startedOffTrack: offTrack,
       startPosition: car?.rank ?? null,
       bestPosition: car?.rank ?? null,
       startDistanceMeters: cumulativeDistanceMetersFromSnapshotCar(car),
@@ -83,8 +93,9 @@ export function createEvaluationTracker(initialResult) {
         if (!car || !entry) return;
         entry.distanceMeters = Math.max(0, cumulativeDistanceMetersFromSnapshotCar(car) - entry.startDistanceMeters);
         entry.lapProgressMeters = lapProgressMetersFromSnapshotCar(car);
-        if (car.surface !== 'track') entry.offTrackSteps += 1;
-        if (entry.startedOffTrack && car.surface === 'track') entry.recoverySuccess = true;
+        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);
@@ -95,7 +106,7 @@ export function createEvaluationTracker(initialResult) {
         }
       });
       result.events.forEach((event) => {
-        if (event.type !== 'collision') return;
+        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;
@@ -135,6 +146,10 @@ function lapProgressMetersFromSnapshotCar(car) {
 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: {
@@ -142,34 +157,41 @@ function runEvaluationCase({ baseOptions, policy, evaluationCase, createEnvironm
       ...(evaluationCase.scenario ?? {}),
     },
   });
-  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], {
+  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,
-        caseName: evaluationCase.name,
-        step: steps,
-        result,
-      }),
-    ]));
-    result = env.step(actions);
-    tracker.update(result);
-    steps += 1;
+        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?.();
   }
-  env.destroy?.();
-  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(),
-  };
+}
+
+function normalizeEvaluationStateOutput(stateOutput) {
+  return stateOutput === 'none' ? 'minimal' : stateOutput;
 }
 
 function predictAction(policy, observation, context) {