@inventure71/paddockjs 4.2.0 → 4.3.1

package/src/simulation/track/trackQuerySegments.js

@@ -0,0 +1,174 @@
+import { clamp } from '../simMath.js';
+
+export function createCenterlineSegments(samples, segmentCount) {
+  const startX = new Float64Array(segmentCount);
+  const startY = new Float64Array(segmentCount);
+  const endX = new Float64Array(segmentCount);
+  const endY = new Float64Array(segmentCount);
+  const deltaX = new Float64Array(segmentCount);
+  const deltaY = new Float64Array(segmentCount);
+  const lengthSquared = new Float64Array(segmentCount);
+  const startDistance = new Float64Array(segmentCount);
+  const endDistance = new Float64Array(segmentCount);
+  const distanceSpan = new Float64Array(segmentCount);
+  const heading = new Float64Array(segmentCount);
+  const normalX = new Float64Array(segmentCount);
+  const normalY = new Float64Array(segmentCount);
+  const endNormalX = new Float64Array(segmentCount);
+  const endNormalY = new Float64Array(segmentCount);
+  const curvature = new Float64Array(segmentCount);
+  const minX = new Float64Array(segmentCount);
+  const maxX = new Float64Array(segmentCount);
+  const minY = new Float64Array(segmentCount);
+  const maxY = new Float64Array(segmentCount);
+
+  for (let id = 0; id < segmentCount; id += 1) {
+    const start = samples[id];
+    const end = samples[id + 1];
+    startX[id] = start.x;
+    startY[id] = start.y;
+    endX[id] = end.x;
+    endY[id] = end.y;
+    deltaX[id] = end.x - start.x;
+    deltaY[id] = end.y - start.y;
+    lengthSquared[id] = deltaX[id] * deltaX[id] + deltaY[id] * deltaY[id];
+    startDistance[id] = start.distance;
+    endDistance[id] = end.distance;
+    distanceSpan[id] = end.distance - start.distance;
+    heading[id] = start.heading;
+    normalX[id] = start.normalX;
+    normalY[id] = start.normalY;
+    endNormalX[id] = end.normalX;
+    endNormalY[id] = end.normalY;
+    curvature[id] = start.curvature ?? 0;
+    minX[id] = Math.min(start.x, end.x);
+    maxX[id] = Math.max(start.x, end.x);
+    minY[id] = Math.min(start.y, end.y);
+    maxY[id] = Math.max(start.y, end.y);
+  }
+
+  return {
+    segmentCount,
+    startX,
+    startY,
+    endX,
+    endY,
+    deltaX,
+    deltaY,
+    lengthSquared,
+    startDistance,
+    endDistance,
+    distanceSpan,
+    heading,
+    normalX,
+    normalY,
+    endNormalX,
+    endNormalY,
+    curvature,
+    minX,
+    maxX,
+    minY,
+    maxY,
+  };
+}
+
+export function createPrecomputedSegmentNeighborhoods(segmentCount, radii) {
+  if (!segmentCount || !radii?.size) return new Map();
+  const neighborhoodsByRadius = new Map();
+  for (const radius of radii) {
+    const width = radius * 2 + 1;
+    const neighborhoods = new Array(segmentCount);
+    for (let centerSegmentId = 0; centerSegmentId < segmentCount; centerSegmentId += 1) {
+      const segmentIds = new Int32Array(width);
+      for (let index = 0; index < width; index += 1) {
+        segmentIds[index] = ((centerSegmentId + (index - radius)) % segmentCount + segmentCount) % segmentCount;
+      }
+      neighborhoods[centerSegmentId] = segmentIds;
+    }
+    neighborhoodsByRadius.set(radius, neighborhoods);
+  }
+  return neighborhoodsByRadius;
+}
+
+export function getPrecomputedSegmentNeighborhood(centerline, centerSegmentId, radius) {
+  const neighborhoods = centerline?.precomputedNeighborhoodsByRadius?.get(radius);
+  return neighborhoods?.[centerSegmentId] ?? null;
+}
+
+export function writeProjectionCandidate(target, {
+  segmentId,
+  x,
+  y,
+  distance,
+  heading,
+  normalX,
+  normalY,
+  curvature,
+  signedOffset,
+  distanceSquared,
+}) {
+  target.segmentId = segmentId;
+  target.x = x;
+  target.y = y;
+  target.distance = distance;
+  target.heading = heading;
+  target.normalX = normalX;
+  target.normalY = normalY;
+  target.curvature = curvature;
+  target.signedOffset = signedOffset;
+  target.crossTrackError = Math.abs(signedOffset);
+  target.distanceSquared = distanceSquared;
+  return target;
+}
+
+export function projectIndexedSegment(centerline, segmentId, position) {
+  if (centerline?.stats) centerline.stats.candidateProjectionObjectAllocations += 1;
+  const ax = centerline.startX[segmentId];
+  const ay = centerline.startY[segmentId];
+  const dx = centerline.deltaX[segmentId];
+  const dy = centerline.deltaY[segmentId];
+  const amount = centerline.lengthSquared[segmentId] > 0
+    ? clamp(((position.x - ax) * dx + (position.y - ay) * dy) / centerline.lengthSquared[segmentId], 0, 1)
+    : 0;
+  const x = ax + dx * amount;
+  const y = ay + dy * amount;
+  const distance = centerline.startDistance[segmentId] +
+    centerline.distanceSpan[segmentId] * amount;
+  const heading = centerline.heading[segmentId];
+  const normalX = centerline.normalX[segmentId];
+  const normalY = centerline.normalY[segmentId];
+  const px = position.x - x;
+  const py = position.y - y;
+  const signedOffset = px * normalX + py * normalY;
+
+  return {
+    segmentId,
+    x,
+    y,
+    distance,
+    heading,
+    normalX,
+    normalY,
+    curvature: centerline.curvature[segmentId],
+    signedOffset,
+    crossTrackError: Math.abs(signedOffset),
+    distanceSquared: px * px + py * py,
+  };
+}
+
+export function segmentFromIndex(centerline, segmentId) {
+  if (centerline?.stats) centerline.stats.raySegmentObjectAllocations += 1;
+  return {
+    segmentId,
+    startX: centerline.startX[segmentId],
+    startY: centerline.startY[segmentId],
+    endX: centerline.endX[segmentId],
+    endY: centerline.endY[segmentId],
+    startDistance: centerline.startDistance[segmentId],
+    endDistance: centerline.endDistance[segmentId],
+    normalX: centerline.normalX[segmentId],
+    normalY: centerline.normalY[segmentId],
+    endNormalX: centerline.endNormalX[segmentId],
+    endNormalY: centerline.endNormalY[segmentId],
+  };
+}

