@inventure71/paddockjs 1.0.0 → 2.0.0

package/src/app/rendering/expertSensorRenderer.js

@@ -0,0 +1,126 @@
+import { getCarRayOrigin, getCarRayVector } from '../../environment/sensors.js';
+import { metersToSimUnits } from '../../simulation/units.js';
+
+const SENSOR_RAY_TRACK_COLOR = 0xf1c65b;
+const SENSOR_RAY_TRACK_ENTRY_COLOR = 0x68d8ff;
+const SENSOR_RAY_CAR_COLOR = 0xff4d5f;
+const SENSOR_RAY_KERB_COLOR = 0x49d17d;
+const SENSOR_RAY_ILLEGAL_COLOR = 0xd946ef;
+const SENSOR_RAY_MARKER_STROKE = 0x10131a;
+
+const SENSOR_HIT_CHANNELS = Object.freeze([
+  { key: 'track', radius: 5.8, alpha: 0.94 },
+  { key: 'kerb', color: SENSOR_RAY_KERB_COLOR, radius: 4.6, alpha: 0.9 },
+  { key: 'illegalSurface', color: SENSOR_RAY_ILLEGAL_COLOR, radius: 5.2, alpha: 0.92 },
+  { key: 'car', color: SENSOR_RAY_CAR_COLOR, radius: 6.6, alpha: 0.96 },
+]);
+
+function expertVisualizesRays(expertOptions) {
+  const setting = expertOptions?.visualizeSensors;
+  if (setting === true) return true;
+  if (!setting || setting === false) return false;
+  return Boolean(setting.rays);
+}
+
+function pointFromRay(origin, ray, distance) {
+  return {
+    x: origin.x + ray.x * distance,
+    y: origin.y + ray.y * distance,
+  };
+}
+
+function clearSensorLayerIfRendered(sensorLayer) {
+  if (!sensorLayer?.__paddockHasExpertSensorRays) return;
+  sensorLayer.clear();
+  sensorLayer.__paddockHasExpertSensorRays = false;
+}
+
+export function renderExpertSensorRays({ snapshot, observation, sensorLayer, expertMode, expertOptions }) {
+  if (!sensorLayer) return;
+  if (!expertMode || !expertVisualizesRays(expertOptions)) {
+    clearSensorLayerIfRendered(sensorLayer);
+    return;
+  }
+
+  const controlledDrivers = visualizedSensorDrivers(expertOptions);
+  if (!controlledDrivers.length || !observation) {
+    clearSensorLayerIfRendered(sensorLayer);
+    return;
+  }
+
+  const carsById = new Map(snapshot.cars.map((car) => [car.id, car]));
+  const drawableDrivers = controlledDrivers.filter((driverId) => {
+    const car = carsById.get(driverId);
+    const rays = observation?.[driverId]?.object?.rays;
+    return Boolean(car && Array.isArray(rays) && rays.length > 0);
+  });
+  if (!drawableDrivers.length) {
+    clearSensorLayerIfRendered(sensorLayer);
+    return;
+  }
+
+  sensorLayer.clear();
+  sensorLayer.__paddockHasExpertSensorRays = true;
+  drawableDrivers.forEach((driverId) => {
+    const car = carsById.get(driverId);
+    const rays = observation?.[driverId]?.object?.rays;
+    if (!car || !Array.isArray(rays) || rays.length === 0) return;
+
+    const origin = getCarRayOrigin(car);
+
+    rays.forEach((ray) => {
+      const rayVector = getCarRayVector(car, Number(ray.angleDegrees) || 0);
+      const totalDistanceMeters = Math.max(0, Number(ray.lengthMeters) || 0);
+      const fullEnd = pointFromRay(origin, rayVector, metersToSimUnits(totalDistanceMeters));
+
+      sensorLayer
+        .moveTo(origin.x, origin.y)
+        .lineTo(fullEnd.x, fullEnd.y)
+        .stroke({ width: 2, color: 0xffffff, alpha: 0.18, cap: 'round' });
+
+      rayHitMarkers(ray, totalDistanceMeters).forEach((marker) => {
+        const hitEnd = pointFromRay(origin, rayVector, metersToSimUnits(marker.distanceMeters));
+        sensorLayer
+          .circle(hitEnd.x, hitEnd.y, marker.radius)
+          .fill({ color: marker.color, alpha: marker.alpha })
+          .stroke({ width: 1.4, color: SENSOR_RAY_MARKER_STROKE, alpha: 0.82 });
+      });
+    });
+  });
+}
+
+function rayHitMarkers(ray, totalDistanceMeters) {
+  return SENSOR_HIT_CHANNELS
+    .map((channel) => {
+      const hit = ray[channel.key];
+      const distanceMeters = Math.max(0, Number(hit?.distanceMeters));
+      if (!hit?.hit || !Number.isFinite(distanceMeters) || distanceMeters > totalDistanceMeters) return null;
+      return {
+        ...channel,
+        distanceMeters,
+        color: markerColor(channel, hit),
+      };
+    })
+    .filter(Boolean);
+}
+
+function markerColor(channel, hit) {
+  if (channel.key === 'track') {
+    return hit.kind === 'entry' ? SENSOR_RAY_TRACK_ENTRY_COLOR : SENSOR_RAY_TRACK_COLOR;
+  }
+  return channel.color;
+}
+
+function visualizedSensorDrivers(expertOptions) {
+  const controlledDrivers = expertOptions?.controlledDrivers ?? [];
+  if (!controlledDrivers.length) return [];
+  const setting = expertOptions?.visualizeSensors;
+  if (setting && typeof setting === 'object') {
+    if (Array.isArray(setting.drivers)) {
+      return setting.drivers.filter((driverId) => controlledDrivers.includes(driverId));
+    }
+    if (setting.drivers === 'all') return controlledDrivers;
+    if (controlledDrivers.includes(setting.selectedDriverId)) return [setting.selectedDriverId];
+  }
+  return [controlledDrivers[0]];
+}

