@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/simulation/track/trackQueryPitIndex.js

@@ -0,0 +1,140 @@
+import { createSpatialGrid, insertIdIntoGridBounds, candidateIdsFromGrid } from './trackQueryGrid.js';
+import { recordFallback, recordStat } from './trackQueryStats.js';
+
+export function createPitQueryIndex(track, cellSize) {
+  const pitLane = track.pitLane;
+  if (!pitLane?.enabled) return null;
+  const bounds = {
+    minX: pitLane.bounds.minX - cellSize,
+    maxX: pitLane.bounds.maxX + cellSize,
+    minY: pitLane.bounds.minY - cellSize,
+    maxY: pitLane.bounds.maxY + cellSize,
+  };
+  const roadGrid = createSpatialGrid(bounds, cellSize);
+  const boxGrid = createSpatialGrid(bounds, cellSize);
+  const roadSegments = [];
+  const routes = {};
+
+  [
+    ['entry', pitLane.entry?.roadCenterline],
+    ['main', pitLane.mainLane?.points],
+    ['working', pitLane.workingLane?.points],
+    ['exit', pitLane.exit?.roadCenterline],
+  ].forEach(([routeId, points]) => {
+    routes[routeId] = { start: roadSegments.length };
+    indexPitRoute(roadGrid, roadSegments, routeId, points, cellSize);
+    routes[routeId].end = roadSegments.length;
+  });
+
+  const boxCandidates = [];
+  [
+    ...(pitLane.serviceAreas ?? []).flatMap((area) => [
+      { type: 'service-area', target: area, polygon: area.corners },
+      { type: 'service-queue', target: area, polygon: area.queueCorners },
+    ]),
+    ...(pitLane.boxes ?? []).map((box) => ({ type: 'garage-box', target: box, polygon: box.corners })),
+  ]
+    .filter((candidate) => Array.isArray(candidate.polygon) && candidate.polygon.length >= 3)
+    .forEach((candidate) => {
+      const id = boxCandidates.length;
+      boxCandidates.push(candidate);
+      insertIdIntoGridBounds(boxGrid, id, polygonBounds(candidate.polygon, cellSize));
+    });
+
+  return {
+    roadGrid,
+    boxGrid,
+    routes,
+    roadSegments,
+    boxCandidates,
+  };
+}
+
+export function queryPitBoxCandidates(track, position) {
+  const index = track?.queryIndex;
+  const pit = index?.pit;
+  if (!pit?.boxGrid) {
+    recordFallback(index, 'pitFallbackReasons', 'missing-box-index');
+    return null;
+  }
+  if (!finitePoint(position)) {
+    recordFallback(index, 'pitFallbackReasons', 'invalid-position');
+    return null;
+  }
+  index.stats.pitQueries += 1;
+  const ids = candidateIdsFromGrid(index, pit.boxGrid, position, 1);
+  if (!ids.length) {
+    recordStat(index, 'pitPaths', 'box-grid-miss');
+    return [];
+  }
+  recordStat(index, 'pitPaths', 'box-grid-hit');
+  return ids.map((id) => pit.boxCandidates[id]).filter(Boolean);
+}
+
+export function queryPitRoadSegmentCandidates(track, routeId, position) {
+  const candidatesByRoute = queryPitRoadSegmentCandidatesByRoute(track, position);
+  return candidatesByRoute?.[routeId] ?? candidatesByRoute;
+}
+
+export function queryPitRoadSegmentCandidatesByRoute(track, position) {
+  const index = track?.queryIndex;
+  const pit = index?.pit;
+  if (!pit?.roadGrid) {
+    recordFallback(index, 'pitFallbackReasons', 'missing-road-index');
+    return null;
+  }
+  if (!finitePoint(position)) {
+    recordFallback(index, 'pitFallbackReasons', 'invalid-position');
+    return null;
+  }
+  index.stats.pitQueries += 1;
+  const ids = candidateIdsFromGrid(index, pit.roadGrid, position, 1);
+  if (!ids.length) {
+    recordStat(index, 'pitPaths', 'road-grid-miss');
+    return null;
+  }
+  const candidatesByRoute = { entry: [], main: [], working: [], exit: [] };
+  ids.forEach((id) => {
+    const segment = pit.roadSegments[id];
+    if (!segment || !candidatesByRoute[segment.routeId]) return;
+    candidatesByRoute[segment.routeId].push(segment.segmentIndex);
+  });
+  recordStat(index, 'pitPaths', 'road-grid-hit');
+  return candidatesByRoute;
+}
+
+function indexPitRoute(grid, roadSegments, routeId, points, expansion) {
+  if (!Array.isArray(points) || points.length < 2) return;
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const start = points[index];
+    const end = points[index + 1];
+    const id = roadSegments.length;
+    roadSegments.push({ routeId, segmentIndex: index });
+    const bounds = {
+      minX: Math.min(start.x, end.x) - expansion,
+      maxX: Math.max(start.x, end.x) + expansion,
+      minY: Math.min(start.y, end.y) - expansion,
+      maxY: Math.max(start.y, end.y) + expansion,
+    };
+    insertIdIntoGridBounds(grid, id, bounds);
+  }
+}
+
+function polygonBounds(polygon, expansion) {
+  const bounds = polygon.reduce((current, point) => ({
+    minX: Math.min(current.minX, point.x),
+    maxX: Math.max(current.maxX, point.x),
+    minY: Math.min(current.minY, point.y),
+    maxY: Math.max(current.maxY, point.y),
+  }), { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity });
+  return {
+    minX: bounds.minX - expansion,
+    maxX: bounds.maxX + expansion,
+    minY: bounds.minY - expansion,
+    maxY: bounds.maxY + expansion,
+  };
+}
+
+function finitePoint(point) {
+  return Number.isFinite(point?.x) && Number.isFinite(point?.y);
+}