package/src/simulation/track/trackQueryStats.js

@@ -51,3 +51,15 @@ export function recordStat(index, bucket, key) {
   target[key] = (target[key] ?? 0) + 1;
   index.stats[bucket] = target;
 }
+
+export function resetTrackQueryStats(track) {
+  const stats = track?.queryIndex?.stats;
+  if (!stats) return null;
+  Object.assign(stats, createQueryStats());
+  return stats;
+}
+
+export function snapshotTrackQueryStats(track) {
+  const stats = track?.queryIndex?.stats;
+  return stats ? JSON.parse(JSON.stringify(stats)) : null;
+}

package/src/simulation/track/trackRayQueries.js

@@ -0,0 +1,165 @@
+import { gridCellForPoint } from './trackQueryGrid.js';
+import { ensureQueryScratch, ensureScratchArray, nextScratchEpoch } from './trackQueryScratch.js';
+import { segmentFromIndex } from './trackQuerySegments.js';
+import { finitePoint } from './trackMath.js';
+
+const RAY_TRACE_BUCKET_DEGREES = 10;
+
+export function queryTrackSegmentIdsAlongRay(track, origin, vector, maxDistance, margin = 0) {
+  const index = track?.queryIndex;
+  if (
+    !index?.centerline?.segmentCount ||
+    !finitePoint(origin) ||
+    !Number.isFinite(vector?.x) ||
+    !Number.isFinite(vector?.y) ||
+    !Number.isFinite(maxDistance) ||
+    maxDistance < 0
+  ) return null;
+
+  const grid = index.segmentGrid ?? index.grid;
+  const scratch = ensureQueryScratch(index);
+  const segmentMarks = ensureScratchArray(scratch, 'raySegmentMarks', index.centerline.segmentCount);
+  const cellMarks = ensureScratchArray(scratch, 'rayCellMarks', grid.columns * grid.rows);
+  const segmentEpoch = nextScratchEpoch(scratch, 'raySegmentEpoch', segmentMarks);
+  const cellEpoch = nextScratchEpoch(scratch, 'rayCellEpoch', cellMarks);
+  const ids = scratch.raySegmentIds;
+  ids.length = 0;
+  const radius = Math.max(0, Math.ceil(Math.max(0, margin) / grid.cellSize));
+  const step = Math.max(grid.cellSize * 0.5, 1);
+  const sampleCount = Math.max(1, Math.ceil(maxDistance / step));
+  const visitedCells = scratch.rayVisitedCells;
+  visitedCells.length = 0;
+  const point = scratch.rayTracePoint ?? { x: 0, y: 0 };
+  scratch.rayTracePoint = point;
+
+  const seed = seedRayTraceFromNearbyCache(index, grid, origin, vector, radius, maxDistance, segmentMarks, segmentEpoch, cellMarks, cellEpoch, ids);
+
+  for (let sample = 0; sample <= sampleCount; sample += 1) {
+    const distance = Math.min(maxDistance, sample * step);
+    point.x = origin.x + vector.x * distance;
+    point.y = origin.y + vector.y * distance;
+    const center = gridCellForPoint(grid, point, false);
+    if (!center) continue;
+    for (let row = center.row - radius; row <= center.row + radius; row += 1) {
+      for (let column = center.column - radius; column <= center.column + radius; column += 1) {
+        if (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows) continue;
+        const cellIndex = row * grid.columns + column;
+        if (cellMarks[cellIndex] === cellEpoch) continue;
+        cellMarks[cellIndex] = cellEpoch;
+        visitedCells.push(cellIndex);
+        const cell = grid.cells[cellIndex];
+        if (!cell) continue;
+        for (const segmentId of cell) {
+          if (segmentMarks[segmentId] === segmentEpoch) continue;
+          segmentMarks[segmentId] = segmentEpoch;
+          ids.push(segmentId);
+        }
+      }
+    }
+  }
+
+  storeRayTraceCache(index, grid, origin, vector, radius, maxDistance, ids, visitedCells, seed);
+  return ids;
+}
+
+export function queryTrackSegmentsAlongRay(track, origin, vector, maxDistance, margin = 0) {
+  const index = track?.queryIndex;
+  const ids = queryTrackSegmentIdsAlongRay(track, origin, vector, maxDistance, margin);
+  if (!ids) return null;
+  if (!ids.length) return [];
+  return ids.map((segmentId) => segmentFromIndex(index.centerline, segmentId));
+}
+
+function seedRayTraceFromNearbyCache(
+  index,
+  grid,
+  origin,
+  vector,
+  radius,
+  maxDistance,
+  segmentMarks,
+  segmentEpoch,
+  cellMarks,
+  cellEpoch,
+  ids,
+) {
+  const scratch = ensureQueryScratch(index);
+  const traceCache = scratch.rayTraceCache;
+  const originCell = gridCellForPoint(grid, origin, false);
+  if (!originCell) return null;
+  const bucket = rayTraceBucket(vector);
+  const base = rayTraceBaseKey(grid, originCell, radius);
+  const minimumSeedDistance = maxDistance * 0.85;
+  let seed = traceCache.get(rayTraceKey(base, bucket));
+  let bestSeedDistance = seed?.maxDistance ?? -Infinity;
+  if (bestSeedDistance < minimumSeedDistance) {
+    seed = null;
+    bestSeedDistance = -Infinity;
+  }
+  const beforeSeed = traceCache.get(rayTraceKey(base, bucket - 1));
+  if ((beforeSeed?.maxDistance ?? -Infinity) >= minimumSeedDistance && beforeSeed.maxDistance > bestSeedDistance) {
+    seed = beforeSeed;
+    bestSeedDistance = beforeSeed.maxDistance;
+  }
+  const afterSeed = traceCache.get(rayTraceKey(base, bucket + 1));
+  if ((afterSeed?.maxDistance ?? -Infinity) >= minimumSeedDistance && afterSeed.maxDistance > bestSeedDistance) {
+    seed = afterSeed;
+  }
+  if (!seed) return { base, bucket };
+
+  for (const segmentId of seed.segmentIds) {
+    if (segmentMarks[segmentId] === segmentEpoch) continue;
+    segmentMarks[segmentId] = segmentEpoch;
+    ids.push(segmentId);
+  }
+  for (const cellId of seed.cellIds) {
+    cellMarks[cellId] = cellEpoch;
+  }
+  return { base, bucket };
+}
+
+function storeRayTraceCache(index, grid, origin, vector, radius, maxDistance, segmentIds, cellIds, seed) {
+  const scratch = ensureQueryScratch(index);
+  const traceCache = scratch.rayTraceCache;
+  const originCell = gridCellForPoint(grid, origin, false);
+  if (!originCell) return;
+  const bucket = seed?.bucket ?? rayTraceBucket(vector);
+  const base = seed?.base ?? rayTraceBaseKey(grid, originCell, radius);
+  const key = rayTraceKey(base, bucket);
+  let entry = traceCache.get(key);
+  if (!entry) {
+    entry = {
+      maxDistance: 0,
+      segmentIds: [],
+      cellIds: [],
+    };
+    traceCache.set(key, entry);
+    if (index.stats) index.stats.rayTraceCacheEntryAllocations += 1;
+  }
+  entry.maxDistance = maxDistance;
+  entry.segmentIds.length = segmentIds.length;
+  for (let index = 0; index < segmentIds.length; index += 1) {
+    entry.segmentIds[index] = segmentIds[index];
+  }
+  entry.cellIds.length = cellIds.length;
+  for (let index = 0; index < cellIds.length; index += 1) {
+    entry.cellIds[index] = cellIds[index];
+  }
+  if (traceCache.size > 96) {
+    const oldestKey = traceCache.keys().next().value;
+    if (oldestKey) traceCache.delete(oldestKey);
+  }
+}
+
+function rayTraceBaseKey(grid, center, radius) {
+  return `${center.column}:${center.row}:${radius}:${grid.columns}:${grid.rows}`;
+}
+
+function rayTraceKey(base, bucket) {
+  return `${base}:${bucket}`;
+}
+
+function rayTraceBucket(vector) {
+  const angleDegrees = Math.atan2(vector.y, vector.x) * 180 / Math.PI;
+  return Math.round(angleDegrees / RAY_TRACE_BUCKET_DEGREES);
+}

