@inventure71/paddockjs 4.2.0 → 4.3.1

package/src/simulation/track/pitLaneModel.js

@@ -0,0 +1,70 @@
+function clonePointLike(point) {
+  if (!point) return point;
+  return { ...point };
+}
+
+function clonePointArray(points) {
+  return Array.isArray(points) ? points.map(clonePointLike) : points;
+}
+
+export function clonePitLaneModel(pitLane) {
+  if (!pitLane) return pitLane;
+  return {
+    ...pitLane,
+    entry: pitLane.entry ? {
+      ...pitLane.entry,
+      trackPoint: clonePointLike(pitLane.entry.trackPoint),
+      edgePoint: clonePointLike(pitLane.entry.edgePoint),
+      trackConnectPoint: clonePointLike(pitLane.entry.trackConnectPoint),
+      lanePoint: clonePointLike(pitLane.entry.lanePoint),
+      roadCenterline: clonePointArray(pitLane.entry.roadCenterline),
+      connector: clonePointArray(pitLane.entry.connector),
+    } : pitLane.entry,
+    exit: pitLane.exit ? {
+      ...pitLane.exit,
+      trackPoint: clonePointLike(pitLane.exit.trackPoint),
+      edgePoint: clonePointLike(pitLane.exit.edgePoint),
+      trackConnectPoint: clonePointLike(pitLane.exit.trackConnectPoint),
+      lanePoint: clonePointLike(pitLane.exit.lanePoint),
+      roadCenterline: clonePointArray(pitLane.exit.roadCenterline),
+      connector: clonePointArray(pitLane.exit.connector),
+    } : pitLane.exit,
+    mainLane: pitLane.mainLane ? {
+      ...pitLane.mainLane,
+      start: clonePointLike(pitLane.mainLane.start),
+      end: clonePointLike(pitLane.mainLane.end),
+      points: clonePointArray(pitLane.mainLane.points),
+    } : pitLane.mainLane,
+    workingLane: pitLane.workingLane ? {
+      ...pitLane.workingLane,
+      start: clonePointLike(pitLane.workingLane.start),
+      end: clonePointLike(pitLane.workingLane.end),
+      points: clonePointArray(pitLane.workingLane.points),
+    } : pitLane.workingLane,
+    fastLane: pitLane.fastLane ? { ...pitLane.fastLane } : pitLane.fastLane,
+    serviceNormal: clonePointLike(pitLane.serviceNormal),
+    boxes: Array.isArray(pitLane.boxes)
+      ? pitLane.boxes.map((box) => ({
+        ...box,
+        laneTarget: clonePointLike(box.laneTarget),
+        center: clonePointLike(box.center),
+        corners: clonePointArray(box.corners),
+      }))
+      : pitLane.boxes,
+    serviceAreas: Array.isArray(pitLane.serviceAreas)
+      ? pitLane.serviceAreas.map((area) => ({
+        ...area,
+        laneTarget: clonePointLike(area.laneTarget),
+        center: clonePointLike(area.center),
+        queuePoint: clonePointLike(area.queuePoint),
+        corners: clonePointArray(area.corners),
+        queueCorners: clonePointArray(area.queueCorners),
+        garageBoxIds: [...(area.garageBoxIds ?? [])],
+        pitCrew: area.pitCrew ? { ...area.pitCrew } : area.pitCrew,
+      }))
+      : pitLane.serviceAreas,
+    teams: Array.isArray(pitLane.teams)
+      ? pitLane.teams.map((team) => ({ ...team, boxIds: [...(team.boxIds ?? [])], pitCrew: team.pitCrew ? { ...team.pitCrew } : team.pitCrew }))
+      : pitLane.teams,
+  };
+}

package/src/simulation/track/pitLaneState.js

@@ -1,5 +1,4 @@
 import { clamp, wrapDistance } from '../simMath.js';