package/src/simulation/track/trackQueryScratch.js

@@ -0,0 +1,46 @@
+export function createQueryScratch(index) {
+  const segmentCount = Math.max(0, index?.centerline?.segmentCount ?? 0);
+  const maxId = Math.max(
+    segmentCount,
+    index?.pit?.roadSegments?.length ?? 0,
+    index?.pit?.boxCandidates?.length ?? 0,
+  );
+  const grid = index?.segmentGrid ?? index?.grid;
+  const cellCount = Math.max(0, (grid?.columns ?? 0) * (grid?.rows ?? 0));
+  return {
+    candidateMarks: new Uint32Array(Math.max(1, maxId)),
+    candidateEpoch: 1,
+    sampleMarks: new Uint32Array(Math.max(1, segmentCount)),
+    sampleEpoch: 1,
+    raySegmentMarks: new Uint32Array(Math.max(1, segmentCount)),
+    raySegmentEpoch: 1,
+    rayCellMarks: new Uint32Array(Math.max(1, cellCount)),
+    rayCellEpoch: 1,
+    raySegmentIds: [],
+    rayVisitedCells: [],
+    rayTraceCache: new Map(),
+  };
+}
+
+export function ensureQueryScratch(index) {
+  if (index.queryScratch) return index.queryScratch;
+  index.queryScratch = createQueryScratch(index);
+  return index.queryScratch;
+}
+
+export function ensureScratchArray(scratch, key, minimumLength) {
+  if (!scratch[key] || scratch[key].length < minimumLength) {
+    scratch[key] = new Uint32Array(Math.max(1, minimumLength));
+  }
+  return scratch[key];
+}
+
+export function nextScratchEpoch(scratch, key, marks) {
+  let epoch = (scratch[key] ?? 0) + 1;
+  if (epoch >= 0xFFFFFFFF) {
+    marks.fill(0);
+    epoch = 1;
+  }
+  scratch[key] = epoch;
+  return epoch;
+}

package/src/simulation/track/trackQueryStats.js

