@inventure71/paddockjs 0.2.0 → 0.3.0

package/src/environment/rewards.js

@@ -0,0 +1,69 @@
+const DEFAULT_PROGRESS_REWARD_WEIGHTS = Object.freeze({
+  progress: 1,
+  speed: 0.01,
+  offTrack: -2,
+  collision: -10,
+  steering: -0.03,
+  brake: -0.02,
+});
+
+export function createProgressReward(options = {}) {
+  const weights = {
+    ...DEFAULT_PROGRESS_REWARD_WEIGHTS,
+    ...(options.weights ?? {}),
+  };
+
+  return function progressReward(context = {}) {
+    const driverId = context.driverId;
+    const previousCar = findSnapshotCar(context.previous, driverId);
+    const currentCar = findSnapshotCar(context.state?.snapshot, driverId);
+    const progressMeters = getProgressMeters(previousCar, currentCar);
+    const self = context.current?.object?.self ?? {};
+    const speedKph = Number(self.speedKph ?? 0);
+    const isOnTrack = self.onTrack !== false;
+    const collisionCount = countDriverCollisions(context.events, driverId);
+    const steering = Math.abs(Number(context.action?.steering ?? 0));
+    const brake = Math.abs(Number(context.action?.brake ?? 0));
+
+    return (
+      progressMeters * weights.progress +
+      (isOnTrack ? speedKph * weights.speed : 0) +
+      (isOnTrack ? 0 : weights.offTrack) +
+      collisionCount * weights.collision +
+      steering * weights.steering +
+      brake * weights.brake
+    );
+  };
+}
+
+function findSnapshotCar(snapshot, driverId) {
+  if (!snapshot || !driverId || !Array.isArray(snapshot.cars)) return null;
+  return snapshot.cars.find((car) => car?.id === driverId) ?? null;
+}
+
+function getProgressMeters(previousCar, currentCar) {
+  if (!previousCar || !currentCar) return 0;
+  const previous = Number(previousCar.distanceMeters ?? previousCar.raceDistanceMeters ?? 0);
+  const current = Number(currentCar.distanceMeters ?? currentCar.raceDistanceMeters ?? 0);
+  if (!Number.isFinite(previous) || !Number.isFinite(current)) return 0;
+  return current - previous;
+}
+
+function countDriverCollisions(events = [], driverId) {
+  if (!driverId || !Array.isArray(events)) return 0;
+  return events.filter((event) => isCollisionEvent(event) && eventIncludesDriver(event, driverId)).length;
+}
+
+function isCollisionEvent(event) {
+  return event?.type === 'collision' || event?.type === 'contact';
+}
+
+function eventIncludesDriver(event, driverId) {
+  if (event.driverId === driverId ||
+      event.carId === driverId ||
+      event.primaryDriverId === driverId ||
+      event.otherDriverId === driverId) {
+    return true;
+  }
+  return Array.isArray(event.driverIds) && event.driverIds.includes(driverId);
+}

package/src/environment/runtime.js

