@inventure71/paddockjs 0.1.0 → 0.3.0

package/docs/training.md

@@ -0,0 +1,104 @@
+# Bring Your Own Model
+
+PaddockJS does not train models for you. It provides a simulator environment contract so users can train with any toolchain, then run the resulting policy in the visual simulator.
+
+## Boundary
+
+PaddockJS owns:
+
+- deterministic simulator stepping
+- observations
+- normalized actions
+- events
+- optional reward callback hooks
+- browser expert stepping
+- sensor visualization
+
+Users own:
+
+- ML framework choice
+- training algorithm
+- model weights
+- model storage
+- model loading
+- reward design beyond optional starter helpers
+
+## Policy Shape
+
+Use this convention for browser playback:
+
+```js
+const policy = {
+  predict(observation) {
+    return {
+      steering: 0,
+      throttle: 1,
+      brake: 0,
+    };
+  },
+};
+```
+
+`predict()` receives one controlled driver's observation. It returns normalized controls:
+
+- `steering`: `-1` full left, `1` full right
+- `throttle`: `0` to `1`
+- `brake`: `0` to `1`
+
+## Headless Training Loop
+
+```js
+import { createPaddockEnvironment } from '@inventure71/paddockjs/environment';
+
+const env = createPaddockEnvironment({
+  drivers,
+  entries,
+  controlledDrivers: ['budget'],
+  frameSkip: 4,
+  reward: myReward,
+});
+
+let result = env.reset();
+while (!result.done) {
+  const observation = result.observation.budget;
+  const action = policy.predict(observation);
+  result = env.step({ budget: action });
+}
+```
+
+## Visual Playback Loop
+
+```js
+import { mountF1Simulator } from '@inventure71/paddockjs';
+
+const simulator = await mountF1Simulator(root, {
+  drivers,
+  entries,
+  expert: {
+    enabled: true,
+    controlledDrivers: ['budget'],
+    frameSkip: 4,
+    visualizeSensors: { rays: true },
+  },
+});
+
+function frame() {
+  const observation = simulator.expert.getObservation().budget;
+  const action = policy.predict(observation);
+  simulator.expert.step({ budget: action });
+  requestAnimationFrame(frame);
+}
+
+frame();
+```
+
+## Specs
+
+Use specs to connect external training code without guessing:
+
+```js
+const actionSpec = env.getActionSpec();
+const observationSpec = env.getObservationSpec();
+```
+
+These specs describe the action ranges, controlled drivers, ray layout, nearby-car limits, and vector schema.