@@ -0,0 +1,28 @@
+export function createQueryStats() {
+  return {
+    nearestQueries: 0,
+    nearestFallbacks: 0,
+    nearestPaths: {},
+    nearestFallbackReasons: {
+      'spatial-grid-no-candidates': 0,
+    },
+    pitQueries: 0,
+    pitFallbacks: 0,
+    pitPaths: {},
+    pitFallbackReasons: {},
+  };
+}
+
+export function recordFallback(index, bucket, reason) {
+  if (!index?.stats) return;
+  if (bucket === 'nearestFallbackReasons') index.stats.nearestFallbacks += 1;
+  if (bucket === 'pitFallbackReasons') index.stats.pitFallbacks += 1;
+  recordStat(index, bucket, reason);
+}
+
+export function recordStat(index, bucket, key) {
+  if (!index?.stats || !bucket || !key) return;
+  const target = index.stats[bucket] ?? {};
+  target[key] = (target[key] ?? 0) + 1;
+  index.stats[bucket] = target;
+}

package/src/simulation/track/trackSectors.js

@@ -0,0 +1,19 @@
+export function createTrackSectors(totalLength) {
+  return Array.from({ length: 3 }, (_, index) => {
+    const startRatio = index / 3;
+    const endRatio = (index + 1) / 3;
+    const start = totalLength * startRatio;
+    const end = totalLength * endRatio;
+
+    return {
+      index: index + 1,
+      id: `s${index + 1}`,
+      label: `S${index + 1}`,
+      start,
+      end,
+      startRatio,
+      endRatio,
+      length: end - start,
+    };
+  });
+}

package/src/simulation/track/trackStatePolicy.js

@@ -0,0 +1,24 @@
+import { nearestTrackState } from './trackModel.js';
+
+export function pitOverrideAllowedForCar(car) {
+  if (!car?.environmentControlled) return true;
+  const status = car.pitStop?.status ?? null;
+  const pitRouteActive = status != null && status !== 'pending' && status !== 'completed';
+  const pitIntentCommitted = Number(car.pitStop?.intent ?? car.pitIntent ?? 0) >= 2;
+  return pitRouteActive || pitIntentCommitted;
+}
+
+export function nearestTrackStateForCar(
+  track,
+  car,
+  position = car,
+  progressHint = car?.progress ?? null,
+  options = {},
+) {
+  const resolvedAllowPitOverride = options.allowPitOverride ?? pitOverrideAllowedForCar(car);
+  return nearestTrackState(track, position, progressHint, {
+    indexMode: options.indexMode ?? 'legacy',
+    ...options,
+    allowPitOverride: resolvedAllowPitOverride,
+  });
+}

package/src/simulation/track/trackValidation.js