-import { PIT_LANE_WIDTH } from './trackConstants.js';
 import { nearestPointOnPolyline, nearestPointOnPolylineInto, pointInsideBounds, pointIsInsidePolygon } from './trackMath.js';
 import { queryPitBoxCandidates, queryPitRoadSegmentCandidatesByRoute } from './trackQueryIndex.js';
 import { ensureQueryScratch } from './trackQueryScratch.js';

package/src/simulation/track/pitServiceLayout.js

@@ -0,0 +1,121 @@
+import { PIT_BOX_COUNT, PIT_BOX_DEPTH, PIT_BOX_LENGTH, PIT_BOX_PAIR_GAP, PIT_BOX_TO_LANE_GAP, PIT_LANE_WIDTH, PIT_SERVICE_AREA_DEPTH, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_QUEUE_GAP, PIT_TEAM_COUNT, PIT_TEAM_GAP, PIT_BOXES_PER_TEAM, PIT_WORKING_LANE_GAP, PIT_WORKING_LANE_WIDTH } from './trackConstants.js';
+import { interpolatePitPoint, projectPitPoint } from './trackMath.js';
+
+export function getPitBoxRunLength({
+  teamCount = PIT_TEAM_COUNT,
+  boxesPerTeam = PIT_BOXES_PER_TEAM,
+  boxLength = PIT_BOX_LENGTH,
+  pairGap = PIT_BOX_PAIR_GAP,
+  teamGap = PIT_TEAM_GAP,
+} = {}) {
+  const boxCount = teamCount * boxesPerTeam;
+  return (
+    boxCount * boxLength +
+    teamCount * Math.max(0, boxesPerTeam - 1) * pairGap +
+    Math.max(0, teamCount - 1) * teamGap
+  );
+}
+
+export function createPitBoxCorners(center, forward, serviceNormal) {
+  return createPitRectangleCorners(center, forward, serviceNormal, PIT_BOX_LENGTH, PIT_BOX_DEPTH);
+}
+
+export function createPitRectangleCorners(center, forward, serviceNormal, length, depth) {
+  const halfLength = length / 2;
+  const halfDepth = depth / 2;
+  return [
+    {
+      x: center.x + forward.x * halfLength + serviceNormal.x * halfDepth,
+      y: center.y + forward.y * halfLength + serviceNormal.y * halfDepth,
+    },
+    {
+      x: center.x - forward.x * halfLength + serviceNormal.x * halfDepth,
+      y: center.y - forward.y * halfLength + serviceNormal.y * halfDepth,
+    },
+    {
+      x: center.x - forward.x * halfLength - serviceNormal.x * halfDepth,
+      y: center.y - forward.y * halfLength - serviceNormal.y * halfDepth,
+    },
+    {
+      x: center.x + forward.x * halfLength - serviceNormal.x * halfDepth,
+      y: center.y + forward.y * halfLength - serviceNormal.y * halfDepth,
+    },
+  ];
+}
+
+export function createPitBoxes({ laneStart, laneForward, laneLength, serviceNormal }) {
+  const runLength = getPitBoxRunLength();
+  let cursor = Math.max(PIT_SERVICE_QUEUE_GAP + PIT_BOX_LENGTH / 2, (laneLength - runLength) / 2);
+  const workingLaneOffset = PIT_LANE_WIDTH / 2 + PIT_WORKING_LANE_GAP + PIT_WORKING_LANE_WIDTH / 2;
+  const boxLateral = workingLaneOffset + PIT_WORKING_LANE_WIDTH / 2 + PIT_BOX_TO_LANE_GAP + PIT_BOX_DEPTH / 2;
+  const boxes = [];
+  const serviceAreas = [];
+
+  for (let index = 0; index < PIT_BOX_COUNT; index += 1) {
+    const distanceAlongLane = cursor + PIT_BOX_LENGTH / 2;
+    const laneTarget = interpolatePitPoint(laneStart, laneForward, distanceAlongLane);
+    const center = {
+      x: laneTarget.x + serviceNormal.x * boxLateral,
+      y: laneTarget.y + serviceNormal.y * boxLateral,
+    };
+    const teamIndex = Math.floor(index / PIT_BOXES_PER_TEAM);
+    const teamBoxIndex = index % PIT_BOXES_PER_TEAM;
+
+    boxes.push({
+      id: `team-${teamIndex + 1}-box-${teamBoxIndex + 1}`,
+      index,
+      teamIndex,
+      teamBoxIndex,
+      distanceAlongLane,
+      laneTarget,
+      center,
+      length: PIT_BOX_LENGTH,
+      depth: PIT_BOX_DEPTH,
+      corners: createPitBoxCorners(center, laneForward, serviceNormal),
+    });
+
+    if (teamBoxIndex === PIT_BOXES_PER_TEAM - 1) {
+      const firstTeamBox = boxes[index - (PIT_BOXES_PER_TEAM - 1)];
+      const serviceDistance = (firstTeamBox.distanceAlongLane + distanceAlongLane) / 2;
+      const queueDistance = Math.max(PIT_SERVICE_QUEUE_GAP / 2, serviceDistance - PIT_SERVICE_QUEUE_GAP);
+      const serviceCenter = projectPitPoint(
+        laneStart,
+        laneForward,
+        serviceNormal,
+        serviceDistance,
+        workingLaneOffset,
+      );
+      const queuePoint = projectPitPoint(
+        laneStart,
+        laneForward,
+        serviceNormal,
+        queueDistance,
+        workingLaneOffset,
+      );
+
+      serviceAreas.push({
+        id: `team-${teamIndex + 1}-service`,
+        index: teamIndex,
+        teamIndex,
+        distanceAlongLane: serviceDistance,
+        queueDistanceAlongLane: queueDistance,
+        laneTarget: serviceCenter,
+        center: serviceCenter,
+        queuePoint,
+        length: PIT_SERVICE_AREA_LENGTH,
+        depth: PIT_SERVICE_AREA_DEPTH,
+        corners: createPitRectangleCorners(serviceCenter, laneForward, serviceNormal, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_AREA_DEPTH),
+        queueCorners: createPitRectangleCorners(queuePoint, laneForward, serviceNormal, PIT_SERVICE_AREA_LENGTH * 0.72, PIT_SERVICE_AREA_DEPTH),
+        garageBoxIds: boxes
+          .slice(index - (PIT_BOXES_PER_TEAM - 1), index + 1)
+          .map((box) => box.id),
+      });
+    }
+
+    cursor += PIT_BOX_LENGTH;
+    if (teamBoxIndex === 0) cursor += PIT_BOX_PAIR_GAP;
+    else if (teamIndex < PIT_TEAM_COUNT - 1) cursor += PIT_TEAM_GAP;
+  }
+
+  return { boxes, serviceAreas, workingLaneOffset };
+}

