@inventure71/paddockjs 0.2.0 → 1.0.0

package/src/simulation/rules/collisionSteward.js

@@ -0,0 +1,69 @@
+import { simSpeedToKph } from '../units.js';
+
+export function calculateCollisionPenalties({ first, second, collision = null, rule }) {
+  if (!rule) return [];
+  const severity = collision?.depth ?? 0;
+  const severityThreshold = (rule.minimumSeverity ?? 0) + (rule.relaxedSeverityMargin ?? 0) * (1 - rule.strictness);
+  const impactSpeed = collision?.impactSpeed ?? 0;
+  const impactSpeedThreshold = (rule.minimumImpactSpeed ?? 0) + (rule.relaxedImpactSpeed ?? 0) * (1 - rule.strictness);
+  const atFaultDriverId = collision?.atFaultDriverId ?? null;
+  const aheadDriverId = collision?.aheadDriverId ?? null;
+  const sharedFaultDriverIds = Array.isArray(collision?.sharedFaultDriverIds)
+    ? collision.sharedFaultDriverIds
+    : [];
+
+  if (severity < severityThreshold) return [];
+  if (impactSpeed < impactSpeedThreshold) return [];
+
+  if (sharedFaultDriverIds.length > 0) {
+    return sharedFaultDriverIds
+      .map((driverId) => {
+        const car = first.id === driverId ? first : second.id === driverId ? second : null;
+        if (!car) return null;
+        const other = first.id === driverId ? second : first;
+        return buildCollisionPenalty(car, other, rule, {
+          severity,
+          severityThreshold,
+          impactSpeed,
+          impactSpeedThreshold,
+          aheadDriverId: null,
+          atFaultDriverId: driverId,
+          sharedFault: true,
+          reason: 'Unclear collision responsibility',
+        });
+      })
+      .filter(Boolean);
+  }
+
+  if (!atFaultDriverId || !aheadDriverId) return [];
+
+  const atFault = first.id === atFaultDriverId ? first : second;
+  const other = first.id === atFaultDriverId ? second : first;
+  return [buildCollisionPenalty(atFault, other, rule, {
+    severity,
+    severityThreshold,
+    impactSpeed,
+    impactSpeedThreshold,
+    aheadDriverId,
+    atFaultDriverId,
+  })];
+}
+
+function buildCollisionPenalty(car, other, rule, context) {
+  return {
+    type: 'collision',
+    driverId: car.id,
+    otherCarId: other.id,
+    aheadDriverId: context.aheadDriverId,
+    atFaultDriverId: context.atFaultDriverId,
+    strictness: rule.strictness,
+    penaltySeconds: rule.timePenaltySeconds,
+    consequences: rule.consequences,
+    severity: context.severity,
+    threshold: context.severityThreshold,
+    impactSpeedKph: simSpeedToKph(context.impactSpeed),
+    impactSpeedThresholdKph: simSpeedToKph(context.impactSpeedThreshold),
+    sharedFault: Boolean(context.sharedFault),
+    reason: context.reason ?? 'Avoidable contact with car ahead',
+  };
+}

package/src/simulation/rules/penaltyLedger.js