package/src/app/rendering/pitLaneStatusRenderer.js

@@ -0,0 +1,50 @@
+import { colorToTint } from './displayUtils.js';
+
+export class PitLaneStatusRenderer {
+  constructor() {
+    this.lastRenderKey = null;
+  }
+
+  reset() {
+    this.lastRenderKey = null;
+  }
+
+  render(snapshot, pitLaneStatusLayer) {
+    if (!pitLaneStatusLayer) return;
+    const pitLane = snapshot.track?.pitLane;
+    if (!pitLane?.enabled || !pitLane.mainLane?.start) {
+      if (this.lastRenderKey !== 'none') {
+        pitLaneStatusLayer.clear();
+        this.lastRenderKey = 'none';
+      }
+      return;
+    }
+    const status = snapshot.pitLaneStatus ?? snapshot.raceControl?.pitLaneStatus;
+    const color = colorToTint(status?.light ?? (status?.open ? '#22c55e' : '#ef4444'));
+    const heading = pitLane.mainLane.heading ?? 0;
+    const normal = pitLane.serviceNormal ?? { x: -Math.sin(heading), y: Math.cos(heading) };
+    const sign = pitLane.workingLane?.offset != null && pitLane.workingLane.offset < 0 ? 1 : -1;
+    const base = pitLane.mainLane.start;
+    const x = base.x + normal.x * sign * (pitLane.width * 0.72);
+    const y = base.y + normal.y * sign * (pitLane.width * 0.72);
+    const renderKey = [
+      color,
+      x.toFixed(3),
+      y.toFixed(3),
+      pitLane.width,
+      status?.open ? 1 : 0,
+      status?.reason ?? '',
+    ].join(':');
+    if (renderKey === this.lastRenderKey) return;
+    this.lastRenderKey = renderKey;
+
+    pitLaneStatusLayer.clear();
+    pitLaneStatusLayer
+      .circle(x, y, 17)
+      .fill({ color: 0x0b0f14, alpha: 0.92 })
+      .circle(x, y, 11)
+      .fill({ color, alpha: 0.94 })
+      .circle(x, y, 18)
+      .stroke({ width: 3, color: 0xf8fafc, alpha: 0.82 });
+  }
+}

package/src/app/rendering/replayGhostRenderer.js