@@ -0,0 +1,140 @@
+import { createRaceSimulation, FIXED_STEP } from '../simulation/raceSimulation.js';
+import { resolveActionMap } from './actions.js';
+import { collectStepEvents } from './events.js';
+import { createEpisodeState, evaluateEpisode } from './episode.js';
+import { buildEnvironmentObservation } from './observations.js';
+import { resolveEnvironmentOptions } from './options.js';
+import { buildActionSpec, buildObservationSpec } from './specs.js';
+
+export function createPaddockEnvironment(options = {}) {
+  let resolvedOptions = resolveEnvironmentOptions(options);
+  let sim = createRaceSimulation(resolvedOptions);
+  return createEnvironmentRuntime({
+    getSimulation: () => sim,
+    setSimulation(nextSim) {
+      sim = nextSim;
+    },
+    createSimulation(nextOptions) {
+      return createRaceSimulation(nextOptions);
+    },
+    getOptions: () => resolvedOptions,
+    setOptions(nextOptions) {
+      resolvedOptions = nextOptions;
+    },
+    afterReset() {},
+    afterStep() {},
+  });
+}
+
+export function createEnvironmentRuntime(host) {
+  const episodeState = createEpisodeState();
+
+  function reset(nextOptions = {}) {
+    const options = resolveEnvironmentOptions({
+      ...host.getOptions(),
+      ...nextOptions,
+    });
+    host.setOptions(options);
+    host.setSimulation(host.createSimulation(options));
+    episodeState.step = 0;
+    episodeState.previousSnapshot = null;
+    const result = buildResult({ host, episodeState, events: [], actionErrors: [] });
+    episodeState.lastResult = result;
+    host.afterReset(result);
+    return result;
+  }
+
+  function step(actions = {}) {
+    const options = host.getOptions();
+    const sim = host.getSimulation();
+    const { controlsByDriver, errors } = resolveActionMap(actions, options.controlledDrivers, {
+      policy: options.actionPolicy,
+    });
+
+    Object.entries(controlsByDriver).forEach(([driverId, controls]) => {
+      sim.setCarControls(driverId, controls);
+    });
+
+    episodeState.previousSnapshot = sim.snapshot();
+    const stepEvents = [];
+    for (let index = 0; index < options.frameSkip; index += 1) {
+      sim.step(FIXED_STEP);
+      stepEvents.push(...collectStepEvents(sim.snapshot().events));
+    }
+    episodeState.step += 1;
+    const result = buildResult({ host, episodeState, events: stepEvents, actionErrors: errors, actions });
+    episodeState.lastResult = result;
+    host.afterStep(result);
+    return result;
+  }
+
+  function getObservation() {
+    return episodeState.lastResult?.observation ??
+      buildResult({ host, episodeState, events: [], actionErrors: [] }).observation;
+  }
+
+  function getState() {
+    return { snapshot: host.getSimulation().snapshot() };
+  }
+
+  function getActionSpec() {
+    return buildActionSpec(host.getOptions());
+  }
+
+  function getObservationSpec() {
+    return buildObservationSpec(host.getOptions());
+  }
+
+  function destroy() {
+    episodeState.lastResult = null;
+    episodeState.previousSnapshot = null;
+  }
+
+  return { reset, step, getObservation, getState, getActionSpec, getObservationSpec, destroy };
+}
+
+function buildResult({ host, episodeState, events, actionErrors, actions = {} }) {
+  const options = host.getOptions();
+  const snapshot = host.getSimulation().snapshot();
+  const observation = buildEnvironmentObservation({
+    snapshot,
+    previousSnapshot: episodeState.previousSnapshot,
+    options,
+    events,
+  });
+  const episode = evaluateEpisode(snapshot, options, episodeState);
+  const reward = computeReward({ options, observation, events, snapshot, actions, previousSnapshot: episodeState.previousSnapshot });
+  return {
+    observation,
+    reward,
+    terminated: episode.terminated,
+    truncated: episode.truncated,
+    done: episode.terminated || episode.truncated,
+    events,
+    state: { snapshot },
+    info: {
+      step: episodeState.step,
+      elapsedSeconds: snapshot.time,
+      seed: options.seed,
+      trackSeed: options.trackSeed,
+      controlledDrivers: [...options.controlledDrivers],
+      actionErrors,
+      endReason: episode.endReason,
+    },
+  };
+}
+
+function computeReward({ options, observation, events, snapshot, actions, previousSnapshot }) {
+  if (!options.reward) return null;
+  return Object.fromEntries(options.controlledDrivers.map((driverId) => [
+    driverId,
+    Number(options.reward({
+      driverId,
+      previous: previousSnapshot,
+      current: observation[driverId],
+      action: actions?.[driverId],
+      events: observation[driverId]?.events ?? events,
+      state: { snapshot },
+    }) ?? 0),
+  ]));
+}

package/src/environment/sensors.js