@@ -0,0 +1,153 @@
+const DEFAULT_SERVICE_CONVERSION_SECONDS = {
+  driveThrough: 20,
+  stopGo: 30,
+};
+
+export function createPenaltyRecord({ sequence, time, lap, penalty }) {
+  const consequences = normalizePenaltyConsequences(penalty.consequences, penalty.penaltySeconds);
+  const immediatePenaltySeconds = sumTimeConsequences(consequences);
+  const serviceConsequence = consequences.find((consequence) => (
+    consequence.type === 'driveThrough' || consequence.type === 'stopGo'
+  ));
+  const status = penalty.status ?? (serviceConsequence ? 'issued' : 'applied');
+
+  return {
+    id: `penalty-${sequence}`,
+    at: time,
+    lap,
+    ...penalty,
+    status,
+    consequences,
+    penaltySeconds: Number.isFinite(Number(penalty.penaltySeconds))
+      ? Number(penalty.penaltySeconds)
+      : immediatePenaltySeconds,
+    pendingPenaltySeconds: serviceConsequence
+      ? serviceConversionSeconds(serviceConsequence)
+      : 0,
+    serviceType: serviceConsequence?.type ?? null,
+    serviceRequired: Boolean(serviceConsequence),
+    serviceServedAt: null,
+    unserved: false,
+    positionDrop: sumPositionDropConsequences(consequences),
+    gridDrop: sumGridDropConsequences(consequences),
+    disqualified: consequences.some((consequence) => consequence.type === 'disqualification'),
+  };
+}
+
+export function createPenaltyEvent(entry) {
+  return {
+    type: 'penalty',
+    at: entry.at,
+    penaltyId: entry.id,
+    penaltyType: entry.type,
+    driverId: entry.driverId,
+    penaltySeconds: entry.penaltySeconds,
+    status: entry.status,
+    strictness: entry.strictness,
+  };
+}
+
+export function serializePenalty(penalty) {
+  return { ...penalty };
+}
+
+export function servePenaltyRecord(penalty, time) {
+  if (!penalty || penalty.status === 'cancelled') return penalty;
+  if (!penalty.serviceRequired) return penalty;
+  penalty.status = 'served';
+  penalty.serviceServedAt = time;
+  penalty.unserved = false;
+  return penalty;
+}
+
+export function getPitServicePenaltySeconds(penalty) {
+  if (!penalty || penalty.status === 'cancelled' || penalty.status === 'served') return 0;
+  if (penalty.serviceRequired && penalty.status === 'issued') {
+    if (penalty.serviceType === 'stopGo') return sumStopGoServiceSeconds(penalty.consequences);
+    if (penalty.serviceType === 'driveThrough') return 0;
+  }
+  if (!penalty.serviceRequired && penalty.status === 'applied') {
+    return sumTimeConsequences(penalty.consequences);
+  }
+  return 0;
+}
+
+export function isPenaltyPitServiceable(penalty) {
+  if (!penalty || penalty.status === 'cancelled' || penalty.status === 'served') return false;
+  if (penalty.serviceRequired && penalty.status === 'issued') return true;
+  return !penalty.serviceRequired &&
+    penalty.status === 'applied' &&
+    getPitServicePenaltySeconds(penalty) > 0;
+}
+
+export function servePitPenaltyRecord(penalty, time) {
+  if (!isPenaltyPitServiceable(penalty)) return penalty;
+  penalty.status = 'served';
+  penalty.serviceServedAt = time;
+  penalty.unserved = false;
+  penalty.penaltySeconds = 0;
+  penalty.pendingPenaltySeconds = 0;
+  return penalty;
+}
+
+export function cancelPenaltyRecord(penalty, time) {
+  if (!penalty) return penalty;
+  penalty.status = 'cancelled';
+  penalty.cancelledAt = time;
+  penalty.penaltySeconds = 0;
+  penalty.pendingPenaltySeconds = 0;
+  penalty.positionDrop = 0;
+  penalty.gridDrop = 0;
+  penalty.disqualified = false;
+  penalty.unserved = false;
+  return penalty;
+}
+
+export function applyUnservedServicePenalty(penalty, time) {
+  if (!penalty || penalty.status !== 'issued' || !penalty.serviceRequired) return penalty;
+  penalty.status = 'applied';
+  penalty.appliedAt = time;
+  penalty.unserved = true;
+  penalty.penaltySeconds += penalty.pendingPenaltySeconds;
+  return penalty;
+}
+
+export function isPenaltyActive(penalty) {
+  return penalty?.status !== 'cancelled';
+}
+
+function normalizePenaltyConsequences(consequences, fallbackSeconds = 0) {
+  if (Array.isArray(consequences) && consequences.length) return consequences.map((consequence) => ({ ...consequence }));
+  const seconds = Number(fallbackSeconds) || 0;
+  return seconds > 0 ? [{ type: 'time', seconds }] : [];
+}
+
+function sumTimeConsequences(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'time' ? total + (Number(consequence.seconds) || 0) : total
+  ), 0);
+}
+
+function sumStopGoServiceSeconds(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'stopGo' ? total + (Number(consequence.seconds) || 0) : total
+  ), 0);
+}
+
+function sumPositionDropConsequences(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'positionDrop' ? total + Math.max(0, Math.floor(Number(consequence.positions) || 0)) : total
+  ), 0);
+}
+
+function sumGridDropConsequences(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'gridDrop' ? total + Math.max(0, Math.floor(Number(consequence.positions) || 0)) : total
+  ), 0);
+}
+
+function serviceConversionSeconds(consequence) {
+  return Number.isFinite(Number(consequence.conversionSeconds))
+    ? Math.max(0, Number(consequence.conversionSeconds))
+    : DEFAULT_SERVICE_CONVERSION_SECONDS[consequence.type] ?? 0;
+}

package/src/simulation/rules/pitLaneSpeedingSteward.js

