@inventure71/paddockjs 1.0.0 → 2.0.1

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;
+}