@inventure71/paddockjs 4.2.0 → 4.3.0

package/src/simulation/driver/advancedRacePace.js

@@ -0,0 +1,112 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { metersToSimUnits, simUnitsToMeters, TOP_SPEED_SIM_UNITS_PER_SECOND } from '../units.js';
+import { pointAtInto } from '../track/trackModel.js';
+import { tirePerformanceFactor } from '../vehicle/vehiclePhysics.js';
+import { advancedDriveForce } from '../vehicle/advancedVehicleModel.js';
+import { createAdvancedRacingEnvelopeScratch, estimateAdvancedRacingLateralCapacity,
+  estimateAdvancedRacingLongitudinalLimits, estimateAdvancedRacingBrakeForce } from './advancedRacingEnvelope.js';
+import { racingDriverProfile } from './racingDriverProfile.js';
+import { advancedRacingPreviewReserveMeters } from './advancedRacingTiming.js';
+import { followingSpeedLimit } from './trafficScan.js';
+
+const MAX_SPEED = simUnitsToMeters(TOP_SPEED_SIM_UNITS_PER_SECOND);
+const SAMPLE_SPACING = 12; // meters
+const PREVIEW_POINT_SCRATCH = { x: 0, y: 0, heading: 0, normalX: 0, normalY: 0, curvature: 0, distance: 0 };
+const CAPACITY_SCRATCH = createAdvancedRacingEnvelopeScratch();
+const LONGITUDINAL_SCRATCH = createAdvancedRacingEnvelopeScratch();
+
+export function advancedCornerSpeed(car, curvature, tireFactor, profile = racingDriverProfile(car)) {
+  return cornerSpeedWithEndpoints(car, curvature, tireFactor, profile);
+}
+
+function endpointCapacity(car, speed, tireFactor, direction, endpoints) {
+  if (!endpoints || (speed !== MAX_SPEED && speed !== 0)) {
+    return estimateAdvancedRacingLateralCapacity(car, speed, tireFactor, CAPACITY_SCRATCH, { turnDirection: direction });
+  }
+  const key = `${direction}:${speed === MAX_SPEED ? 'maximum' : 'zero'}`;
+  return endpoints[key] ??= estimateAdvancedRacingLateralCapacity(car, speed, tireFactor, CAPACITY_SCRATCH, { turnDirection: direction });
+}
+
+function cornerSpeedWithEndpoints(car, curvature, tireFactor, profile, endpoints = null) {
+  const curve = Math.abs(curvature);
+  if (curve < 1e-6) return MAX_SPEED;
+  const direction = Math.sign(curvature);
+  let high = MAX_SPEED ** 2;
+  let highValue = profile.lateralShare * endpointCapacity(car, MAX_SPEED, tireFactor, direction, endpoints) - curve * high;
+  if (highValue >= 0) return MAX_SPEED;
+  let low = 0;
+  let lowValue = profile.lateralShare * endpointCapacity(car, 0, tireFactor, direction, endpoints);
+  let speed = 0;
+  // Keep an explicit feasible/infeasible bracket: mixed surfaces and load
+  // transfer must not inherit the old static-capacity concavity assumption.
+  for (let iteration = 0; iteration < 8; iteration += 1) {
+    const next = low + (high - low) * lowValue / (lowValue - highValue);
+    const nextSpeed = Math.sqrt(next);
+    const value = profile.lateralShare * endpointCapacity(car, nextSpeed, tireFactor, direction, endpoints) - curve * next;
+    if (value < 0) { high = next; highValue = value; }
+    else {
+      const difference = nextSpeed - speed;
+      low = next; lowValue = value; speed = nextSpeed;
+      if (difference < 0.01) return speed;
+    }
+  }
+  return speed;
+}
+
+export function advancedRaceTargetSpeed(car, track, pathCurvature, profile = racingDriverProfile(car)) {
+  const speed = simUnitsToMeters(car.speed);
+  const tireFactor = tirePerformanceFactor(car.tireEnergy ?? 100);
+  const horizon = Math.max(80, speed * 3);
+  const anticipationDistance = advancedRacingPreviewReserveMeters(speed, profile, SAMPLE_SPACING);
+  let targetSpeed = MAX_SPEED;
+  // Endpoints depend on the car's current tires, surfaces and aero, but not
+  // preview curvature. Reuse them only during this synchronous decision.
+  const endpoints = Object.create(null);
+  const farDistance = Math.ceil(horizon / SAMPLE_SPACING) * SAMPLE_SPACING;
+  let futureHeading = pointAtInto(track, car.progress + metersToSimUnits(farDistance + SAMPLE_SPACING), PREVIEW_POINT_SCRATCH).heading;
+  // Work backward from future corners. Reserve lateral grip when estimating
+  // braking; the lower future speed also gives a conservative aero estimate.
+  // Anticipation and judgement precision depend on the existing driver skills.
+  for (let distance = farDistance; distance >= 0; distance -= SAMPLE_SPACING) {
+    const sample = pointAtInto(track, car.progress + metersToSimUnits(distance), PREVIEW_POINT_SCRATCH);
+    // Track samples store curvature magnitude; recover turn direction from
+    // consecutive tangents for asymmetric wheel-surface/load estimates.
+    const turnDirection = Math.sign(normalizeAngle(futureHeading - sample.heading)) || Math.sign(pathCurvature) || 1;
+    const curve = sample.curvature * metersToSimUnits(1) * turnDirection;
+    futureHeading = sample.heading;
+    const corner = cornerSpeedWithEndpoints(car, curve, tireFactor, profile, endpoints);
+    const futureSpeed = Math.min(targetSpeed, corner);
+    const limits = estimateAdvancedRacingBrakeForce(car, futureSpeed, tireFactor, futureSpeed ** 2 * curve, LONGITUDINAL_SCRATCH);
+    const deceleration = (limits.brakeForce * profile.longitudinalShare + limits.brakeResistanceForce) / car.mass;
+    // Inspect every nearby bend, including those inside the reaction window.
+    // Only distance beyond pursuit/response/driver anticipation can be spent
+    // braking. Shifting the sample origin would silently skip nearby corners.
+    const usableDistance = Math.max(0, distance + SAMPLE_SPACING - anticipationDistance) -
+      Math.max(0, distance - anticipationDistance);
+    targetSpeed = Math.min(corner, Math.sqrt(futureSpeed ** 2 + 2 * deceleration * usableDistance));
+  }
+  // Passing and path correction may demand a tighter turn than the centerline.
+  return Math.min(MAX_SPEED, Math.min(targetSpeed, cornerSpeedWithEndpoints(car, pathCurvature, tireFactor, profile, endpoints)) * profile.speedJudgementScale);
+}
+
+export function advancedRacingSpeedControls(car, targetSpeed, profile = racingDriverProfile(car)) {
+  const speed = simUnitsToMeters(car.speed);
+  const actualLateral = car.lateralAcceleration ?? speed * (car.yawRate ?? 0);
+  const limits = estimateAdvancedRacingLongitudinalLimits(car, speed, tirePerformanceFactor(car.tireEnergy ?? 100), actualLateral, LONGITUDINAL_SCRATCH);
+  const resistance = targetSpeed > 0 ? limits.resistanceForce : 0;
+  // Request net acceleration, then add the force needed merely to hold speed.
+  // Both pedals share one signed demand so a slowdown cannot request throttle
+  // and braking together. Tire/engine limits remain those of the actual car.
+  const responseSeconds = 0.05 + 0.045 * (1 - profile.ability);
+  const requestedForce = car.mass * (targetSpeed - speed) / responseSeconds + resistance;
+  return {
+    throttle: clamp(requestedForce / advancedDriveForce(car, speed), 0,
+      Math.min(1, limits.driveForce * profile.longitudinalShare / advancedDriveForce(car, speed))),
+    brake: clamp(-requestedForce / car.brakeNewtons, 0,
+      Math.min(1, limits.brakeForce * profile.longitudinalShare / car.brakeNewtons)),
+  };
+}
+
+export function advancedFollowingSpeed(car, cars, trackLength) {
+  return followingSpeedLimit(car, cars, trackLength);
+}