@@ -0,0 +1,71 @@
+const SPEED_LIMITED_PIT_PARTS = new Set(['fast-lane', 'working-lane', 'service-box', 'garage-box']);
+
+export function calculatePitLaneSpeedingReview({ car, rule, stewardState }) {
+  const current = stewardState ?? { active: false, violations: 0 };
+  if (!rule) {
+    return {
+      nextState: current,
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const speedKph = Number(car.speedKph);
+  const pitLanePart = car.trackState?.pitLanePart ?? car.pitLanePart;
+  const inLimitedPitLane = Boolean(car.trackState?.inPitLane) && SPEED_LIMITED_PIT_PARTS.has(pitLanePart);
+  const marginKph = (Number(rule.marginKph) || 0) + ((Number(rule.relaxedMarginKph) || 0) * (1 - rule.strictness));
+  const speedLimitKph = Number(rule.speedLimitKph) || 80;
+  const excessKph = speedKph - speedLimitKph;
+  const isViolation = inLimitedPitLane && excessKph > marginKph;
+
+  if (!isViolation) {
+    return {
+      nextState: { ...current, active: false },
+      event: null,
+      penalty: null,
+    };
+  }
+
+  if (current.active) {
+    return {
+      nextState: current,
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const violationCount = current.violations + 1;
+  const nextState = {
+    active: true,
+    violations: violationCount,
+  };
+  const event = {
+    type: 'pit-lane-speeding',
+    carId: car.id,
+    violationCount,
+    speedKph,
+    speedLimitKph,
+    excessKph,
+    pitLanePart,
+    strictness: rule.strictness,
+  };
+
+  return {
+    nextState,
+    event,
+    penalty: {
+      type: 'pit-lane-speeding',
+      driverId: car.id,
+      strictness: rule.strictness,
+      penaltySeconds: rule.timePenaltySeconds,
+      consequences: rule.consequences,
+      violationCount,
+      speedKph,
+      speedLimitKph,
+      excessKph,
+      marginKph,
+      pitLanePart,
+      reason: 'Exceeded pit lane speed limit',
+    },
+  };
+}

package/src/simulation/rules/tireRequirementSteward.js

@@ -0,0 +1,29 @@
+export function calculateTireRequirementPenalty({ car, tireStrategy, rule }) {
+  if (!rule || !tireStrategy?.enabled) return null;
+
+  const requiredDistinctCompounds = tireStrategy.mandatoryDistinctDryCompounds;
+  if (!Number.isFinite(requiredDistinctCompounds) || requiredDistinctCompounds <= 0) return null;
+
+  const usedCompounds = Array.isArray(car.usedTireCompounds) && car.usedTireCompounds.length
+    ? [...new Set(car.usedTireCompounds.filter(Boolean))]
+    : [...new Set([car.tire].filter(Boolean))];
+  const usedDistinctCompounds = usedCompounds.length;
+  const missingCompounds = Math.max(0, requiredDistinctCompounds - usedDistinctCompounds);
+  const toleratedMissingCompounds = Math.floor((1 - rule.strictness) * requiredDistinctCompounds);
+
+  if (missingCompounds <= toleratedMissingCompounds) return null;
+
+  return {
+    type: 'tire-requirement',
+    driverId: car.id,
+    strictness: rule.strictness,
+    penaltySeconds: rule.timePenaltySeconds,
+    consequences: rule.consequences,
+    requiredDistinctCompounds,
+    usedDistinctCompounds,
+    usedCompounds,
+    missingCompounds,
+    toleratedMissingCompounds,
+    reason: 'Mandatory dry compound requirement not met',
+  };
+}

package/src/simulation/rules/trackLimitsSteward.js

@@ -0,0 +1,85 @@
+import { calculateWheelSurfaceState, isWholeCarOutsideTrackLimits } from '../wheelSurface.js';
+import { metersToSimUnits } from '../units.js';
+
+const STEWARD_TRACK_LIMIT_EPSILON = metersToSimUnits(0.2);
+
+export function calculateTrackLimitReview({ car, rule, track, stewardState }) {
+  if (!rule) {
+    return {
+      nextState: stewardState ?? { active: false, violations: 0 },
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const current = stewardState ?? { active: false, violations: 0 };
+  const wheelSurfaceState = car.wheelStates?.length
+    ? {
+        wheels: car.wheelStates,
+        trackLimits: isWholeCarOutsideTrackLimits(car.wheelStates, track),
+      }
+    : calculateWheelSurfaceState({ car, track });
+  const wheelStates = wheelSurfaceState.wheels;
+  if (wheelStates.some((wheelState) => wheelState.inPitLane)) {
+    return {
+      nextState: { ...current, active: false },
+      event: null,
+      penalty: null,
+    };
+  }
+  const relaxedMargin = ((rule.relaxedMargin ?? 0) * (1 - rule.strictness)) + STEWARD_TRACK_LIMIT_EPSILON;
+  const trackLimitState = isWholeCarOutsideTrackLimits(wheelStates, track, relaxedMargin);
+  const outsideBy = trackLimitState.outsideBy;
+  const isViolation = trackLimitState.violating;
+
+  if (!isViolation) {
+    return {
+      nextState: { ...current, active: false },
+      event: null,
+      penalty: null,
+    };
+  }
+
+  if (current.active) {
+    return {
+      nextState: current,
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const violationCount = current.violations + 1;
+  const nextState = {
+    active: true,
+    violations: violationCount,
+  };
+  const event = {
+    type: 'track-limits',
+    carId: car.id,
+    violationCount,
+    warningsBeforePenalty: rule.warningsBeforePenalty,
+    decision: violationCount <= rule.warningsBeforePenalty ? 'warning' : 'penalty',
+    strictness: rule.strictness,
+  };
+
+  if (violationCount <= rule.warningsBeforePenalty) {
+    return { nextState, event, penalty: null };
+  }
+
+  return {
+    nextState,
+    event,
+    penalty: {
+      type: 'track-limits',
+      driverId: car.id,
+      strictness: rule.strictness,
+      penaltySeconds: rule.timePenaltySeconds,
+      consequences: rule.consequences,
+      violationCount,
+      margin: relaxedMargin,
+      outsideBy,
+      wheelOffsets: wheelStates.map((wheelState) => wheelState.signedOffset),
+      reason: 'Exceeded track limits',
+    },
+  };
+}