package/src/simulation/vehicle/advancedContactResponse.js

@@ -0,0 +1,89 @@
+import { clamp } from '../simMath.js';
+import { SIM_UNITS_PER_METER } from '../units.js';
+import { ADVANCED_VEHICLE_MODEL } from './advancedVehicleModel.js';
+import { VEHICLE_GEOMETRY } from './vehicleGeometry.js';
+
+function inverseMass(car, fixed) {
+  if (fixed) return 0;
+  return 1 / (Number.isFinite(car.mass) && car.mass > 0 ? car.mass : 798);
+}
+
+function supportOffset(car, normalX, normalY, coordinate) {
+  const cos = Math.cos(car.heading);
+  const sin = Math.sin(car.heading);
+  const along = normalX * cos + normalY * sin;
+  const across = -normalX * sin + normalY * cos;
+  // A normal parallel to a face selects its center, rather than an arbitrary corner.
+  const longitudinal = Math.abs(along) < 1e-10 ? 0 : Math.sign(along) * VEHICLE_GEOMETRY.bodyLength / 2;
+  const lateral = Math.abs(across) < 1e-10 ? 0 : Math.sign(across) * VEHICLE_GEOMETRY.bodyWidth / 2;
+  return coordinate === 'x' ? cos * longitudinal - sin * lateral : sin * longitudinal + cos * lateral;
+}
+
+function velocityComponent(car, coordinate) {
+  if (Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)) {
+    return coordinate === 'x' ? car.velocityX : car.velocityY;
+  }
+  return (coordinate === 'x' ? Math.cos(car.heading) : Math.sin(car.heading)) * car.speed;
+}
+
+function writeVelocity(car, velocityX, velocityY, yawRate) {
+  car.velocityX = velocityX * SIM_UNITS_PER_METER;
+  car.velocityY = velocityY * SIM_UNITS_PER_METER;
+  car.speed = Math.hypot(car.velocityX, car.velocityY);
+  car.yawRate = yawRate;
+}
+
+export function applyAdvancedContactResponse(first, second, axis, {
+  restitution = 0,
+  firstFixed = false,
+  secondFixed = false,
+} = {}) {
+  const axisLength = Math.hypot(axis.x, axis.y);
+  if (!(axisLength > 0)) return 0;
+  const nx = axis.x / axisLength;
+  const ny = axis.y / axisLength;
+  const firstInverseMass = inverseMass(first, firstFixed);
+  const secondInverseMass = inverseMass(second, secondFixed);
+  if (firstInverseMass + secondInverseMass === 0) return 0;
+  const firstInverseInertia = firstInverseMass / ADVANCED_VEHICLE_MODEL.yawInertiaPerMass;
+  const secondInverseInertia = secondInverseMass / ADVANCED_VEHICLE_MODEL.yawInertiaPerMass;
+
+  let firstLever = 0;
+  let secondLever = 0;
+  if ([first.x, first.y, second.x, second.y].every(Number.isFinite)) {
+    // SAT supplies a normal but no clipped contact manifold. Approximate a common
+    // contact point by the midpoint of opposing body support features. This keeps
+    // equal/opposite impulses and their moments consistent without rewinding poses.
+    const dx = second.x - first.x;
+    const dy = second.y - first.y;
+    const supportX = supportOffset(first, nx, ny, 'x') + supportOffset(second, -nx, -ny, 'x');
+    const supportY = supportOffset(first, nx, ny, 'y') + supportOffset(second, -nx, -ny, 'y');
+    firstLever = ((dx + supportX) * ny - (dy + supportY) * nx) / (2 * SIM_UNITS_PER_METER);
+    secondLever = ((-dx + supportX) * ny - (-dy + supportY) * nx) / (2 * SIM_UNITS_PER_METER);
+  }
+
+  let firstVX = velocityComponent(first, 'x') / SIM_UNITS_PER_METER;
+  let firstVY = velocityComponent(first, 'y') / SIM_UNITS_PER_METER;
+  let secondVX = velocityComponent(second, 'x') / SIM_UNITS_PER_METER;
+  let secondVY = velocityComponent(second, 'y') / SIM_UNITS_PER_METER;
+  let firstYaw = first.yawRate ?? 0;
+  let secondYaw = second.yawRate ?? 0;
+  const closingVelocity = (secondVX - firstVX) * nx + (secondVY - firstVY) * ny +
+    secondYaw * secondLever - firstYaw * firstLever;
+  let impulse = 0;
+  if (closingVelocity < 0) {
+    const inverseEffectiveMass = firstInverseMass + secondInverseMass +
+      firstLever * firstLever * firstInverseInertia + secondLever * secondLever * secondInverseInertia;
+    impulse = -(1 + clamp(restitution, 0, 1)) * closingVelocity / inverseEffectiveMass;
+    firstVX -= impulse * nx * firstInverseMass;
+    firstVY -= impulse * ny * firstInverseMass;
+    secondVX += impulse * nx * secondInverseMass;
+    secondVY += impulse * ny * secondInverseMass;
+    firstYaw -= impulse * firstLever * firstInverseInertia;
+    secondYaw += impulse * secondLever * secondInverseInertia;
+  }
+
+  if (!firstFixed) writeVelocity(first, firstVX, firstVY, firstYaw);
+  if (!secondFixed) writeVelocity(second, secondVX, secondVY, secondYaw);
+  return impulse;
+}

