@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/environment/options.js

@@ -1,9 +1,16 @@
 import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
 import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
+import { normalizePhysicsMode } from '../simulation/vehicle/vehiclePhysics.js';
+import { normalizeWarmupOptions } from '../simulation/warmup/runtimeWarmup.js';
+import { normalizeObservationOptions } from './observationOptions.js';
+import { resolveScenarioPlacementConfig } from './scenarios.js';
+import { normalizeRayOptions } from './sensors.js';
 
 const DEFAULT_SEED = 1971;
 const DEFAULT_FRAME_SKIP = 1;
 const DEFAULT_MAX_STEPS = 10000;
+const RESULT_STATE_OUTPUTS = new Set(['full', 'minimal', 'none']);
+const RESET_OBSERVATION_SCOPES = new Set(['all', 'reset']);
 
 const DEFAULT_SENSOR_OPTIONS = {
   rays: {
@@ -35,6 +42,7 @@ export function resolveEnvironmentOptions(options = {}) {
     ...options,
     seed,
     trackSeed,
+    trackGeneration: options.trackGeneration ?? {},
     totalLaps: options.totalLaps,
     drivers: normalizedDrivers,
   };
@@ -58,20 +66,41 @@ export function resolveEnvironmentOptions(options = {}) {
     }
   });
 
+  const externalRenderer = normalizeExternalRenderer(options.externalRenderer);
+
   return {
     ...resolved,
+    physicsMode: normalizePhysicsMode(options.physicsMode),
+    warmup: normalizeWarmupOptions(options.warmup, 'environment'),
     drivers: participantDrivers,
     controlledDrivers,
     frameSkip: normalizePositiveInteger(options.frameSkip, DEFAULT_FRAME_SKIP, 'frameSkip'),
     actionPolicy: options.actionPolicy === 'report' ? 'report' : 'strict',
     scenario,
+    observation: {
+      ...normalizeObservationOptions(options.observation ?? {}),
+    },
     sensors: mergeSensorOptions(options.sensors),
     sensorsByDriver: options.sensorsByDriver ?? {},
     episode: {
       maxSteps: normalizePositiveInteger(options.episode?.maxSteps, DEFAULT_MAX_STEPS, 'episode.maxSteps'),
       endOnRaceFinish: options.episode?.endOnRaceFinish !== false,
     },
+    result: normalizeResultOptions(options.result),
     reward: typeof options.reward === 'function' ? options.reward : null,
+    externalRenderer,
+  };
+}
+
+export function normalizeResultOptions(result = {}) {
+  const stateOutput = RESULT_STATE_OUTPUTS.has(result.stateOutput) ? result.stateOutput : 'full';
+  const resetDriversObservationScope = RESET_OBSERVATION_SCOPES.has(result.resetDriversObservationScope)
+    ? result.resetDriversObservationScope
+    : 'all';
+  return {
+    ...result,
+    stateOutput,
+    resetDriversObservationScope,
   };
 }
 
@@ -118,6 +147,7 @@ function resolveScenario(scenario = {}, controlledDrivers, driverIds) {
   return {
     participants,
     nonControlled: 'ai',
+    ...resolveScenarioPlacementConfig(scenario, driverIds),
   };
 }
 