@@ -0,0 +1,257 @@
+import { nearestTrackState } from '../simulation/trackModel.js';
+import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+import { VEHICLE_LIMITS } from '../simulation/vehiclePhysics.js';
+
+const TRACK_RAY_STEP_METERS = 1;
+const TRACK_RAY_REFINE_STEPS = 12;
+export const DEFAULT_RAY_ANGLES_DEGREES = [-135, -60, -20, 0, 20, 60, 135, 180];
+
+export function buildNearbyCars(car, snapshot, { maxCars = 6, radiusMeters = 150 } = {}) {
+  return snapshot.cars
+    .filter((other) => other.id !== car.id)
+    .map((other) => {
+      const dx = other.x - car.x;
+      const dy = other.y - car.y;
+      const distanceMeters = simUnitsToMeters(Math.hypot(dx, dy));
+      const forward = Math.cos(car.heading) * dx + Math.sin(car.heading) * dy;
+      const right = -Math.sin(car.heading) * dx + Math.cos(car.heading) * dy;
+      return {
+        id: other.id,
+        relativeForwardMeters: simUnitsToMeters(forward),
+        relativeRightMeters: simUnitsToMeters(right),
+        relativeDistanceMeters: distanceMeters,
+        relativeSpeedKph: other.speedKph - car.speedKph,
+        relativeHeadingRadians: normalizeRelativeHeading(other.heading - car.heading),
+        ahead: forward > 0,
+        sameLap: other.lap === car.lap,
+      };
+    })
+    .filter((entry) => entry.relativeDistanceMeters <= radiusMeters)
+    .sort((a, b) => a.relativeDistanceMeters - b.relativeDistanceMeters)
+    .slice(0, maxCars);
+}
+
+export function buildRaySensors(car, snapshot, rayOptions = {}) {
+  const angles = rayOptions.anglesDegrees ?? DEFAULT_RAY_ANGLES_DEGREES;
+  const lengthMeters = rayOptions.lengthMeters ?? 120;
+
+  return angles.map((angleDegrees) => ({
+    angleDegrees,
+    angleRadians: degreesToRadians(angleDegrees),
+    lengthMeters,
+    track: rayOptions.detectTrack === false
+      ? createTrackMiss(lengthMeters)
+      : estimateTrackHit(car, snapshot, angleDegrees, lengthMeters),
+    car: rayOptions.detectCars === false
+      ? { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 }
+      : estimateCarHit(car, snapshot, angleDegrees, lengthMeters),
+  }));
+}
+
+function estimateTrackHit(car, snapshot, angleDegrees, lengthMeters) {
+  if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
+    return estimateLocalTrackHit(car, snapshot, angleDegrees, lengthMeters);
+  }
+
+  const origin = getCarRayOrigin(car);
+  const ray = getCarRayVector(car, angleDegrees);
+  const maxDistance = metersToSimUnits(lengthMeters);
+  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
+  let previousDistance = 0;
+  let previousInside = null;
+
+  for (let distance = 0; distance <= maxDistance; distance += step) {
+    const state = nearestTrackState(snapshot.track, pointOnRay(origin, ray, distance), car.progress);
+    const inside = isInsideTrackBorder(state, snapshot.track);
+    if (previousInside == null) {
+      previousInside = inside;
+      previousDistance = distance;
+      continue;
+    }
+
+    if (inside !== previousInside) {
+      const kind = previousInside ? 'exit' : 'entry';
+      const hitDistance = refineTrackTransitionDistance(
+        snapshot.track,
+        origin,
+        ray,
+        car.progress,
+        previousDistance,
+        distance,
+        kind,
+      );
+      return {
+        hit: true,
+        distanceMeters: simUnitsToMeters(hitDistance),
+        kind,
+      };
+    }
+    previousDistance = distance;
+    previousInside = inside;
+  }
+
+  return createTrackMiss(lengthMeters);
+}
+
+function estimateLocalTrackHit(car, snapshot, angleDegrees, lengthMeters) {
+  const trackHalfWidthMeters = simUnitsToMeters(snapshot.track.width / 2);
+  const offsetMeters = simUnitsToMeters(car.signedOffset ?? 0);
+  const lateral = Math.sin(degreesToRadians(angleDegrees));
+  if (Math.abs(lateral) < 0.08) {
+    return createTrackMiss(lengthMeters);
+  }
+
+  const inside = Math.abs(offsetMeters) <= trackHalfWidthMeters;
+  const targetEdge = getLocalTrackTransitionTarget({ inside, offsetMeters, lateral, trackHalfWidthMeters });
+  if (targetEdge == null) return createTrackMiss(lengthMeters);
+
+  const distanceMeters = (targetEdge - offsetMeters) / lateral;
+  if (distanceMeters < 0 || distanceMeters > lengthMeters) return createTrackMiss(lengthMeters);
+
+  return {
+    hit: true,
+    distanceMeters,
+    kind: inside ? 'exit' : 'entry',
+  };
+}
+
+function getLocalTrackTransitionTarget({ inside, offsetMeters, lateral, trackHalfWidthMeters }) {
+  if (inside) return lateral > 0 ? trackHalfWidthMeters : -trackHalfWidthMeters;
+  if (offsetMeters > trackHalfWidthMeters) return lateral < 0 ? trackHalfWidthMeters : null;
+  if (offsetMeters < -trackHalfWidthMeters) return lateral > 0 ? -trackHalfWidthMeters : null;
+  return null;
+}
+
+function refineTrackTransitionDistance(track, origin, ray, progressHint, lowDistance, highDistance, kind) {
+  let low = lowDistance;
+  let high = highDistance;
+  for (let index = 0; index < TRACK_RAY_REFINE_STEPS; index += 1) {
+    const middle = (low + high) / 2;
+    const state = nearestTrackState(track, pointOnRay(origin, ray, middle), progressHint);
+    const inside = isInsideTrackBorder(state, track);
+    if (kind === 'entry') {
+      if (inside) high = middle;
+      else low = middle;
+    } else if (inside) {
+      low = middle;
+    } else {
+      high = middle;
+    }
+  }
+  return high;
+}
+
+function isInsideTrackBorder(state, track) {
+  return state.crossTrackError <= track.width / 2;
+}
+
+function createTrackMiss(lengthMeters) {
+  return {
+    hit: false,
+    distanceMeters: lengthMeters,
+    kind: null,
+  };
+}
+
+function estimateCarHit(car, snapshot, angleDegrees, lengthMeters) {
+  const origin = getCarRayOrigin(car);
+  const ray = getCarRayVector(car, angleDegrees);
+  const maxDistance = metersToSimUnits(lengthMeters);
+  let closest = null;
+  snapshot.cars.forEach((other) => {
+    if (other.id === car.id) return;
+    const hitDistance = intersectCarFootprint(origin, ray, other);
+    if (hitDistance == null || hitDistance > maxDistance) return;
+    const distanceMeters = simUnitsToMeters(hitDistance);
+    if (!closest || hitDistance < closest.distanceSimUnits) {
+      closest = {
+        hit: true,
+        distanceSimUnits: hitDistance,
+        distanceMeters,
+        driverId: other.id,
+        relativeSpeedKph: other.speedKph - car.speedKph,
+      };
+    }
+  });
+  if (!closest) return { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 };
+  const { distanceSimUnits, ...publicHit } = closest;
+  return publicHit;
+}
+
+export function getCarRayOrigin(car) {
+  return {
+    x: car.x,
+    y: car.y,
+  };
+}
+
+export function getCarRayVector(car, angleDegrees) {
+  const angle = car.heading + degreesToRadians(angleDegrees);
+  return {
+    x: Math.cos(angle),
+    y: Math.sin(angle),
+  };
+}
+
+function pointOnRay(origin, ray, distance) {
+  return {
+    x: origin.x + ray.x * distance,
+    y: origin.y + ray.y * distance,
+  };
+}
+
+function intersectCarFootprint(origin, ray, other) {
+  const forward = { x: Math.cos(other.heading), y: Math.sin(other.heading) };
+  const right = { x: -Math.sin(other.heading), y: Math.cos(other.heading) };
+  const delta = { x: origin.x - other.x, y: origin.y - other.y };
+  const localOrigin = {
+    x: dot(delta, forward),
+    y: dot(delta, right),
+  };
+  const localRay = {
+    x: dot(ray, forward),
+    y: dot(ray, right),
+  };
+  const halfLength = VEHICLE_LIMITS.carLength / 2;
+  const halfWidth = VEHICLE_LIMITS.carWidth / 2;
+  return intersectAxisAlignedBoxRay(localOrigin, localRay, halfLength, halfWidth);
+}
+
+function intersectAxisAlignedBoxRay(origin, ray, halfLength, halfWidth) {
+  let tMin = -Infinity;
+  let tMax = Infinity;
+  const xRange = intersectSlab(origin.x, ray.x, -halfLength, halfLength);
+  const yRange = intersectSlab(origin.y, ray.y, -halfWidth, halfWidth);
+  if (!xRange || !yRange) return null;
+  tMin = Math.max(tMin, xRange.min, yRange.min);
+  tMax = Math.min(tMax, xRange.max, yRange.max);
+  if (tMax < 0 || tMin > tMax) return null;
+  return Math.max(0, tMin);
+}
+
+function intersectSlab(origin, direction, min, max) {
+  if (Math.abs(direction) < 1e-9) {
+    return origin >= min && origin <= max ? { min: -Infinity, max: Infinity } : null;
+  }
+  const first = (min - origin) / direction;
+  const second = (max - origin) / direction;
+  return {
+    min: Math.min(first, second),
+    max: Math.max(first, second),
+  };
+}
+
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y;
+}
+
+function degreesToRadians(degrees) {
+  return (degrees * Math.PI) / 180;
+}
+
+function normalizeRelativeHeading(angle) {
+  let value = angle;
+  while (value > Math.PI) value -= Math.PI * 2;
+  while (value < -Math.PI) value += Math.PI * 2;
+  return value;
+}

