@inventure71/paddockjs 0.3.0 → 1.0.0

package/src/simulation/units.js

@@ -1,9 +1,11 @@
-import { VEHICLE_LIMITS } from './vehiclePhysics.js';
-
 export const REAL_F1_CAR_LENGTH_METERS = 5.63;
+export const REAL_F1_CAR_WIDTH_METERS = 1.9;
+export const REAL_F1_WHEELBASE_METERS = 3.6;
 export const TARGET_F1_TOP_SPEED_KPH = 330;
-export const SIM_UNITS_PER_METER = (VEHICLE_LIMITS.maxSpeed * 3.6) / TARGET_F1_TOP_SPEED_KPH;
-export const VISUAL_CAR_LENGTH_METERS = VEHICLE_LIMITS.carLength / SIM_UNITS_PER_METER;
+export const SIM_UNITS_PER_METER = 12;
+export const TOP_SPEED_SIM_UNITS_PER_SECOND = (TARGET_F1_TOP_SPEED_KPH / 3.6) * SIM_UNITS_PER_METER;
+export const VISUAL_CAR_LENGTH_METERS = REAL_F1_CAR_LENGTH_METERS;
+export const VISUAL_CAR_WIDTH_METERS = REAL_F1_CAR_WIDTH_METERS;
 
 export function metersToSimUnits(meters) {
   return meters * SIM_UNITS_PER_METER;

package/src/simulation/vehicleGeometry.js

@@ -0,0 +1,247 @@
+import { normalizeAngle } from './simMath.js';
+import {
+  REAL_F1_CAR_LENGTH_METERS,
+  REAL_F1_CAR_WIDTH_METERS,
+  REAL_F1_WHEELBASE_METERS,
+  metersToSimUnits,
+} from './units.js';
+
+export const VEHICLE_GEOMETRY = {
+  visualLength: metersToSimUnits(REAL_F1_CAR_LENGTH_METERS),
+  visualWidth: metersToSimUnits(REAL_F1_CAR_WIDTH_METERS),
+  bodyLength: metersToSimUnits(4.65),
+  bodyWidth: metersToSimUnits(1.24),
+  wheelLength: metersToSimUnits(0.72),
+  wheelWidth: metersToSimUnits(0.38),
+  wheelLongitudinalOffset: metersToSimUnits(REAL_F1_WHEELBASE_METERS / 2),
+  wheelLateralOffset: metersToSimUnits((REAL_F1_CAR_WIDTH_METERS - 0.38) / 2),
+};
+
+const WHEEL_SPECS = [
+  { id: 'front-left', longitudinal: 1, lateral: -1 },
+  { id: 'front-right', longitudinal: 1, lateral: 1 },
+  { id: 'rear-left', longitudinal: -1, lateral: -1 },
+  { id: 'rear-right', longitudinal: -1, lateral: 1 },
+];
+
+function finiteOr(value, fallback) {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function vehiclePose(car, { previous = false } = {}) {
+  const x = previous ? finiteOr(car.previousX, car.x) : car.x;
+  const y = previous ? finiteOr(car.previousY, car.y) : car.y;
+  const heading = previous ? finiteOr(car.previousHeading, car.heading) : car.heading;
+
+  return {
+    x: finiteOr(x, 0),
+    y: finiteOr(y, 0),
+    heading: normalizeAngle(finiteOr(heading, 0)),
+  };
+}
+
+export function vehicleAxes(heading) {
+  const cos = Math.cos(heading);
+  const sin = Math.sin(heading);
+  return {
+    forward: { x: cos, y: sin },
+    right: { x: -sin, y: cos },
+  };
+}
+
+function offsetPoint(center, axes, longitudinal, lateral) {
+  return {
+    x: center.x + axes.forward.x * longitudinal + axes.right.x * lateral,
+    y: center.y + axes.forward.y * longitudinal + axes.right.y * lateral,
+  };
+}
+
+export function createOrientedRect({ id, type, center, heading, length, width }) {
+  const axes = vehicleAxes(heading);
+  const halfLength = length / 2;
+  const halfWidth = width / 2;
+  const corners = [
+    offsetPoint(center, axes, halfLength, halfWidth),
+    offsetPoint(center, axes, halfLength, -halfWidth),
+    offsetPoint(center, axes, -halfLength, -halfWidth),
+    offsetPoint(center, axes, -halfLength, halfWidth),
+  ];
+
+  return {
+    id,
+    type,
+    center,
+    heading,
+    length,
+    width,
+    halfLength,
+    halfWidth,
+    forward: axes.forward,
+    right: axes.right,
+    corners,
+  };
+}
+
+export function createVehicleGeometry(car, options = {}) {
+  const pose = vehiclePose(car, options);
+  const axes = vehicleAxes(pose.heading);
+  const center = { x: pose.x, y: pose.y };
+  const body = createOrientedRect({
+    id: 'body',
+    type: 'body',
+    center,
+    heading: pose.heading,
+    length: VEHICLE_GEOMETRY.bodyLength,
+    width: VEHICLE_GEOMETRY.bodyWidth,
+  });
+  const wheels = WHEEL_SPECS.map((spec) => {
+    const wheelCenter = offsetPoint(
+      center,
+      axes,
+      spec.longitudinal * VEHICLE_GEOMETRY.wheelLongitudinalOffset,
+      spec.lateral * VEHICLE_GEOMETRY.wheelLateralOffset,
+    );
+    return createOrientedRect({
+      id: spec.id,
+      type: 'wheel',
+      center: wheelCenter,
+      heading: pose.heading,
+      length: VEHICLE_GEOMETRY.wheelLength,
+      width: VEHICLE_GEOMETRY.wheelWidth,
+    });
+  });
+
+  return {
+    body,
+    wheels,
+    contactPatches: wheels,
+    shapes: [body, ...wheels],
+  };
+}
+
+function geometryPoseSignature(pose) {
+  return [
+    pose.x,
+    pose.y,
+    pose.heading,
+    pose.previousX,
+    pose.previousY,
+    pose.previousHeading,
+  ].join(':');
+}
+
+function geometryPose(car) {
+  const x = finiteOr(car.x, 0);
+  const y = finiteOr(car.y, 0);
+  const heading = normalizeAngle(finiteOr(car.heading, 0));
+  return {
+    x,
+    y,
+    heading,
+    previousX: finiteOr(car.previousX, x),
+    previousY: finiteOr(car.previousY, y),
+    previousHeading: normalizeAngle(finiteOr(car.previousHeading, heading)),
+  };
+}
+
+function geometryStateMatches(car, state) {
+  const pose = state?.pose;
+  if (!pose) return false;
+  const x = finiteOr(car.x, 0);
+  const y = finiteOr(car.y, 0);
+  const heading = normalizeAngle(finiteOr(car.heading, 0));
+  return (
+    pose.x === x &&
+    pose.y === y &&
+    pose.heading === heading &&
+    pose.previousX === finiteOr(car.previousX, x) &&
+    pose.previousY === finiteOr(car.previousY, y) &&
+    pose.previousHeading === normalizeAngle(finiteOr(car.previousHeading, heading))
+  );
+}
+
+export function createVehicleShapeAabb(shape) {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let index = 0; index < shape.corners.length; index += 1) {
+    const corner = shape.corners[index];
+    if (corner.x < minX) minX = corner.x;
+    if (corner.x > maxX) maxX = corner.x;
+    if (corner.y < minY) minY = corner.y;
+    if (corner.y > maxY) maxY = corner.y;
+  }
+  return {
+    minX,
+    maxX,
+    minY,
+    maxY,
+  };
+}
+
+export function mergeAabbs(aabbs) {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let index = 0; index < aabbs.length; index += 1) {
+    const aabb = aabbs[index];
+    if (aabb.minX < minX) minX = aabb.minX;
+    if (aabb.maxX > maxX) maxX = aabb.maxX;
+    if (aabb.minY < minY) minY = aabb.minY;
+    if (aabb.maxY > maxY) maxY = aabb.maxY;
+  }
+  return { minX, maxX, minY, maxY };
+}
+
+export function createVehicleGeometryState(car) {
+  const pose = geometryPose(car);
+  const current = createVehicleGeometry(car);
+  const previous = createVehicleGeometry(car, { previous: true });
+  const bodyAabb = createVehicleShapeAabb(current.body);
+  const previousBodyAabb = createVehicleShapeAabb(previous.body);
+  const sweptBodyAabb = mergeAabbs([previousBodyAabb, bodyAabb]);
+
+  return {
+    pose,
+    signature: geometryPoseSignature(pose),
+    current,
+    previous,
+    body: current.body,
+    wheels: current.wheels,
+    contactPatches: current.contactPatches,
+    bodyAabb,
+    previousBodyAabb,
+    sweptBodyAabb,
+  };
+}
+
+export function getVehicleGeometryState(car) {
+  if (geometryStateMatches(car, car.geometryState)) return car.geometryState;
+  car.geometryState = createVehicleGeometryState(car);
+  return car.geometryState;
+}
+
+export function createVehicleAabb(car, options = {}) {
+  const geometry = createVehicleGeometry(car, options);
+  return mergeAabbs(geometry.shapes.map(createVehicleShapeAabb));
+}
+
+export function interpolateVehiclePose(car, amount) {
+  const previousX = finiteOr(car.previousX, car.x);
+  const previousY = finiteOr(car.previousY, car.y);
+  const previousHeading = finiteOr(car.previousHeading, car.heading);
+  const headingDelta = normalizeAngle(finiteOr(car.heading, 0) - previousHeading);
+
+  return {
+    ...car,
+    x: previousX + (finiteOr(car.x, previousX) - previousX) * amount,
+    y: previousY + (finiteOr(car.y, previousY) - previousY) * amount,
+    heading: normalizeAngle(previousHeading + headingDelta * amount),
+  };
+}
+
+export function getCarCorners(car) {
+  return createVehicleGeometry(car).body.corners;
+}

