@inventure71/paddockjs 1.0.0 → 2.0.0

package/src/simulation/track/trackGenerationOptions.js

@@ -0,0 +1,283 @@
+import {
+  GENERATED_FALLBACK_ATTEMPTS,
+  GENERATED_TRACK_ATTEMPTS,
+  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,
+  START_STRAIGHT_BLEND_LENGTH,
+  START_STRAIGHT_EXIT_LENGTH,
+  START_STRAIGHT_GRID_LENGTH,
+  START_STRAIGHT_LOCK_EXTRA,
+} from './trackConstants.js';
+import { metersToSimUnits, simUnitsToMeters } from '../units.js';
+
+export const PROCEDURAL_TRACK_PROFILES = {
+  race: {},
+  'training-short': {
+    length: { minMeters: 900, maxMeters: 1800 },
+    startStraight: { gridMeters: 0, exitMeters: 80, blendMeters: 80, lockExtraMeters: 0 },
+    pitLane: { enabled: false },
+    shape: { scale: 0.2, cornerDensity: 1.3, variation: 0.22 },
+    validation: {
+      minClearanceMultiplier: 1,
+      minNonAdjacentArcMeters: 160,
+      maxLocalTurnRadians: 1.85,
+    },
+    attempts: { primary: 80, fallback: 200 },
+  },
+  'training-medium': {
+    length: { minMeters: 1600, maxMeters: 3000 },
+    startStraight: { gridMeters: 80, exitMeters: 140, blendMeters: 120, lockExtraMeters: 0 },
+    pitLane: { enabled: false },
+    shape: { scale: 0.38, cornerDensity: 1.18, variation: 0.24 },
+    validation: {
+      minClearanceMultiplier: 1.15,
+      minNonAdjacentArcMeters: 260,
+      maxLocalTurnRadians: 1.7,
+    },
+    attempts: { primary: 80, fallback: 200 },
+  },
+  'training-technical': {
+    length: { minMeters: 800, maxMeters: 1700 },
+    startStraight: { gridMeters: 0, exitMeters: 60, blendMeters: 70, lockExtraMeters: 0 },
+    pitLane: { enabled: false },
+    shape: { scale: 0.18, cornerDensity: 1.55, variation: 0.2 },
+    validation: {
+      minClearanceMultiplier: 0.9,
+      minNonAdjacentArcMeters: 140,
+      maxLocalTurnRadians: 2.05,
+    },
+    attempts: { primary: 100, fallback: 240 },
+  },
+};
+
+const RACE_DEFAULTS = {
+  profile: 'race',
+  length: {
+    min: GENERATED_TRACK_MIN_LENGTH,
+    max: GENERATED_TRACK_MAX_LENGTH,
+  },
+  startStraight: {
+    grid: START_STRAIGHT_GRID_LENGTH,
+    exit: START_STRAIGHT_EXIT_LENGTH,
+    blend: START_STRAIGHT_BLEND_LENGTH,
+    lockExtra: START_STRAIGHT_LOCK_EXTRA,
+  },
+  pitLane: {
+    enabled: true,
+  },
+  shape: {
+    scale: 1,
+    cornerDensity: 1,
+    variation: MIN_TRACK_SHAPE_VARIATION,
+  },
+  validation: {
+    minClearanceMultiplier: MIN_TRACK_CLEARANCE_MULTIPLIER,
+    minShapeVariation: MIN_TRACK_SHAPE_VARIATION,
+    minNonAdjacentArcDistance: MIN_NON_ADJACENT_ARC_DISTANCE,
+    maxLocalTurnRadians: MAX_LOCAL_TURN_RADIANS,
+    maxSampleHeadingDeltaRadians: MAX_SAMPLE_HEADING_DELTA_RADIANS,
+  },
+  attempts: {
+    primary: GENERATED_FALLBACK_ATTEMPTS,
+    fallback: GENERATED_TRACK_ATTEMPTS,
+  },
+};
+
+export function resolveProceduralTrackOptions(options = {}) {
+  const requestedProfile = options.profile ?? 'race';
+  if (!Object.hasOwn(PROCEDURAL_TRACK_PROFILES, requestedProfile)) {
+    throw new Error(`Unsupported procedural track profile: ${requestedProfile}`);
+  }
+
+  const expanded = expandLegacyTrackOptions(options);
+  const profile = expandLegacyTrackOptions(PROCEDURAL_TRACK_PROFILES[requestedProfile]);
+  const merged = deepMerge(deepMerge({ profile: requestedProfile }, profile), expanded);
+
+  const resolved = {
+    profile: requestedProfile,
+    length: {
+      min: positiveMetersToSimUnits(merged.length?.minMeters, RACE_DEFAULTS.length.min, 'length.minMeters'),
+      max: positiveMetersToSimUnits(merged.length?.maxMeters, RACE_DEFAULTS.length.max, 'length.maxMeters'),
+    },
+    startStraight: {
+      grid: nonNegativeMetersToSimUnits(merged.startStraight?.gridMeters, RACE_DEFAULTS.startStraight.grid, 'startStraight.gridMeters'),
+      exit: nonNegativeMetersToSimUnits(merged.startStraight?.exitMeters, RACE_DEFAULTS.startStraight.exit, 'startStraight.exitMeters'),
+      blend: nonNegativeMetersToSimUnits(merged.startStraight?.blendMeters, RACE_DEFAULTS.startStraight.blend, 'startStraight.blendMeters'),
+      lockExtra: nonNegativeMetersToSimUnits(merged.startStraight?.lockExtraMeters, RACE_DEFAULTS.startStraight.lockExtra, 'startStraight.lockExtraMeters'),
+    },
+    pitLane: {
+      enabled: merged.pitLane?.enabled !== false,
+    },
+    shape: {
+      scale: positiveNumber(merged.shape?.scale, RACE_DEFAULTS.shape.scale, 'shape.scale'),
+      cornerDensity: positiveNumber(merged.shape?.cornerDensity, RACE_DEFAULTS.shape.cornerDensity, 'shape.cornerDensity'),
+      variation: nonNegativeNumber(merged.shape?.variation, RACE_DEFAULTS.shape.variation, 'shape.variation'),
+    },
+    validation: {
+      minClearanceMultiplier: nonNegativeNumber(
+        merged.validation?.minClearanceMultiplier,
+        RACE_DEFAULTS.validation.minClearanceMultiplier,
+        'validation.minClearanceMultiplier',
+      ),
+      minShapeVariation: nonNegativeNumber(
+        merged.validation?.minShapeVariation ?? merged.shape?.variation,
+        RACE_DEFAULTS.validation.minShapeVariation,
+        'validation.minShapeVariation',
+      ),
+      minNonAdjacentArcDistance: nonNegativeMetersToSimUnits(
+        merged.validation?.minNonAdjacentArcMeters,
+        RACE_DEFAULTS.validation.minNonAdjacentArcDistance,
+        'validation.minNonAdjacentArcMeters',
+      ),
+      maxLocalTurnRadians: positiveNumber(
+        merged.validation?.maxLocalTurnRadians,
+        RACE_DEFAULTS.validation.maxLocalTurnRadians,
+        'validation.maxLocalTurnRadians',
+      ),
+      maxSampleHeadingDeltaRadians: positiveNumber(
+        merged.validation?.maxSampleHeadingDeltaRadians,
+        RACE_DEFAULTS.validation.maxSampleHeadingDeltaRadians,
+        'validation.maxSampleHeadingDeltaRadians',
+      ),
+    },
+    attempts: {
+      primary: positiveInteger(merged.attempts?.primary, RACE_DEFAULTS.attempts.primary, 'attempts.primary'),
+      fallback: positiveInteger(merged.attempts?.fallback, RACE_DEFAULTS.attempts.fallback, 'attempts.fallback'),
+    },
+  };
+
+  if (resolved.length.min > resolved.length.max) {
+    throw new Error('Procedural track length.minMeters must be less than or equal to length.maxMeters.');
+  }
+  resolved.cacheKey = stableTrackGenerationCacheKey(resolved);
+  return resolved;
+}
+
+export function stableTrackGenerationCacheKey(options) {
+  return JSON.stringify({
+    profile: options.profile,
+    length: {
+      minMeters: roundMeters(options.length.min),
+      maxMeters: roundMeters(options.length.max),
+    },
+    startStraight: {
+      gridMeters: roundMeters(options.startStraight.grid),
+      exitMeters: roundMeters(options.startStraight.exit),
+      blendMeters: roundMeters(options.startStraight.blend),
+      lockExtraMeters: roundMeters(options.startStraight.lockExtra),
+    },
+    pitLane: { enabled: options.pitLane.enabled },
+    shape: {
+      scale: roundNumber(options.shape.scale),
+      cornerDensity: roundNumber(options.shape.cornerDensity),
+      variation: roundNumber(options.shape.variation),
+    },
+    validation: {
+      minClearanceMultiplier: roundNumber(options.validation.minClearanceMultiplier),
+      minShapeVariation: roundNumber(options.validation.minShapeVariation),
+      minNonAdjacentArcMeters: roundMeters(options.validation.minNonAdjacentArcDistance),
+      maxLocalTurnRadians: roundNumber(options.validation.maxLocalTurnRadians),
+      maxSampleHeadingDeltaRadians: roundNumber(options.validation.maxSampleHeadingDeltaRadians),
+    },
+    attempts: options.attempts,
+  });
+}
+
+function expandLegacyTrackOptions(options = {}) {
+  const next = { ...options };
+  if (options.minLengthMeters != null || options.maxLengthMeters != null) {
+    next.length = {
+      ...(options.length ?? {}),
+      ...(options.minLengthMeters != null ? { minMeters: options.minLengthMeters } : {}),
+      ...(options.maxLengthMeters != null ? { maxMeters: options.maxLengthMeters } : {}),
+    };
+  }
+  if (options.startStraightMeters != null) {
+    next.startStraight = {
+      ...(options.startStraight ?? {}),
+      gridMeters: options.startStraightMeters,
+      exitMeters: options.startStraightMeters,
+    };
+  }
+  if (options.includePitLane != null) {
+    next.pitLane = {
+      ...(options.pitLane ?? {}),
+      enabled: Boolean(options.includePitLane),
+    };
+  }
+  return next;
+}
+
+function deepMerge(base, override) {
+  const result = { ...base };
+  Object.entries(override ?? {}).forEach(([key, value]) => {
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], value);
+      return;
+    }
+    if (value !== undefined) result[key] = value;
+  });
+  return result;
+}
+
+function isPlainObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function positiveMetersToSimUnits(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new Error(`Procedural track ${label} must be a positive number.`);
+  }
+  return metersToSimUnits(number);
+}
+
+function nonNegativeMetersToSimUnits(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) {
+    throw new Error(`Procedural track ${label} must be a non-negative number.`);
+  }
+  return metersToSimUnits(number);
+}
+
+function positiveNumber(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new Error(`Procedural track ${label} must be a positive number.`);
+  }
+  return number;
+}
+
+function nonNegativeNumber(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) {
+    throw new Error(`Procedural track ${label} must be a non-negative number.`);
+  }
+  return number;
+}
+
+function positiveInteger(value, fallback, label) {
+  if (value == null) return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new Error(`Procedural track ${label} must be a positive integer.`);
+  }
+  return number;
+}
+
+function roundMeters(value) {
+  return roundNumber(simUnitsToMeters(value));
+}
+
+function roundNumber(value) {
+  return Math.round(value * 1e6) / 1e6;
+}

