@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/simulation/driver/racingLinePlan.js

@@ -0,0 +1,166 @@
+import { clamp, TWO_PI } from '../simMath.js';
+import { kphToSimSpeed, metersToSimUnits, simSpeedToKph, simUnitsToMeters } from '../units.js';
+import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { DEFEND_MIN_OFFSET, DEFEND_REAR_GAP, LANE_EDGE_CLEARANCE_TARGET, LANE_OFFSETS, OVERTAKE_COMMIT_FRAMES, OVERTAKE_GAP_AGGRESSION, OVERTAKE_GAP_BASE, OVERTAKE_LATERAL_MIN, OVERTAKE_LATERAL_REWARD, PASS_SIDE_AGGRESSION, PASS_SIDE_BASE, TRAFFIC_GAP_AHEAD, TRAFFIC_REAR_WINDOW, TRAFFIC_SIDE_GAP, TRAFFIC_SIDE_OVERLAP } from './driverControlConstants.js';
+import { findDefensiveThreat, findLaneTrafficAhead, findLaneTrafficBeside, scanNearbyTraffic } from './trafficScan.js';
+
+export function planRacingLine(car, orderIndex, race) {
+  const aggression = car.aggression ?? car.personality?.baseAggression ?? 0.5;
+  const riskTolerance = car.personality?.riskTolerance ?? aggression;
+  const trackLimit = race.track.width / 2 - VEHICLE_LIMITS.carWidth * clamp(1.55 - aggression * 0.28, 1.26, 1.55);
+  const preferred = Math.sin((car.index / Math.max(1, race.cars.length)) * TWO_PI) * metersToSimUnits(1.1);
+  const currentOffset = clamp(car.desiredOffset ?? preferred, -trackLimit, trackLimit);
+  const ahead = race.orderedCars[orderIndex - 1];
+  const traffic = scanNearbyTraffic(car, race);
+  const rearThreat = findDefensiveThreat(traffic);
+  const attackPlan = planAttackCommitment(car, ahead, traffic, trackLimit, aggression, race);
+
+  let bestOffset = currentOffset;
+  let bestScore = -Infinity;
+
+  LANE_OFFSETS.forEach((rawOffset) => {
+    const offset = clamp(rawOffset, -trackLimit, trackLimit);
+    const edgeClearance = trackLimit - Math.abs(offset);
+    let score = 80;
+    score -= Math.abs(offset - preferred) * 0.18;
+    score -= Math.abs(offset - currentOffset) * (0.09 - aggression * 0.025);
+    score -= Math.max(0, LANE_EDGE_CLEARANCE_TARGET - edgeClearance) * (0.92 - aggression * 0.42);
+
+    traffic.forEach((entry) => {
+      const lateral = Math.abs(entry.signedOffset - offset);
+      if (entry.gap > 0 && entry.gap < TRAFFIC_GAP_AHEAD) {
+        const overlapRisk = clamp(TRAFFIC_SIDE_OVERLAP - lateral, 0, TRAFFIC_SIDE_OVERLAP);
+        score -= overlapRisk * (TRAFFIC_GAP_AHEAD - entry.gap) * 0.038 * (1 - riskTolerance * 0.34);
+        if (entry.gap < OVERTAKE_GAP_BASE + aggression * OVERTAKE_GAP_AGGRESSION && lateral > OVERTAKE_LATERAL_MIN - aggression * metersToSimUnits(4)) {
+          score += Math.min(metersToSimUnits(14) + aggression * metersToSimUnits(8.5), lateral - (OVERTAKE_LATERAL_REWARD - aggression * metersToSimUnits(3))) * (0.62 + aggression * 0.82);
+        }
+      } else if (entry.gap <= 0 && entry.gap > -TRAFFIC_SIDE_OVERLAP) {
+        const sideOverlapRisk = clamp(TRAFFIC_SIDE_OVERLAP - lateral, 0, TRAFFIC_SIDE_OVERLAP);
+        score -= sideOverlapRisk * (TRAFFIC_SIDE_OVERLAP + entry.gap) * 0.052 * (1 - riskTolerance * 0.22);
+      }
+    });
+
+    if (ahead && car.gapAhead < TRAFFIC_GAP_AHEAD) {
+      const passSide = attackPlan?.targetOffset ?? clamp(
+        (ahead.trackState.signedOffset * -0.65) + (car.index % 2 === 0 ? -1 : 1) * (PASS_SIDE_BASE + aggression * PASS_SIDE_AGGRESSION),
+        -trackLimit,
+        trackLimit,
+      );
+      const attackPressure = attackPlan?.pressure ?? 0.45;
+      score -= Math.abs(offset - passSide) * (0.12 + aggression * 0.16) * attackPressure;
+      if (attackPlan && Math.sign(offset || passSide) === attackPlan.side && Math.abs(offset - ahead.trackState.signedOffset) > OVERTAKE_LATERAL_MIN) {
+        score += metersToSimUnits(4 + aggression * 5) * attackPressure;
+      }
+    }
+
+    const defenseIntensity = clamp((aggression - 0.5) / 0.3, 0, 1) *
+      clamp((Math.max(riskTolerance, aggression) - 0.42) / 0.4, 0, 1);
+    if (rearThreat && defenseIntensity > 0.04) {
+      const threatSide = Math.sign(rearThreat.signedOffset || currentOffset || (car.index % 2 === 0 ? 1 : -1));
+      const defendOffset = clamp(
+        threatSide * Math.max(Math.abs(rearThreat.signedOffset) + metersToSimUnits(0.8), DEFEND_MIN_OFFSET),
+        -trackLimit,
+        trackLimit,
+      );
+      const closingPressure = clamp((DEFEND_REAR_GAP + rearThreat.gap) / DEFEND_REAR_GAP, 0, 1);
+      score -= Math.abs(offset - defendOffset) * (0.75 + aggression * 0.45) * closingPressure * defenseIntensity;
+      if (Math.sign(offset) === threatSide && Math.abs(offset) >= DEFEND_MIN_OFFSET) {
+        score += metersToSimUnits(10) * (0.42 + aggression * 0.36) * closingPressure * defenseIntensity;
+      }
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestOffset = offset;
+    }
+  });
+
+  const laneChangeRate = metersToSimUnits(0.95 + car.racecraft * 0.32 + aggression * 0.78);
+  car.desiredOffset = currentOffset + clamp(bestOffset - currentOffset, -laneChangeRate, laneChangeRate);
+
+  return {
+    offset: car.desiredOffset,
+    sameLaneAhead: findLaneTrafficAhead(traffic, car.desiredOffset, TRAFFIC_GAP_AHEAD),
+    actualLaneAhead: findLaneTrafficAhead(traffic, car.trackState?.signedOffset ?? car.desiredOffset, TRAFFIC_GAP_AHEAD),
+    sideRisk: findLaneTrafficBeside(traffic, car.desiredOffset),
+    attackCommitted: Boolean(attackPlan),
+  };
+}
+
+export function calculatePlannedTrafficPenalty(entry, plannedPassingOverlap) {
+  return clamp(
+    simUnitsToMeters(TRAFFIC_GAP_AHEAD - entry.gap) * (plannedPassingOverlap ? 0.08 : 0.16),
+    0,
+    plannedPassingOverlap ? 24 : 32,
+  );
+}
+
+export function calculateActualOverlapPenalty(car, entry) {
+  const gapMeters = simUnitsToMeters(entry.gap);
+  const closingKph = Math.max(0, simSpeedToKph(car.speed - (entry.speed ?? car.speed)));
+  const urgent = gapMeters < 12
+    ? (12 - gapMeters) * (2.8 + closingKph * 0.04)
+    : 0;
+
+  return clamp(urgent, 0, 72);
+}
+
+export function planAttackCommitment(car, ahead, traffic, trackLimit, aggression, race) {
+  const existingFrames = Math.max(0, Math.floor(car.attackCommitmentFrames ?? 0));
+  const relativeSpeed = ahead ? car.speed - ahead.speed : 0;
+  const closeEnough = ahead &&
+    car.gapAhead > 0 &&
+    car.gapAhead < OVERTAKE_GAP_BASE + aggression * OVERTAKE_GAP_AGGRESSION + metersToSimUnits(28);
+  const speedPressure = clamp(relativeSpeed / kphToSimSpeed(34), -0.4, 1);
+
+  if (closeEnough && speedPressure > -0.15) {
+    const aheadOffset = ahead.trackState?.signedOffset ?? 0;
+    const currentSide = Math.sign(car.attackSide ?? 0);
+    const blockedCommitment = currentSide &&
+      Math.sign(aheadOffset || currentSide) === currentSide &&
+      Math.abs(aheadOffset - (car.trackState?.signedOffset ?? 0)) < TRAFFIC_SIDE_GAP &&
+      Math.abs(aheadOffset) > trackLimit * 0.55;
+
+    if (!existingFrames || !currentSide || blockedCommitment) {
+      const leftSpace = trackLimit + aheadOffset;
+      const rightSpace = trackLimit - aheadOffset;
+      const preferredSide = leftSpace > rightSpace ? -1 : 1;
+      const freeSide = chooseFreerAttackSide(traffic, preferredSide);
+      car.attackSide = freeSide;
+    }
+    car.attackCommitmentFrames = OVERTAKE_COMMIT_FRAMES;
+  } else if (existingFrames > 0) {
+    car.attackCommitmentFrames = existingFrames - 1;
+  } else {
+    car.attackSide = 0;
+    car.attackCommitmentFrames = 0;
+  }
+
+  const side = Math.sign(car.attackSide ?? 0);
+  if (!side || !ahead) return null;
+
+  const targetOffset = clamp(
+    (ahead.trackState?.signedOffset ?? 0) + side * (PASS_SIDE_BASE + aggression * PASS_SIDE_AGGRESSION + metersToSimUnits(2.4)),
+    -trackLimit,
+    trackLimit,
+  );
+  const pressure = clamp(
+    0.48 +
+      aggression * 0.34 +
+      speedPressure * 0.28 +
+      (car.attackCommitmentFrames ?? 0) / OVERTAKE_COMMIT_FRAMES * 0.22,
+    0.45,
+    1.15,
+  );
+
+  return { side, targetOffset, pressure };
+}
+
+export function chooseFreerAttackSide(traffic, preferredSide) {
+  const sideScore = (side) => traffic.reduce((score, entry) => {
+    if (entry.gap < -TRAFFIC_REAR_WINDOW || entry.gap > TRAFFIC_GAP_AHEAD) return score;
+    const sameSide = Math.sign(entry.signedOffset || side) === side;
+    return score - (sameSide ? 1 : 0) * (1 - clamp(Math.abs(entry.gap) / TRAFFIC_GAP_AHEAD, 0, 1));
+  }, side === preferredSide ? 0.18 : 0);
+  return sideScore(1) >= sideScore(-1) ? 1 : -1;
+}

