@inventure71/paddockjs 4.1.0 → 4.3.0

package/src/index.d.ts

@@ -1,7 +1,14 @@
+import type { PaddockProceduralTrackProfile, PaddockProceduralTrackOptions, PaddockTrackPoint, PaddockDrsZone, PaddockResolvedProceduralTrackOptions, PaddockProceduralTrack } from './data/trackTypes.js';
+import type { TireCompound, CustomField, CustomFieldInput, EntryPresentation, SimulatorDriver, DriverRatings, VehicleRatings, DriverBlueprint, VehicleBlueprint, DriverConstructorArgs, VehicleConstructorArgs, DriverData, VehicleData, ChampionshipEntryBlueprint, NormalizedSimulatorDriver } from './data/entryTypes.js';
+export type { PaddockProceduralTrackProfile, PaddockProceduralTrackOptions, PaddockTrackPoint, PaddockDrsZone, PaddockResolvedProceduralTrackOptions, PaddockProceduralTrack } from './data/trackTypes.js';
+export type { TireCompound, CustomField, CustomFieldInput, EntryPresentation, SimulatorDriver, DriverRatings, VehicleRatings, DriverBlueprint, VehicleBlueprint, DriverConstructorArgs, VehicleConstructorArgs, ChampionshipEntryBlueprint, NormalizedSimulatorDriver } from './data/entryTypes.js';
+export { DriverData, VehicleData } from './data/entryTypes.js';
+
 import type {
   PaddockActionSpec,
   PaddockDriverControllerLoop,
   PaddockDriverControllerLoopOptions,
+  PaddockEnvironmentResult,
   PaddockEnvironmentOptions,
   PaddockObservationSpec,
   PaddockParticipantInteraction as EnvPaddockParticipantInteraction,
@@ -12,6 +19,11 @@ import type {
   PaddockReplayGhostSnapshot as EnvPaddockReplayGhostSnapshot,
   PaddockReplayGhostTrajectorySample as EnvPaddockReplayGhostTrajectorySample,
 } from './environment/index.js';
+import type {
+  PaddockPitCrewStats,
+  PaddockThemeSelector,
+  TeamData,
+} from './data/teamTypes.js';
 
 export type {
   PaddockActionSpec,
@@ -20,13 +32,18 @@ export type {
   PaddockDriverControllerContext,
   PaddockDriverControllerLoop,
   PaddockDriverControllerLoopOptions,
+  PaddockEnvironmentResult,
+  PaddockEnvironmentSnapshotResult,
   PaddockObservationSpec,
 } from './environment/index.js';
+export type {
+  PaddockPitCrewStats,
+  PaddockThemeSelector,
+  TeamData,
+} from './data/teamTypes.js';
 
-export type TireCompound = 'S' | 'M' | 'H';
 export type PaddockPhysicsMode = 'arcade' | 'advanced';
 export type PaddockWarmupPolicy = 'config-change' | 'always' | 'never';
-export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
 
 export interface PaddockWarmupOptions {
   enabled?: boolean;
@@ -34,43 +51,6 @@ export interface PaddockWarmupOptions {
   steps?: number;
 }
 
-export interface PaddockProceduralTrackOptions {
-  profile?: PaddockProceduralTrackProfile;
-  minLengthMeters?: number;
-  maxLengthMeters?: number;
-  startStraightMeters?: number;
-  includePitLane?: boolean;
-  length?: {
-    minMeters?: number;
-    maxMeters?: number;
-  };
-  startStraight?: {
-    gridMeters?: number;
-    exitMeters?: number;
-    blendMeters?: number;
-    lockExtraMeters?: number;
-  };
-  pitLane?: {
-    enabled?: boolean;
-  };
-  shape?: {
-    scale?: number;
-    cornerDensity?: number;
-    variation?: number;
-  };
-  validation?: {
-    minClearanceMultiplier?: number;
-    minShapeVariation?: number;
-    minNonAdjacentArcMeters?: number;
-    maxLocalTurnRadians?: number;
-    maxSampleHeadingDeltaRadians?: number;
-  };
-  attempts?: {
-    primary?: number;
-    fallback?: number;
-  };
-}
-
 export type PaddockStabilityState = 'stable' | 'understeer' | 'oversteer' | 'spin-risk' | 'destroyed';
 export type PaddockPitIntent = 0 | 1 | 2;
 export type PaddockPitIntentRequest = PaddockPitIntent | {
@@ -90,6 +70,7 @@ export type TimingTowerVerticalFit = 'expand-race-view' | 'scroll';
 export type TimingGapMode = 'interval' | 'leader';
 export type LayoutPreset = 'standard' | 'left-tower-overlay';
 export type CameraControlsMode = 'embedded' | 'external' | false;
+export type ViewControlsMode = 'switch' | 'toggle';
 export type PaddockPresetName = 'dashboard' | 'timing-overlay' | 'compact-race' | 'full-dashboard';
 export type TelemetryModuleName = 'core' | 'sectors' | 'lapTimes' | 'sectorTimes';
 export type SectorPerformanceStatus = 'overall-best' | 'personal-best' | 'slower';
@@ -101,164 +82,7 @@ export type PaddockReplayGhostTrajectorySample = EnvPaddockReplayGhostTrajectory
 export type PaddockReplayGhostOptions = EnvPaddockReplayGhostOptions;
 export type PaddockReplayGhostSnapshot = EnvPaddockReplayGhostSnapshot;
 
-export interface CustomField {
-  label: string;
-  value: string;
-}
-
-export type CustomFieldInput = CustomField[] | Record<string, string>;
-
-export interface TeamData {
-  id?: string;
-  name?: string;
-  color?: string;
-  icon?: string;
-  theme?: PaddockThemeSelector;
-  pitCrew?: PaddockPitCrewStats;
-  pitCrewStats?: PaddockPitCrewStats;
-}
-
-export interface PaddockPitCrewStats {
-  speed?: number;
-  consistency?: number;
-  reliability?: number;
-}
-
-export interface SimulatorDriver {
-  id: string;
-  name: string;
-  color: string;
-  link?: string;
-  icon?: string;
-  code?: string;
-  timingName?: string;
-  tire?: TireCompound;
-  raceData?: string[];
-  customFields?: CustomFieldInput;
-  team?: TeamData | null;
-  driverNumber?: number;
-}
-
-export interface DriverRatings {
-  pace: number;
-  racecraft: number;
-  aggression: number;
-  riskTolerance: number;
-  patience: number;
-  consistency: number;
-}
-
-export interface VehicleRatings {
-  power: number;
-  braking: number;
-  aero: number;
-  dragEfficiency: number;
-  mechanicalGrip: number;
-  weightControl: number;
-  tireCare: number;
-}
-
-export interface DriverBlueprint extends Partial<DriverRatings> {
-  customFields?: CustomFieldInput;
-}
-
-export interface VehicleBlueprint extends Partial<VehicleRatings> {
-  id?: string | null;
-  name?: string | null;
-  customFields?: CustomFieldInput;
-}
-
-export interface DriverConstructorArgs {
-  ratings: DriverRatings;
-  customFields: CustomField[];
-  pace: number;
-  racecraft: number;
-  consistency: number;
-  personality: {
-    aggression: number;
-    riskTolerance: number;
-    patience: number;
-  };
-}
-
-export interface VehicleConstructorArgs {
-  id: string | null;
-  name: string | null;
-  ratings: VehicleRatings;
-  customFields: CustomField[];
-  powerNewtons: number;
-  brakeNewtons: number;
-  downforceCoefficient: number;
-  dragCoefficient: number;
-  tireGrip: number;
-  mass: number;
-  tireCare: number;
-}
-
-export class DriverData {
-  constructor(input?: DriverBlueprint);
-  readonly pace: number;
-  readonly racecraft: number;
-  readonly aggression: number;
-  readonly riskTolerance: number;
-  readonly patience: number;
-  readonly consistency: number;
-  readonly customFields: CustomField[];
-  ratings(): DriverRatings;
-  toConstructorArgs(): DriverConstructorArgs;
-}
-
-export class VehicleData {
-  constructor(input?: VehicleBlueprint);
-  readonly id: string | null;
-  readonly name: string | null;
-  readonly power: number;
-  readonly braking: number;
-  readonly aero: number;
-  readonly dragEfficiency: number;
-  readonly mechanicalGrip: number;
-  readonly weightControl: number;
-  readonly tireCare: number;
-  readonly customFields: CustomField[];
-  ratings(): VehicleRatings;
-  toConstructorArgs(): VehicleConstructorArgs;
-}
-
-export interface ChampionshipEntryBlueprint {
-  driverId: string;
-  driverNumber?: number;
-  timingName?: string;
-  driver?: DriverData | DriverBlueprint;
-  vehicle?: VehicleData | VehicleBlueprint;
-  team?: TeamData;
-}
-
-export interface NormalizedSimulatorDriver extends SimulatorDriver {
-  code: string;
-  timingCode: string;
-  raceName: string;
-  driverNumber: number;
-  team: TeamData | null;
-  pace: number;
-  racecraft: number;
-  consistency: number;
-  personality: DriverConstructorArgs['personality'];
-  vehicle: VehicleConstructorArgs;
-  constructorArgs: {
-    driver: DriverConstructorArgs;
-    vehicle: VehicleConstructorArgs;
-  };
-  championship: {
-    id: string;
-    name: string;
-    season: number;
-    entryIndex: number;
-    vehicleId: string | null;
-  };
-}
-
 export type PaddockThemeMode = 'dark' | 'light' | 'system';
-export type PaddockThemeSelector = 'default' | 'active' | 'selectedTeam' | 'team' | `team:${string}` | string;
 export type PaddockThemeTokenValue = string | { light?: string; dark?: string };
 export type PaddockThemeTokenName =
   | 'primary'
@@ -366,6 +190,8 @@ export interface PaddockThemeSyncOptions {
 export interface F1SimulatorUiOptions {
   layoutPreset?: LayoutPreset;
   cameraControls?: CameraControlsMode;
+  /** Two mode buttons by default; toggle uses one Start race / Stop race action. */
+  viewControls?: ViewControlsMode;
   showFps?: boolean;
   showTimingTower?: boolean;
   showTelemetry?: boolean;
@@ -959,14 +785,14 @@ export interface PaddockEnvironmentResultOptions {
 }
 
 export interface F1SimulatorExpertApi {
-  reset(options?: unknown): unknown;
-  step(actions: Record<string, F1SimulatorExpertAction>): unknown;
+  reset(options?: unknown): PaddockEnvironmentResult;
+  step(actions: Record<string, F1SimulatorExpertAction>): PaddockEnvironmentResult;
   resetDrivers?(
     placements: Record<string, PaddockScenarioPlacement>,
     resultOptions?: PaddockEnvironmentResultOptions
-  ): unknown;
-  getObservation(): unknown;
-  getState(): unknown;
+  ): PaddockEnvironmentResult;
+  getObservation(): PaddockEnvironmentResult['observation'];
+  getState(): PaddockEnvironmentResult['state'];
   getActionSpec(): PaddockActionSpec;
   getObservationSpec(): PaddockObservationSpec;
   attachExternalRenderer(source: PaddockExternalRendererSource): void;
@@ -975,7 +801,16 @@ export interface F1SimulatorExpertApi {
   destroy(): void;
 }
 
+export type PaddockView = 'grid-walk' | 'race';
+
+export interface GridWalkOptions {
+  enabled?: boolean;
+  initialView?: PaddockView;
+  ambientMotion?: boolean;
+}
+
 export interface F1SimulatorOptions extends F1SimulatorCallbacks {
+  gridWalk?: GridWalkOptions;
   preset?: PaddockPresetName;
   drivers: SimulatorDriver[];
   entries?: ChampionshipEntryBlueprint[];
@@ -1031,6 +866,8 @@ export interface F1MountedSimulator {
   getTheme(): ResolvedPaddockTheme;
   syncThemeFrom(source: Element, options?: PaddockThemeSyncOptions): () => void;
   selectDriver(driverId: string): void;
+  setView(view: PaddockView): boolean;
+  getView(): PaddockView;
   setSafetyCarDeployed(deployed: boolean): void;
   setRedFlagDeployed(deployed: boolean): void;
   setPitLaneOpen(open: boolean): void;
@@ -1053,6 +890,7 @@ export interface PaddockSimulatorController {
   readonly expert: F1SimulatorExpertApi | null;
   mountRaceControls<T extends Element>(root: T): T;
   mountCameraControls<T extends Element>(root: T): T;
+  mountViewControls<T extends Element>(root: T): T;
   mountSafetyCarControl<T extends Element>(root: T): T;
   mountTimingTower<T extends Element>(root: T): T;
   mountRaceCanvas<T extends Element>(root: T, options?: MountRaceCanvasOptions): T;
@@ -1075,6 +913,8 @@ export interface PaddockSimulatorController {
   getTheme(): ResolvedPaddockTheme;
   syncThemeFrom(source: Element, options?: PaddockThemeSyncOptions): () => void;
   selectDriver(driverId: string): void;
+  setView(view: PaddockView): boolean;
+  getView(): PaddockView;
   setSafetyCarDeployed(deployed: boolean): void;
   setRedFlagDeployed(deployed: boolean): void;
   setPitLaneOpen(open: boolean): void;
@@ -1133,11 +973,12 @@ export function simSpeedToMetersPerSecond(simSpeed: number): number;
 
 export function createPaddockSimulator(options: F1SimulatorOptions): PaddockSimulatorController;
 export function mountF1Simulator(root: Element, options: F1SimulatorOptions): Promise<F1MountedSimulator>;
-export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): unknown;
+export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): PaddockProceduralTrack;
 export function createPaddockDriverControllerLoop(options: PaddockDriverControllerLoopOptions): PaddockDriverControllerLoop;
 
 export function mountRaceControls<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
 export function mountCameraControls<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
+export function mountViewControls<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
 export function mountSafetyCarControl<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
 export function mountTimingTower<T extends Element>(root: T, simulator: PaddockSimulatorController): T;
 export function mountRaceCanvas<T extends Element>(

package/src/index.js

@@ -8,6 +8,7 @@ export {
   createPaddockSimulator,
   mountCarDriverOverview,
   mountCameraControls,
+  mountViewControls,
   mountRaceCanvas,
   mountRaceControls,
   mountRaceDataPanel,
@@ -60,14 +61,30 @@ function assertMountRoot(root) {
   }
 }
 
+const activeSimulatorRoots = new WeakMap();
+
 export async function mountF1Simulator(root, options = {}) {
   assertMountRoot(root);
+  if (activeSimulatorRoots.has(root)) {
+    throw new Error('mountF1Simulator root already has an active simulator. Destroy it before mounting again.');
+  }
 
-  let resolvedOptions = resolveF1SimulatorOptions(options);
-  root.innerHTML = createF1SimulatorShell(resolvedOptions);
-  const shell = root.querySelector('[data-f1-simulator-shell]');
-  const app = new F1SimulatorApp(shell, resolvedOptions);
-  await app.init();
+  const mountToken = {};
+  activeSimulatorRoots.set(root, mountToken);
+  let app = null;
+  let resolvedOptions;
+  try {
+    resolvedOptions = resolveF1SimulatorOptions(options);
+    root.innerHTML = createF1SimulatorShell(resolvedOptions);
+    const shell = root.querySelector('[data-f1-simulator-shell]');
+    app = new F1SimulatorApp(shell, resolvedOptions);
+    await app.init();
+  } catch (error) {
+    app?.destroy();
+    if (activeSimulatorRoots.get(root) === mountToken) activeSimulatorRoots.delete(root);
+    root.innerHTML = '';
+    throw error;
+  }
 
   const syncResolvedTimingGapMode = (timingGapMode) => {
     resolvedOptions = {
@@ -90,7 +107,10 @@ export async function mountF1Simulator(root, options = {}) {
     },
     destroy() {
       app.destroy();
-      root.innerHTML = '';
+      if (activeSimulatorRoots.get(root) === mountToken) {
+        activeSimulatorRoots.delete(root);
+        root.innerHTML = '';
+      }
     },
     restart(nextOptions = {}) {
       const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(syncResolvedRuntimeOptions(), nextOptions));
@@ -116,6 +136,8 @@ export async function mountF1Simulator(root, options = {}) {
     selectDriver(driverId) {
       app.selectCar(driverId, { focus: true });
     },
+    setView(view) { return app.setView(view); },
+    getView() { return app.getView(); },
     setSafetyCarDeployed(deployed) {
       app.setSafetyCarDeployed(deployed);
     },

package/src/placeholder/index.js

@@ -1,11 +1,4 @@
-function escapeHtml(value) {
-  return String(value ?? '')
-    .replaceAll('&', '&')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
-}
+import { escapeHtml } from '../ui/htmlEscaping.js';
 
 function normalizeVariant(value) {
   return value === 'custom' ? 'custom' : 'lights';

package/src/rendering/displayLifecycle.js

@@ -0,0 +1,6 @@
+// Display objects own their children, while simulator textures remain shared.
+export function destroyDisplayChildren(container) {
+  container?.removeChildren?.().forEach((child) => {
+    child.destroy?.({ children: true, texture: false, textureSource: false });
+  });
+}

package/src/rendering/proceduralTrackAsset.js

@@ -1,6 +1,6 @@
 import { Container } from 'pixi.js';
 import { WORLD } from '../simulation/track/trackModel.js';
-import { destroyDisplayChildren } from './track/trackRenderGeometry.js';
+import { destroyDisplayChildren } from './displayLifecycle.js';
 import { addAsphalt, addBarriers, addBorders, addBoundaryUnderlay, addGrass, addGravelRunoff, addKerbs } from './track/trackMaterialRenderer.js';
 import { addPitLane, addPitLaneRunoff } from './track/pitLaneRenderer.js';
 import { addStartingGrid } from './track/gridRenderer.js';

package/src/rendering/renderSnapshot.js

@@ -11,6 +11,9 @@ function interpolateAngle(previous, current, amount) {
 
 function interpolateMovingEntityInto(target, entity, alpha) {
   Object.assign(target, entity);
+  // Retirement stops pose integration, so its previous endpoint may be from
+  // the last moving step. A stationary wreck must not replay that movement.
+  if (entity.destroyed || entity.outOfRace) return target;
   target.x = lerp(entity.previousX ?? entity.x, entity.x, alpha);
   target.y = lerp(entity.previousY ?? entity.y, entity.y, alpha);
   target.heading = interpolateAngle(entity.previousHeading ?? entity.heading, entity.heading, alpha);

package/src/rendering/track/finishLineRenderer.js

@@ -1,5 +1,5 @@
 import { Graphics } from 'pixi.js';
-import { offsetTrackPoint, pointAt } from '../../simulation/trackModel.js';
+import { offsetTrackPoint, pointAt } from '../../simulation/track/trackModel.js';
 import { FINISH_LINE_COLUMNS, FINISH_LINE_DEPTH } from './trackRenderConstants.js';
 
 export function addFinishLine(asset, track) {

package/src/rendering/track/gridRenderer.js

@@ -1,5 +1,5 @@
 import { Graphics } from 'pixi.js';
-import { offsetTrackPoint, pointAt } from '../../simulation/trackModel.js';
+import { offsetTrackPoint, pointAt } from '../../simulation/track/trackModel.js';
 import { START_GRID_BOX_LENGTH, START_GRID_BOX_WIDTH, START_GRID_FIRST_DISTANCE, START_GRID_LATERAL_OFFSET, START_GRID_SLOT_COUNT, START_GRID_SLOT_SPACING } from './trackRenderConstants.js';
 
 export function addStartingGrid(asset, track) {

package/src/rendering/track/offsetStrokeSafety.js

@@ -1,7 +1,7 @@
-import { nearestTrackState, offsetTrackPoint } from '../../simulation/trackModel.js';
+import { nearestTrackState, offsetTrackPoint } from '../../simulation/track/trackModel.js';
 import { queryNearbyTrackProjections } from '../../simulation/track/trackQueryIndex.js';
 import { metersToSimUnits } from '../../simulation/units.js';
-import { NON_LOCAL_SAMPLE_STEP, OFFSET_GAP_SAMPLE_COUNT, OFFSET_SEGMENT_SAMPLE_COUNT } from './trackRenderConstants.js';
+import { NON_LOCAL_SAMPLE_STEP, OFFSET_GAP_SAMPLE_COUNT, OFFSET_SEGMENT_SAMPLE_COUNT, SEGMENTED_STROKE_STEP } from './trackRenderConstants.js';
 import { arcDistance, interpolatedSegmentPoint, pointDistance } from './trackRenderGeometry.js';
 
 export function offsetPointIsLocal(track, source, point, offset) {

package/src/rendering/track/pitLaneRenderer.js

@@ -1,5 +1,5 @@
 import { Graphics } from 'pixi.js';
-import { nearestTrackState } from '../../simulation/trackModel.js';
+import { nearestTrackState } from '../../simulation/track/trackModel.js';
 import { ASPHALT_COLOR, GRAVEL_COLOR, PIT_ASPHALT_COLOR, PIT_BOX_COLOR, PIT_CONNECTOR_WIDTH, PIT_LINE_COLOR, PIT_SPEED_LINE_COLOR } from './trackRenderConstants.js';
 import { colorToNumber, createTeamPitGroupCorners, drawPolyline, offsetVectorPoint } from './trackRenderGeometry.js';
 

package/src/rendering/track/trackMaterialRenderer.js

@@ -1,5 +1,5 @@
 import { Graphics, TilingSprite } from 'pixi.js';
-import { offsetTrackPoint } from '../../simulation/trackModel.js';
+import { offsetTrackPoint } from '../../simulation/track/trackModel.js';
 import { ASPHALT_COLOR, BARRIER_WALL_WIDTH, EDGE_REVEAL_OFFSET, EDGE_REVEAL_WIDTH, GRASS_COLOR, GRAVEL_COLOR, KERB_CURVATURE_THRESHOLD, KERB_OFFSET, KERB_STEP, KERB_WIDTH, MATERIAL_TILE_SCALE, OUTER_BOUNDARY_OFFSET, OUTER_BOUNDARY_WIDTH, RUNOFF_GRASS_COLOR, SEGMENTED_STROKE_STEP, WORLD_BACKGROUND_PADDING_MULTIPLIER } from './trackRenderConstants.js';
 import { makeTrackPath, textureOrWhite } from './trackRenderGeometry.js';
 import { getOffsetGapBridges, getOffsetStrokeSegments, offsetSegmentIsSafe } from './offsetStrokeSafety.js';
@@ -149,7 +149,7 @@ export function addBoundaryUnderlay(asset, track) {
       });
     });
 
-    drawKerbStripes(asset, boundary, track, { clipUnsafeSegments: false });
+    drawKerbStripes(boundary, track, { clipUnsafeSegments: false });
 
     [-1, 1].forEach((side) => {
       drawContinuousOffsetStroke(boundary, track, {
@@ -214,7 +214,7 @@ export function getTrackMaterialBands(track) {
     };
 }
 
-export function drawKerbStripes(asset, kerbs, track, { clipUnsafeSegments }) {
+export function drawKerbStripes(kerbs, track, { clipUnsafeSegments }) {
     const samples = track.samples.slice(0, -1);
 
     for (let index = 0; index < samples.length; index += KERB_STEP) {
@@ -320,7 +320,7 @@ export function addBorders(asset, track) {
 export function addKerbs(asset, track) {
     const kerbs = new Graphics();
     kerbs.label = 'track-kerbs';
-    drawKerbStripes(asset, kerbs, track, { clipUnsafeSegments: true });
+    drawKerbStripes(kerbs, track, { clipUnsafeSegments: true });
     asset.container.addChild(kerbs);
 
 }

package/src/rendering/track/trackRenderConstants.js

@@ -14,7 +14,6 @@ export const PIT_BOX_COLOR = 0x242831;
 export const PIT_LINE_COLOR = 0xf8fafc;
 export const PIT_SPEED_LINE_COLOR = 0xffd166;
 export const PIT_CONNECTOR_WIDTH = metersToSimUnits(12);
-export const PIT_EDGE_WIDTH = metersToSimUnits(0.35);
 export const EDGE_REVEAL_OFFSET = metersToSimUnits(0.35);
 export const EDGE_REVEAL_WIDTH = metersToSimUnits(0.5);
 export const OUTER_BOUNDARY_OFFSET = metersToSimUnits(1.1);

package/src/rendering/track/trackRenderGeometry.js

@@ -1,5 +1,5 @@
 import { Graphics, Texture } from 'pixi.js';
-import { offsetTrackPoint } from '../../simulation/trackModel.js';
+import { offsetTrackPoint } from '../../simulation/track/trackModel.js';
 import { PIT_LINE_COLOR } from './trackRenderConstants.js';
 
 export function colorToNumber(color, fallback = PIT_LINE_COLOR) {
@@ -29,12 +29,6 @@ export function textureOrWhite(texture) {
   return texture ?? Texture.WHITE;
 }
 
-export function destroyDisplayChildren(container) {
-  container.removeChildren().forEach((child) => {
-    child.destroy?.({ children: true, texture: false, textureSource: false });
-  });
-}
-
 export function arcDistance(track, first, second) {
   const delta = Math.abs(first - second);
   return Math.min(delta, track.length - delta);

package/src/simulation/collisionGeometry.js

@@ -1,7 +1,4 @@
-import {
-  getVehicleGeometryState,
-  vehicleAxes,
-} from './vehicle/vehicleGeometry.js';
+import { getVehicleGeometryState } from './vehicle/vehicleGeometry.js';
 import { normalizeAngle } from './simMath.js';
 
 const DEFAULT_SWEEP_STEPS = 16;
@@ -10,10 +7,6 @@ const DEFAULT_DISTANCE_WINDOW = 150;
 const COLLISION_PAIR_FIRST_INDEX = Symbol('collisionPairFirstIndex');
 const COLLISION_PAIR_SECOND_INDEX = Symbol('collisionPairSecondIndex');
 
-function dot(a, b) {
-  return a.x * b.x + a.y * b.y;
-}
-
 function projectShapeInto(target, shape, axis) {
   let min = Infinity;
   let max = -Infinity;
@@ -91,10 +84,6 @@ function aabbsOverlap(first, second) {
   );
 }
 
-function createSweptAabb(car) {
-  return getVehicleGeometryState(car).sweptBodyAabb;
-}
-
 function writeShapeCollisionResult(target, firstShape, secondShape, axisX, axisY, depth) {
   target.axis ??= {};
   target.axis.x = axisX;
@@ -123,10 +112,12 @@ function withCollisionMetadata(collision, timeOfImpact, swept, scratch) {
 function detectVehicleCollisionWithScratch(first, second, sweepSteps, scratch) {
   const firstState = getVehicleGeometryState(first);
   const secondState = getVehicleGeometryState(second);
-  const current = detectShapeCollision(firstState.current.body, secondState.current.body, scratch);
-  if (current) return withCollisionMetadata(current, 1, false, scratch);
+  if (aabbsOverlap(firstState.bodyAabb, secondState.bodyAabb)) {
+    const current = detectShapeCollision(firstState.current.body, secondState.current.body, scratch);
+    if (current) return withCollisionMetadata(current, 1, false, scratch);
+  }
 
-  if (!aabbsOverlap(createSweptAabb(first), createSweptAabb(second))) return null;
+  if (!aabbsOverlap(firstState.sweptBodyAabb, secondState.sweptBodyAabb)) return null;
 
   const sweepShapes = ensureSweepShapes(scratch, firstState.current.body, secondState.current.body);
   for (let step = 1; step < sweepSteps; step += 1) {
@@ -340,17 +331,18 @@ function writeInterpolatedBodyShape(target, geometryState, amount) {
   const x = pose.previousX + (pose.x - pose.previousX) * amount;
   const y = pose.previousY + (pose.y - pose.previousY) * amount;
   const heading = normalizeAngle(pose.previousHeading + headingDelta * amount);
-  const axes = vehicleAxes(heading);
+  const cos = Math.cos(heading);
+  const sin = Math.sin(heading);
   const halfLength = target.halfLength;
   const halfWidth = target.halfWidth;
 
   target.center.x = x;
   target.center.y = y;
   target.heading = heading;
-  target.forward.x = axes.forward.x;
-  target.forward.y = axes.forward.y;
-  target.right.x = axes.right.x;
-  target.right.y = axes.right.y;
+  target.forward.x = cos;
+  target.forward.y = sin;
+  target.right.x = -sin;
+  target.right.y = cos;
 
   writeOffsetCorner(target.corners[0], target.center, target.forward, target.right, halfLength, halfWidth);
   writeOffsetCorner(target.corners[1], target.center, target.forward, target.right, halfLength, -halfWidth);

package/src/simulation/driver/advancedPathControls.js

@@ -0,0 +1,53 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { simUnitsToMeters } from '../units.js';
+import { VEHICLE_LIMITS, tirePerformanceFactor } from '../vehicle/vehiclePhysics.js';
+import { ADVANCED_VEHICLE_MODEL, advancedDriveForce } from '../vehicle/advancedVehicleModel.js';
+import { advancedLateralAccelerationLimit, advancedRearForceCapacity, advancedRollingResistanceForce } from '../vehicle/advancedTireForces.js';
+
+export function advancedSteeringToPoint(car, target) {
+  const speed = simUnitsToMeters(car.speed);
+  const dx = simUnitsToMeters(target.x - car.x);
+  const dy = simUnitsToMeters(target.y - car.y);
+  const angle = normalizeAngle(Math.atan2(dy, dx) - car.heading);
+  // Pure pursuit gives a geometric curvature in 1/m, then a physical wheel
+  // angle. Yaw feedback damps the inertial response without moving the car.
+  const curvature = 2 * Math.sin(angle) / Math.max(Math.hypot(dx, dy), 1);
+  const desiredYaw = speed * curvature;
+  const slip = car.slipAngleRadians ?? 0;
+  const countersteer = Math.sign(slip) * Math.max(0, Math.abs(slip) - 0.08) * 0.35;
+  return {
+    curvature,
+    steering: Math.atan(simUnitsToMeters(VEHICLE_LIMITS.wheelbase) * curvature) +
+      (desiredYaw - (car.yawRate ?? 0)) * 0.04 + countersteer,
+  };
+}
+
+export function advancedLongitudinalLimits(car) {
+  const speed = simUnitsToMeters(car.speed);
+  const tireFactor = tirePerformanceFactor(car.tireEnergy ?? 100);
+  const capacity = advancedLateralAccelerationLimit(car, speed, tireFactor);
+  const lateralUsage = clamp(Math.abs(speed * (car.yawRate ?? 0)) / capacity, 0, 0.95);
+  // Static axle capacity is an estimate: keep a margin for load transfer and
+  // reserve the lateral share before requesting rear drive or brake force.
+  const longitudinalFraction = Math.sqrt(1 - lateralUsage ** 2) * 0.65;
+  const force = capacity * car.mass * longitudinalFraction;
+  let driveForce = force * (1 - ADVANCED_VEHICLE_MODEL.frontWeightFraction);
+  if (speed < 5 && !car.trackState.onTrack) {
+    // A crawling car must overcome all four wheels' rolling resistance. Use
+    // the rear tires' remaining adhesion, not an artificial minimum throttle.
+    const rearCapacity = advancedRearForceCapacity(car, speed, tireFactor) * Math.sqrt(1 - lateralUsage ** 2);
+    const rollingCompensation = advancedRollingResistanceForce(car, speed) * (1 - speed / 5);
+    driveForce = Math.min(rearCapacity, driveForce + rollingCompensation);
+  }
+  const throttleLimit = driveForce / advancedDriveForce(car, speed);
+  const brakeLimit = force / car.brakeNewtons;
+  return { speed, throttleLimit, brakeLimit };
+}
+
+export function advancedSpeedControls(car, targetSpeed) {
+  const { speed, throttleLimit, brakeLimit } = advancedLongitudinalLimits(car);
+  const error = targetSpeed - speed;
+  const brake = clamp(-error / 8, 0, Math.min(0.85, brakeLimit));
+  const throttle = brake > 0.03 ? 0 : clamp(error / 8, 0, Math.min(1, throttleLimit));
+  return { throttle, brake };
+}