package/src/simulation/track/trackMath.js

@@ -0,0 +1,241 @@
+import { clamp } from '../simMath.js';
+import { WORLD, PIT_WORLD_PADDING } from './trackConstants.js';
+
+export function distance(a, b) {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+export function orientation(a, b, c) {
+  return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+}
+
+export function segmentBoxesOverlap(a, b, c, d) {
+  return (
+    Math.max(Math.min(a.x, b.x), Math.min(c.x, d.x)) <= Math.min(Math.max(a.x, b.x), Math.max(c.x, d.x)) &&
+    Math.max(Math.min(a.y, b.y), Math.min(c.y, d.y)) <= Math.min(Math.max(a.y, b.y), Math.max(c.y, d.y))
+  );
+}
+
+export function segmentsIntersect(a, b, c, d) {
+  if (!segmentBoxesOverlap(a, b, c, d)) return false;
+  const abC = orientation(a, b, c);
+  const abD = orientation(a, b, d);
+  const cdA = orientation(c, d, a);
+  const cdB = orientation(c, d, b);
+  return abC * abD < 0 && cdA * cdB < 0;
+}
+
+export function distanceForwardAlongTrack(from, to, totalLength) {
+  return to >= from ? to - from : totalLength - from + to;
+}
+
+export function smoothstep(value) {
+  const amount = clamp(value, 0, 1);
+  return amount * amount * (3 - 2 * amount);
+}
+
+export function blendPoint(original, target, amount) {
+  return {
+    ...original,
+    x: original.x + (target.x - original.x) * amount,
+    y: original.y + (target.y - original.y) * amount,
+  };
+}
+
+export function clonePoint(point) {
+  return {
+    x: point.x,
+    y: point.y,
+    heading: point.heading,
+    distance: point.distance,
+  };
+}
+
+export function normalizeVector(vector) {
+  const length = Math.hypot(vector.x, vector.y) || 1;
+  return {
+    x: vector.x / length,
+    y: vector.y / length,
+    length,
+  };
+}
+
+export function headingVector(heading) {
+  return {
+    x: Math.cos(heading),
+    y: Math.sin(heading),
+  };
+}
+
+export function dotVectors(first, second) {
+  return first.x * second.x + first.y * second.y;
+}
+
+export function angleBetweenVectors(first, second) {
+  const firstUnit = normalizeVector(first);
+  const secondUnit = normalizeVector(second);
+  return Math.acos(clamp(dotVectors(firstUnit, secondUnit), -1, 1));
+}
+
+export function signedLateralOffsetToPoint(trackPoint, point) {
+  return (point.x - trackPoint.x) * trackPoint.normalX + (point.y - trackPoint.y) * trackPoint.normalY;
+}
+
+export function interpolatePitPoint(start, forward, distanceAlong) {
+  return {
+    x: start.x + forward.x * distanceAlong,
+    y: start.y + forward.y * distanceAlong,
+  };
+}
+
+export function projectPitPoint(startPoint, forward, normal, distanceAlong, lateralOffset) {
+  return {
+    x: startPoint.x + forward.x * distanceAlong + normal.x * lateralOffset,
+    y: startPoint.y + forward.y * distanceAlong + normal.y * lateralOffset,
+  };
+}
+
+export function pointWorldClearance(point) {
+  return Math.min(
+    point.x - PIT_WORLD_PADDING,
+    WORLD.width - PIT_WORLD_PADDING - point.x,
+    point.y - PIT_WORLD_PADDING,
+    WORLD.height - PIT_WORLD_PADDING - point.y,
+  );
+}
+
+export function sampleCubicBezier(p0, p1, p2, p3, steps) {
+  return Array.from({ length: steps + 1 }, (_, index) => {
+    const t = index / steps;
+    const mt = 1 - t;
+    const mt2 = mt * mt;
+    const t2 = t * t;
+    return {
+      x: mt2 * mt * p0.x + 3 * mt2 * t * p1.x + 3 * mt * t2 * p2.x + t2 * t * p3.x,
+      y: mt2 * mt * p0.y + 3 * mt2 * t * p1.y + 3 * mt * t2 * p2.y + t2 * t * p3.y,
+    };
+  });
+}
+
+export function expandBounds(bounds, point) {
+  if (!point) return bounds;
+  return {
+    minX: Math.min(bounds.minX, point.x),
+    maxX: Math.max(bounds.maxX, point.x),
+    minY: Math.min(bounds.minY, point.y),
+    maxY: Math.max(bounds.maxY, point.y),
+  };
+}
+
+export function createPointBounds(points, padding = 0) {
+  const bounds = points.filter(Boolean).reduce(
+    (current, point) => expandBounds(current, point),
+    { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity },
+  );
+  if (!Number.isFinite(bounds.minX)) return null;
+  return {
+    minX: bounds.minX - padding,
+    maxX: bounds.maxX + padding,
+    minY: bounds.minY - padding,
+    maxY: bounds.maxY + padding,
+  };
+}
+
+export function pointInsideBounds(point, bounds) {
+  if (!bounds) return true;
+  return (
+    point.x >= bounds.minX &&
+    point.x <= bounds.maxX &&
+    point.y >= bounds.minY &&
+    point.y <= bounds.maxY
+  );
+}
+
+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) {
+  if (!Array.isArray(points) || points.length < 2) return null;
+  const restrictedSegments = Array.isArray(segmentIndices) && segmentIndices.length > 0
+    ? [...new Set(segmentIndices)].filter((index) => Number.isInteger(index) && index >= 0 && index < points.length - 1)
+    : null;
+  const cumulativeDistances = restrictedSegments ? createPolylineCumulativeDistances(points) : null;
+  let best = null;
+  let distanceBefore = 0;
+  let totalLength = 0;
+
+  const segmentCount = restrictedSegments?.length ?? (points.length - 1);
+  for (let segmentOffset = 0; segmentOffset < segmentCount; segmentOffset += 1) {
+    const index = restrictedSegments ? restrictedSegments[segmentOffset] : segmentOffset;
+    const current = points[index];
+    const next = points[index + 1];
+    const projection = projectPointToSegment(position, current, next);
+    if (!best || projection.crossTrackError < best.crossTrackError) {
+      best = {
+        ...projection,
+        segmentIndex: index,
+        distanceAlong: (restrictedSegments ? cumulativeDistances[index] : distanceBefore) + projection.length * projection.amount,
+      };
+    }
+    if (!restrictedSegments) distanceBefore += projection.length;
+    totalLength += projection.length;
+  }
+
+  if (!best) return null;
+  return {
+    ...best,
+    totalLength: restrictedSegments
+      ? cumulativeDistances[cumulativeDistances.length - 1]
+      : totalLength,
+  };
+}
+
+function createPolylineCumulativeDistances(points) {
+  const distances = new Array(points.length).fill(0);
+  for (let index = 1; index < points.length; index += 1) {
+    distances[index] = distances[index - 1] + distance(points[index - 1], points[index]);
+  }
+  return distances;
+}
+
+export function pointIsInsidePolygon(point, polygon) {
+  if (!Array.isArray(polygon) || polygon.length < 3) return false;
+  let inside = false;
+
+  for (let currentIndex = 0, previousIndex = polygon.length - 1; currentIndex < polygon.length; previousIndex = currentIndex, currentIndex += 1) {
+    const current = polygon[currentIndex];
+    const previous = polygon[previousIndex];
+    const crossesY = (current.y > point.y) !== (previous.y > point.y);
+    if (!crossesY) continue;
+    const xAtY = ((previous.x - current.x) * (point.y - current.y)) / (previous.y - current.y) + current.x;
+    if (point.x < xAtY) inside = !inside;
+  }
+
+  return inside;
+}