package/src/simulation/driver/advancedRacingControls.js

@@ -0,0 +1,61 @@
+import { clamp } from '../simMath.js';
+import { metersToSimUnits, simUnitsToMeters } from '../units.js';
+import { pointAtInto } from '../track/trackModel.js';
+import { VEHICLE_LIMITS, tirePerformanceFactor } from '../vehicle/vehiclePhysics.js';
+import { advancedRaceTargetSpeed, advancedRacingSpeedControls } from './advancedRacePace.js';
+import { advancedLateralAccelerationLimit } from '../vehicle/advancedTireForces.js';
+import { mainTrackCenterOffset } from './trafficScan.js';
+import { createDriverInput } from './driverInput.js';
+import { advancedRacingPathCurvature, advancedRacingSteeringToPoint } from './advancedRacingSteering.js';
+import { advancedRacingLookaheadMeters } from './advancedRacingTiming.js';
+import { racingDriverProfile } from './racingDriverProfile.js';
+import { planRacingLine, calculateRacingTrafficPenalty } from './racingLinePlan.js';
+
+const TARGET_BASE_SCRATCH = { x: 0, y: 0, heading: 0, normalX: 0, normalY: 0, curvature: 0, distance: 0 };
+const TARGET_POINT_SCRATCH = { x: 0, y: 0 };
+
+export function decideAdvancedRacingControls(car, orderIndex, race) {
+  const speed = simUnitsToMeters(car.speed);
+  const profile = racingDriverProfile(car);
+  const lane = planRacingLine(car, orderIndex, race);
+  const lookahead = advancedRacingLookaheadMeters(speed);
+  const target = pointAtInto(race.track, car.progress + metersToSimUnits(lookahead), TARGET_BASE_SCRATCH);
+  const offsetLimit = race.track.width / 2 - VEHICLE_LIMITS.carWidth;
+  const offset = clamp(
+    clamp(advancedRacingOffset(car, lane.offset + metersToSimUnits(profile.lineErrorMeters), race.track.width, profile), lane.minimumOffset, lane.maximumOffset),
+    -offsetLimit, offsetLimit,
+  );
+  TARGET_POINT_SCRATCH.x = target.x + target.normalX * offset;
+  TARGET_POINT_SCRATCH.y = target.y + target.normalY * offset;
+  const pathCurvature = advancedRacingPathCurvature(car, TARGET_POINT_SCRATCH);
+
+  let targetSpeed = advancedRaceTargetSpeed(car, race.track, pathCurvature, profile);
+  const trafficPenalty = calculateRacingTrafficPenalty(car, lane) * (1 - (car.aggression ?? 0.5) * 0.28);
+  targetSpeed = Math.max(0, targetSpeed - trafficPenalty / 3.6);
+  // A passing intention does not create physical clearance. Match a slower
+  // car until the actual footprints separate, including enough reaction gap.
+  targetSpeed = Math.min(targetSpeed, lane.followingSpeed);
+  const { throttle, brake } = advancedRacingSpeedControls(car, targetSpeed, profile);
+  const { steering } = advancedRacingSteeringToPoint(car, TARGET_POINT_SCRATCH, profile, { throttle, brake });
+  return createDriverInput().steer(steering).accelerate(throttle).brake(brake).controls();
+}
+
+export function advancedRacingOffset(car, plannedOffset, trackWidth, profile = racingDriverProfile(car)) {
+  const speed = simUnitsToMeters(car.speed);
+  const capacity = advancedLateralAccelerationLimit(car, speed, tirePerformanceFactor(car.tireEnergy ?? 100));
+  const cornerUsage = clamp(Math.abs(speed * (car.yawRate ?? 0)) / (capacity * profile.lateralShare * 0.9), 0, 1);
+  const currentOffset = mainTrackCenterOffset(car);
+  // Hold a consistent line when cornering consumes the racing grip budget.
+  // As the car unwinds on exit, progressively allow the planned lane change.
+  const comfortLimit = Math.max(0, trackWidth / 2 - VEHICLE_LIMITS.carWidth * 2);
+  const edgePressure = clamp((Math.abs(currentOffset) - comfortLimit) / VEHICLE_LIMITS.carWidth, 0, 1);
+  const needsEdgeCorrection = cornerUsage > 0.5 && edgePressure > 0;
+  if (needsEdgeCorrection) {
+    // Holding a loaded corner line must not preserve a developing excursion.
+    // Correct inward on the current side before considering a cross-track pass.
+    plannedOffset = Math.sign(currentOffset) * Math.min(Math.abs(plannedOffset), comfortLimit);
+  }
+  const laneChangeShare = Math.max(1 - cornerUsage ** 2, needsEdgeCorrection ? edgePressure : 0);
+  const offsetLimit = trackWidth / 2 - VEHICLE_LIMITS.carWidth;
+  return clamp(currentOffset + (plannedOffset - currentOffset) * laneChangeShare, -offsetLimit, offsetLimit);
+}

