@inventure71/paddockjs 1.0.0 → 2.0.1

package/src/simulation/track/trackModel.js

@@ -0,0 +1,240 @@
+import { normalizeAngle } from '../simMath.js';
+import { CENTERLINE_CONTROLS, TRACK } from './trackConstants.js';
+import { distance } from './trackMath.js';
+import { rawCenterPoint } from './centerlineSpline.js';
+import { generateCenterlineControls, generateFallbackCenterlineControls, generateSafeFallbackCenterlineControls, normalizeSeed } from './proceduralCenterline.js';
+import { isValidProceduralTrackModel } from './trackValidation.js';
+import { recalculateSampleGeometry } from './sampleGeometry.js';
+import { rotateSamplesToStandingStart, straightenStandingStartSamples } from './startStraight.js';
+import { createTrackSectors } from './trackSectors.js';
+import { deriveDrsZones, normalizeDrsZone } from './drsZones.js';
+import { createPitLaneModel } from './pitLaneLayout.js';
+import { attachTrackQueryIndex, createTrackQueryIndex } from './trackQueryIndex.js';
+import { resolveProceduralTrackOptions } from './trackGenerationOptions.js';
+
+export { WORLD, TRACK } from './trackConstants.js';
+export { isInDrsZone } from './drsZones.js';
+export { nearestTrackState, offsetTrackPoint, pointAt } from './spatialQueries.js';
+
+const PROCEDURAL_TRACK_CACHE = new Map();
+const TRACK_MODEL_CACHE = new WeakMap();
+
+export function buildTrackModel(track = TRACK) {
+  const canReuseCachedModel = track === TRACK || Object.isFrozen(track);
+  const cached = canReuseCachedModel ? TRACK_MODEL_CACHE.get(track) : null;
+  if (cached) return cached;
+
+  const controls = track.centerlineControls ?? CENTERLINE_CONTROLS;
+  const base = [];
+  for (let index = 0; index <= track.sampleCount; index += 1) {
+    base.push(rawCenterPoint(index / track.sampleCount, controls, track.curveInterpolation));
+  }
+
+  let totalLength = 0;
+  const samples = base.map((point, index) => {
+    if (index > 0) totalLength += distance(base[index - 1], point);
+    return { ...point, distance: totalLength, heading: 0, normalX: 0, normalY: 0, curvature: 0 };
+  });
+  recalculateSampleGeometry(samples);
+
+  const startStraightOptions = track.generationOptions?.startStraight;
+  const rotatedSamples = rotateSamplesToStandingStart(samples, totalLength, startStraightOptions);
+  const straightenedTrack = straightenStandingStartSamples(rotatedSamples, totalLength, startStraightOptions);
+  const normalizedSamples = straightenedTrack.samples;
+  totalLength = straightenedTrack.totalLength;
+
+  const model = {
+    ...track,
+    centerlineControls: controls,
+    length: totalLength,
+    samples: normalizedSamples,
+    sectors: createTrackSectors(totalLength),
+    drsZones: (track.drsZones ?? deriveDrsZones(normalizedSamples, totalLength))
+      .map((zone) => normalizeDrsZone(zone, totalLength)),
+  };
+  model.pitLane = track.pitLane?.enabled === false || track.generationOptions?.pitLane?.enabled === false
+    ? null
+    : createPitLaneModel(model);
+  attachTrackQueryIndex(model, createTrackQueryIndex(model));
+  if (canReuseCachedModel) {
+    TRACK_MODEL_CACHE.set(track, freezeTrackModel(model));
+  }
+  return model;
+}
+
+export function createProceduralTrack(seed = Date.now(), options = {}) {
+  const normalizedSeed = normalizeSeed(seed);
+  const generationOptions = resolveProceduralTrackOptions(options);
+  const cacheKey = `${normalizedSeed}:${generationOptions.cacheKey}`;
+  const cached = PROCEDURAL_TRACK_CACHE.get(cacheKey);
+  if (cached) return cached;
+
+  for (let attempt = 0; attempt < generationOptions.attempts.primary; attempt += 1) {
+    const candidateSeed = (normalizedSeed + Math.imul(attempt, 2654435761)) >>> 0;
+    const candidate = {
+      ...TRACK,
+      name: `Generated GP ${candidateSeed.toString(36).toUpperCase().padStart(6, '0').slice(-6)}`,
+      seed: candidateSeed,
+      curveInterpolation: 'centripetal',
+      centerlineControls: generateCenterlineControls(candidateSeed, generationOptions.shape),
+      drsZones: null,
+      generationOptions,
+      ...(generationOptions.pitLane.enabled === false ? { pitLane: { enabled: false } } : {}),
+    };
+    const model = buildTrackModel(candidate);
+    if (isValidProceduralTrackModel(model, generationOptions)) {
+      const trackDefinition = {
+        ...candidate,
+        drsZones: model.drsZones.map(({ id, startRatio, endRatio }) => ({ id, startRatio, endRatio })),
+      };
+      return cacheProceduralTrackDefinition(cacheKey, trackDefinition);
+    }
+  }
+
+  let fallback = null;
+  let fallbackModel = null;
+  for (let attempt = 0; attempt < generationOptions.attempts.fallback; attempt += 1) {
+    const candidateSeed = (normalizedSeed ^ Math.imul(attempt + 1, 2246822519)) >>> 0;
+    const candidate = {
+      ...TRACK,
+      name: `Generated GP ${normalizedSeed.toString(36).toUpperCase().padStart(6, '0').slice(-6)}`,
+      seed: candidateSeed,
+      curveInterpolation: 'centripetal',
+      centerlineControls: generateFallbackCenterlineControls(candidateSeed, generationOptions.shape),
+      drsZones: null,
+      generationOptions,
+      ...(generationOptions.pitLane.enabled === false ? { pitLane: { enabled: false } } : {}),
+    };
+    const model = buildTrackModel(candidate);
+    if (isValidProceduralTrackModel(model, generationOptions)) {
+      fallback = candidate;
+      fallbackModel = model;
+      break;
+    }
+  }
+
+  if (!fallback || !fallbackModel) {
+    fallback = {
+      ...TRACK,
+      name: `Generated GP ${normalizedSeed.toString(36).toUpperCase().padStart(6, '0').slice(-6)}`,
+      seed: normalizedSeed,
+      curveInterpolation: 'centripetal',
+      centerlineControls: generateSafeFallbackCenterlineControls(normalizedSeed, generationOptions.shape),
+      drsZones: null,
+      generationOptions,
+      ...(generationOptions.pitLane.enabled === false ? { pitLane: { enabled: false } } : {}),
+    };
+    fallbackModel = buildTrackModel(fallback);
+  }
+  const fallbackDefinition = {
+    ...fallback,
+    drsZones: fallbackModel.drsZones.map(({ id, startRatio, endRatio }) => ({ id, startRatio, endRatio })),
+  };
+  return cacheProceduralTrackDefinition(cacheKey, fallbackDefinition);
+}
+
+export { normalizeAngle };
+
+function cacheProceduralTrackDefinition(cacheKey, trackDefinition) {
+  const frozen = deepFreeze(trackDefinition);
+  PROCEDURAL_TRACK_CACHE.set(cacheKey, frozen);
+  return frozen;
+}
+
+function freezeTrackModel(model) {
+  freezeArrayItems(model.samples);
+  freezeArrayItems(model.centerlineControls);
+  freezeArrayItems(model.sectors);
+  freezeArrayItems(model.drsZones);
+  deepFreeze(model.pitLane);
+  freezeTrackQueryIndex(model.queryIndex);
+  return Object.freeze(model);
+}
+
+function freezeArrayItems(items) {
+  if (!Array.isArray(items)) return;
+  items.forEach((item) => deepFreeze(item));
+  Object.freeze(items);
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  Object.values(value).forEach((child) => {
+    deepFreeze(child);
+  });
+  return value;
+}
+
+function freezeTrackQueryIndex(index) {
+  if (!index || typeof index !== 'object') return index;
+  deepFreeze(index.bands);
+  freezeCenterlineSegments(index.centerline);
+  freezeSpatialGrid(index.grid);
+  freezeSpatialGrid(index.segmentGrid);
+  freezeArcBuckets(index.arcBuckets);
+  freezePitQueryIndex(index.pit);
+  return Object.freeze(index);
+}
+
+function freezeCenterlineSegments(centerline) {
+  if (!centerline || typeof centerline !== 'object') return centerline;
+  Object.entries(centerline).forEach(([key, value]) => {
+    if (ArrayBuffer.isView(value)) {
+      centerline[key] = Object.freeze(Array.from(value));
+    }
+  });
+  return Object.freeze(centerline);
+}
+
+function freezeSpatialGrid(grid) {
+  if (!grid || typeof grid !== 'object') return grid;
+  deepFreeze(grid.bounds);
+  if (grid.cells instanceof Map) {
+    for (const cell of grid.cells.values()) Object.freeze(cell);
+    grid.cells = readonlyMap(grid.cells);
+  }
+  return Object.freeze(grid);
+}
+
+function freezeArcBuckets(arcBuckets) {
+  if (!arcBuckets || typeof arcBuckets !== 'object') return arcBuckets;
+  if (Array.isArray(arcBuckets.buckets)) {
+    arcBuckets.buckets.forEach((bucket) => Object.freeze(bucket));
+    Object.freeze(arcBuckets.buckets);
+  }
+  return Object.freeze(arcBuckets);
+}
+
+function freezePitQueryIndex(pit) {
+  if (!pit || typeof pit !== 'object') return pit;
+  freezeSpatialGrid(pit.roadGrid);
+  freezeSpatialGrid(pit.boxGrid);
+  deepFreeze(pit.routes);
+  freezeArrayItems(pit.roadSegments);
+  freezeArrayItems(pit.boxCandidates);
+  return Object.freeze(pit);
+}
+
+function readonlyMap(map) {
+  return new Proxy(map, {
+    get(target, property) {
+      if (property === 'set' || property === 'delete' || property === 'clear') {
+        return () => {
+          throw new TypeError('Cannot mutate a cached track query index');
+        };
+      }
+      const value = Reflect.get(target, property, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+    set() {
+      throw new TypeError('Cannot mutate a cached track query index');
+    },
+    deleteProperty() {
+      throw new TypeError('Cannot mutate a cached track query index');
+    },
+    defineProperty() {
+      throw new TypeError('Cannot mutate a cached track query index');
+    },
+  });
+}

package/src/simulation/track/trackQueryGrid.js

@@ -0,0 +1,94 @@
+import { clamp } from '../simMath.js';
+import { ensureQueryScratch, ensureScratchArray, nextScratchEpoch } from './trackQueryScratch.js';
+
+export function createSpatialGrid(bounds, cellSize) {
+  const columns = Math.max(1, Math.ceil((bounds.maxX - bounds.minX) / cellSize));
+  const rows = Math.max(1, Math.ceil((bounds.maxY - bounds.minY) / cellSize));
+  return {
+    bounds,
+    cellSize,
+    columns,
+    rows,
+    cells: new Array(columns * rows),
+  };
+}
+
+export function insertIdIntoGridBounds(grid, id, bounds) {
+  const minCell = gridCellForPoint(grid, { x: bounds.minX, y: bounds.minY }, true);
+  const maxCell = gridCellForPoint(grid, { x: bounds.maxX, y: bounds.maxY }, true);
+  for (let row = minCell.row; row <= maxCell.row; row += 1) {
+    for (let column = minCell.column; column <= maxCell.column; column += 1) {
+      const cellIndex = row * grid.columns + column;
+      const cell = grid.cells[cellIndex];
+      if (cell) cell.push(id);
+      else grid.cells[cellIndex] = [id];
+    }
+  }
+}
+
+export function candidateIdsFromGrid(index, grid, position, neighborLimit) {
+  const center = gridCellForPoint(grid, position, false);
+  if (!center) return [];
+  const scratch = ensureQueryScratch(index);
+  const maxId = Math.max(index.centerline.segmentCount, index.pit?.roadSegments?.length ?? 0, index.pit?.boxCandidates?.length ?? 0);
+  const idMarks = ensureScratchArray(scratch, 'candidateMarks', maxId);
+  const ids = [];
+  for (let radius = 0; radius <= neighborLimit; radius += 1) {
+    const candidateEpoch = nextScratchEpoch(scratch, 'candidateEpoch', idMarks);
+    ids.length = 0;
+    for (let row = center.row - radius; row <= center.row + radius; row += 1) {
+      for (let column = center.column - radius; column <= center.column + radius; column += 1) {
+        if (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows) continue;
+        const cell = grid.cells[row * grid.columns + column];
+        if (!cell) continue;
+        for (const id of cell) {
+          if (idMarks[id] === candidateEpoch) continue;
+          idMarks[id] = candidateEpoch;
+          ids.push(id);
+        }
+      }
+    }
+    if (ids.length) return ids.slice();
+  }
+  return [];
+}
+
+export function candidateIdsFromGridBounds(index, grid, bounds) {
+  if (
+    bounds.maxX < grid.bounds.minX ||
+    bounds.minX > grid.bounds.maxX ||
+    bounds.maxY < grid.bounds.minY ||
+    bounds.minY > grid.bounds.maxY
+  ) return [];
+  const minPoint = { x: bounds.minX, y: bounds.minY };
+  const maxPoint = { x: bounds.maxX, y: bounds.maxY };
+  const minCell = gridCellForPoint(grid, minPoint, true);
+  const maxCell = gridCellForPoint(grid, maxPoint, true);
+  const scratch = ensureQueryScratch(index);
+  const maxId = Math.max(index.centerline.segmentCount, index.pit?.roadSegments?.length ?? 0, index.pit?.boxCandidates?.length ?? 0);
+  const idMarks = ensureScratchArray(scratch, 'candidateMarks', maxId);
+  const candidateEpoch = nextScratchEpoch(scratch, 'candidateEpoch', idMarks);
+  const ids = [];
+  for (let row = minCell.row; row <= maxCell.row; row += 1) {
+    for (let column = minCell.column; column <= maxCell.column; column += 1) {
+      const cell = grid.cells[row * grid.columns + column];
+      if (!cell) continue;
+      for (const id of cell) {
+        if (idMarks[id] === candidateEpoch) continue;
+        idMarks[id] = candidateEpoch;
+        ids.push(id);
+      }
+    }
+  }
+  return ids;
+}
+
+export function gridCellForPoint(grid, point, clampToGrid) {
+  const column = Math.floor((point.x - grid.bounds.minX) / grid.cellSize);
+  const row = Math.floor((point.y - grid.bounds.minY) / grid.cellSize);
+  if (!clampToGrid && (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows)) return null;
+  return {
+    column: clampToGrid ? clamp(column, 0, grid.columns - 1) : column,
+    row: clampToGrid ? clamp(row, 0, grid.rows - 1) : row,
+  };
+}