package/src/simulation/driver/recoveryDynamics.js

@@ -0,0 +1,38 @@
+import { normalizeAngle } from '../simMath.js';
+import { simUnitsToMeters } from '../units.js';
+
+export function analyzeTrackEdgeMotion(car, race) {
+  const state = car.trackState ?? {};
+  const signedOffset = Number(state.signedOffset ?? 0);
+  const side = Math.sign(signedOffset);
+  const heading = Number(car.heading ?? 0);
+  const normalX = Number(state.normalX ?? 0);
+  const normalY = Number(state.normalY ?? 0);
+  const velocity = resolveVelocity(car);
+  const signedLateralVelocity = velocity.x * normalX + velocity.y * normalY;
+  const outwardVelocity = side === 0 ? 0 : signedLateralVelocity * side;
+  const headingDelta = normalizeAngle(heading - Number(state.heading ?? heading));
+  const trackLimit = race?.track?.width != null ? race.track.width / 2 : 0;
+
+  return {
+    side,
+    signedOffset,
+    headingDelta,
+    headingOutward: side !== 0 && Math.sign(headingDelta) === side,
+    outwardSpeedMps: simUnitsToMeters(Math.max(0, outwardVelocity)),
+    inwardSpeedMps: simUnitsToMeters(Math.max(0, -outwardVelocity)),
+    distanceFromRoadMeters: simUnitsToMeters(Math.max(0, Number(state.crossTrackError ?? 0) - trackLimit)),
+  };
+}
+
+function resolveVelocity(car) {
+  if (Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)) {
+    return { x: car.velocityX, y: car.velocityY };
+  }
+  const heading = Number(car.heading ?? 0);
+  const speed = Number(car.speed ?? 0);
+  return {
+    x: Math.cos(heading) * speed,
+    y: Math.sin(heading) * speed,
+  };
+}

