@inventure71/paddockjs 4.2.0 → 4.3.1

package/src/environment/runtime.js

@@ -1,21 +1,16 @@
-import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.js';
-import { disableWarmupOptions, runWarmupWithGuard } from '../simulation/warmup/runtimeWarmup.js';
+import { FIXED_STEP } from '../simulation/raceSimulation.js';
 import { handleActionError, resolveActionMap } from './actions.js';
 import { collectStepEvents } from './events.js';
-import {
-  advanceDriverEpisodes,
-  buildDriverEpisodeInfo,
-  createEpisodeState,
-  evaluateEpisode,
-  initializeDriverEpisodes,
-  markDestroyedDriverEpisodes,
-  resetDriverEpisodes,
-} from './episode.js';
-import { buildDriverMetrics } from './metrics.js';
-import { buildEnvironmentObservation } from './observations.js';
+import { advanceDriverEpisodes, createEpisodeState, initializeDriverEpisodes, resetDriverEpisodes } from './episode.js';
 import { resolveEnvironmentOptions } from './options.js';
-import { applyEnvironmentPlacements, applyEnvironmentScenario, normalizeEnvironmentPlacements } from './scenarios.js';
+import { applyEnvironmentPlacements, normalizeEnvironmentPlacements } from './scenarios.js';
 import { buildActionSpec, buildObservationSpec } from './specs.js';
+import { initializeControlledPitIntent, resetControlledDriverState } from './driverReset.js';
+import { createSimulationWithEnvironmentScenario } from './simulationSetup.js';
+import { mergeEnvironmentResetOptions } from './resetOptions.js';
+import { buildEnvironmentResult, snapshotForResult } from './results.js';
+import { emitExternalRenderFrame } from './renderFrames.js';
+import { clearMetricScratch, clearObservationScratch } from './scratch.js';
 
 export function createPaddockEnvironment(options = {}) {
   let resolvedOptions = resolveEnvironmentOptions(options);
@@ -37,31 +32,6 @@ export function createPaddockEnvironment(options = {}) {
   });
 }
 