@@ -0,0 +1,124 @@
+import { Graphics, Sprite, Text, Texture } from 'pixi.js';
+import { CAR_WORLD_LENGTH } from '../camera/cameraConstants.js';
+import { VEHICLE_GEOMETRY } from '../../simulation/vehicleGeometry.js';
+import { colorToTint, smoothAngle } from './displayUtils.js';
+
+const CAR_WORLD_WIDTH = VEHICLE_GEOMETRY.visualWidth;
+
+export class ReplayGhostRenderer {
+  constructor() {
+    this.sprites = new Map();
+    this.labels = new Map();
+    this.halos = new Map();
+  }
+
+  render(snapshot, { textures, replayGhostLayer }) {
+    if (!replayGhostLayer) return;
+    const visibleGhosts = (snapshot.replayGhosts ?? []).filter((ghost) => ghost.visible !== false);
+    const visibleIds = new Set(visibleGhosts.map((ghost) => ghost.id));
+    [...this.sprites.keys()].forEach((id) => {
+      if (visibleIds.has(id)) return;
+      this.destroyGhost(id);
+    });
+
+    visibleGhosts.forEach((ghost) => {
+      const halo = this.ensureHalo(ghost, replayGhostLayer);
+      halo.x = ghost.x;
+      halo.y = ghost.y;
+      halo.rotation = ghost.heading;
+      this.drawHalo(halo, ghost);
+
+      const sprite = this.ensureSprite(ghost, textures, replayGhostLayer);
+      sprite.x = ghost.x;
+      sprite.y = ghost.y;
+      sprite.currentRotation = smoothAngle(sprite.currentRotation, ghost.heading, 0.24);
+      sprite.rotation = sprite.currentRotation;
+      sprite.alpha = ghost.opacity;
+      sprite.tint = colorToTint(ghost.color);
+
+      const label = this.ensureLabel(ghost, replayGhostLayer);
+      label.text = ghost.label;
+      label.x = ghost.x;
+      label.y = ghost.y - CAR_WORLD_WIDTH * 1.15;
+      label.alpha = Math.min(1, ghost.opacity + 0.2);
+      label.visible = Boolean(ghost.label);
+    });
+  }
+
+  destroy() {
+    [...this.sprites.keys()].forEach((id) => this.destroyGhost(id));
+  }
+
+  ensureHalo(ghost, replayGhostLayer) {
+    let halo = this.halos.get(ghost.id);
+    if (halo) return halo;
+    halo = new Graphics();
+    halo.eventMode = 'none';
+    halo.ghostVisualRole = 'replay-halo';
+    this.halos.set(ghost.id, halo);
+    replayGhostLayer.addChild(halo);
+    return halo;
+  }
+
+  ensureSprite(ghost, textures, replayGhostLayer) {
+    let sprite = this.sprites.get(ghost.id);
+    if (sprite) return sprite;
+    const texture = textures.car ?? Texture.WHITE;
+    sprite = new Sprite(texture);
+    sprite.anchor.set(0.5);
+    sprite.baseScale = Math.min(
+      CAR_WORLD_LENGTH / Math.max(texture.width, 1),
+      CAR_WORLD_WIDTH / Math.max(texture.height, 1),
+    );
+    sprite.scale.set(sprite.baseScale);
+    sprite.eventMode = 'none';
+    sprite.currentRotation = ghost.heading;
+    this.sprites.set(ghost.id, sprite);
+    replayGhostLayer.addChild(sprite);
+    return sprite;
+  }
+
+  ensureLabel(ghost, replayGhostLayer) {
+    let label = this.labels.get(ghost.id);
+    if (label) return label;
+    label = new Text({
+      text: ghost.label,
+      style: {
+        fill: 0xffffff,
+        fontFamily: 'Arial, sans-serif',
+        fontSize: 18,
+        fontWeight: '800',
+        align: 'center',
+        stroke: { color: 0x000000, width: 3 },
+      },
+    });
+    label.anchor.set(0.5);
+    label.resolution = 2;
+    this.labels.set(ghost.id, label);
+    replayGhostLayer.addChild(label);
+    return label;
+  }
+
+  destroyGhost(id) {
+    this.halos.get(id)?.destroy?.();
+    this.sprites.get(id)?.destroy?.();
+    this.labels.get(id)?.destroy?.();
+    this.halos.delete(id);
+    this.sprites.delete(id);
+    this.labels.delete(id);
+  }
+
+  drawHalo(halo, ghost) {
+    const tint = colorToTint(ghost.color);
+    const alpha = Math.max(0.18, Math.min(0.55, ghost.opacity + 0.16));
+    halo.clear();
+    halo
+      .ellipse(0, 0, CAR_WORLD_LENGTH * 0.72, CAR_WORLD_WIDTH * 1.25)
+      .fill({ color: tint, alpha: Math.min(0.14, alpha * 0.28) })
+      .stroke({ width: 5, color: tint, alpha });
+    halo
+      .moveTo(CAR_WORLD_LENGTH * 0.55, 0)
+      .lineTo(CAR_WORLD_LENGTH * 0.92, 0)
+      .stroke({ width: 3, color: 0xffffff, alpha: Math.min(0.72, alpha + 0.14) });
+  }
+}