package/src/simulation/driver/rejoinControls.js

@@ -0,0 +1,213 @@
+import { clamp } from '../simMath.js';
+import { kphToSimSpeed, simUnitsToMeters } from '../units.js';
+import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
+import { REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_MAX } from './driverControlConstants.js';
+import { angleToPoint } from './driverMath.js';
+import { createDriverInput } from './driverInput.js';
+import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+import { analyzeTrackEdgeMotion } from './recoveryDynamics.js';
+
+export function decideRejoinControls(car, race) {
+  if (race.physicsMode === 'simulator') {
+    return decideSimulatorRejoinControls(car, race);
+  }
+  return decideArcadeRejoinControls(car, race);
+}
+
+export function decideArcadeRejoinControls(car, race) {
+  return decideRejoinControlsForMode(car, race, {
+    simulatorMode: false,
+    inwardOffsetRatio: 0.34,
+    surfaceTargetSpeeds: {
+      track: 88,
+      kerb: 72,
+      gravel: 56,
+      grass: 48,
+      barrier: 34,
+    },
+    lowSpeedRecovery: {
+      barrier: 0.34,
+      default: 0.18,
+    },
+    throttleLimits: {
+      barrier: 0.68,
+      gravel: 0.46,
+      grass: 0.42,
+      default: 0.42,
+    },
+    brakeResponseKph: 30,
+    onTrackBrakeLimit: 0.46,
+    offTrackBrakeLimit: 0.74,
+    steerGain: 1.65,
+    outwardBrakeStartMps: 1.2,
+    outwardBrakeGain: 0.08,
+    misalignmentBrakeGain: 0.06,
+    slideThrottleDamping: 0.36,
+    offTrackForwardTargetScale: 0.42,
+    lowSpeedForwardTargetScale: 0,
+    lowSpeedOffTrackSteerLimit: 0.52,
+    lowSpeedRecoveryThrottle: 0.32,
+    lowSpeedOutwardBrakeStartMps: 1.2,
+    lowSpeedCrawlOutwardToleranceMps: 0,
+    lowSpeedHeadingOutwardThrottleLimit: 1,
+    stabilizeLowSpeedOutward: false,
+    stabilizeRejoinHoldOutsideRoad: false,
+    unsettledScale: () => 1,
+  });
+}
+
+export function decideSimulatorRejoinControls(car, race) {
+  return decideRejoinControlsForMode(car, race, {
+    simulatorMode: true,
+    inwardOffsetRatio: 0.24,
+    surfaceTargetSpeeds: {
+      track: 78,
+      kerb: 58,
+      gravel: 62,
+      grass: 52,
+      barrier: 22,
+    },
+    lowSpeedRecovery: {
+      barrier: 0.42,
+      default: 0.36,
+    },
+    throttleLimits: {
+      barrier: 0.5,
+      gravel: 0.82,
+      grass: 0.76,
+      default: 0.52,
+    },
+    brakeResponseKph: 24,
+    onTrackBrakeLimit: 0.34,
+    offTrackBrakeLimit: 0.24,
+    steerGain: 0.94,
+    outwardBrakeStartMps: 0.45,
+    outwardBrakeGain: 0.12,
+    misalignmentBrakeGain: 0.08,
+    slideThrottleDamping: 0.62,
+    offTrackForwardTargetScale: 0.32,
+    lowSpeedForwardTargetScale: 0.22,
+    lowSpeedOffTrackSteerLimit: 0.68,
+    lowSpeedRecoveryThrottle: 0.68,
+    lowSpeedOutwardBrakeStartMps: 0.24,
+    lowSpeedCrawlOutwardToleranceMps: 0.42,
+    lowSpeedHeadingOutwardThrottleLimit: 0.24,
+    stabilizeLowSpeedOutward: true,
+    stabilizeRejoinHoldOutsideRoad: true,
+    unsettledScale: (entry) => clamp(
+      1 - Math.max(0, (entry.gripUsage ?? 0) - 0.55) * 0.75 - Math.abs(entry.slipAngleRadians ?? 0) * 1.65,
+      0.22,
+      1,
+    ),
+  });
+}
+
+function decideRejoinControlsForMode(car, race, profile) {
+  const simulatorMode = race.physicsMode === 'simulator';
+  const lookahead = clamp(car.speed * (profile.simulatorMode ? 0.58 : 0.72) + REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_BASE, REJOIN_LOOKAHEAD_MAX);
+  const edgeMotion = analyzeTrackEdgeMotion(car, race);
+  const lowSpeedOffTrack = !car.trackState.onTrack && car.speed < kphToSimSpeed(24);
+  const distanceFromRoadMeters = simUnitsToMeters(Math.max(0, car.trackState.crossTrackError - race.track.width / 2));
+  const inRejoinHold = (car.rejoinRecoveryFrames ?? 0) > 0;
+  const recoveringOutsideRoad = distanceFromRoadMeters > 0.25 &&
+    (!car.trackState.onTrack || (profile.stabilizeRejoinHoldOutsideRoad && inRejoinHold));
+  const offTrackTargetScale = lowSpeedOffTrack
+    ? profile.lowSpeedForwardTargetScale
+    : profile.offTrackForwardTargetScale;
+  const targetBase = !car.trackState.onTrack && distanceFromRoadMeters > 2.5
+    ? pointAt(race.track, car.progress + lookahead * offTrackTargetScale)
+    : pointAt(race.track, car.progress + lookahead * 0.78);
+  const signedSide = Math.sign(car.trackState?.signedOffset ?? 0);
+  const rejoinOffset = signedSide !== 0 && (
+    distanceFromRoadMeters > 0.5 ||
+    car.trackState.crossTrackError > race.track.width / 2 - VEHICLE_LIMITS.carWidth * 1.6
+  )
+    ? -signedSide * race.track.width * profile.inwardOffsetRatio
+    : 0;
+  const target = offsetTrackPoint(targetBase, rejoinOffset);
+  const angleError = angleToPoint(car, target);
+  const surfaceTargetSpeedKph = car.trackState.surface === 'track'
+    ? profile.surfaceTargetSpeeds.track
+    : car.trackState.surface === 'kerb'
+      ? profile.surfaceTargetSpeeds.kerb
+      : car.trackState.surface === 'gravel'
+        ? profile.surfaceTargetSpeeds.gravel
+        : car.trackState.surface === 'grass'
+          ? profile.surfaceTargetSpeeds.grass
+          : profile.surfaceTargetSpeeds.barrier;
+  const alignment = clamp(1 - Math.abs(angleError) / Math.PI, 0.22, 1);
+  const desiredSpeed = kphToSimSpeed(clamp(
+    surfaceTargetSpeedKph * (0.62 + alignment * 0.38) - distanceFromRoadMeters * 0.065,
+    car.trackState.surface === 'barrier' ? 12 : 24,
+    surfaceTargetSpeedKph,
+  ));
+  const speedError = desiredSpeed - car.speed;
+  const lowSpeedRecovery = car.speed < kphToSimSpeed(18)
+    ? car.trackState.surface === 'barrier' ? profile.lowSpeedRecovery.barrier : profile.lowSpeedRecovery.default
+    : 0;
+  const outwardBrakeStart = lowSpeedOffTrack
+    ? profile.lowSpeedOutwardBrakeStartMps
+    : profile.outwardBrakeStartMps;
+  const canCrawlSteerRecovery = lowSpeedOffTrack &&
+    car.speed < kphToSimSpeed(8) &&
+    edgeMotion.outwardSpeedMps < profile.lowSpeedCrawlOutwardToleranceMps;
+  const needsOutwardStabilization = recoveringOutsideRoad &&
+    (!lowSpeedOffTrack || profile.stabilizeLowSpeedOutward) &&
+    !canCrawlSteerRecovery &&
+    edgeMotion.outwardSpeedMps > outwardBrakeStart &&
+    distanceFromRoadMeters > 0.25;
+  const recoveryThrottleFloorBase = profile.simulatorMode && !car.trackState.onTrack
+    ? (car.trackState.surface === 'barrier' ? profile.lowSpeedRecovery.barrier : profile.lowSpeedRecovery.default)
+    : lowSpeedRecovery;
+  const lowSpeedRecoveryThrottle = lowSpeedOffTrack && car.trackState.surface !== 'barrier'
+    ? profile.lowSpeedRecoveryThrottle
+    : 0;
+  const recoveryThrottleFloor = needsOutwardStabilization
+    ? 0
+    : Math.max(recoveryThrottleFloorBase, lowSpeedRecoveryThrottle);
+  const surfaceThrottleLimit = car.trackState.surface === 'barrier'
+    ? profile.throttleLimits.barrier
+    : car.trackState.surface === 'gravel'
+      ? profile.throttleLimits.gravel
+      : car.trackState.surface === 'grass'
+        ? profile.throttleLimits.grass
+        : profile.throttleLimits.default;
+  const throttleLimit = lowSpeedOffTrack && edgeMotion.headingOutward && distanceFromRoadMeters > 0.5
+    ? Math.min(surfaceThrottleLimit, profile.lowSpeedHeadingOutwardThrottleLimit)
+    : surfaceThrottleLimit;
+  let brakeAmount = speedError < -kphToSimSpeed(5)
+    ? clamp(Math.abs(speedError) / kphToSimSpeed(profile.brakeResponseKph), 0.04, car.trackState.onTrack ? profile.onTrackBrakeLimit : profile.offTrackBrakeLimit)
+    : 0;
+  if (needsOutwardStabilization) {
+    brakeAmount = Math.max(
+      brakeAmount,
+      clamp(
+        (edgeMotion.outwardSpeedMps - outwardBrakeStart) * profile.outwardBrakeGain +
+          Math.max(0, Math.abs(angleError) - 1.05) * profile.misalignmentBrakeGain,
+        0,
+        car.trackState.onTrack ? profile.onTrackBrakeLimit : profile.offTrackBrakeLimit,
+      ),
+    );
+  }
+  const unsettledScale = lowSpeedOffTrack
+    ? Math.max(profile.unsettledScale(car), 0.82)
+    : profile.unsettledScale(car);
+  const slideThrottleScale = 1 - clamp(
+    Math.max(0, edgeMotion.outwardSpeedMps - profile.outwardBrakeStartMps) * profile.slideThrottleDamping +
+      Math.max(0, Math.abs(angleError) - 1.25) * 0.22,
+    0,
+    0.94,
+  );
+  const steeringRequest = lowSpeedOffTrack
+    ? clamp(angleError * profile.steerGain, -profile.lowSpeedOffTrackSteerLimit, profile.lowSpeedOffTrackSteerLimit)
+    : angleError * profile.steerGain;
+  const minimumAcceleration = needsOutwardStabilization ? 0 : 0.04;
+
+  return createDriverInput()
+    .steer(steeringRequest)
+    .accelerate(brakeAmount > 0.05 ? 0 : speedError > 0
+      ? clamp(((speedError / kphToSimSpeed(24)) * alignment + recoveryThrottleFloor) * unsettledScale * slideThrottleScale, minimumAcceleration, throttleLimit)
+      : recoveryThrottleFloor * unsettledScale * slideThrottleScale)
+    .brake(brakeAmount)
+    .controls();
+}