package/src/simulation/track/proceduralTrack.js

@@ -0,0 +1,77 @@
+import { TRACK } from './trackConstants.js';
+import { buildTrackModel } from './trackBuilder.js';
+import { generateCenterlineControls, generateFallbackCenterlineControls, generateSafeFallbackCenterlineControls, normalizeSeed } from './proceduralCenterline.js';
+import { isValidProceduralTrackModel } from './trackValidation.js';
+import { resolveProceduralTrackOptions } from './trackGenerationOptions.js';
+import { cacheProceduralTrackDefinition, getCachedProceduralTrack } from './trackModelCache.js';
+
+export function createProceduralTrack(seed = Date.now(), options = {}) {
+  const normalizedSeed = normalizeSeed(seed);
+  const generationOptions = resolveProceduralTrackOptions(options);
+  const cacheKey = `${normalizedSeed}:${generationOptions.cacheKey}`;
+  const cached = getCachedProceduralTrack(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, model);
+    }
+  }
+
+  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, fallbackModel);
+}

package/src/simulation/track/spatialQueries.js

@@ -2,7 +2,7 @@ import { clamp, normalizeAngle, wrapDistance } from '../simMath.js';
 import { PIT_LANE_WIDTH } from './trackConstants.js';
 import { pointInsideBounds } from './trackMath.js';
 import { nearestPitLaneState, resolveDirectConnectorPitLaneState } from './pitLaneState.js';