package/src/simulation/vehiclePhysics.js

@@ -1,32 +1,75 @@
 import { clamp, normalizeAngle } from './simMath.js';
+import {
+  REAL_F1_WHEELBASE_METERS,
+  SIM_UNITS_PER_METER,
+  TOP_SPEED_SIM_UNITS_PER_SECOND,
+  simUnitsToMeters,
+  metersToSimUnits,
+} from './units.js';
+import { VEHICLE_GEOMETRY, getCarCorners } from './vehicleGeometry.js';
 
 const G = 9.80665;
 
 export const VEHICLE_LIMITS = {
-  wheelbase: 3.65,
+  wheelbase: metersToSimUnits(REAL_F1_WHEELBASE_METERS),
   maxSteer: 0.56,
   steerRate: 2.35,
-  maxSpeed: 192,
-  carLength: 66,
-  carWidth: 21,
+  maxSpeed: TOP_SPEED_SIM_UNITS_PER_SECOND,
+  carLength: VEHICLE_GEOMETRY.visualLength,
+  carWidth: VEHICLE_GEOMETRY.visualWidth,
 };
 
 const SURFACE_MODEL = {
   track: { grip: 1, drag: 0, rollingResistance: 0 },
+  'pit-entry': { grip: 0.96, drag: 0.04, rollingResistance: 0.012 },
+  'pit-lane': { grip: 0.96, drag: 0.04, rollingResistance: 0.012 },
+  'pit-exit': { grip: 0.96, drag: 0.04, rollingResistance: 0.012 },
+  'pit-box': { grip: 0.94, drag: 0.08, rollingResistance: 0.025 },
   kerb: { grip: 0.92, drag: 0.12, rollingResistance: 0.045 },
-  gravel: { grip: 0.43, drag: 2.6, rollingResistance: 0.48 },
+  gravel: { grip: 0.43, drag: 4.0, rollingResistance: 0.68 },
   grass: { grip: 0.34, drag: 1.9, rollingResistance: 0.36 },
   barrier: { grip: 0.18, drag: 9, rollingResistance: 1.2 },
 };