package/src/simulation/driver/safetyCarControls.js

@@ -0,0 +1,35 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { kphToSimSpeed, metersToSimUnits, simUnitsToMeters } from '../units.js';
+import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
+import { SAFETY_CAR_LOOKAHEAD_MAX, SAFETY_CAR_LOOKAHEAD_MIN } from './driverControlConstants.js';
+import { angleToPoint } from './driverMath.js';
+import { createDriverInput } from './driverInput.js';
+
+export function decideSafetyCarControls(car, orderIndex, race) {
+  const queueSlot = race.safetyCar.progress - race.rules.safetyCarLeadDistance - orderIndex * race.rules.safetyCarGap;
+  const lookahead = clamp(car.speed * 0.55 + metersToSimUnits(20), SAFETY_CAR_LOOKAHEAD_MIN, SAFETY_CAR_LOOKAHEAD_MAX);
+  const targetBase = pointAt(race.track, car.progress + lookahead);
+  const target = offsetTrackPoint(targetBase, 0);
+  const slotError = queueSlot - car.raceDistance;
+  const headingError = normalizeAngle(targetBase.heading - car.heading);
+  const lateralError = car.trackState?.signedOffset ?? 0;
+  const centerlineCorrection = -Math.atan2(
+    lateralError * 1.25,
+    Math.max(car.speed, kphToSimSpeed(35)),
+  );
+  const cornerRadiusMeters = simUnitsToMeters(1 / Math.max(Math.abs(targetBase.curvature), 1e-7));
+  const cornerSpeed = kphToSimSpeed(clamp(Math.sqrt(4.2 * cornerRadiusMeters) * 3.6, 45, 158));
+  const edgePenalty = clamp(simUnitsToMeters(Math.abs(lateralError)) - simUnitsToMeters(race.track.width / 2) * 0.68, 0, 3) * kphToSimSpeed(18);
+  const desiredSpeed = clamp(
+    race.rules.safetyCarSpeed + slotError * 0.24 - edgePenalty,
+    kphToSimSpeed(22),
+    Math.min(race.rules.safetyCarSpeed + kphToSimSpeed(32), cornerSpeed),
+  );
+  const speedError = desiredSpeed - car.speed;
+
+  return createDriverInput()
+    .steer(angleToPoint(car, target) * 1.18 + headingError * 0.32 + centerlineCorrection)
+    .accelerate(speedError > kphToSimSpeed(1) ? clamp(speedError / kphToSimSpeed(16), 0, 0.5) : 0)
+    .brake(speedError < -kphToSimSpeed(0.5) ? clamp(Math.abs(speedError) / kphToSimSpeed(14), 0, 1) : 0)
+    .controls();
+}