package/examples/train-basic-policy.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+import { createPaddockEnvironment, createProgressReward } from '../src/environment/index.js';
+import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../src/data/championship.js';
+import { DEMO_PROJECT_DRIVERS } from '../src/data/demoDrivers.js';
+
+const DEFAULT_OPTIONS = Object.freeze({
+  generations: 4,
+  candidates: 5,
+  episodes: 1,
+  steps: 240,
+  frameSkip: 4,
+  seed: 71,
+  traffic: false,
+  evalOnly: false,
+});
+
+const INITIAL_POLICY = Object.freeze({
+  steeringHeading: -1.2,
+  steeringOffset: -0.35,
+  steeringRayBalance: 0.45,
+  throttleBias: 0.72,
+  throttleFrontClearance: 0.28,
+  throttleSpeedDamping: 0.18,
+  brakeBias: 0,
+  brakeFrontDanger: 0.65,
+  brakeOffTrack: 0.2,
+});
+
+const POLICY_KEYS = Object.keys(INITIAL_POLICY);
+
+main();
+
+function main() {
+  const options = parseCliArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const driverId = DEMO_PROJECT_DRIVERS[0].id;
+  const rng = createSeededRandom(options.seed);
+  const reward = createProgressReward();
+  const evaluate = (policy, seedOffset = 0) => evaluatePolicy({
+    policy,
+    driverId,
+    reward,
+    options,
+    seedOffset,
+  });
+
+  if (options.evalOnly) {
+    const baseline = evaluate(INITIAL_POLICY);
+    printSummary({ options, driverId, bestPolicy: INITIAL_POLICY, best: baseline });
+    return;
+  }
+
+  let bestPolicy = { ...INITIAL_POLICY };
+  let best = evaluate(bestPolicy);
+
+  console.log(formatGenerationLine(0, best));
+
+  for (let generation = 1; generation <= options.generations; generation += 1) {
+    const mutationScale = 0.45 / Math.sqrt(generation);
+    const candidates = [{ policy: bestPolicy, scoreSeedOffset: generation * 1000 }];
+
+    for (let index = 1; index < options.candidates; index += 1) {
+      candidates.push({
+        policy: mutatePolicy(bestPolicy, rng, mutationScale),
+        scoreSeedOffset: generation * 1000 + index * 100,
+      });
+    }
+
+    for (const candidate of candidates) {
+      const score = evaluate(candidate.policy, candidate.scoreSeedOffset);
+      if (score.averageReward > best.averageReward) {
+        best = score;
+        bestPolicy = candidate.policy;
+      }
+    }
+
+    console.log(formatGenerationLine(generation, best));
+  }
+
+  printSummary({ options, driverId, bestPolicy, best });
+}
+
+function evaluatePolicy({ policy, driverId, reward, options, seedOffset = 0 }) {
+  let totalReward = 0;
+  let totalDistanceMeters = 0;
+  let totalCollisions = 0;
+  let totalOffTrackSteps = 0;
+  let completedEpisodes = 0;
+
+  for (let episode = 0; episode < options.episodes; episode += 1) {
+    const env = createTrainingEnvironment({ driverId, reward, options, episode, seedOffset });
+    let result = env.reset();
+    let episodeReward = 0;
+
+    for (let step = 0; step < options.steps && !result.done; step += 1) {
+      const observation = result.observation[driverId];
+      const action = chooseAction(policy, observation);
+      result = env.step({ [driverId]: action });
+      episodeReward += result.reward?.[driverId] ?? 0;
+      totalCollisions += result.events.filter((event) => event.type === 'collision').length;
+      if (result.observation[driverId]?.object?.self?.onTrack === false) totalOffTrackSteps += 1;
+    }
+
+    const car = result.state.snapshot.cars.find((entry) => entry.id === driverId);
+    totalReward += episodeReward;
+    totalDistanceMeters += Number(car?.distanceMeters ?? 0);
+    completedEpisodes += 1;
+    env.destroy();
+  }
+
+  return {
+    averageReward: totalReward / Math.max(1, completedEpisodes),
+    averageDistanceMeters: totalDistanceMeters / Math.max(1, completedEpisodes),
+    collisions: totalCollisions,
+    offTrackSteps: totalOffTrackSteps,
+  };
+}
+
+function createTrainingEnvironment({ driverId, reward, options, episode, seedOffset }) {
+  const drivers = options.traffic ? DEMO_PROJECT_DRIVERS.slice(0, 8) : DEMO_PROJECT_DRIVERS.slice(0, 1);
+  return createPaddockEnvironment({
+    drivers,
+    entries: CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+    controlledDrivers: [driverId],
+    seed: options.seed + seedOffset + episode,
+    trackSeed: options.seed + 2026 + seedOffset + episode,
+    totalLaps: 3,
+    frameSkip: options.frameSkip,
+    scenario: {
+      participants: options.traffic ? 'all' : 'controlled-only',
+      nonControlled: 'ai',
+    },
+    episode: {
+      maxSteps: options.steps,
+      endOnRaceFinish: true,
+    },
+    rules: {
+      standingStart: false,
+    },
+    reward,
+  });
+}
+
+function chooseAction(policy, observation) {
+  const self = observation.object.self;
+  const frontRay = getRayDistance(observation, 0);
+  const leftRay = getRayDistance(observation, -60);
+  const rightRay = getRayDistance(observation, 60);
+  const frontDanger = clamp01((35 - frontRay) / 35);
+  const rayBalanceMeters = rightRay - leftRay;
+
+  const steering = clamp(
+    policy.steeringHeading * self.trackHeadingErrorRadians +
+      policy.steeringOffset * (self.trackOffsetMeters / 12) +
+      policy.steeringRayBalance * (rayBalanceMeters / 120),
+    -1,
+    1,
+  );
+  const throttle = clamp01(
+    policy.throttleBias +
+      policy.throttleFrontClearance * (frontRay / 120) -
+      policy.throttleSpeedDamping * (self.speedKph / 320) -
+      (self.onTrack ? 0 : 0.35),
+  );
+  const brake = clamp01(
+    policy.brakeBias +
+      policy.brakeFrontDanger * frontDanger +
+      (self.onTrack ? 0 : policy.brakeOffTrack),
+  );
+
+  return { steering, throttle, brake };
+}
+
+function getRayDistance(observation, angleDegrees) {
+  const ray = observation.object.rays.find((entry) => entry.angleDegrees === angleDegrees);
+  return Number(ray?.track?.distanceMeters ?? ray?.lengthMeters ?? 120);
+}
+
+function mutatePolicy(policy, rng, scale) {
+  return Object.fromEntries(POLICY_KEYS.map((key) => [
+    key,
+    policy[key] + randomNormal(rng) * scale,
+  ]));
+}
+
+function parseCliArgs(argv) {
+  const options = { ...DEFAULT_OPTIONS };
+
+  for (const arg of argv) {
+    const [name, rawValue] = arg.split('=');
+    if (name === '--help' || name === '-h') options.help = true;
+    else if (name === '--eval-only') options.evalOnly = true;
+    else if (name === '--traffic') options.traffic = true;
+    else if (name === '--no-traffic') options.traffic = false;
+    else if (name === '--generations') options.generations = parsePositiveInt(rawValue, name);
+    else if (name === '--candidates') options.candidates = parsePositiveInt(rawValue, name);
+    else if (name === '--episodes') options.episodes = parsePositiveInt(rawValue, name);
+    else if (name === '--steps') options.steps = parsePositiveInt(rawValue, name);
+    else if (name === '--frame-skip') options.frameSkip = parsePositiveInt(rawValue, name);
+    else if (name === '--seed') options.seed = parsePositiveInt(rawValue, name);
+    else throw new Error(`Unknown option: ${name}`);
+  }
+
+  return options;
+}
+
+function parsePositiveInt(value, optionName) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${optionName} requires a positive integer value.`);
+  }
+  return parsed;
+}
+
+function createSeededRandom(seed) {
+  let state = seed >>> 0;
+  return function random() {
+    state += 0x6D2B79F5;
+    let value = state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function randomNormal(rng) {
+  const a = Math.max(Number.EPSILON, rng());
+  const b = Math.max(Number.EPSILON, rng());
+  return Math.sqrt(-2 * Math.log(a)) * Math.cos(2 * Math.PI * b);
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function clamp01(value) {
+  return clamp(value, 0, 1);
+}
+
+function formatGenerationLine(generation, score) {
+  return [
+    `generation=${generation}`,
+    `reward=${score.averageReward.toFixed(2)}`,
+    `distanceMeters=${score.averageDistanceMeters.toFixed(1)}`,
+    `collisions=${score.collisions}`,
+    `offTrackSteps=${score.offTrackSteps}`,
+  ].join(' ');
+}
+
+function printSummary({ options, driverId, bestPolicy, best }) {
+  console.log(JSON.stringify({
+    driverId,
+    options,
+    best,
+    bestPolicy,
+  }, null, 2));
+}
+
+function printHelp() {
+  console.log(`Usage: node examples/train-basic-policy.mjs [options]
+
+Options:
+  --generations=N   Random-search generations. Default: ${DEFAULT_OPTIONS.generations}
+  --candidates=N    Candidate policies per generation. Default: ${DEFAULT_OPTIONS.candidates}
+  --episodes=N      Episodes per policy evaluation. Default: ${DEFAULT_OPTIONS.episodes}
+  --steps=N         Maximum manual environment steps per episode. Default: ${DEFAULT_OPTIONS.steps}
+  --frame-skip=N    Simulator frames advanced by each step(action). Default: ${DEFAULT_OPTIONS.frameSkip}
+  --seed=N          Deterministic random seed. Default: ${DEFAULT_OPTIONS.seed}
+  --traffic         Keep built-in AI traffic on track during training.
+  --eval-only       Evaluate the starter policy without training.
+`);
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "A data-driven browser F1 simulator component for project portfolios.",
+  "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
   "author": "Matteo Giorgetti",
   "homepage": "https://github.com/Inventure71/PaddockJS#readme",
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.19.0"
   },
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -40,24 +40,30 @@
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./environment": {
+      "types": "./src/environment/index.d.ts",
+      "import": "./src/environment/index.js",
+      "default": "./src/environment/index.js"
+    },
     "./styles.css": "./src/styles.css"
   },
   "files": [
-    "AGENTS.md",
     "CHANGELOG.md",
+    "INSTALL_AND_UPDATE.md",
     "LICENSE",
     "assets",
-    "docs",
+    "docs/*.md",
+    "examples",
     "src/api",
     "src/app",
     "src/config",
     "src/data",
+    "src/environment",
     "src/rendering",
     "src/simulation",
     "src/ui",
     "src/index.d.ts",
     "src/index.js",
-    "src/standalone.js",
     "src/styles.css",
     "README.md"
   ],
@@ -72,7 +78,8 @@
     "showcase:ci": "npm --prefix local-preview ci && npm --prefix local-preview run build",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "release": "npm publish --provenance"
+    "release": "npm publish --provenance",
+    "example:train": "node examples/train-basic-policy.mjs"
   },
   "dependencies": {
     "pixi.js": "8.18.1"

package/src/api/PaddockSimulatorController.js

@@ -5,8 +5,14 @@ import {
   createRaceCanvasMarkup,
   createRaceControlsMarkup,
   createRaceDataPanelMarkup,
+  createRaceTelemetryDrawerMarkup,
   createSafetyCarControlMarkup,
+  createTelemetryCoreMarkup,
+  createTelemetryLapTimesMarkup,
   createTelemetryPanelMarkup,
+  createTelemetrySectorBannerMarkup,
+  createTelemetrySectorTimesMarkup,
+  createTelemetrySectorsMarkup,
   createTimingTowerMarkup,
 } from '../ui/componentTemplates.js';
 import { applyPaddockThemeCssVariables, resolveF1SimulatorOptions } from '../config/defaultOptions.js';
@@ -117,18 +123,44 @@ export class PaddockSimulatorController {
   mountRaceCanvas(root, {
     includeRaceDataPanel = false,
     includeTimingTower = false,
+    includeTelemetrySectorBanner = false,
     timingTowerVerticalFit,
   } = {}) {
     return this.mountComponent(root, 'race-canvas', createRaceCanvasMarkup({
       ...this.options,
       includeRaceDataPanel,
       includeTimingTower,
+      includeTelemetrySectorBanner,
       timingTowerVerticalFit,
     }));
   }
 
   mountTelemetryPanel(root, { includeOverview } = {}) {
-    return this.mountComponent(root, 'telemetry-panel', createTelemetryPanelMarkup(this.options, { includeOverview }));
+    return this.mountComponent(root, 'telemetry-stack', createTelemetryPanelMarkup(this.options, { includeOverview }));
+  }
+
+  mountTelemetryCore(root) {
+    return this.mountComponent(root, 'telemetry-core', createTelemetryCoreMarkup(this.options));
+  }
+
+  mountTelemetrySectors(root) {
+    return this.mountComponent(root, 'telemetry-sectors', createTelemetrySectorsMarkup(this.options));
+  }
+
+  mountTelemetryLapTimes(root) {
+    return this.mountComponent(root, 'telemetry-lap-times', createTelemetryLapTimesMarkup(this.options));
+  }
+
+  mountTelemetrySectorTimes(root) {
+    return this.mountComponent(root, 'telemetry-sector-times', createTelemetrySectorTimesMarkup(this.options));
+  }
+
+  mountTelemetrySectorBanner(root) {
+    return this.mountComponent(root, 'telemetry-sector-banner', createTelemetrySectorBannerMarkup(this.options));
+  }
+
+  mountRaceTelemetryDrawer(root, options = {}) {
+    return this.mountComponent(root, 'race-telemetry-drawer', createRaceTelemetryDrawerMarkup(this.options, options));
   }
 
   mountCarDriverOverview(root) {
@@ -155,6 +187,10 @@ export class PaddockSimulatorController {
     return this;
   }
 
+  get expert() {
+    return this.app?.expert ?? null;
+  }
+
   destroy() {
     this.app?.destroy();
     this.app = null;
@@ -165,9 +201,10 @@ export class PaddockSimulatorController {
   }
 
   restart(nextOptions = {}) {
-    this.options = resolveF1SimulatorOptions(mergeResolvedOptions(this.options, nextOptions));
+    const nextResolvedOptions = resolveF1SimulatorOptions(mergeResolvedOptions(this.options, nextOptions));
+    this.app?.restart(nextResolvedOptions);
+    this.options = nextResolvedOptions;
     this.compositeRoot.applyCssVariables();
-    this.app?.restart(this.options);
   }
 
   selectDriver(driverId) {
@@ -228,6 +265,30 @@ export function mountTelemetryPanel(root, simulator, options) {
   return simulator.mountTelemetryPanel(root, options);
 }
 
+export function mountTelemetryCore(root, simulator) {
+  return simulator.mountTelemetryCore(root);
+}
+
+export function mountTelemetrySectors(root, simulator) {
+  return simulator.mountTelemetrySectors(root);
+}
+
+export function mountTelemetryLapTimes(root, simulator) {
+  return simulator.mountTelemetryLapTimes(root);
+}
+
+export function mountTelemetrySectorTimes(root, simulator) {
+  return simulator.mountTelemetrySectorTimes(root);
+}
+
+export function mountTelemetrySectorBanner(root, simulator) {
+  return simulator.mountTelemetrySectorBanner(root);
+}
+
+export function mountRaceTelemetryDrawer(root, simulator, options) {
+  return simulator.mountRaceTelemetryDrawer(root, options);
+}
+
 export function mountRaceDataPanel(root, simulator) {
   return simulator.mountRaceDataPanel(root);
 }

package/src/app/BrowserExpertAdapter.js

@@ -0,0 +1,32 @@
+import { createEnvironmentRuntime } from '../environment/runtime.js';
+import { resolveEnvironmentOptions } from '../environment/options.js';
+
+export function createBrowserExpertAdapter(app, expertOptions = {}) {
+  let resolvedOptions = resolveEnvironmentOptions({
+    ...app.options,
+    ...expertOptions,
+    controlledDrivers: expertOptions.controlledDrivers,
+  });
+
+  return createEnvironmentRuntime({
+    getSimulation: () => app.sim,
+    setSimulation(nextSim) {
+      app.sim = nextSim;
+    },
+    createSimulation(nextOptions) {
+      app.applyExpertOptions(nextOptions);
+      return app.createRaceSimulation(nextOptions);
+    },
+    getOptions: () => resolvedOptions,
+    setOptions(nextOptions) {
+      resolvedOptions = nextOptions;
+    },
+    afterReset(result) {
+      app.renderTrack();
+      app.renderExpertFrame(result.state.snapshot, { observation: result.observation });
+    },
+    afterStep(result) {
+      app.renderExpertFrame(result.state.snapshot, { observation: result.observation });
+    },
+  });
+}