package/src/environment/specs.js

@@ -0,0 +1,79 @@
+export function buildActionSpec(options) {
+  return {
+    version: 1,
+    controlledDrivers: [...options.controlledDrivers],
+    action: {
+      type: 'continuous',
+      perDriver: {
+        steering: { min: -1, max: 1, unit: 'normalized' },
+        throttle: { min: 0, max: 1, unit: 'normalized' },
+        brake: { min: 0, max: 1, unit: 'normalized' },
+      },
+    },
+  };
+}
+
+export function buildObservationSpec(options) {
+  const rayOptions = options.sensors.rays;
+  const nearbyOptions = options.sensors.nearbyCars;
+  return {
+    version: 1,
+    controlledDrivers: [...options.controlledDrivers],
+    object: {
+      self: [
+        { name: 'id', unit: 'id' },
+        { name: 'speedKph', unit: 'kph' },
+        { name: 'speedMetersPerSecond', unit: 'm/s' },
+        { name: 'headingRadians', unit: 'rad' },
+        { name: 'steeringAngleRadians', unit: 'rad' },
+        { name: 'throttle', unit: 'normalized' },
+        { name: 'brake', unit: 'normalized' },
+        { name: 'lap', unit: 'count' },
+        { name: 'completedLaps', unit: 'count' },
+        { name: 'lapProgressMeters', unit: 'm' },
+        { name: 'trackOffsetMeters', unit: 'm' },
+        { name: 'trackHeadingErrorRadians', unit: 'rad' },
+        { name: 'onTrack', unit: 'boolean' },
+        { name: 'surface', unit: 'label' },
+        { name: 'tireEnergy', unit: 'nullable:number' },
+      ],
+      race: [
+        { name: 'position', unit: 'rank' },
+        { name: 'totalCars', unit: 'count' },
+        { name: 'raceMode', unit: 'label' },
+        { name: 'totalLaps', unit: 'count' },
+      ],
+      rays: {
+        enabled: Boolean(rayOptions.enabled),
+        anglesDegrees: [...rayOptions.anglesDegrees],
+        lengthMeters: rayOptions.lengthMeters,
+        track: {
+          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+          hit: { unit: 'boolean' },
+          kind: { values: ['exit', 'entry', null] },
+        },
+        car: {
+          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+          hit: { unit: 'boolean' },
+          driverId: { nullable: true },
+          relativeSpeedKph: { unit: 'kph' },
+        },
+      },
+      nearbyCars: {
+        enabled: Boolean(nearbyOptions.enabled),
+        maxCars: nearbyOptions.maxCars,
+        radiusMeters: nearbyOptions.radiusMeters,
+      },
+      events: { type: 'array' },
+    },
+    vector: {
+      schema: [
+        { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
+        { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
+        { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
+        { name: 'self.onTrack', scale: 'boolean' },
+        { name: 'race.position', scale: 'fixed:field-position' },
+      ],
+    },
+  };
+}

package/src/index.d.ts

@@ -1,5 +1,9 @@
+import type { PaddockActionSpec, PaddockObservationSpec } from './environment/index.js';
+
+export type { PaddockActionSpec, PaddockObservationSpec } from './environment/index.js';
+
 export type TireCompound = 'S' | 'M' | 'H';
-export type CameraMode = 'overview' | 'leader' | 'selected';
+export type CameraMode = 'overview' | 'leader' | 'selected' | 'show-all';
 export type RaceBannerMode = 'project' | 'radio' | 'hidden';
 export type RaceBannerEnabledMode = 'project' | 'radio';
 export type RaceDataBannerSize = 'auto' | 'custom';
@@ -179,6 +183,7 @@ export interface F1SimulatorUiOptions {
     enabled?: true | false | RaceBannerEnabledMode[];
   };
   raceDataBannerSize?: RaceDataBannerSize;
+  raceDataTelemetryDetail?: boolean;
   timingTowerVerticalFit?: TimingTowerVerticalFit;
 }
 
@@ -323,6 +328,31 @@ export interface F1SimulatorCallbacks {
   }) => void;
 }
 