package/src/simulation/vehicle/advancedTireForces.js

@@ -0,0 +1,92 @@
+import { clamp } from '../simMath.js';
+import { ADVANCED_VEHICLE_MODEL as MODEL, ADVANCED_WHEELS, advancedWheelSurface } from './advancedVehicleModel.js';
+
+// Quasi-static load transfer: both axles conserve their total vertical load.
+// A wheel can unload, but cannot pull down on the ground. This planar model
+// does not simulate roll/pitch displacement or suspension travel.
+export function advancedNormalLoads(car, speedMps, longitudinalAcceleration, lateralAcceleration) {
+  const weight = car.mass * MODEL.gravity;
+  const downforce = car.downforceCoefficient * MODEL.downforceScale * speedMps ** 2;
+  const aero = car.drsActive ? downforce * 0.82 : downforce;
+  const transfer = car.mass * longitudinalAcceleration * MODEL.centerOfGravityHeight / MODEL.wheelbase;
+  const total = weight + aero;
+  const front = clamp(weight * MODEL.frontWeightFraction + aero * MODEL.frontAeroFraction - transfer, 0, total);
+  const rear = total - front;
+  const lateralTransfer = car.mass * lateralAcceleration * MODEL.centerOfGravityHeight / MODEL.trackWidth;
+  const frontTransfer = clamp(lateralTransfer * MODEL.frontRollTransferFraction, -front / 2, front / 2);
+  const rearTransfer = clamp(lateralTransfer * (1 - MODEL.frontRollTransferFraction), -rear / 2, rear / 2);
+  return [front / 2 + frontTransfer, front / 2 - frontTransfer, rear / 2 + rearTransfer, rear / 2 - rearTransfer];
+}
+
+export function advancedTireForce({ normalLoad, nominalLoad, grip, tireFactor, surface, longitudinalDemand, forwardVelocity, lateralVelocity }) {
+  if (normalLoad <= 0) return { longitudinal: 0, lateral: 0, usage: 0, capacity: 0, slipAngle: 0 };
+  const capacity = contactCapacity(normalLoad, nominalLoad, grip, tireFactor, surface);
+  const slipAngle = Math.atan2(lateralVelocity, Math.max(Math.abs(forwardVelocity), MODEL.lowSpeedSlipReference));
+  const stiffness = MODEL.corneringStiffnessPerLoad * nominalLoad * (normalLoad / nominalLoad) ** 0.8;
+  const lateralDemand = -stiffness * Math.tan(slipAngle);
+  const demand = Math.hypot(longitudinalDemand, lateralDemand);
+  const usage = demand / Math.max(capacity, 1e-9);
+  const longitudinal = clamp(longitudinalDemand, -capacity, capacity);
+  const lateralCapacity = Math.sqrt(Math.max(0, capacity ** 2 - longitudinal ** 2));
+  // Longitudinal input is a requested force, not a slip ratio. Reserve its
+  // friction-circle share; the brush curve applies to the lateral slip demand.
+  const q = lateralCapacity > 1e-9 ? Math.min(Math.abs(lateralDemand) / (3 * lateralCapacity), 1) : 1;
+  let lateral = Math.sign(lateralDemand) * lateralCapacity * (1 - (1 - q) ** 3);
+  let longitudinalForce = longitudinal;
+  // With brake demand beyond adhesion, a sliding contact opposes its actual
+  // velocity. This captures directional loss under lock without wheel-spin state.
+  if (Math.abs(longitudinalDemand) >= capacity && longitudinalDemand * forwardVelocity < 0) {
+    const speed = Math.hypot(forwardVelocity, lateralVelocity);
+    longitudinalForce = -capacity * forwardVelocity / speed;
+    lateral = -capacity * lateralVelocity / speed;
+  }
+  return { longitudinal: longitudinalForce, lateral, usage, capacity, slipAngle };
+
+}
+
+// Policy-facing capacity estimate; the driver chooses how much margin to keep.
+// No controller gets additional grip beyond these same contact-patch capacities.
+function contactCapacity(normalLoad, nominalLoad, grip, tireFactor, surface) {
+  return grip * MODEL.tireGripScale * tireFactor * surface.grip * nominalLoad *
+    (normalLoad / nominalLoad) ** MODEL.tireLoadExponent;
+}
+
+export { contactCapacity as advancedContactCapacity };
+
+// Signed wheel-angle correction needed to produce the requested lateral
+// force. Tire-local velocity slip has the opposite sign in advancedTireForce.
+export function advancedLateralSlipAngle({ normalLoad, nominalLoad, longitudinalForce = 0, lateralForce, capacity }) {
+  if (!(normalLoad > 0) || !(nominalLoad > 0) || !(capacity > 0)) return 0;
+  const remaining = Math.sqrt(Math.max(0, capacity ** 2 - longitudinalForce ** 2));
+  if (!(remaining > 0)) return 0;
+  const q = 1 - Math.cbrt(1 - clamp(Math.abs(lateralForce) / remaining, 0, 1));
+  const lateralDemand = 3 * remaining * q;
+  const stiffness = MODEL.corneringStiffnessPerLoad * nominalLoad * (normalLoad / nominalLoad) ** 0.8;
+  return Math.sign(lateralForce) * Math.atan(lateralDemand / stiffness);
+}
+
+function summedCapacity(car, speedMps, tireFactor, rearOnly) {
+  const loads = advancedNormalLoads(car, speedMps, 0, 0);
+  let force = 0;
+  for (let index = 0; index < ADVANCED_WHEELS.length; index += 1) {
+    const wheel = ADVANCED_WHEELS[index];
+    if (rearOnly && wheel.front) continue;
+    const nominalLoad = car.mass * MODEL.gravity * (wheel.front ? MODEL.frontWeightFraction : 1 - MODEL.frontWeightFraction) / 2;
+    const surface = advancedWheelSurface(car, wheel.id);
+    force += contactCapacity(loads[index], nominalLoad, car.tireGrip, tireFactor, surface);
+  }
+  return force;
+}
+
+export function advancedLateralAccelerationLimit(car, speedMps, tireFactor) {
+  return summedCapacity(car, speedMps, tireFactor, false) / car.mass;
+}
+
+export function advancedRearForceCapacity(car, speedMps, tireFactor) {
+  return summedCapacity(car, speedMps, tireFactor, true);
+}
+
+export function advancedRollingResistanceForce(car, speedMps) {
+  const loads = advancedNormalLoads(car, speedMps, 0, 0);
+  return ADVANCED_WHEELS.reduce((force, wheel, index) => force + advancedWheelSurface(car, wheel.id).rolling * loads[index], 0);
+}