package/src/simulation/driver/trafficScan.js

@@ -0,0 +1,51 @@
+import { metersToSimUnits } from '../units.js';
+import { DEFEND_REAR_GAP, TRAFFIC_GAP_AHEAD, TRAFFIC_SIDE_GAP, TRAFFIC_REAR_WINDOW } from './driverControlConstants.js';
+import { VEHICLE_LIMITS } from '../vehicle/vehiclePhysics.js';
+
+export function scanNearbyTraffic(car, race) {
+  return race.cars
+    .filter((other) => other !== car)
+    .map((other) => ({
+      car: other,
+      gap: other.raceDistance - car.raceDistance,
+      signedOffset: other.trackState?.signedOffset ?? 0,
+      speed: other.speed,
+    }))
+    .filter((entry) => entry.gap > -metersToSimUnits(39) && entry.gap < metersToSimUnits(134));
+}
+
+export function findDefensiveThreat(traffic) {
+  let closest = null;
+
+  traffic.forEach((entry) => {
+    if (entry.gap >= -VEHICLE_LIMITS.carLength * 1.1 || entry.gap < -DEFEND_REAR_GAP) return;
+    if (!closest || entry.gap > closest.gap) closest = entry;
+  });
+
+  return closest;
+}
+
+export function findLaneTrafficAhead(traffic, offset, maxDistance) {
+  let closest = null;
+
+  traffic.forEach((entry) => {
+    if (entry.gap <= 0 || entry.gap > maxDistance) return;
+    if (Math.abs(entry.signedOffset - offset) > TRAFFIC_SIDE_GAP) return;
+    if (!closest || entry.gap < closest.gap) closest = entry;
+  });
+
+  return closest;
+}
+
+export function findLaneTrafficBeside(traffic, offset) {
+  let closest = null;
+
+  traffic.forEach((entry) => {
+    const lateral = Math.abs(entry.signedOffset - offset);
+    if (Math.abs(entry.gap) > metersToSimUnits(28) || lateral > TRAFFIC_SIDE_GAP) return;
+    const risk = (metersToSimUnits(28) - Math.abs(entry.gap)) + (TRAFFIC_SIDE_GAP - lateral);
+    if (!closest || risk > closest.risk) closest = { ...entry, lateral, risk };
+  });
+
+  return closest;
+}