+export interface F1SimulatorExpertOptions {
+  enabled: boolean;
+  controlledDrivers: string[];
+  frameSkip?: number;
+  visualizeSensors?: boolean | {
+    rays?: boolean;
+  };
+}
+
+export interface F1SimulatorExpertAction {
+  steering: number;
+  throttle: number;
+  brake: number;
+}
+
+export interface F1SimulatorExpertApi {
+  reset(options?: unknown): unknown;
+  step(actions: Record<string, F1SimulatorExpertAction>): unknown;
+  getObservation(): unknown;
+  getState(): unknown;
+  getActionSpec(): PaddockActionSpec;
+  getObservationSpec(): PaddockObservationSpec;
+  destroy(): void;
+}
+
 export interface F1SimulatorOptions extends F1SimulatorCallbacks {
   preset?: PaddockPresetName;
   drivers: SimulatorDriver[];
@@ -339,8 +369,11 @@ export interface F1SimulatorOptions extends F1SimulatorCallbacks {
   showBackLink?: boolean;
   ui?: F1SimulatorUiOptions;
   assets?: F1SimulatorAssets;
+  expert?: F1SimulatorExpertOptions;
 }
 
+export type F1SimulatorRestartOptions = Partial<Omit<F1SimulatorOptions, 'assets' | 'expert'>>;
+
 export interface MountRaceCanvasOptions {
   includeRaceDataPanel?: boolean;
   includeTimingTower?: boolean;
@@ -355,11 +388,13 @@ export interface MountTelemetryPanelOptions {
 export interface MountRaceTelemetryDrawerOptions {
   timingTowerVerticalFit?: TimingTowerVerticalFit;
   drawerInitiallyOpen?: boolean;
+  raceDataTelemetryDetail?: boolean;
 }
 
 export interface F1MountedSimulator {
+  readonly expert: F1SimulatorExpertApi | null;
   destroy(): void;
-  restart(nextOptions?: Partial<F1SimulatorOptions>): void;
+  restart(nextOptions?: F1SimulatorRestartOptions): void;
   selectDriver(driverId: string): void;
   setSafetyCarDeployed(deployed: boolean): void;
   callSafetyCar(): void;
@@ -369,6 +404,7 @@ export interface F1MountedSimulator {
 }
 
 export interface PaddockSimulatorController {
+  readonly expert: F1SimulatorExpertApi | null;
   mountRaceControls<T extends Element>(root: T): T;
   mountCameraControls<T extends Element>(root: T): T;
   mountSafetyCarControl<T extends Element>(root: T): T;
@@ -387,7 +423,7 @@ export interface PaddockSimulatorController {
   querySelectorAll(selector: string): Element[];
   start(): Promise<PaddockSimulatorController>;
   destroy(): void;
-  restart(nextOptions?: Partial<F1SimulatorOptions>): void;
+  restart(nextOptions?: F1SimulatorRestartOptions): void;
   selectDriver(driverId: string): void;
   setSafetyCarDeployed(deployed: boolean): void;
   callSafetyCar(): void;
@@ -416,7 +452,7 @@ export function buildChampionshipDriverGrid(
 export function formatDriverNumber(driverNumber: number | string | null | undefined): string;
 export function normalizeSimulatorDrivers(
   drivers: SimulatorDriver[],
-  options?: { entries?: ChampionshipEntryBlueprint[] },
+  options?: { entries?: ChampionshipEntryBlueprint[]; caller?: string },
 ): NormalizedSimulatorDriver[];
 
 export function metersToSimUnits(meters: number): number;

package/src/index.js

@@ -91,13 +91,17 @@ export async function mountF1Simulator(root, options = {}) {
   await app.init();
 
   return {
+    get expert() {
+      return app.expert ?? null;
+    },
     destroy() {
       app.destroy();
       root.innerHTML = '';
     },
     restart(nextOptions = {}) {
-      resolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(resolvedOptions, nextOptions));
-      app.restart(resolvedOptions);
+      const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(resolvedOptions, nextOptions));
+      app.restart(nextResolvedOptions);
+      resolvedOptions = nextResolvedOptions;
     },
     selectDriver(driverId) {
       app.selectCar(driverId, { focus: true });

package/src/rendering/proceduralTrackAsset.js

@@ -48,6 +48,12 @@ function textureOrWhite(texture) {
   return texture ?? Texture.WHITE;
 }
 
+function destroyDisplayChildren(container) {
+  container.removeChildren().forEach((child) => {
+    child.destroy?.({ children: true, texture: false, textureSource: false });
+  });
+}
+
 function arcDistance(track, first, second) {
   const delta = Math.abs(first - second);
   return Math.min(delta, track.length - delta);
@@ -269,7 +275,7 @@ export class ProceduralTrackAsset {
   }
 
   render(track) {
-    this.container.removeChildren();
+    destroyDisplayChildren(this.container);
     this.addGrass();
     this.addGravelRunoff(track);
     this.addBoundaryUnderlay(track);