package/src/simulation/vehicle/advancedVehicleModel.js

@@ -0,0 +1,65 @@
+import { VEHICLE_GEOMETRY } from './vehicleGeometry.js';
+import { simUnitsToMeters } from '../units.js';
+
+// SI calibration for the package's DRS-era Formula-style car. Existing setup
+// ratings remain force/grip parameters; this is not a particular team's dataset.
+export const ADVANCED_VEHICLE_MODEL = Object.freeze({
+  gravity: 9.80665,
+  wheelbase: simUnitsToMeters(VEHICLE_GEOMETRY.wheelLongitudinalOffset * 2),
+  trackWidth: simUnitsToMeters(VEHICLE_GEOMETRY.wheelLateralOffset * 2),
+  frontWeightFraction: 0.5, // stored pose/velocity and collision origin are the chassis center
+  frontAeroFraction: 0.44,
+  frontRollTransferFraction: 0.52,
+  centerOfGravityHeight: 0.3,
+  yawInertiaPerMass: 1.65, // m²: yaw inertia = mass × radius of gyration squared
+  frontBrakeFraction: 0.57,
+  tireGripScale: 0.72,
+  tireLoadExponent: 0.9,
+  corneringStiffnessPerLoad: 28, // N/rad per N of normal load
+  maxIntegrationStep: 1 / 240,
+  lowSpeedSlipReference: 2.5, // m/s, regularizes the static tire limit
+  engineForceScale: 0.5, // legacy force rating to peak rear-axle wheel force
+  enginePowerSpeed: 28, // m/s: peak force × crossover speed gives the power envelope
+  airDensity: 1.225,
+  dragAreaScale: 4.5, // m² per existing dragCoefficient unit
+  downforceScale: 0.5, // existing coefficient × v² × scale gives newtons
+});
+
+export const ADVANCED_WHEELS = Object.freeze([
+  { id: 'front-left', front: true, side: -1 },
+  { id: 'front-right', front: true, side: 1 },
+  { id: 'rear-left', front: false, side: -1 },
+  { id: 'rear-right', front: false, side: 1 },
+].map((wheel) => Object.freeze({
+  ...wheel,
+  x: simUnitsToMeters(VEHICLE_GEOMETRY.wheelLongitudinalOffset) * (wheel.front ? 1 : -1),
+  y: simUnitsToMeters(VEHICLE_GEOMETRY.wheelLateralOffset) * wheel.side,
+})));
+
+const SURFACES = {
+  track: { grip: 1, rolling: 0.012 },
+  'pit-entry': { grip: 0.97, rolling: 0.015 },
+  'pit-lane': { grip: 0.97, rolling: 0.015 },
+  'pit-exit': { grip: 0.97, rolling: 0.015 },
+  'pit-box': { grip: 0.94, rolling: 0.02 },
+  kerb: { grip: 0.82, rolling: 0.035 },
+  gravel: { grip: 0.38, rolling: 0.19 },
+  grass: { grip: 0.3, rolling: 0.1 },
+  barrier: { grip: 0.2, rolling: 0.25 },
+};
+
+export function advancedWheelSurface(car, wheelId) {
+  const name = car.wheelStates?.find((wheel) => wheel.id === wheelId)?.surface ?? car.trackState?.surface;
+  return SURFACES[name] ?? SURFACES.track;
+}
+
+// Requested longitudinal drive force at full throttle, before tire adhesion.
+export function advancedDriveForce(car, forwardSpeedMps) {
+  return car.powerNewtons * ADVANCED_VEHICLE_MODEL.engineForceScale * Math.min(1, ADVANCED_VEHICLE_MODEL.enginePowerSpeed / Math.max(Math.abs(forwardSpeedMps), ADVANCED_VEHICLE_MODEL.enginePowerSpeed));
+}
+
+// Drag force is this coefficient times speed squared. The integrator applies
+// it opposite the velocity vector; pace control estimates straight resistance.
+export function advancedDragFactor(car) {
+  return 0.5 * ADVANCED_VEHICLE_MODEL.airDensity * car.dragCoefficient * ADVANCED_VEHICLE_MODEL.dragAreaScale * (car.drsActive ? 0.72 : 1);
+}