@@ -138,13 +168,22 @@ function normalizePositiveInteger(value, fallback, label) {
 
 function mergeSensorOptions(sensors = {}) {
   return {
-    rays: {
+    rays: normalizeRayOptions({
       ...DEFAULT_SENSOR_OPTIONS.rays,
       ...(sensors.rays ?? {}),
-    },
+    }),
     nearbyCars: {
       ...DEFAULT_SENSOR_OPTIONS.nearbyCars,
       ...(sensors.nearbyCars ?? {}),
     },
   };
 }
+
+function normalizeExternalRenderer(value) {
+  if (value == null) return null;
+  if (typeof value === 'function') return { onFrame: value };
+  if (typeof value === 'object' && typeof value.onFrame === 'function') {
+    return { onFrame: value.onFrame };
+  }
+  throw new Error('PaddockJS environment externalRenderer must be a function or an object with onFrame(frame).');
+}

package/src/environment/recorder.js

@@ -0,0 +1,28 @@
+export function createRolloutRecorder() {
+  const transitions = [];
+  return {
+    recordStep(previousResult, action, nextResult) {
+      const transition = createRolloutTransition(previousResult, action, nextResult);
+      transitions.push(transition);
+      return transition;
+    },
+    clear() {
+      transitions.length = 0;
+    },
+    toJSON() {
+      return transitions.map((entry) => ({ ...entry }));
+    },
+  };
+}
+
+export function createRolloutTransition(previousResult, action, nextResult) {
+  return {
+    observation: previousResult.observation,
+    action,
+    reward: nextResult.reward,
+    nextObservation: nextResult.observation,
+    terminated: nextResult.terminated,
+    truncated: nextResult.truncated,
+    info: nextResult.info,
+  };
+}

package/src/environment/runtime.js

@@ -1,21 +1,32 @@
 import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.js';
-import { resolveActionMap } from './actions.js';
+import { disableWarmupOptions, runWarmupWithGuard } from '../simulation/warmup/runtimeWarmup.js';
+import { handleActionError, resolveActionMap } from './actions.js';
 import { collectStepEvents } from './events.js';
-import { createEpisodeState, evaluateEpisode } from './episode.js';
+import {
+  advanceDriverEpisodes,
+  buildDriverEpisodeInfo,
+  createEpisodeState,
+  evaluateEpisode,
+  initializeDriverEpisodes,
+  markDestroyedDriverEpisodes,
+  resetDriverEpisodes,
+} from './episode.js';
+import { buildDriverMetrics } from './metrics.js';
 import { buildEnvironmentObservation } from './observations.js';
 import { resolveEnvironmentOptions } from './options.js';
+import { applyEnvironmentPlacements, applyEnvironmentScenario, normalizeEnvironmentPlacements } from './scenarios.js';
 import { buildActionSpec, buildObservationSpec } from './specs.js';
 
 export function createPaddockEnvironment(options = {}) {
   let resolvedOptions = resolveEnvironmentOptions(options);
-  let sim = createRaceSimulation(resolvedOptions);
+  let sim = createSimulationWithEnvironmentScenario(resolvedOptions);
   return createEnvironmentRuntime({
     getSimulation: () => sim,
     setSimulation(nextSim) {
       sim = nextSim;
     },
     createSimulation(nextOptions) {
-      return createRaceSimulation(nextOptions);
+      return createSimulationWithEnvironmentScenario(nextOptions);
     },
     getOptions: () => resolvedOptions,
     setOptions(nextOptions) {
@@ -26,20 +37,52 @@ export function createPaddockEnvironment(options = {}) {
   });
 }
 
+function createSimulationWithEnvironmentScenario(options) {
+  const simulationOptions = {
+    ...options,
+    trackQueryIndex: shouldUseTrackQueryIndex(options),
+  };
+  runWarmupWithGuard({
+    options: simulationOptions,
+    surface: 'environment',
+    execute: ({ warmup }) => {
+      const warmupSimulation = createRaceSimulation(disableWarmupOptions(simulationOptions, warmup.surface));
+      applyEnvironmentScenario(warmupSimulation, options);
+      for (let index = 0; index < warmup.steps; index += 1) warmupSimulation.step(FIXED_STEP);
+      const warmupSnapshot = warmupSimulation.snapshotObservation?.() ?? warmupSimulation.snapshot();
+      buildEnvironmentObservation({
+        snapshot: warmupSnapshot,
+        options,
+        events: [],
+      });
+    },
+  });
+  const sim = createRaceSimulation(disableWarmupOptions(simulationOptions, 'environment'));
+  applyEnvironmentScenario(sim, options);
+  return sim;
+}
+
+function shouldUseTrackQueryIndex(options) {
+  return options.trackQueryIndex !== false;
+}
+
 export function createEnvironmentRuntime(host) {
   const episodeState = createEpisodeState();
 
+  initializeControlledPitIntent(host);
+  initializeDriverEpisodes(episodeState, host.getOptions().controlledDrivers);
+
   function reset(nextOptions = {}) {
-    const options = resolveEnvironmentOptions({
-      ...host.getOptions(),
-      ...nextOptions,
-    });
+    const options = resolveEnvironmentOptions(mergeEnvironmentResetOptions(host.getOptions(), nextOptions));
     host.setOptions(options);
     host.setSimulation(host.createSimulation(options));
+    initializeControlledPitIntent(host);
     episodeState.step = 0;
     episodeState.previousSnapshot = null;
+    initializeDriverEpisodes(episodeState, options.controlledDrivers);
     const result = buildResult({ host, episodeState, events: [], actionErrors: [] });
     episodeState.lastResult = result;
+    emitExternalRenderFrame(host, result, { source: 'reset' });
     host.afterReset(result);
     return result;
   }
@@ -47,23 +90,39 @@ export function createEnvironmentRuntime(host) {
   function step(actions = {}) {
     const options = host.getOptions();
     const sim = host.getSimulation();
-    const { controlsByDriver, errors } = resolveActionMap(actions, options.controlledDrivers, {
+    const { controlsByDriver, pitIntentByDriver, errors } = resolveActionMap(actions, options.controlledDrivers, {
       policy: options.actionPolicy,
     });
 
+    if (options.actionPolicy === 'report') {
+      options.controlledDrivers.forEach((driverId) => {
+        if (!Object.hasOwn(controlsByDriver, driverId)) sim.clearCarControls?.(driverId);
+      });
+    }
     Object.entries(controlsByDriver).forEach(([driverId, controls]) => {
       sim.setCarControls(driverId, controls);
     });
+    Object.entries(pitIntentByDriver).forEach(([driverId, pitIntent]) => {
+      const applied = Boolean(sim.setPitIntent?.(driverId, pitIntent));
+      if (!applied && !isNoopPitIntent(pitIntent)) {
+        handleActionError(`Pit intent could not be applied for controlled driver: ${driverId}`, options.actionPolicy, errors);
+      }
+    });
 
-    episodeState.previousSnapshot = sim.snapshot();
+    episodeState.previousSnapshot = episodeState.lastRewardSnapshot ?? snapshotForResult(sim, options, options.result.stateOutput);
     const stepEvents = [];
     for (let index = 0; index < options.frameSkip; index += 1) {
       sim.step(FIXED_STEP);
-      stepEvents.push(...collectStepEvents(sim.snapshot().events));
+      const events = typeof sim.consumeStepEvents === 'function'
+        ? sim.consumeStepEvents()
+        : sim.events;
+      stepEvents.push(...collectStepEvents(events));
     }
     episodeState.step += 1;
+    advanceDriverEpisodes(episodeState, options.controlledDrivers);
     const result = buildResult({ host, episodeState, events: stepEvents, actionErrors: errors, actions });
     episodeState.lastResult = result;
+    emitExternalRenderFrame(host, result, { source: 'step', actions });
     host.afterStep(result);
     return result;
   }
@@ -73,8 +132,49 @@ export function createEnvironmentRuntime(host) {
       buildResult({ host, episodeState, events: [], actionErrors: [] }).observation;
   }
 
-  function getState() {
-    return { snapshot: host.getSimulation().snapshot() };
+  function getState({ output = 'full' } = {}) {
+    const sim = host.getSimulation();
+    if (output === 'none') return null;
+    if (output === 'minimal') return { snapshot: sim.snapshotObservation?.() ?? sim.snapshot() };
+    return { snapshot: sim.snapshot() };
+  }
+
+  function resetDrivers(placements = {}, resultOptions = {}) {
+    const options = host.getOptions();
+    const sim = host.getSimulation();
+    const driverIds = new Set(options.controlledDrivers);
+    const normalizedPlacements = normalizeEnvironmentPlacements(placements, driverIds);
+    const snapshot = sim.snapshotObservation?.() ?? sim.snapshot();
+    const carsById = new Map(snapshot.cars.map((car) => [car.id, car]));
+    applyEnvironmentPlacements(sim, snapshot.track, carsById, normalizedPlacements);
+    Object.keys(normalizedPlacements).forEach((driverId) => {
+      sim.clearCarControls?.(driverId);
+      sim.setAutomaticPitIntentEnabled?.(driverId, false);
+      sim.setPitIntent?.(driverId, 0);
+      const car = sim.cars?.find?.((item) => item.id === driverId);
+      if (car) sim.applyRunoffResponse?.(car);
+    });
+    resetDriverEpisodes(episodeState, Object.keys(normalizedPlacements));
+    episodeState.previousSnapshot = null;
+    const resetDriverIds = Object.keys(normalizedPlacements);
+    const observationScope = resultOptions.observationScope ??
+      resultOptions.resetDriversObservationScope ??
+      options.result.resetDriversObservationScope;
+    const result = buildResult({
+      host,
+      episodeState,
+      events: [],
+      actionErrors: [],
+      controlledDrivers: observationScope === 'reset' ? resetDriverIds : options.controlledDrivers,
+      stateOutput: resultOptions.stateOutput,
+    });
+    episodeState.lastResult = result;
+    emitExternalRenderFrame(host, result, {
+      source: 'resetDrivers',
+      resetDriverIds,
+      observationScope,
+    });
+    return result;
   }
 
   function getActionSpec() {
@@ -88,53 +188,189 @@ export function createEnvironmentRuntime(host) {
   function destroy() {
     episodeState.lastResult = null;
     episodeState.previousSnapshot = null;
+    episodeState.lastObservationSnapshot = null;
+    episodeState.lastRewardSnapshot = null;
+    episodeState.drivers?.clear?.();
+  }
+
+  return { reset, step, resetDrivers, getObservation, getState, getActionSpec, getObservationSpec, destroy };
+}
+
+function mergeEnvironmentResetOptions(currentOptions, nextOptions = {}) {
+  return mergePlainObjects(currentOptions, nextOptions);
+}
+
+const REPLACE_OBJECT_PATHS = new Set([
+  'scenario.placements',
+]);
+
+function mergePlainObjects(base, overrides, path = []) {
+  if (!isPlainObject(base) || !isPlainObject(overrides)) return overrides;
+  const merged = { ...base };
+  Object.entries(overrides).forEach(([key, value]) => {
+    const nextPath = [...path, key];
+    merged[key] = isPlainObject(value) &&
+      isPlainObject(base[key]) &&
+      !REPLACE_OBJECT_PATHS.has(nextPath.join('.'))
+      ? mergePlainObjects(base[key], value, nextPath)
+      : value;
+  });
+  return merged;
+}
+
+function isPlainObject(value) {
+  return value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+
+function isNoopPitIntent(pitIntent) {
+  if (pitIntent && typeof pitIntent === 'object') {
+    return Number(pitIntent.intent ?? pitIntent.pitIntent) === 0;
   }
+  return Number(pitIntent) === 0;
+}
 
-  return { reset, step, getObservation, getState, getActionSpec, getObservationSpec, destroy };
+function initializeControlledPitIntent(host) {
+  const sim = host.getSimulation?.();
+  const options = host.getOptions?.();
+  options?.controlledDrivers?.forEach?.((driverId) => {
+    sim?.setAutomaticPitIntentEnabled?.(driverId, false);
+    sim?.setPitIntent?.(driverId, 0);
+    const car = sim?.cars?.find?.((item) => item.id === driverId);
+    if (car) car.environmentControlled = true;
+  });
 }
 
-function buildResult({ host, episodeState, events, actionErrors, actions = {} }) {
+function buildResult({
+  host,
+  episodeState,
+  events,
+  actionErrors,
+  actions = {},
+  controlledDrivers = null,
+  stateOutput = null,
+}) {
   const options = host.getOptions();
-  const snapshot = host.getSimulation().snapshot();
+  const sim = host.getSimulation();
+  const resultDrivers = controlledDrivers ?? options.controlledDrivers;
+  const resolvedStateOutput = stateOutput ?? options.result.stateOutput;
+  const observationSnapshot = snapshotForResult(sim, options, resolvedStateOutput);
+  markDestroyedDriverEpisodes(episodeState, options.controlledDrivers, observationSnapshot);
   const observation = buildEnvironmentObservation({
-    snapshot,
+    snapshot: observationSnapshot,
     previousSnapshot: episodeState.previousSnapshot,
     options,
     events,
+    controlledDrivers: resultDrivers,
+  });
+  const episode = evaluateEpisode(observationSnapshot, options, episodeState, resultDrivers);
+  const metrics = buildDriverMetrics({
+    snapshot: observationSnapshot,
+    previousSnapshot: episodeState.previousSnapshot,
+    options: { ...options, controlledDrivers: resultDrivers },
+    events,
+  });
+  const rewardEpisodeInfo = buildDriverEpisodeInfo(episodeState, {
+    ...options,
+    controlledDrivers: resultDrivers,
+  }, episode);
+  const driverEpisodeInfo = buildDriverEpisodeInfo(episodeState, options, episode);
+  const { state, rewardSnapshot } = buildResultState(sim, observationSnapshot, resolvedStateOutput);
+  const reward = computeReward({
+    options: { ...options, controlledDrivers: resultDrivers },
+    observation,
+    events,
+    snapshot: rewardSnapshot,
+    actions,
+    previousSnapshot: episodeState.previousSnapshot,
+    metrics,
+    driverEpisodeInfo: rewardEpisodeInfo,
   });
-  const episode = evaluateEpisode(snapshot, options, episodeState);
-  const reward = computeReward({ options, observation, events, snapshot, actions, previousSnapshot: episodeState.previousSnapshot });
+  episodeState.lastObservationSnapshot = observationSnapshot;
+  episodeState.lastRewardSnapshot = rewardSnapshot;
   return {
     observation,
     reward,
+    metrics,
     terminated: episode.terminated,
     truncated: episode.truncated,
     done: episode.terminated || episode.truncated,
     events,
-    state: { snapshot },
+    state,
     info: {
       step: episodeState.step,
-      elapsedSeconds: snapshot.time,
+      elapsedSeconds: observationSnapshot.time,
       seed: options.seed,
       trackSeed: options.trackSeed,
       controlledDrivers: [...options.controlledDrivers],
       actionErrors,
       endReason: episode.endReason,
+      drivers: driverEpisodeInfo,
     },
   };
 }
 
-function computeReward({ options, observation, events, snapshot, actions, previousSnapshot }) {
+function buildResultState(sim, observationSnapshot, stateOutput) {
+  if (stateOutput === 'none') return { state: null, rewardSnapshot: observationSnapshot };
+  if (stateOutput === 'minimal') return { state: { snapshot: observationSnapshot }, rewardSnapshot: observationSnapshot };
+  const snapshot = sim.snapshot();
+  return { state: { snapshot }, rewardSnapshot: snapshot };
+}
+
+function snapshotForResult(sim, options, stateOutput) {
+  if (canUseTrainingSnapshot(options, stateOutput)) {
+    return sim.snapshotTraining?.() ?? sim.snapshotObservation?.() ?? sim.snapshot();
+  }
+  return sim.snapshotObservation?.() ?? sim.snapshot();
+}
+
+function canUseTrainingSnapshot(options, stateOutput) {
+  return stateOutput === 'none' &&
+    options.observation?.output === 'vector' &&
+    options.observation?.includeSchema === false;
+}
+
+function computeReward({ options, observation, events, snapshot, actions, previousSnapshot, metrics, driverEpisodeInfo }) {
   if (!options.reward) return null;
   return Object.fromEntries(options.controlledDrivers.map((driverId) => [
     driverId,
-    Number(options.reward({
+    normalizeRewardValue(options.reward({
       driverId,
       previous: previousSnapshot,
       current: observation[driverId],
       action: actions?.[driverId],
       events: observation[driverId]?.events ?? events,
       state: { snapshot },
-    }) ?? 0),
+      metrics: metrics?.[driverId] ?? null,
+      episode: driverEpisodeInfo?.[driverId] ?? null,
+    })),
   ]));
 }
+
+function emitExternalRenderFrame(host, result, meta = {}) {
+  const options = host.getOptions?.();
+  const onFrame = options?.externalRenderer?.onFrame;
+  if (typeof onFrame !== 'function') return;
+  try {
+    onFrame({
+      snapshot: result?.state?.snapshot ??
+        host.getSimulation?.()?.snapshotObservation?.() ??
+        host.getSimulation?.()?.snapshot?.(),
+      observation: result?.observation ?? {},
+      meta: {
+        ...meta,
+        step: result?.info?.step ?? null,
+        elapsedSeconds: result?.info?.elapsedSeconds ?? null,
+      },
+    });
+  } catch {
+    // External rendering hooks are observer-only and must not break stepping.
+  }
+}
+
+function normalizeRewardValue(value) {
+  const reward = Number(value ?? 0);
+  return Number.isFinite(reward) ? reward : 0;
+}