-import { queryNearestTrackProjection, queryNearestTrackProjectionInto } from './trackQueryIndex.js';
+import { queryNearestTrackProjectionInto } from './trackQueryIndex.js';
 import { recordStat } from './trackQueryStats.js';
 
 export function pointAt(track, distanceAlong) {
@@ -108,30 +108,6 @@ function sampleIndexAtDistanceUnwrapped(track, wrapped) {
   return index;
 }
 
-export function nearestSampleInRange(track, position, startIndex, endIndex) {
-  const sampleCount = track.samples.length - 1;
-  let best = null;
-  let bestDistance = Infinity;
-
-  for (let index = startIndex; index <= endIndex; index += 1) {
-    const wrappedIndex = ((index % sampleCount) + sampleCount) % sampleCount;
-    const sample = track.samples[wrappedIndex];
-    const dx = position.x - sample.x;
-    const dy = position.y - sample.y;
-    const squared = dx * dx + dy * dy;
-    if (squared < bestDistance) {
-      bestDistance = squared;
-      best = sample;
-    }
-  }
-
-  return { best, bestDistance };
-}
-
-export function nearestSampleGlobal(track, position) {
-  return nearestSampleInRange(track, position, 0, track.samples.length - 2);
-}
-
 export function createTrackState(track, position, best) {
   return writeTrackState({}, track, position, best);
 }

package/src/simulation/track/trackBuilder.js

@@ -0,0 +1,54 @@
+import { CENTERLINE_CONTROLS, TRACK } from './trackConstants.js';
+import { distance } from './trackMath.js';
+import { rawCenterPoint } from './centerlineSpline.js';
+import { recalculateSampleGeometry } from './sampleGeometry.js';
+import { rotateSamplesToStandingStart, straightenStandingStartSamples } from './startStraight.js';
+import { prepareSampleIndexLut } from './spatialQueries.js';
+import { createTrackSectors } from './trackSectors.js';
+import { deriveDrsZones, normalizeDrsZone } from './drsZones.js';
+import { createPitLaneModel } from './pitLaneLayout.js';
+import { attachTrackQueryIndex, createTrackQueryIndex } from './trackQueryConstruction.js';
+import { attachTrackSnapshotJsonSerializer } from './trackSnapshotJson.js';
+import { cacheTrackModel, getCachedTrackModel } from './trackModelCache.js';
+
+export function buildTrackModel(track = TRACK) {
+  const cached = getCachedTrackModel(track);
+  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));
+  prepareSampleIndexLut(model);
+  attachTrackSnapshotJsonSerializer(model);
+  cacheTrackModel(track, model);
+  return model;
+}

package/src/simulation/track/trackConstants.js

@@ -34,7 +34,6 @@ export const START_STRAIGHT_GRID_LENGTH = metersToSimUnits(496);
 export const START_STRAIGHT_EXIT_LENGTH = metersToSimUnits(500);
 export const START_STRAIGHT_LOCK_EXTRA = metersToSimUnits(43);
 export const START_STRAIGHT_BLEND_LENGTH = metersToSimUnits(320);
-export const NEAREST_HINT_WINDOW_SAMPLES = 240;
 export const PIT_LANE_WIDTH = metersToSimUnits(12);
 export const PIT_LANE_EDGE_GAP = metersToSimUnits(16);
 export const PIT_ACCESS_MIN_LENGTH = metersToSimUnits(70);