-function createSimulationWithEnvironmentScenario(options) {
-  runWarmupWithGuard({
-    options,
-    surface: 'environment',
-    execute: ({ warmup }) => {
-      const warmupSimulation = createRaceSimulation(disableWarmupOptions(options, warmup.surface));
-      initializeControlledPitIntentForSimulation(warmupSimulation, options);
-      applyEnvironmentScenario(warmupSimulation, options);
-      applyControlledRunoffResponse(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(options, 'environment'));
-  initializeControlledPitIntentForSimulation(sim, options);
-  applyEnvironmentScenario(sim, options);
-  applyControlledRunoffResponse(sim, options);
-  return sim;
-}
-
 export function createEnvironmentRuntime(host) {
   const episodeState = createEpisodeState();
 
@@ -76,9 +46,9 @@ export function createEnvironmentRuntime(host) {
     episodeState.step = 0;
     episodeState.previousSnapshot = null;
     initializeDriverEpisodes(episodeState, options.controlledDrivers);
-    const result = buildResult({ host, episodeState, events: [], actionErrors: [] });
+    const result = buildEnvironmentResult({ host, episodeState, events: [], actionErrors: [] });
     episodeState.lastResult = result;
-    emitExternalRenderFrame(host, result, { source: 'reset' });
+    emitExternalRenderFrame(host, result, { source: 'reset' }, episodeState.lastObservationSnapshot);
     host.afterReset(result);
     return result;
   }
@@ -116,7 +86,7 @@ export function createEnvironmentRuntime(host) {
     }
     episodeState.step += 1;
     advanceDriverEpisodes(episodeState, options.controlledDrivers);
-    const result = buildResult({
+    const result = buildEnvironmentResult({
       host,
       episodeState,
       events: stepEvents,
@@ -125,14 +95,14 @@ export function createEnvironmentRuntime(host) {
       rewardEnabled: true,
     });
     episodeState.lastResult = result;
-    emitExternalRenderFrame(host, result, { source: 'step', actions });
+    emitExternalRenderFrame(host, result, { source: 'step', actions }, episodeState.lastObservationSnapshot);
     host.afterStep(result);
     return result;
   }
 
   function getObservation() {
     return episodeState.lastResult?.observation ??
-      buildResult({ host, episodeState, events: [], actionErrors: [] }).observation;
+      buildEnvironmentResult({ host, episodeState, events: [], actionErrors: [] }).observation;
   }
 
   function getState({ output = 'full' } = {}) {
@@ -150,21 +120,14 @@ export function createEnvironmentRuntime(host) {
     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);
-      const car = sim.cars?.find?.((item) => item.id === driverId);
-      resetEnvironmentPitStop(car);
-      sim.setPitIntent?.(driverId, 0);
-      if (car) sim.applyRunoffResponse?.(car);
-    });
+    resetControlledDriverState(sim, Object.keys(normalizedPlacements));
     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({
+    const result = buildEnvironmentResult({
       host,
       episodeState,
       events: [],
@@ -177,7 +140,7 @@ export function createEnvironmentRuntime(host) {
       source: 'resetDrivers',
       resetDriverIds,
       observationScope,
-    });
+    }, episodeState.lastObservationSnapshot);
     return result;
   }
 
@@ -203,255 +166,9 @@ export function createEnvironmentRuntime(host) {
   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]) => {
-    if (value === undefined) return;
-    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;
 }
-
-function initializeControlledPitIntent(host) {
-  const sim = host.getSimulation?.();
-  const options = host.getOptions?.();
-  initializeControlledPitIntentForSimulation(sim, options);
-}
-
-function initializeControlledPitIntentForSimulation(sim, options) {
-  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 resetEnvironmentPitStop(car) {
-  const stop = car?.pitStop;
-  if (!stop) return;
-  stop.status = 'pending';
-  stop.phase = null;
-  stop.intent = 0;
-  stop.queueingForService = false;
-  stop.route = null;
-  stop.routeProgress = 0;
-  stop.routeStartRaceDistance = null;
-  stop.routeEndRaceDistance = null;
-  stop.serviceRemaining = 0;
-  stop.penaltyServiceRemaining = 0;
-  stop.penaltyServiceTotal = 0;
-  stop.servingPenaltyIds = [];
-  stop.serviceProfile = null;
-}
-
-function buildResult({
-  host,
-  episodeState,
-  events,
-  actionErrors,
-  actions = {},
-  controlledDrivers = null,
-  stateOutput = null,
-  rewardEnabled = false,
-}) {
-  const options = host.getOptions();
-  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: observationSnapshot,
-    previousSnapshot: episodeState.previousSnapshot,
-    options,
-    events,
-    controlledDrivers: resultDrivers,
-    scratch: episodeState.observationScratch,
-  });
-  const episode = evaluateEpisode(observationSnapshot, options, episodeState, resultDrivers);
-  const metrics = buildDriverMetrics({
-    snapshot: observationSnapshot,
-    previousSnapshot: episodeState.previousSnapshot,
-    options: { ...options, controlledDrivers: resultDrivers },
-    events,
-    scratch: episodeState.metricScratch,
-  });
-  const rewardEpisodeInfo = buildDriverEpisodeInfo(episodeState, {
-    ...options,
-    controlledDrivers: resultDrivers,
-  }, episode);
-  const driverEpisode = resultDrivers === options.controlledDrivers
-    ? episode
-    : evaluateEpisode(observationSnapshot, options, episodeState, options.controlledDrivers);
-  const driverEpisodeInfo = buildDriverEpisodeInfo(episodeState, options, driverEpisode);
-  const { state, rewardSnapshot } = buildResultState(sim, observationSnapshot, resolvedStateOutput);
-  const reward = rewardEnabled
-    ? computeReward({
-      options: { ...options, controlledDrivers: resultDrivers },
-      observation,
-      events,
-      snapshot: rewardSnapshot,
-      actions,
-      previousSnapshot: episodeState.previousSnapshot,
-      metrics,
-      driverEpisodeInfo: rewardEpisodeInfo,
-    })
-    : null;
-  episodeState.lastObservationSnapshot = observationSnapshot;
-  episodeState.lastRewardSnapshot = rewardSnapshot;
-  return {
-    observation,
-    reward,
-    metrics,
-    terminated: episode.terminated,
-    truncated: episode.truncated,
-    done: episode.terminated || episode.truncated,
-    events,
-    state,
-    info: {
-      step: episodeState.step,
-      elapsedSeconds: observationSnapshot.time,
-      seed: options.seed,
-      trackSeed: options.trackSeed,
-      controlledDrivers: [...resultDrivers],
-      actionErrors,
-      endReason: episode.endReason,
-      drivers: driverEpisodeInfo,
-    },
-  };
-}
-
-function clearObservationScratch(scratch) {
-  if (!scratch) return;
-  scratch.carsById?.clear?.();
-  scratch.eventsByDriver?.clear?.();
-  scratch.controlledEventDrivers?.clear?.();
-  clearRayBatchContextScratch(scratch.rayBatchContextScratch);
-  if (Array.isArray(scratch.eventDriverIds)) scratch.eventDriverIds.length = 0;
-}
-
-function clearRayBatchContextScratch(scratch) {
-  if (!scratch) return;
-  const arrayKeys = [
-    'rayTargets',
-    'rayTargetPool',
-    'carTargets',
-    'rayVectors',
-    'sharedRayQueries',
-    'rays',
-    'rayPool',
-    'rayVectorValues',
-    'rayVectorValuePool',
-  ];
-  for (let index = 0; index < arrayKeys.length; index += 1) {
-    const value = scratch[arrayKeys[index]];
-    if (Array.isArray(value)) value.length = 0;
-  }
-}
-
-function clearMetricScratch(scratch) {
-  if (!scratch) return;
-  scratch.previousCarsById?.clear?.();
-  scratch.currentCarsById?.clear?.();
-  scratch.contactCounts?.clear?.();
-  if (Array.isArray(scratch.eventDriverIds)) scratch.eventDriverIds.length = 0;
-}
-
-function applyControlledRunoffResponse(sim, options) {
-  options?.controlledDrivers?.forEach?.((driverId) => {
-    const car = sim?.cars?.find?.((item) => item.id === driverId);
-    if (car) sim?.applyRunoffResponse?.(car);
-  });
-}
-
-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,
-    normalizeRewardValue(options.reward({
-      driverId,
-      previous: previousSnapshot,
-      current: observation[driverId],
-      action: actions?.[driverId],
-      events: observation[driverId]?.events ?? events,
-      state: { snapshot },
-      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;
-}

package/src/environment/scenarioOptions.js

@@ -0,0 +1,90 @@
+import { ENVIRONMENT_SCENARIO_PRESETS } from './scenarioPresets.js';
+
+export function resolveScenarioPlacementConfig(scenario = {}, driverIds = new Set()) {
+  const preset = scenario.preset == null ? null : String(scenario.preset);
+  if (preset && !ENVIRONMENT_SCENARIO_PRESETS.includes(preset)) {
+    throw new Error(`PaddockJS environment scenario.preset must be one of: ${ENVIRONMENT_SCENARIO_PRESETS.join(', ')}.`);
+  }
+
+  const placements = normalizePlacementMap(scenario.placements, driverIds);
+  const traffic = normalizeTrafficLayout(scenario.traffic, driverIds);
+
+  return {
+    preset,
+    placements,
+    traffic,
+  };
+}
+
+export function normalizeEnvironmentPlacements(placements = {}, driverIds = new Set()) {
+  return normalizePlacementMap(placements, driverIds);
+}
+
+function normalizePlacementMap(value, driverIds) {
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('PaddockJS environment scenario.placements must be an object keyed by driver id.');
+  }
+  return Object.fromEntries(Object.entries(value).map(([driverId, placement]) => {
+    assertKnownDriver(driverId, driverIds, 'scenario placement');
+    return [driverId, normalizePlacement(placement, `scenario.placements.${driverId}`)];
+  }));
+}
+
+function normalizeTrafficLayout(value, driverIds) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error('PaddockJS environment scenario.traffic must be an array.');
+  }
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== 'object') {
+      throw new Error(`PaddockJS environment scenario.traffic[${index}] must be an object.`);
+    }
+    assertKnownDriver(entry.driverId, driverIds, `scenario.traffic[${index}].driverId`);
+    assertKnownDriver(entry.relativeTo, driverIds, `scenario.traffic[${index}].relativeTo`);
+    return {
+      driverId: entry.driverId,
+      relativeTo: entry.relativeTo,
+      deltaDistanceMeters: finiteNumber(entry.deltaDistanceMeters, 0, `scenario.traffic[${index}].deltaDistanceMeters`),
+      offsetMeters: finiteNumber(entry.offsetMeters, 0, `scenario.traffic[${index}].offsetMeters`),
+      speedKph: optionalFiniteNumber(entry.speedKph, `scenario.traffic[${index}].speedKph`),
+      headingErrorRadians: finiteNumber(entry.headingErrorRadians, 0, `scenario.traffic[${index}].headingErrorRadians`),
+    };
+  });
+}
+
+function normalizePlacement(placement, label) {
+  if (!placement || typeof placement !== 'object') {
+    throw new Error(`PaddockJS environment ${label} must be an object.`);
+  }
+  const distanceMeters = placement.distanceMeters ?? placement.startDistanceMeters;
+  return {
+    distanceMeters: optionalFiniteNumber(distanceMeters, `${label}.distanceMeters`),
+    offsetMeters: finiteNumber(placement.offsetMeters, 0, `${label}.offsetMeters`),
+    speedKph: optionalFiniteNumber(placement.speedKph, `${label}.speedKph`),
+    headingErrorRadians: finiteNumber(placement.headingErrorRadians, 0, `${label}.headingErrorRadians`),
+  };
+}
+
+function assertKnownDriver(driverId, driverIds, label) {
+  if (typeof driverId !== 'string' || driverId.length === 0) {
+    throw new Error(`PaddockJS environment ${label} must be a driver id.`);
+  }
+  if (!driverIds.has(driverId)) {
+    throw new Error(`PaddockJS environment ${label} does not exist: ${driverId}`);
+  }
+}
+
+function finiteNumber(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number)) {
+    throw new Error(`PaddockJS environment ${label} must be a finite number.`);
+  }
+  return number;
+}
+
+function optionalFiniteNumber(value, label) {
+  if (value == null) return undefined;
+  return finiteNumber(value, undefined, label);
+}