package/src/simulation/driver/advancedRacingEnvelope.js

@@ -0,0 +1,255 @@
+import { advancedContactCapacity, advancedNormalLoads } from '../vehicle/advancedTireForces.js';
+import { ADVANCED_VEHICLE_MODEL as MODEL, ADVANCED_WHEELS, advancedWheelSurface, advancedDragFactor } from '../vehicle/advancedVehicleModel.js';
+
+const SOLVE_PASSES = 3;
+const FEASIBILITY_MARGIN = 0.999;
+const INVOCATION_INPUTS = Symbol('racingEnvelopeInvocationInputs');
+
+function prepareInvocationInputs(car, speedMps, scratch) {
+  // Buffers persist with scratch; their contents are refreshed unconditionally
+  // for this invocation. No car reference or identity-based validity is stored.
+  let inputs = scratch[INVOCATION_INPUTS];
+  if (!inputs) {
+    inputs = { surfaces: [null, null, null, null], nominalLoads: [0, 0, 0, 0] };
+    Object.defineProperty(scratch, INVOCATION_INPUTS, { value: inputs });
+  }
+  inputs.uniformRolling = true;
+  inputs.strongestSurface = null;
+  for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) {
+    const wheel = ADVANCED_WHEELS[index];
+    const surface = advancedWheelSurface(car, wheel.id);
+    inputs.surfaces[index] = surface;
+    inputs.nominalLoads[index] = car.mass * MODEL.gravity * (wheel.front ? MODEL.frontWeightFraction : 1 - MODEL.frontWeightFraction) / 2;
+    if (index > 0 && surface.rolling !== inputs.surfaces[0].rolling) inputs.uniformRolling = false;
+    if (!inputs.strongestSurface || surface.grip > inputs.strongestSurface.grip) inputs.strongestSurface = surface;
+  }
+  inputs.staticWeight = car.mass * MODEL.gravity;
+  inputs.tireGrip = car.tireGrip;
+  inputs.dragForce = advancedDragFactor(car) * speedMps ** 2;
+  return inputs;
+}
+
+export function createAdvancedRacingEnvelopeScratch() {
+  return {
+    loads: [0, 0, 0, 0],
+    capacities: [0, 0, 0, 0],
+    lateralForces: [0, 0, 0, 0],
+    longitudinalRemaining: [0, 0, 0, 0],
+    driveRemaining: [0, 0, 0, 0],
+    brakeRemaining: [0, 0, 0, 0],
+  };
+}
+
+// The scratch is owned by one synchronous policy decision, never by a car
+// identity cache. Lateral force is yaw-balanced between the two equal-length
+// axles, then apportioned within each axle by contact capacity.
+export function writeAdvancedRacingWheelEnvelope(car, speedMps, tireFactor, scratch, {
+  longitudinalAcceleration = 0,
+  lateralAcceleration = 0,
+} = {}) {
+  const inputs = prepareInvocationInputs(car, speedMps, scratch);
+  return writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, longitudinalAcceleration, lateralAcceleration);
+}
+
+function writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, longitudinalAcceleration = 0, lateralAcceleration = 0) {
+  const loads = advancedNormalLoads(car, speedMps, longitudinalAcceleration, lateralAcceleration);
+  let frontCapacity = 0;
+  let rearCapacity = 0;
+  let rollingResistance = 0;
+  for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) {
+    const wheel = ADVANCED_WHEELS[index];
+    const surface = inputs.surfaces[index];
+    const nominalLoad = inputs.nominalLoads[index];
+    const capacity = advancedContactCapacity(loads[index], nominalLoad, inputs.tireGrip, tireFactor, surface);
+    scratch.loads[index] = loads[index];
+    scratch.capacities[index] = capacity;
+    if (wheel.front) frontCapacity += capacity;
+    else rearCapacity += capacity;
+    rollingResistance += surface.rolling * loads[index];
+  }
+  const lateralAxleForce = Math.abs(lateralAcceleration) * car.mass / 2;
+  for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) {
+    const capacity = scratch.capacities[index];
+    const axleCapacity = ADVANCED_WHEELS[index].front ? frontCapacity : rearCapacity;
+    const lateralForce = axleCapacity > 0 ? lateralAxleForce * capacity / axleCapacity : lateralAxleForce / 2;
+    scratch.lateralForces[index] = Math.sign(lateralAcceleration) * lateralForce;
+    scratch.longitudinalRemaining[index] = Math.sqrt(Math.max(0, capacity ** 2 - lateralForce ** 2));
+  }
+  scratch.frontCapacity = frontCapacity;
+  scratch.rearCapacity = rearCapacity;
+  scratch.lateralCapacity = 2 * Math.min(frontCapacity, rearCapacity) / car.mass;
+  scratch.lateralFeasible = lateralAxleForce <= Math.min(frontCapacity, rearCapacity);
+  scratch.resistanceForce = rollingResistance + inputs.dragForce;
+  scratch.uniformRolling = inputs.uniformRolling;
+  return scratch;
+}
+
+export function estimateAdvancedRacingLateralCapacity(car, speedMps, tireFactor, scratch, {
+  turnDirection = Math.sign(car.yawRate || car.lateralAcceleration || 1),
+} = {}) {
+  const direction = turnDirection < 0 ? -1 : 1;
+  const inputs = prepareInvocationInputs(car, speedMps, scratch);
+  writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs);
+  let candidate = scratch.lateralCapacity;
+  let previous = candidate;
+  for (let pass = 0; pass < SOLVE_PASSES; pass += 1) {
+    previous = candidate;
+    writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, 0, direction * candidate);
+    candidate = scratch.lateralCapacity;
+  }
+  let conservative = Math.min(candidate, previous) * FEASIBILITY_MARGIN;
+  writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, 0, direction * conservative);
+  // A bound must fit its own predicted load transfer, including mixed surfaces.
+  // One final conservative projection handles unusual rating/load extremes.
+  if (!scratch.lateralFeasible) {
+    conservative = Math.min(conservative, scratch.lateralCapacity) * FEASIBILITY_MARGIN;
+    writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, 0, direction * conservative);
+  }
+  if (!scratch.lateralFeasible) return 0;
+  return conservative;
+}
+
+function availableLongitudinalForce(scratch, braking) {
+  if (!scratch.lateralFeasible) return 0;
+  if (!braking) return 2 * Math.min(scratch.longitudinalRemaining[2], scratch.longitudinalRemaining[3]);
+  let force = Infinity;
+  for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) {
+    const fraction = (ADVANCED_WHEELS[index].front ? MODEL.frontBrakeFraction : 1 - MODEL.frontBrakeFraction) / 2;
+    force = Math.min(force, scratch.longitudinalRemaining[index] / fraction);
+  }
+  return force;
+}
+
+function writeLongitudinalPrediction(car, speedMps, tireFactor, lateralAcceleration, scratch, force, braking, inputs) {
+  const signedForce = braking ? -force : force;
+  // Wheel force changes longitudinal load transfer. Drag and rolling oppose
+  // forward motion and contribute to the net acceleration seen by physics.
+  const passes = scratch.uniformRolling ? 1 : 3;
+  for (let pass = 0; pass < passes; pass += 1) {
+    const resistance = scratch.resistanceForce;
+    writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, (signedForce - resistance) / car.mass, lateralAcceleration);
+  }
+}
+
+function longitudinalMargin(scratch, force, braking) {
+  let margin = Infinity;
+  for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) {
+    const wheel = ADVANCED_WHEELS[index];
+    if (!braking && wheel.front) {
+      margin = Math.min(margin, scratch.capacities[index] - Math.abs(scratch.lateralForces[index]));
+      continue;
+    }
+    const fraction = braking ? (wheel.front ? MODEL.frontBrakeFraction : 1 - MODEL.frontBrakeFraction) / 2 : 0.5;
+    const squared = scratch.capacities[index] ** 2 - scratch.lateralForces[index] ** 2;
+    // Keep a signed continuous residual when lateral demand is infeasible.
+    // Clamping this to zero would hide feasible nonzero load-transfer windows.
+    const remaining = Math.sign(squared) * Math.sqrt(Math.abs(squared));
+    margin = Math.min(margin, remaining / fraction - force);
+  }
+  return margin;
+}
+
+function longitudinalForceUpper(car, tireFactor, scratch, inputs) {
+  let totalLoad = 0;
+  for (let index = 0; index < scratch.loads.length; index += 1) totalLoad += scratch.loads[index];
+  // Concavity bounds the sum of contact capacities by distributing normal
+  // load in proportion to nominal load, with the strongest surface at all
+  // contacts. This bounds force without imposing engine or brake hardware.
+  return advancedContactCapacity(totalLoad, inputs.staticWeight, inputs.tireGrip, tireFactor, inputs.strongestSurface);
+}
+
+function bracketLongitudinalForce(car, speedMps, tireFactor, lateralAcceleration, scratch, braking, candidate, inputs) {
+  const upper = longitudinalForceUpper(car, tireFactor, scratch, inputs);
+  const marginAt = (force) => {
+    writeLongitudinalPrediction(car, speedMps, tireFactor, lateralAcceleration, scratch, force, braking, inputs);
+    return longitudinalMargin(scratch, force, braking);
+  };
+  let low = candidate;
+  if (!(low > 0) || marginAt(low) < 0) {
+    low = braking ? Math.min(upper, Math.max(0, (car.brake ?? 0) * car.brakeNewtons)) : 0;
+    if (marginAt(low) < 0) {
+      // Zero force need not be feasible: braking can load an otherwise weak
+      // front axle. Find a feasible seed before bracketing its upper root.
+      let left = 0;
+      let right = upper;
+      const ratio = (Math.sqrt(5) - 1) / 2;
+      let first = right - (right - left) * ratio;
+      let second = left + (right - left) * ratio;
+      let firstMargin = marginAt(first);
+      let secondMargin = marginAt(second);
+      for (let iteration = 0; iteration < 20; iteration += 1) {
+        if (firstMargin < secondMargin) {
+          left = first; first = second; firstMargin = secondMargin;
+          second = left + (right - left) * ratio; secondMargin = marginAt(second);
+        } else {
+          right = second; second = first; secondMargin = firstMargin;
+          first = right - (right - left) * ratio; firstMargin = marginAt(first);
+        }
+      }
+      low = firstMargin >= secondMargin ? first : second;
+      if (marginAt(low) < 0) return 0;
+    }
+  }
+  let high = upper;
+  for (let iteration = 0; iteration < 16; iteration += 1) {
+    const middle = (low + high) / 2;
+    if (marginAt(middle) >= 0) low = middle;
+    else high = middle;
+  }
+  // Shrinking toward zero can leave a disconnected feasible interval. Keep
+  // the validated feasible endpoint instead of applying a blanket force scale.
+  marginAt(low);
+  return low;
+}
+
+function solveLongitudinalForce(car, speedMps, tireFactor, lateralAcceleration, scratch, braking, remaining, inputs) {
+  writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, 0, lateralAcceleration);
+  let candidate = availableLongitudinalForce(scratch, braking);
+  let previous = candidate;
+  for (let pass = 0; pass < SOLVE_PASSES; pass += 1) {
+    previous = candidate;
+    writeLongitudinalPrediction(car, speedMps, tireFactor, lateralAcceleration, scratch, candidate, braking, inputs);
+    candidate = availableLongitudinalForce(scratch, braking);
+  }
+  candidate = Math.min(candidate, previous) * FEASIBILITY_MARGIN;
+  writeLongitudinalPrediction(car, speedMps, tireFactor, lateralAcceleration, scratch, candidate, braking, inputs);
+  if (candidate > availableLongitudinalForce(scratch, braking)) {
+    candidate = availableLongitudinalForce(scratch, braking) * FEASIBILITY_MARGIN;
+    writeLongitudinalPrediction(car, speedMps, tireFactor, lateralAcceleration, scratch, candidate, braking, inputs);
+  }
+  // Retain the cheap iteration when it is feasible and close to the upper
+  // root; otherwise a safeguarded bracket handles near-limit transfer.
+  const margin = longitudinalMargin(scratch, candidate, braking);
+  const probe = candidate / 0.985;
+  writeLongitudinalPrediction(car, speedMps, tireFactor, lateralAcceleration, scratch, probe, braking, inputs);
+  const probeMargin = longitudinalMargin(scratch, probe, braking);
+  if (!(candidate > 0) || margin < 0 || probeMargin >= 0) {
+    candidate = bracketLongitudinalForce(car, speedMps, tireFactor, lateralAcceleration, scratch, braking, candidate, inputs);
+  }
+  writeLongitudinalPrediction(car, speedMps, tireFactor, lateralAcceleration, scratch, candidate, braking, inputs);
+  if (longitudinalMargin(scratch, candidate, braking) < 0) candidate = 0;
+  for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) remaining[index] = scratch.longitudinalRemaining[index];
+  return candidate;
+}
+
+export function estimateAdvancedRacingBrakeForce(car, speedMps, tireFactor, lateralAcceleration, scratch) {
+  const inputs = prepareInvocationInputs(car, speedMps, scratch);
+  return estimateBrakeForce(car, speedMps, tireFactor, lateralAcceleration, scratch, inputs);
+}
+
+function estimateBrakeForce(car, speedMps, tireFactor, lateralAcceleration, scratch, inputs) {
+  scratch.brakeForce = solveLongitudinalForce(car, speedMps, tireFactor, lateralAcceleration, scratch, true, scratch.brakeRemaining, inputs);
+  scratch.brakeResistanceForce = scratch.resistanceForce;
+  return scratch;
+}
+
+export function estimateAdvancedRacingLongitudinalLimits(car, speedMps, tireFactor, lateralAcceleration, scratch) {
+  const inputs = prepareInvocationInputs(car, speedMps, scratch);
+  estimateBrakeForce(car, speedMps, tireFactor, lateralAcceleration, scratch, inputs);
+  scratch.driveForce = solveLongitudinalForce(car, speedMps, tireFactor, lateralAcceleration, scratch, false, scratch.driveRemaining, inputs);
+  scratch.driveResistanceForce = scratch.resistanceForce;
+  // Feedforward users see the actual present load state, not the last solver's
+  // hypothetical drive state. The solved remaining budgets stay separate.
+  writeWheelEnvelope(car, speedMps, tireFactor, scratch, inputs, car.longitudinalAcceleration ?? 0, lateralAcceleration);
+  return scratch;
+}