package/src/app/rendering/trackRenderer.js

@@ -0,0 +1,25 @@
+import { Graphics } from 'pixi.js';
+import { offsetTrackPoint, pointAt } from '../../simulation/trackModel.js';
+import { destroyDisplayChildren } from './displayUtils.js';
+
+export function renderTrackSurface({ drsLayer, sensorLayer, pitLaneStatusLayer, trackAsset, snapshot }) {
+  destroyDisplayChildren(drsLayer);
+  sensorLayer?.clear();
+  pitLaneStatusLayer?.clear();
+  const track = snapshot.track;
+
+  trackAsset.render(track);
+
+  track.drsZones.forEach((zone) => {
+    const zoneLine = new Graphics();
+    const steps = 44;
+    for (let index = 0; index <= steps; index += 1) {
+      const basePoint = pointAt(track, zone.start + ((zone.end - zone.start) * index) / steps);
+      const point = offsetTrackPoint(basePoint, track.width / 2 - 22);
+      if (index === 0) zoneLine.moveTo(point.x, point.y);
+      else zoneLine.lineTo(point.x, point.y);
+    }
+    zoneLine.stroke({ width: 8, color: 0x14c784, alpha: 0.5, join: 'round', cap: 'round' });
+    drsLayer.addChild(zoneLine);
+  });
+}

package/src/app/runtime/frameLoop.js

@@ -0,0 +1,66 @@
+import { interpolateRenderSnapshotInto } from '../../rendering/renderSnapshot.js';
+import { FIXED_STEP } from '../../simulation/raceSimulation.js';
+import { clamp } from '../../simulation/simMath.js';
+import {
+  domUpdateIntervalForSpeed,
+  FRAME_PACING_EPSILON_MS,
+  maxSimulationStepsForFrame,
+  MAX_FRAME_CATCHUP_COUNT,
+  TARGET_FRAME_MS,
+} from './runtimeTiming.js';
+
+export function runFrameLoopTick(app) {
+  if (app.expertMode) return;
+  const now = performance.now();
+  if (now < app.nextGameFrameTime - FRAME_PACING_EPSILON_MS) return;
+
+  const elapsedFrameCount = clamp(
+    Math.floor((now - app.nextGameFrameTime + FRAME_PACING_EPSILON_MS) / TARGET_FRAME_MS) + 1,
+    1,
+    MAX_FRAME_CATCHUP_COUNT,
+  );
+  const frameSeconds = (TARGET_FRAME_MS * elapsedFrameCount) / 1000;
+  app.nextGameFrameTime += TARGET_FRAME_MS * elapsedFrameCount;
+  if (now - app.nextGameFrameTime > TARGET_FRAME_MS * MAX_FRAME_CATCHUP_COUNT) {
+    app.nextGameFrameTime = now + TARGET_FRAME_MS;
+  }
+  app.lastTime = now;
+  app.sampleFps(now);
+  app.accumulator += frameSeconds * app.simulationSpeed;
+
+  let simulationSteps = 0;
+  const stepEvents = [];
+  const maxSimulationSteps = maxSimulationStepsForFrame(app.simulationSpeed, elapsedFrameCount);
+  while (app.accumulator >= FIXED_STEP && simulationSteps < maxSimulationSteps) {
+    app.sim.step(FIXED_STEP);
+    if (Array.isArray(app.sim.events) && app.sim.events.length > 0) {
+      stepEvents.push(...app.sim.events);
+    }
+    app.accumulator -= FIXED_STEP;
+    simulationSteps += 1;
+  }
+
+  if (app.accumulator >= FIXED_STEP) {
+    app.accumulator %= FIXED_STEP;
+    app.nextGameFrameTime = now + TARGET_FRAME_MS;
+  }
+
+  const shouldUpdateDom = now - app.lastDomUpdateTime >= domUpdateIntervalForSpeed(app.simulationSpeed);
+  const fullSnapshot = stepEvents.length > 0 || shouldUpdateDom ? app.sim.snapshot() : null;
+  if (stepEvents.length > 0) app.emitRaceEvents(stepEvents, fullSnapshot);
+  const renderSource = fullSnapshot ?? app.sim.snapshotRender?.() ?? app.sim.snapshot();
+  const renderSnapshot = interpolateRenderSnapshotInto(
+    app.renderSnapshotBuffer ?? {},
+    renderSource,
+    clamp(app.accumulator / FIXED_STEP, 0, 1),
+  );
+  app.renderSnapshotBuffer = renderSnapshot;
+  app.applyCamera(renderSnapshot);
+  app.renderDrsTrails(renderSnapshot);
+  app.renderPitLaneStatus(renderSnapshot);
+  app.renderCars(renderSnapshot);
+  if (shouldUpdateDom) {
+    app.updateDom(fullSnapshot, { emitLifecycle: false });
+    app.lastDomUpdateTime = now;
+  }
+}