package/src/environment/scenarioPlacements.js

@@ -0,0 +1,70 @@
+import { normalizeAngle } from '../simulation/simMath.js';
+import { offsetTrackPoint, pointAt } from '../simulation/track/trackModel.js';
+import { kphToSimSpeed, metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+
+export function applyEnvironmentPlacements(sim, track, carsById, placements = {}) {
+  const states = {};
+  Object.entries(placements).forEach(([driverId, placement]) => {
+    const currentCar = carsById.get(driverId);
+    if (!currentCar) return;
+    states[driverId] = placementToCarState(track, currentCar, placement, {
+      physicsMode: sim.physicsMode,
+    });
+  });
+  if (typeof sim.setCarStates === 'function') {
+    sim.setCarStates(states);
+    return;
+  }
+  Object.entries(states).forEach(([driverId, partial]) => {
+    sim.setCarState(driverId, partial);
+  });
+}
+
+function placementToCarState(track, currentCar, placement, { physicsMode = 'arcade' } = {}) {
+  const currentDistanceMeters = currentCar.distanceMeters ?? simUnitsToMeters(currentCar.raceDistance ?? currentCar.progress ?? 0);
+  const raceDistance = metersToSimUnits(Math.max(0, placement.distanceMeters ?? currentDistanceMeters));
+  const offset = metersToSimUnits(placement.offsetMeters ?? 0);
+  const base = pointAt(track, raceDistance);
+  const position = offsetTrackPoint(base, offset);
+  const heading = normalizeAngle(base.heading + (placement.headingErrorRadians ?? 0));
+  const speed = placement.speedKph == null ? null : kphToSimSpeed(placement.speedKph);
+  const partial = {
+    x: position.x,
+    y: position.y,
+    previousX: position.x,
+    previousY: position.y,
+    progress: base.distance,
+    raceDistance,
+    desiredOffset: offset,
+    heading,
+    previousHeading: heading,
+    destroyed: false,
+    destroyReason: null,
+    destroyedAt: null,
+    outOfRace: false,
+    canAttack: true,
+    throttle: 0,
+    brake: 0,
+    longitudinalAcceleration: 0,
+    lateralAcceleration: 0,
+    lateralG: 0,
+    longitudinalG: 0,
+    gripUsage: 0,
+    slipAngleRadians: 0,
+    tractionLimited: false,
+    steeringAngle: 0,
+    yawRate: 0,
+    stabilityState: 'stable',
+  };
+  if (speed != null) {
+    partial.speed = speed;
+    if (physicsMode === 'advanced') {
+      partial.velocityX = Math.cos(heading) * speed;
+      partial.velocityY = Math.sin(heading) * speed;
+    } else {
+      partial.velocityX = null;
+      partial.velocityY = null;
+    }
+  }
+  return partial;
+}

package/src/environment/scenarioPresets.js

@@ -0,0 +1,78 @@
+import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+
+export const ENVIRONMENT_SCENARIO_PRESETS = Object.freeze([
+  'cornering',
+  'off-track-recovery',
+  'overtaking-pack',
+  'pit-entry',
+]);
+
+export function buildPresetPlacements(snapshot, options) {
+  const preset = options.scenario?.preset;
+  if (!preset) return {};
+  const controlledDriverId = options.controlledDrivers[0];
+  const cars = snapshot.cars;
+  const track = snapshot.track;
+  const primaryDistance = presetBaseDistance(track, preset);
+  const placements = {};
+
+  if (preset === 'cornering') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: 0,
+      speedKph: 135,
+      headingErrorRadians: 0,
+    };
+  } else if (preset === 'off-track-recovery') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: simUnitsToMeters(track.width / 2) + 7,
+      speedKph: 52,
+      headingErrorRadians: -0.45,
+    };
+  } else if (preset === 'pit-entry') {
+    placements[controlledDriverId] = {
+      distanceMeters: simUnitsToMeters(primaryDistance),
+      offsetMeters: 0,
+      speedKph: 120,
+      headingErrorRadians: 0,
+    };
+  } else if (preset === 'overtaking-pack') {
+    const baseMeters = simUnitsToMeters(primaryDistance);
+    cars.slice(0, 4).forEach((car, index) => {
+      placements[car.id] = {
+        distanceMeters: baseMeters + (index - 1) * 18,
+        offsetMeters: index % 2 === 0 ? -2.2 : 2.2,
+        speedKph: 135 - index * 3,
+        headingErrorRadians: 0,
+      };
+    });
+  }
+
+  return placements;
+}
+
+function presetBaseDistance(track, preset) {
+  if (preset === 'cornering') return findHighCurvatureDistance(track) - metersToSimUnits(70);
+  if (preset === 'off-track-recovery') return track.length * 0.42;
+  if (preset === 'overtaking-pack') return track.length * 0.35;
+  if (preset === 'pit-entry') {
+    const pitDistance = track.pitLane?.entry?.trackDistance ??
+      track.pitLane?.entry?.distanceFromStart ??
+      track.length * 0.92;
+    return pitDistance - metersToSimUnits(170);
+  }
+  return 0;
+}
+
+function findHighCurvatureDistance(track) {
+  const samples = Array.isArray(track.samples) ? track.samples : [];
+  const fallback = track.length * 0.25;
+  const best = samples
+    .filter((sample) => sample.distance > metersToSimUnits(350))
+    .reduce((selected, sample) => {
+      if (!selected || (sample.curvature ?? 0) > (selected.curvature ?? 0)) return sample;
+      return selected;
+    }, null);
+  return best?.distance ?? fallback;
+}