@@ -0,0 +1,98 @@
+import { normalizeAngle } from '../simMath.js';
+import { GENERATED_TRACK_MAX_LENGTH, GENERATED_TRACK_MIN_LENGTH, MAX_LOCAL_TURN_RADIANS, MAX_SAMPLE_HEADING_DELTA_RADIANS, MIN_NON_ADJACENT_ARC_DISTANCE, MIN_TRACK_CLEARANCE_MULTIPLIER, MIN_TRACK_SHAPE_VARIATION, TRACK_BOUNDARY_PADDING, WORLD } from './trackConstants.js';
+import { distance, segmentsIntersect } from './trackMath.js';
+
+export function hasSelfIntersections(samples) {
+  const points = samples.slice(0, -1).filter((_, index) => index % 12 === 0);
+  for (let first = 0; first < points.length - 1; first += 1) {
+    for (let second = first + 2; second < points.length - 1; second += 1) {
+      const sharesLoopClosure = first === 0 && second >= points.length - 3;
+      if (sharesLoopClosure) continue;
+      if (segmentsIntersect(points[first], points[first + 1], points[second], points[second + 1])) return true;
+    }
+  }
+  return false;
+}
+
+export function samplesStayInsideWorld(samples) {
+  return samples.every((sample) => (
+    sample.x >= TRACK_BOUNDARY_PADDING &&
+    sample.x <= WORLD.width - TRACK_BOUNDARY_PADDING &&
+    sample.y >= TRACK_BOUNDARY_PADDING &&
+    sample.y <= WORLD.height - TRACK_BOUNDARY_PADDING
+  ));
+}
+
+export function hasEnoughTrackClearance(samples, totalLength, minimumClearance, minimumNonAdjacentArcDistance = MIN_NON_ADJACENT_ARC_DISTANCE) {
+  const points = samples.slice(0, -1).filter((_, index) => index % 24 === 0);
+  const minimumClearanceSquared = minimumClearance * minimumClearance;
+  for (let first = 0; first < points.length; first += 1) {
+    for (let second = first + 1; second < points.length; second += 1) {
+      const arcDistance = Math.abs(points[second].distance - points[first].distance);
+      const loopDistance = Math.min(arcDistance, totalLength - arcDistance);
+      if (loopDistance < minimumNonAdjacentArcDistance) continue;
+      const dx = points[first].x - points[second].x;
+      const dy = points[first].y - points[second].y;
+      if (dx * dx + dy * dy < minimumClearanceSquared) return false;
+    }
+  }
+  return true;
+}
+
+export function hasReasonableTurnSharpness(samples, options = {}) {
+  const maxSampleHeadingDeltaRadians = options.maxSampleHeadingDeltaRadians ?? MAX_SAMPLE_HEADING_DELTA_RADIANS;
+  const maxLocalTurnRadians = options.maxLocalTurnRadians ?? MAX_LOCAL_TURN_RADIANS;
+  const usableSamples = samples.slice(0, -1);
+  const windows = [30, 36];
+  const step = 6;
+
+  for (let index = 0; index < usableSamples.length; index += 1) {
+    const current = usableSamples[index];
+    const next = usableSamples[(index + 1) % usableSamples.length];
+    if (Math.abs(normalizeAngle(next.heading - current.heading)) > maxSampleHeadingDeltaRadians) {
+      return false;
+    }
+  }
+
+  for (let index = 0; index < usableSamples.length; index += step) {
+    for (const window of windows) {
+      let accumulatedTurn = 0;
+      for (let offset = 0; offset < window; offset += step) {
+        const current = usableSamples[(index + offset) % usableSamples.length];
+        const next = usableSamples[(index + offset + step) % usableSamples.length];
+        accumulatedTurn += Math.abs(normalizeAngle(next.heading - current.heading));
+      }
+      if (accumulatedTurn > maxLocalTurnRadians) return false;
+    }
+  }
+
+  return true;
+}
+
+export function hasEnoughShapeVariation(controls, minimumVariation = MIN_TRACK_SHAPE_VARIATION) {
+  const center = { x: WORLD.width / 2, y: WORLD.height / 2 };
+  const radii = controls.map((point) => distance(point, center));
+  const mean = radii.reduce((total, radius) => total + radius, 0) / Math.max(1, radii.length);
+  if (mean <= 0) return false;
+  const variance = radii.reduce((total, radius) => total + (radius - mean) ** 2, 0) / Math.max(1, radii.length);
+  return Math.sqrt(variance) / mean > minimumVariation;
+}
+
+export function isValidProceduralTrackModel(model, options = {}) {
+  const length = options.length ?? {};
+  const validation = options.validation ?? {};
+  return (
+    model.length >= (length.min ?? GENERATED_TRACK_MIN_LENGTH) &&
+    model.length <= (length.max ?? GENERATED_TRACK_MAX_LENGTH) &&
+    hasEnoughShapeVariation(model.centerlineControls, validation.minShapeVariation ?? MIN_TRACK_SHAPE_VARIATION) &&
+    samplesStayInsideWorld(model.samples) &&
+    hasEnoughTrackClearance(
+      model.samples,
+      model.length,
+      model.width * (validation.minClearanceMultiplier ?? MIN_TRACK_CLEARANCE_MULTIPLIER),
+      validation.minNonAdjacentArcDistance ?? MIN_NON_ADJACENT_ARC_DISTANCE,
+    ) &&
+    hasReasonableTurnSharpness(model.samples, validation) &&
+    !hasSelfIntersections(model.samples)
+  );
+}