package/src/app/runtime/runtimeTiming.js

@@ -0,0 +1,34 @@
+import { clamp } from '../../simulation/simMath.js';
+
+export const TARGET_RENDER_FPS = 60;
+export const TARGET_FRAME_MS = 1000 / TARGET_RENDER_FPS;
+export const FRAME_PACING_EPSILON_MS = 0.75;
+export const MAX_FRAME_CATCHUP_COUNT = 4;
+export const BASE_MAX_SIMULATION_STEPS_PER_RENDER = 5;
+export const HARD_MAX_SIMULATION_STEPS_PER_RENDER = 60;
+export const DOM_UPDATE_INTERVAL_MS = 100;
+export const TIMING_UPDATE_INTERVAL_MS = 250;
+
+export function maxSimulationStepsForFrame(simulationSpeed, elapsedFrameCount) {
+  const speed = Math.max(1, Number(simulationSpeed) || 1);
+  const frameCount = Math.max(1, Number(elapsedFrameCount) || 1);
+  return clamp(
+    Math.ceil(speed * frameCount) + 1,
+    BASE_MAX_SIMULATION_STEPS_PER_RENDER,
+    HARD_MAX_SIMULATION_STEPS_PER_RENDER,
+  );
+}
+
+export function domUpdateIntervalForSpeed(simulationSpeed) {
+  const speed = Math.max(1, Number(simulationSpeed) || 1);
+  if (speed >= 10) return 250;
+  if (speed >= 5) return 180;
+  return DOM_UPDATE_INTERVAL_MS;
+}
+
+export function timingUpdateIntervalForSpeed(simulationSpeed) {
+  const speed = Math.max(1, Number(simulationSpeed) || 1);
+  if (speed >= 10) return 600;
+  if (speed >= 5) return 400;
+  return TIMING_UPDATE_INTERVAL_MS;
+}

package/src/app/runtime/runtimeVisibility.js

@@ -0,0 +1,45 @@
+export function observeRuntimeVisibility(app) {
+  if (!app.canvasHost) return;
+
+  if (typeof IntersectionObserver === 'function') {
+    app.visibilityObserver?.disconnect?.();
+    app.visibilityObserver = new IntersectionObserver((entries) => {
+      const entry = entries.find((item) => item.target === app.canvasHost) ?? entries[0];
+      app.runtimeViewportVisible = Boolean(entry?.isIntersecting || entry?.intersectionRatio > 0);
+      app.syncRuntimeTicker();
+    }, {
+      root: null,
+      rootMargin: '240px 0px',
+      threshold: 0,
+    });
+    app.visibilityObserver.observe(app.canvasHost);
+  }
+
+  if (typeof document !== 'undefined') {
+    app.visibilityChangeHandler = () => {
+      app.runtimeDocumentVisible = document.visibilityState !== 'hidden';
+      app.syncRuntimeTicker();
+    };
+    document.addEventListener('visibilitychange', app.visibilityChangeHandler, {
+      signal: app.abortController.signal,
+    });
+  }
+
+  app.syncRuntimeTicker();
+}
+
+export function syncRuntimeTicker(app) {
+  if (app.expertMode) return;
+  if (!app.app?.ticker) return;
+
+  const shouldRun = app.runtimeViewportVisible && app.runtimeDocumentVisible;
+  if (shouldRun === app.runtimeTickerRunning) return;
+
+  app.runtimeTickerRunning = shouldRun;
+  if (shouldRun) {
+    app.resetFrameClock();
+    app.app.ticker.start?.();
+  } else {
+    app.app.ticker.stop?.();
+  }
+}

package/src/config/defaultOptions.js

@@ -1,9 +1,17 @@
 import { resolveF1SimulatorAssets } from './defaultAssets.js';
 import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../data/championship.js';
 import { normalizeSimulatorDrivers } from '../data/normalizeDrivers.js';