+const WHEEL_DRAG_YAW_GAIN = 0.08;
+const MAX_WHEEL_DRAG_YAW_RATE = 0.22;
 
 function accelerationLimit(speed, surfaceGrip) {
   const speedRatio = clamp(speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
-  return surfaceGrip * (17 * (1 - speedRatio ** 2.1) + 1.2);
+  return SIM_UNITS_PER_METER * surfaceGrip * (17 * (1 - speedRatio ** 2.1) + 1.2);
 }
 
 function brakingLimit(speed, surfaceGrip) {
   const speedRatio = clamp(speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
-  return surfaceGrip * (20 + speedRatio * 14);
+  return SIM_UNITS_PER_METER * surfaceGrip * (20 + speedRatio * 14);
+}
+
+export function tirePerformanceFactor(tireEnergy = 100) {
+  const normalized = clamp((Number(tireEnergy) || 1) / 100, 0.01, 1);
+  return clamp(0.45 + 0.55 * normalized ** 0.72, 0.45, 1);
+}
+
+function surfaceResistance(surfaceName) {
+  const surface = SURFACE_MODEL[surfaceName] ?? SURFACE_MODEL.track;
+  return surface.drag * 0.14 + surface.rollingResistance * 2.4 + (1 - surface.grip) * 0.65;
+}
+
+function sideWheelResistance(wheels, side) {
+  const sideWheels = wheels.filter((wheel) => wheel.id?.endsWith(`-${side}`));
+  if (!sideWheels.length) return 0;
+  return sideWheels.reduce((total, wheel) => total + surfaceResistance(wheel.surface), 0) / sideWheels.length;
+}
+
+function wheelDragYawRate(car) {
+  const wheels = Array.isArray(car.wheelStates) ? car.wheelStates : [];
+  if (!wheels.length) return 0;
+  const leftResistance = sideWheelResistance(wheels, 'left');
+  const rightResistance = sideWheelResistance(wheels, 'right');
+  const speedFactor = clamp(car.speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
+  return clamp(
+    (rightResistance - leftResistance) * speedFactor * WHEEL_DRAG_YAW_GAIN,
+    -MAX_WHEEL_DRAG_YAW_RATE,
+    MAX_WHEEL_DRAG_YAW_RATE,
+  );
 }
 
 export function integrateVehiclePhysics(car, controls, dt) {
@@ -41,64 +84,53 @@ export function integrateVehiclePhysics(car, controls, dt) {
   const throttle = clamp(controls.throttle ?? 0, 0, 1);
   const brake = clamp(controls.brake ?? 0, 0, 1);
   const surface = SURFACE_MODEL[car.trackState?.surface] ?? SURFACE_MODEL.track;
-  const surfaceGrip = surface.grip;
+  const tireFactor = tirePerformanceFactor(car.tireEnergy ?? 100);
+  const surfaceGrip = surface.grip * tireFactor;
   const dragMultiplier = car.drsActive ? 0.42 : 1;
   const speedRatio = clamp(car.speed / VEHICLE_LIMITS.maxSpeed, 0, 1);
-  const engineForce = throttle * car.powerNewtons * Math.max(0.12, 1 - speedRatio ** 1.15);
+  const engineForce = throttle *
+    car.powerNewtons *
+    (car.drsActive ? 1.08 : 1) *
+    Math.max(0.12, 1 - speedRatio ** 1.15);
   const brakeForce = brake * car.brakeNewtons;
-  const dragForce = (car.dragCoefficient * dragMultiplier * 0.12 + surface.drag) * car.speed * car.speed;
+  const speedMetersPerSecondBefore = simUnitsToMeters(car.speed);
+  const dragForce = (car.dragCoefficient * dragMultiplier * 0.12 + surface.drag) *
+    speedMetersPerSecondBefore * speedMetersPerSecondBefore;
   const rollingForce = surface.rollingResistance * car.mass * G;
-  const driveAcceleration = clamp(engineForce / car.mass, 0, accelerationLimit(car.speed, surfaceGrip));
-  const brakeDeceleration = clamp(brakeForce / car.mass, 0, brakingLimit(car.speed, surfaceGrip));
-  const dragDeceleration = (dragForce + rollingForce) / car.mass;
-  const acceleration = driveAcceleration - brakeDeceleration - dragDeceleration;
+  const driveAcceleration = clamp((engineForce / car.mass) * SIM_UNITS_PER_METER, 0, accelerationLimit(car.speed, surfaceGrip));
+  const drsAcceleration = car.drsActive ? driveAcceleration * 0.06 : 0;
+  const brakeDeceleration = clamp((brakeForce / car.mass) * SIM_UNITS_PER_METER, 0, brakingLimit(car.speed, surfaceGrip));
+  const dragDeceleration = ((dragForce + rollingForce) / car.mass) * SIM_UNITS_PER_METER;
+  const acceleration = driveAcceleration + drsAcceleration - brakeDeceleration - dragDeceleration;
 
   car.speed = clamp(car.speed + acceleration * dt, 0, VEHICLE_LIMITS.maxSpeed);
 
-  const rawYawRate = car.speed / VEHICLE_LIMITS.wheelbase * Math.tan(car.steeringAngle);
-  const downforceGrip = car.downforceCoefficient * car.speed * car.speed / car.mass;
-  const tyreConditionGrip = clamp(0.82 + (car.tireEnergy ?? 100) / 560, 0.82, 1);
-  const maxYawRate = ((car.tireGrip * tyreConditionGrip * G + downforceGrip) * surfaceGrip) / Math.max(car.speed, 8);
-  car.yawRate = clamp(rawYawRate, -maxYawRate, maxYawRate);
+  const speedMetersPerSecond = simUnitsToMeters(car.speed);
+  const rawYawRate = (speedMetersPerSecond / REAL_F1_WHEELBASE_METERS) *
+    Math.tan(car.steeringAngle) *
+    tireFactor;
+  const downforceGrip = car.downforceCoefficient * speedMetersPerSecond * speedMetersPerSecond / car.mass;
+  const tyreConditionGrip = tireFactor;
+  const maxYawRate = ((car.tireGrip * tyreConditionGrip * G + downforceGrip) * surfaceGrip) /
+    Math.max(speedMetersPerSecond, 1);
+  const steeringYawRate = clamp(rawYawRate, -maxYawRate, maxYawRate);
+  const requestedWheelDragYawRate = wheelDragYawRate(car);
+  car.yawRate = clamp(steeringYawRate + requestedWheelDragYawRate, -maxYawRate, maxYawRate);
+  car.wheelDragYawRate = car.yawRate - steeringYawRate;
   car.turnRadius = Math.abs(car.yawRate) < 0.001 ? Infinity : car.speed / Math.abs(car.yawRate);
   car.heading = normalizeAngle(car.heading + car.yawRate * dt);
   car.x += Math.cos(car.heading) * car.speed * dt;
   car.y += Math.sin(car.heading) * car.speed * dt;
   car.throttle = throttle;
   car.brake = brake;
-  car.lateralAcceleration = car.speed * car.yawRate;
-  car.steerSaturation = rawYawRate === 0 ? 0 : Math.abs(car.yawRate / rawYawRate);
+  car.lateralAcceleration = speedMetersPerSecond * car.yawRate;
+  car.steerSaturation = rawYawRate === 0 ? 0 : Math.abs(steeringYawRate / rawYawRate);
   const tyreLoad = Math.abs(car.lateralAcceleration) / G;
-  const wearRate = 0.035 + tyreLoad * 0.11 + brake * 0.07 + throttle * 0.025;
-  car.tireEnergy = clamp((car.tireEnergy ?? 100) - wearRate * dt, 38, 100);
+  const tireCare = clamp(Number(car.tireCare) || 1, 0.45, 1.8);
+  const wearRate = (0.035 + tyreLoad * 0.11 + brake * 0.07 + throttle * 0.025) / tireCare;
+  car.tireEnergy = clamp((car.tireEnergy ?? 100) - wearRate * dt, 1, 100);
 
   return car;
 }
 
-export function getCarCorners(car) {
-  const halfLength = VEHICLE_LIMITS.carLength / 2;
-  const halfWidth = VEHICLE_LIMITS.carWidth / 2;
-  const cos = Math.cos(car.heading);
-  const sin = Math.sin(car.heading);
-  const forward = { x: cos, y: sin };
-  const right = { x: -sin, y: cos };
-
-  return [
-    {
-      x: car.x + forward.x * halfLength + right.x * halfWidth,
-      y: car.y + forward.y * halfLength + right.y * halfWidth,
-    },
-    {
-      x: car.x + forward.x * halfLength - right.x * halfWidth,
-      y: car.y + forward.y * halfLength - right.y * halfWidth,
-    },
-    {
-      x: car.x - forward.x * halfLength - right.x * halfWidth,
-      y: car.y - forward.y * halfLength - right.y * halfWidth,
-    },
-    {
-      x: car.x - forward.x * halfLength + right.x * halfWidth,
-      y: car.y - forward.y * halfLength + right.y * halfWidth,
-    },
-  ];
-}
+export { getCarCorners };