package/src/simulation/driver/advancedRacingSteering.js

@@ -0,0 +1,76 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { simUnitsToMeters } from '../units.js';
+import { VEHICLE_LIMITS, tirePerformanceFactor } from '../vehicle/vehiclePhysics.js';
+import { ADVANCED_VEHICLE_MODEL as MODEL, ADVANCED_WHEELS, advancedWheelSurface } from '../vehicle/advancedVehicleModel.js';
+import { advancedLateralSlipAngle } from '../vehicle/advancedTireForces.js';
+import { createAdvancedRacingEnvelopeScratch, writeAdvancedRacingWheelEnvelope } from './advancedRacingEnvelope.js';
+import { racingDriverProfile } from './racingDriverProfile.js';
+import { advancedRacingYawResponseSeconds } from './advancedRacingTiming.js';
+
+const WHEEL_SCRATCH = createAdvancedRacingEnvelopeScratch();
+
+export function advancedRacingPathCurvature(car, target) {
+  const speed = simUnitsToMeters(car.speed);
+  const dx = simUnitsToMeters(target.x - car.x);
+  const dy = simUnitsToMeters(target.y - car.y);
+  const velocityHeading = speed > 2 && Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)
+    ? Math.atan2(car.velocityY, car.velocityX) : car.heading;
+  const angle = normalizeAngle(Math.atan2(dy, dx) - velocityHeading);
+  return 2 * Math.sin(angle) / Math.max(Math.hypot(dx, dy), 1);
+}
+
+// Racing pursuit follows the velocity direction. The front wheels also need
+// tire slip to generate the requested force; geometric steering alone omits
+// that demand as the car approaches the nonlinear brush envelope.
+export function advancedRacingSteeringToPoint(car, target, profile = racingDriverProfile(car), controls = car) {
+  const speed = simUnitsToMeters(car.speed);
+  const curvature = advancedRacingPathCurvature(car, target);
+  const geometricSteering = Math.atan(MODEL.wheelbase * curvature);
+  if (speed < 2) return { curvature, steering: geometricSteering };
+
+  const cos = Math.cos(car.heading);
+  const sin = Math.sin(car.heading);
+  const vx = Number.isFinite(car.velocityX) ? simUnitsToMeters(car.velocityX) : speed * cos;
+  const vy = Number.isFinite(car.velocityY) ? simUnitsToMeters(car.velocityY) : speed * sin;
+  const u = vx * cos + vy * sin;
+  const v = -vx * sin + vy * cos;
+  const yaw = car.yawRate ?? 0;
+  const desiredYaw = speed * curvature;
+  const responseSeconds = advancedRacingYawResponseSeconds(profile);
+  const frontForce = car.mass * speed ** 2 * curvature / 2 +
+    car.mass * MODEL.yawInertiaPerMass * (desiredYaw - yaw) / (MODEL.wheelbase * responseSeconds);
+  const envelope = writeAdvancedRacingWheelEnvelope(car, speed, tirePerformanceFactor(car.tireEnergy ?? 100), WHEEL_SCRATCH, {
+    longitudinalAcceleration: car.longitudinalAcceleration ?? 0,
+    lateralAcceleration: car.lateralAcceleration ?? 0,
+  });
+  const nominalLoad = car.mass * MODEL.gravity * MODEL.frontWeightFraction / 2;
+  const brakingForce = (controls.brake ?? 0) * car.brakeNewtons * MODEL.frontBrakeFraction / 2;
+  let weightedSteering = 0;
+  let totalWeight = 0;
+  for (let index = 0; index < 2; index += 1) {
+    const wheel = ADVANCED_WHEELS[index];
+    const capacity = envelope.capacities[index];
+    const remaining = Math.sqrt(Math.max(0, capacity ** 2 - brakingForce ** 2));
+    const lateralForce = clamp(
+      frontForce * capacity / Math.max(envelope.frontCapacity, 1e-9),
+      -remaining * 0.995, remaining * 0.995,
+    );
+    const localVelocityAngle = Math.atan2(v + yaw * wheel.x, Math.max(u - yaw * wheel.y, MODEL.lowSpeedSlipReference));
+    const bodyLongitudinalForce = -brakingForce - advancedWheelSurface(car, wheel.id).rolling * envelope.loads[index];
+    let wheelAngle = localVelocityAngle;
+    for (let iteration = 0; iteration < 3; iteration += 1) {
+      // Trail braking rotates longitudinal contact force into body-lateral
+      // force. Invert that projection along with the brush response.
+      const tireLateralForce = clamp((lateralForce - bodyLongitudinalForce * Math.sin(wheelAngle)) /
+        Math.max(0.7, Math.cos(wheelAngle)), -remaining * 0.995, remaining * 0.995);
+      wheelAngle = localVelocityAngle + advancedLateralSlipAngle({ normalLoad: envelope.loads[index], nominalLoad,
+        longitudinalForce: brakingForce, lateralForce: tireLateralForce, capacity });
+    }
+    weightedSteering += wheelAngle * capacity;
+    totalWeight += capacity;
+  }
+  const forceSteering = totalWeight > 0 ? weightedSteering / totalWeight : geometricSteering;
+  const blend = clamp((speed - 2) / 6, 0, 1);
+  return { curvature, steering: clamp(geometricSteering + (forceSteering - geometricSteering) * blend,
+    -VEHICLE_LIMITS.maxSteer, VEHICLE_LIMITS.maxSteer) };
+}