+import { normalizePhysicsMode } from '../simulation/vehicle/vehiclePhysics.js';
+import { normalizeWarmupOptions } from '../simulation/warmup/runtimeWarmup.js';
 
 export const DEFAULT_F1_SIMULATOR_OPTIONS = {
   seed: 1971,
+  physicsMode: 'arcade',
+  trackQueryIndex: true,
+  warmup: {
+    enabled: true,
+    policy: 'config-change',
+  },
   totalLaps: 10,
   initialCameraMode: 'leader',
   title: 'F1 Simulator Lab',
@@ -33,6 +41,9 @@ export const DEFAULT_F1_SIMULATOR_OPTIONS = {
     raceDataBannerSize: 'custom',
     timingTowerVerticalFit: 'expand-race-view',
   },
+  debug: {
+    physicsModeIndicator: false,
+  },
   theme: {
     accentColor: '#e10600',
     greenColor: '#14c784',
@@ -144,6 +155,12 @@ export function resolveF1SimulatorOptions(options = {}) {
     ui.raceDataBannerSize = DEFAULT_F1_SIMULATOR_OPTIONS.ui.raceDataBannerSize;
   }
   ui.raceDataTelemetryDetail = Boolean(ui.raceDataTelemetryDetail);
+  const debug = {
+    ...DEFAULT_F1_SIMULATOR_OPTIONS.debug,
+    ...(preset.debug ?? {}),
+    ...(options.debug ?? {}),
+  };
+  debug.physicsModeIndicator = Boolean(debug.physicsModeIndicator);
   const initialCameraMode = SUPPORTED_CAMERA_MODES.has(options.initialCameraMode)
     ? options.initialCameraMode
     : DEFAULT_F1_SIMULATOR_OPTIONS.initialCameraMode;
@@ -166,8 +183,11 @@ export function resolveF1SimulatorOptions(options = {}) {
     ...preset,
     ...options,
     preset: presetName ?? options.preset,
+    physicsMode: normalizePhysicsMode(options.physicsMode ?? preset.physicsMode),
+    warmup: normalizeWarmupOptions(mergedOptions.warmup, 'browser'),
     initialCameraMode,
     ui,
+    debug,
     theme,
     drivers,
     assets: resolveF1SimulatorAssets(options.assets),

package/src/environment/actions.js

@@ -1,5 +1,5 @@
 import { clamp } from '../simulation/simMath.js';
-import { VEHICLE_LIMITS } from '../simulation/vehiclePhysics.js';
+import { VEHICLE_LIMITS } from '../simulation/vehicle/vehiclePhysics.js';
 
 export function resolveActionMap(actions = {}, controlledDrivers = [], { policy = 'strict' } = {}) {
   const errors = [];
@@ -22,9 +22,9 @@ export function resolveActionMap(actions = {}, controlledDrivers = [], { policy
 }
 
 export function normalizeAction(action, driverId = 'unknown', policy = 'strict', errors = []) {
-  const steering = finiteActionValue(action.steering, `Invalid steering action for controlled driver: ${driverId}`, policy, errors);
-  const throttle = finiteActionValue(action.throttle, `Invalid throttle action for controlled driver: ${driverId}`, policy, errors);
-  const brake = finiteActionValue(action.brake, `Invalid brake action for controlled driver: ${driverId}`, policy, errors);
+  const steering = requiredActionValue(action, 'steering', driverId, policy, errors);
+  const throttle = requiredActionValue(action, 'throttle', driverId, policy, errors);
+  const brake = requiredActionValue(action, 'brake', driverId, policy, errors);
 
   if (steering == null || throttle == null || brake == null) return null;
 
@@ -35,8 +35,16 @@ export function normalizeAction(action, driverId = 'unknown', policy = 'strict',
   };
 }
 
+function requiredActionValue(action, field, driverId, policy, errors) {
+  if (!Object.hasOwn(action, field)) {
+    handleActionError(`Missing ${field} action for controlled driver: ${driverId}`, policy, errors);
+    return null;
+  }
+  return finiteActionValue(action[field], `Invalid ${field} action for controlled driver: ${driverId}`, policy, errors);
+}
+
 function finiteActionValue(value, message, policy, errors) {
-  const number = Number(value ?? 0);
+  const number = Number(value);
   if (Number.isFinite(number)) return number;
   handleActionError(message, policy, errors);
   return null;