@@ -66,27 +65,6 @@ export const PIT_LANE_FINISH_RATIO = 0.64;
 export const PIT_WORLD_PADDING = metersToSimUnits(24);
 export const PIT_TRACK_CLEARANCE_MARGIN = metersToSimUnits(5);
 export const PIT_LANE_OFFSET_SEARCH_STEP = metersToSimUnits(12);
-export const PROCEDURAL_TRACK_TEMPLATES = [
-  [
-    [0.08, 0.55], [0.10, 0.80], [0.22, 0.89], [0.42, 0.84], [0.52, 0.93],
-    [0.60, 0.75], [0.74, 0.88], [0.91, 0.76], [0.94, 0.54], [0.82, 0.46],
-    [0.94, 0.28], [0.78, 0.18], [0.62, 0.31], [0.54, 0.13], [0.43, 0.30],
-    [0.33, 0.17], [0.20, 0.24], [0.12, 0.38], [0.22, 0.48], [0.13, 0.50],
-  ],
-  [
-    [0.07, 0.46], [0.14, 0.72], [0.25, 0.83], [0.39, 0.73], [0.47, 0.88],
-    [0.56, 0.70], [0.67, 0.82], [0.88, 0.84], [0.95, 0.63], [0.83, 0.56],
-    [0.92, 0.43], [0.79, 0.35], [0.88, 0.20], [0.68, 0.15], [0.58, 0.29],
-    [0.47, 0.18], [0.34, 0.30], [0.21, 0.19], [0.10, 0.28], [0.17, 0.39],
-  ],
-  [
-    [0.06, 0.61], [0.13, 0.86], [0.31, 0.91], [0.43, 0.79], [0.57, 0.87],
-    [0.71, 0.70], [0.92, 0.72], [0.95, 0.50], [0.84, 0.43], [0.91, 0.32],
-    [0.74, 0.24], [0.69, 0.11], [0.54, 0.18], [0.45, 0.08], [0.35, 0.22],
-    [0.23, 0.17], [0.11, 0.31], [0.24, 0.43], [0.15, 0.52], [0.28, 0.60],
-  ],
-];
-
 export const CENTERLINE_CONTROLS = [
   { x: WORLD.width * 0.05, y: WORLD.height * 0.56 },
   { x: WORLD.width * 0.10, y: WORLD.height * 0.81 },

package/src/simulation/track/trackMath.js

@@ -161,35 +161,6 @@ export function pointInsideBounds(point, bounds) {
   );
 }
 
-export function projectPointToSegment(position, start, end) {
-  const dx = end.x - start.x;
-  const dy = end.y - start.y;
-  const lengthSquared = dx * dx + dy * dy;
-  const amount = lengthSquared > 0
-    ? clamp(((position.x - start.x) * dx + (position.y - start.y) * dy) / lengthSquared, 0, 1)
-    : 0;
-  const projected = {
-    x: start.x + dx * amount,
-    y: start.y + dy * amount,
-  };
-  const length = Math.sqrt(lengthSquared);
-  const heading = Math.atan2(dy, dx);
-  const normalX = length > 0 ? -dy / length : 0;
-  const normalY = length > 0 ? dx / length : 1;
-  const signedOffset = (position.x - projected.x) * normalX + (position.y - projected.y) * normalY;
-
-  return {
-    point: projected,
-    amount,
-    length,
-    heading,
-    normalX,
-    normalY,
-    signedOffset,
-    crossTrackError: Math.abs(signedOffset),
-  };
-}
-
 export function nearestPointOnPolyline(points, position, segmentIndices = null) {
   return nearestPointOnPolylineInto({}, points, position, { segmentIndices });
 }
@@ -306,3 +277,7 @@ export function pointIsInsidePolygon(point, polygon) {
 
   return inside;
 }
+
+export function finitePoint(point) {
+  return Number.isFinite(point?.x) && Number.isFinite(point?.y);
+}