package/src/simulation/driver/advancedRacingTiming.js

@@ -0,0 +1,16 @@
+import { clamp } from '../simMath.js';
+
+// Keep steering's pursuit horizon and pace's braking reservation in the same
+// geometry. The car must slow before steering starts building corner force.
+export function advancedRacingLookaheadMeters(speedMps) {
+  return clamp(12 + speedMps * 0.65, 12, 55);
+}
+
+export function advancedRacingYawResponseSeconds(profile) {
+  return 0.18 + 0.12 * (1 - profile.ability);
+}
+
+export function advancedRacingPreviewReserveMeters(speedMps, profile, sampleSpacingMeters) {
+  return advancedRacingLookaheadMeters(speedMps) + speedMps *
+    (advancedRacingYawResponseSeconds(profile) + profile.anticipationSeconds) + sampleSpacingMeters;
+}

package/src/simulation/driver/arcadeRacePace.js

@@ -0,0 +1,83 @@
+import { clamp, normalizeAngle } from '../simMath.js';
+import { metersToSimUnits, simUnitsToMeters } from '../units.js';
+import { sampleHeadingAt, sampleHeadingCurvatureAtInto } from '../track/trackModel.js';
+import { VEHICLE_LIMITS, isSimulatorPhysicsMode, arcadeTrackCornerSpeedLimit, arcadeSurfaceGrip } from '../vehicle/vehiclePhysics.js';
+import { BRAKING_LOOKAHEAD_MAX_DISTANCE, CURVATURE_LOOKAHEAD_SAMPLES, LOOKAHEAD_BASE_DISTANCE, PREVIEW_CURVATURE_CAP } from './driverControlConstants.js';
+import { arcadeBrakingDeceleration } from './arcadeRacingEnvelope.js';
+import { racingDriverProfile } from './racingDriverProfile.js';
+
+const LOOKAHEAD_SAMPLE_SCRATCH = { heading: 0, curvature: 0 };
+
+export function arcadePreviewLookahead(speed) {
+  return Math.min(speed * 3.15 + LOOKAHEAD_BASE_DISTANCE, BRAKING_LOOKAHEAD_MAX_DISTANCE);
+}
+
+export function arcadeRacingLookahead(speed) {
+  // A long pursuit chord cuts across tight bends before asking for their
+  // actual steering curvature. Shorten racing path tracking independently
+  // from the longer braking preview and shared recovery/safety policies.
+  return metersToSimUnits(clamp(8 + simUnitsToMeters(speed) * 0.35, 8, 35));
+}
+
+export function maxLookaheadCurvature(track, progress, lookahead) {
+  let maximum = 0;
+  const sample = LOOKAHEAD_SAMPLE_SCRATCH;
+  let previousHeading = sampleHeadingCurvatureAtInto(track, progress, sample).heading;
+  const segmentDistance = Math.max(1, lookahead / CURVATURE_LOOKAHEAD_SAMPLES);
+  for (let index = 1; index <= CURVATURE_LOOKAHEAD_SAMPLES; index += 1) {
+    sampleHeadingCurvatureAtInto(track, progress + lookahead * (index / CURVATURE_LOOKAHEAD_SAMPLES), sample);
+    const segmentCurvature = Math.abs(normalizeAngle(sample.heading - previousHeading)) / segmentDistance;
+    maximum = Math.max(maximum, Math.abs(sample.curvature ?? 0), Math.min(segmentCurvature, PREVIEW_CURVATURE_CAP));
+    previousHeading = sample.heading;
+  }
+  return maximum;
+}
+
+export function calculateRacingLineOffset(car, race, lookahead, curvature, edgeGuard) {
+  const cornerStrength = clamp((curvature - 0.00012) / 0.00095, 0, 1);
+  if (cornerStrength <= 0) return 0;
+
+  const entryHeading = sampleHeadingAt(race.track, car.progress - lookahead * 0.35);
+  const apexHeading = sampleHeadingAt(race.track, car.progress + lookahead * 0.55);
+  const exitHeading = sampleHeadingAt(race.track, car.progress + lookahead * 1.25);
+  const signedEntry = normalizeAngle(apexHeading - entryHeading);
+  const signedExit = normalizeAngle(exitHeading - apexHeading);
+  const turnDirection = Math.sign(Math.abs(signedEntry) > Math.abs(signedExit) ? signedEntry : signedExit);
+  if (turnDirection === 0) return 0;
+
+  const aggression = car.aggression ?? car.personality?.baseAggression ?? 0.5;
+  const simulatorMode = isSimulatorPhysicsMode(race.physicsMode);
+  const safeEdge = race.track.width / 2 - VEHICLE_LIMITS.carWidth *
+    (simulatorMode ? 2.05 - aggression * 0.08 : 1.15 - aggression * 0.12);
+  const apexOffset = turnDirection * safeEdge *
+    (simulatorMode ? 0.42 + aggression * 0.05 : 0.72 + aggression * 0.08);
+
+  return apexOffset * cornerStrength * (1 - edgeGuard.pressure * (simulatorMode ? 0.82 : 0.65));
+}
+
+export function arcadePreviewSpeed(car, track, horizon, aggression, profile = racingDriverProfile(car)) {
+  const speed = simUnitsToMeters(car.speed);
+  const maxSpeed = simUnitsToMeters(VEHICLE_LIMITS.maxSpeed);
+  const surfaceGrip = arcadeSurfaceGrip(car);
+  let target = maxSpeed;
+  const previewHorizon = Math.min(horizon, BRAKING_LOOKAHEAD_MAX_DISTANCE);
+  const spacing = metersToSimUnits(12);
+  let previous = sampleHeadingAt(track, car.progress);
+  const sample = { heading: 0, curvature: 0 };
+  for (let distance = 0; distance <= previewHorizon; distance += spacing) {
+    sampleHeadingCurvatureAtInto(track, car.progress + distance, sample);
+    const segmentCurve = distance > 0 ? Math.min(Math.abs(normalizeAngle(sample.heading - previous)) / spacing, PREVIEW_CURVATURE_CAP) : 0;
+    previous = sample.heading;
+    const curve = Math.max(Math.abs(sample.curvature), segmentCurve);
+    const curvePerMeter = curve * metersToSimUnits(1);
+    const physicalCorner = arcadeTrackCornerSpeedLimit(car, curvePerMeter, surfaceGrip);
+    const ratedCorner = arcadeTrackCornerSpeedLimit(car, curvePerMeter, profile.lateralShare * surfaceGrip);
+    const corner = Math.min(physicalCorner, ratedCorner * profile.speedJudgementScale);
+    const availableDistance = Math.max(0, simUnitsToMeters(distance) - speed * profile.anticipationSeconds);
+    // Braking rises with speed in this model. Evaluating it at the lower future
+    // corner speed retains a conservative bound through the approach.
+    const deceleration = arcadeBrakingDeceleration(car, corner, profile);
+    target = Math.min(target, Math.sqrt(corner ** 2 + 2 * deceleration * availableDistance));
+  }
+  return target * 3.6;
+}