@series-inc/rundot-kinetix 0.0.0-bootstrap.0

package/native/kinetix-fixed1000-physics.cpp

@@ -0,0 +1,887 @@
+// Verbatim C++ transliteration of the syncplay physics slice (see header).
+// Reference: venus packages/syncplay/src/physics3d.ts (createDeterministicPhysicsWorld3D,
+// buildSolverBody, runRigidSolver readback), physics3d-solver.ts (solveRigidStep,
+// sphereSphere/sphereBox narrowphase, solveContactSoft, applyImpulseScalar),
+// physics3d-shared.ts (solverSqrt, quantizeDistance, vector kernel).
+//
+// Slice collapse facts (verified against the sources):
+// - No material -> combined mu = restitution = 0; tangent solves are numeric
+//   no-ops but are kept structurally (they touch +/-0 signs).
+// - No `orientation` on any body -> angularLock = {0,0,0} -> the locked world
+//   inverse inertia is the zero matrix; identity quaternions everywhere.
+// - Bodies are fresh each call: sleeping=false, lowVelFrames=0, warm cache
+//   empty, no joints, no CCD. islandSleep can never trip within one step from
+//   a fresh world (lowVelFrames <= 1 < SLEEP_FRAMES 20), so it is omitted.
+
+#include "kinetix-fixed1000-physics.hpp"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <limits>
+
+namespace {
+
+// ---------------------------------------------------------------------------
+// JS numeric semantics
+// ---------------------------------------------------------------------------
+
+// ECMAScript Math.round: nearest integer, ties toward +Infinity, preserves -0
+// for -0.5 <= x < 0. V8 computes it as ceil(x) minus 1 when ceil overshoots by
+// more than 0.5 -- NOT floor(x+0.5) (which double-rounds near ties).
+double jsRound(double x) {
+  double r = std::ceil(x);
+  if (r - 0.5 <= x) {
+    return r;
+  }
+  return r - 1.0;
+}
+
+// ECMAScript Math.max(a, b): NaN-propagating, +0 beats -0.
+double jsMax(double a, double b) {
+  if (std::isnan(a) || std::isnan(b)) {
+    return std::numeric_limits<double>::quiet_NaN();
+  }
+  if (a > b) {
+    return a;
+  }
+  if (b > a) {
+    return b;
+  }
+  if (a == 0.0) {
+    return std::signbit(a) ? b : a;
+  }
+  return a;
+}
+
+// physics3d-shared.ts clampNumber
+double clampNum(double value, double lo, double hi) {
+  return value < lo ? lo : value > hi ? hi : value;
+}
+
+// physics3d-shared.ts quantizeDistance
+double quantizeDistance(double distance) {
+  const double quantized = jsRound(distance * 1e6) / 1e6;
+  return quantized == 0.0 ? 0.0 : quantized;
+}
+
+// physics3d-shared.ts solverSqrt (unquantized Newton, exact seed schedule)
+double solverSqrt(double value) {
+  if (value <= 0.0) {
+    return 0.0;
+  }
+  if (!std::isfinite(value)) {
+    return value;
+  }
+  double estimate = 1.0;
+  double magnitude = value;
+  while (magnitude >= 4.0) {
+    magnitude /= 4.0;
+    estimate *= 2.0;
+  }
+  if (magnitude > 1.0) {
+    estimate *= 2.0;
+  }
+  for (int iteration = 0; iteration < 8; iteration += 1) {
+    estimate = (estimate + value / estimate) / 2.0;
+  }
+  return estimate;
+}
+
+// ---------------------------------------------------------------------------
+// Vector / quaternion / matrix kernel (physics3d-shared.ts, verbatim order)
+// ---------------------------------------------------------------------------
+
+struct Vec3 {
+  double x, y, z;
+};
+
+struct Quat {
+  double x, y, z, w;
+};
+
+using Mat3 = std::array<double, 9>;
+
+constexpr Vec3 ZERO_VEC{0.0, 0.0, 0.0};
+
+Vec3 addV(const Vec3& a, const Vec3& b) { return {a.x + b.x, a.y + b.y, a.z + b.z}; }
+Vec3 subV(const Vec3& a, const Vec3& b) { return {a.x - b.x, a.y - b.y, a.z - b.z}; }
+Vec3 scaleV(const Vec3& a, double s) { return {a.x * s, a.y * s, a.z * s}; }
+double dotV(const Vec3& a, const Vec3& b) { return a.x * b.x + a.y * b.y + a.z * b.z; }
+Vec3 crossV(const Vec3& a, const Vec3& b) {
+  return {
+    a.y * b.z - a.z * b.y,
+    a.z * b.x - a.x * b.z,
+    a.x * b.y - a.y * b.x,
+  };
+}
+
+Mat3 quatToMat3(const Quat& q) {
+  const double x = q.x;
+  const double y = q.y;
+  const double z = q.z;
+  const double w = q.w;
+  return {
+    1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y),
+    2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x),
+    2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y),
+  };
+}
+
+Vec3 mulMat3Vec(const Mat3& m, const Vec3& a) {
+  return {
+    m[0] * a.x + m[1] * a.y + m[2] * a.z,
+    m[3] * a.x + m[4] * a.y + m[5] * a.z,
+    m[6] * a.x + m[7] * a.y + m[8] * a.z,
+  };
+}
+
+// World-space inverse inertia = R * diag(invI) * R^T (physics3d-shared.ts)
+Mat3 worldInvInertia(const Mat3& rot, const Vec3& invI) {
+  const double invIArr[3] = {invI.x, invI.y, invI.z};
+  Mat3 out{};
+  for (int row = 0; row < 3; row += 1) {
+    for (int col = 0; col < 3; col += 1) {
+      out[row * 3 + col] =
+        rot[row * 3 + 0] * invIArr[0] * rot[col * 3 + 0] +
+        rot[row * 3 + 1] * invIArr[1] * rot[col * 3 + 1] +
+        rot[row * 3 + 2] * invIArr[2] * rot[col * 3 + 2];
+    }
+  }
+  return out;
+}
+
+Quat quatConjugate(const Quat& q) { return {-q.x, -q.y, -q.z, q.w}; }
+
+// Rotate a vector by a quaternion using only mul/add/cross.
+Vec3 rotatePointByQuat(const Quat& q, const Vec3& p) {
+  const Vec3 u{q.x, q.y, q.z};
+  const Vec3 t = scaleV(crossV(u, p), 2.0);
+  return addV(addV(p, scaleV(t, q.w)), crossV(u, t));
+}
+
+Vec3 rotatePointByQuatInverse(const Quat& q, const Vec3& p) {
+  return rotatePointByQuat(quatConjugate(q), p);
+}
+
+// ---------------------------------------------------------------------------
+// Solver constants (physics3d-solver.ts SOLVER_CONSTANTS + module constants)
+// ---------------------------------------------------------------------------
+
+constexpr double SLOP = 0.005;
+constexpr double LINEAR_DAMPING = 0.995;
+constexpr double ANGULAR_DAMPING = 0.98;
+constexpr int SUBSTEPS = 6;
+constexpr int RELAX_ITERATION_SCALE = 2;
+constexpr double CONTACT_ZETA = 10.0;
+constexpr double CONTACT_HERTZ_FRACTION = 0.25;
+constexpr double STATIC_HERTZ_SCALE = 2.0;
+constexpr double MAX_CONTACT_PUSHOUT = 0.05;
+constexpr double RESTITUTION_THRESHOLD = 1.0;
+constexpr double TWO_PI = 6.283185307179586;
+constexpr int VELOCITY_ITERATIONS = 3;  // physics3d.ts DEFAULT_VELOCITY_ITERATIONS
+constexpr double DT = 1.0;
+constexpr double GRAVITY_Y = 0.0;
+
+// ---------------------------------------------------------------------------
+// Solver body (buildSolverBody, physics3d.ts, specialized to the slice)
+// ---------------------------------------------------------------------------
+
+struct SBody {
+  int index = 0;
+  bool isDynamic = false;
+  bool sleeping = false;  // fresh worlds: always false
+  Vec3 p{}, v{}, w{}, vb{}, wb{};
+  Quat q{0.0, 0.0, 0.0, 1.0};  // no body has `orientation`
+  Vec3 invMassVec{};
+  Vec3 invInertiaLocal{};
+  Vec3 angularLock{};  // hasOrientation=false -> {0,0,0}
+  double linearDamping = LINEAR_DAMPING;
+  double angularDamping = ANGULAR_DAMPING;
+  double gravityScale = 1.0;
+  bool isSphere = false;
+  double radius = 0.0;
+  Vec3 half{};
+  int layer = 0;
+  unsigned mask = 0;
+};
+
+bool solid(const SBody& b) { return b.isDynamic && !b.sleeping; }
+
+// physics3d.ts deriveInverseInertia (sphere + box arms; other shapes are
+// outside the slice).
+Vec3 deriveInverseInertia(const SBody& proto, double mass) {
+  if (proto.isSphere) {
+    const double i = (2.0 / 5.0) * mass * proto.radius * proto.radius;
+    return {1.0 / i, 1.0 / i, 1.0 / i};
+  }
+  const double sx = 2.0 * proto.half.x;
+  const double sy = 2.0 * proto.half.y;
+  const double sz = 2.0 * proto.half.z;
+  const double ix = (mass / 12.0) * (sy * sy + sz * sz);
+  const double iy = (mass / 12.0) * (sx * sx + sz * sz);
+  const double iz = (mass / 12.0) * (sx * sx + sy * sy);
+  return {1.0 / ix, 1.0 / iy, 1.0 / iz};
+}
+
+// physics3d-solver.ts worldInvInertiaLocked
+Mat3 worldInvInertiaLocked(const SBody& b) {
+  if (!solid(b)) {
+    return {0, 0, 0, 0, 0, 0, 0, 0, 0};
+  }
+  const Mat3 base = worldInvInertia(quatToMat3(b.q), b.invInertiaLocal);
+  const double lockArr[3] = {b.angularLock.x, b.angularLock.y, b.angularLock.z};
+  Mat3 out{};
+  for (int row = 0; row < 3; row += 1) {
+    for (int col = 0; col < 3; col += 1) {
+      out[row * 3 + col] = base[row * 3 + col] * lockArr[row] * lockArr[col];
+    }
+  }
+  return out;
+}
+
+Vec3 invMassOf(const SBody& b) { return solid(b) ? b.invMassVec : ZERO_VEC; }
+
+// ---------------------------------------------------------------------------
+// Narrowphase (physics3d-solver.ts, sphere-sphere + sphere-box only; box-box
+// pairs are both static and never reach the narrowphase in this slice)
+// ---------------------------------------------------------------------------
+
+struct ContactPoint {
+  Vec3 rA{}, rB{};
+  double penetration = 0.0;
+  int feature = 0;
+};
+
+struct Manifold {
+  int a = 0;
+  int b = 0;
+  Vec3 normal{};
+  // The slice's manifolds always have exactly one point (pointContact /
+  // emitSingle); reducePoints over one point is the identity.
+  ContactPoint point{};
+  bool valid = false;
+};
+
+// physics3d-solver.ts pointContact
+Manifold pointContact(
+  const Vec3& posA, const Vec3& posB, double radiusA, double radiusB,
+  const Vec3& centerA, const Vec3& centerB,
+  double speculativeMargin, int feature, bool flip
+) {
+  const Vec3 delta = subV(posB, posA);
+  const double distSq = dotV(delta, delta);
+  const double dist = solverSqrt(distSq);
+  const double sumR = radiusA + radiusB;
+  const double penetration = sumR - dist;
+  if (penetration < -speculativeMargin) {
+    return {};
+  }
+  Vec3 normal{};
+  if (dist > 1e-9) {
+    normal = scaleV(delta, 1.0 / dist);
+  } else {
+    normal = {0.0, 1.0, 0.0};
+  }
+  const Vec3 surfaceA = addV(posA, scaleV(normal, radiusA));
+  const Vec3 surfaceB = subV(posB, scaleV(normal, radiusB));
+  const Vec3 mid = scaleV(addV(surfaceA, surfaceB), 0.5);
+  const Vec3 outNormal = flip ? scaleV(normal, -1.0) : normal;
+  const Vec3 aCenter = flip ? centerB : centerA;
+  const Vec3 bCenter = flip ? centerA : centerB;
+  Manifold m;
+  m.normal = outNormal;
+  m.point = {subV(mid, aCenter), subV(mid, bCenter), penetration, feature};
+  m.valid = true;
+  return m;
+}
+
+struct ClosestOnBox {
+  Vec3 point{};
+  bool inside = false;
+  Vec3 localClamped{};
+};
+
+// physics3d-solver.ts closestPointOnBox (box.q is always identity here, but the
+// quaternion rotations are kept verbatim -- they shape +/-0 signs).
+ClosestOnBox closestPointOnBox(const SBody& box, const Vec3& worldPoint) {
+  const Vec3 half = box.half;
+  const Vec3 local = rotatePointByQuatInverse(box.q, subV(worldPoint, box.p));
+  const Vec3 clampedLocal{
+    clampNum(local.x, -half.x, half.x),
+    clampNum(local.y, -half.y, half.y),
+    clampNum(local.z, -half.z, half.z),
+  };
+  const bool inside = clampedLocal.x == local.x && clampedLocal.y == local.y && clampedLocal.z == local.z;
+  return {addV(box.p, rotatePointByQuat(box.q, clampedLocal)), inside, clampedLocal};
+}
+
+// physics3d-solver.ts emitSingle
+Manifold emitSingle(
+  const Vec3& nSphereToBox, const Vec3& mid, double penetration,
+  const Vec3& cSphere, const Vec3& cBox, int feature, bool flip
+) {
+  const Vec3 normal = flip ? scaleV(nSphereToBox, -1.0) : nSphereToBox;
+  const Vec3 aCenter = flip ? cBox : cSphere;
+  const Vec3 bCenter = flip ? cSphere : cBox;
+  Manifold m;
+  m.normal = normal;
+  m.point = {subV(mid, aCenter), subV(mid, bCenter), penetration, feature};
+  m.valid = true;
+  return m;
+}
+
+// physics3d-solver.ts sphereBox
+Manifold sphereBox(
+  const SBody& sphere, const SBody& box,
+  const Vec3& cSphere, const Vec3& cBox,
+  double margin, int feature, bool flip
+) {
+  const double radius = sphere.radius;
+  const ClosestOnBox closest = closestPointOnBox(box, sphere.p);
+  const Vec3 half = box.half;
+  if (closest.inside) {
+    const Vec3 local = closest.localClamped;
+    const double distances[3] = {
+      half.x - std::fabs(local.x),
+      half.y - std::fabs(local.y),
+      half.z - std::fabs(local.z),
+    };
+    int axis = 0;
+    if (distances[1] < distances[axis]) axis = 1;
+    if (distances[2] < distances[axis]) axis = 2;
+    const Vec3 localAxes[3] = {{1.0, 0.0, 0.0}, {0.0, 1.0, 0.0}, {0.0, 0.0, 1.0}};
+    const double localComponent = axis == 0 ? local.x : axis == 1 ? local.y : local.z;
+    const Vec3 localNormal = scaleV(localAxes[axis], localComponent >= 0.0 ? 1.0 : -1.0);
+    const Vec3 worldNormal = rotatePointByQuat(box.q, localNormal);
+    const double penetration = distances[axis] + radius;
+    const Vec3 nSphereToBox = scaleV(worldNormal, -1.0);
+    const Vec3 mid = sphere.p;
+    return emitSingle(nSphereToBox, mid, penetration, cSphere, cBox, feature, flip);
+  }
+  const Vec3 delta = subV(sphere.p, closest.point);
+  const double dist = solverSqrt(dotV(delta, delta));
+  const double penetration = radius - dist;
+  if (penetration < -margin) {
+    return {};
+  }
+  const Vec3 nBoxToSphere = dist > 1e-9 ? scaleV(delta, 1.0 / dist) : Vec3{0.0, 1.0, 0.0};
+  const Vec3 nSphereToBox = scaleV(nBoxToSphere, -1.0);
+  const Vec3 mid = scaleV(addV(closest.point, subV(sphere.p, scaleV(nBoxToSphere, radius))), 0.5);
+  return emitSingle(nSphereToBox, mid, penetration, cSphere, cBox, feature, flip);
+}
+
+// generateManifold single-primitive path + collidePrimitives dispatch.
+Manifold generateManifold(const SBody& a, const SBody& b, double speculativeMargin) {
+  const int featureBase = 0;
+  Manifold m;
+  if (a.isSphere && b.isSphere) {
+    m = pointContact(a.p, b.p, a.radius, b.radius, a.p, b.p, speculativeMargin, featureBase, false);
+  } else if (a.isSphere && !b.isSphere) {
+    m = sphereBox(a, b, a.p, b.p, speculativeMargin, featureBase, false);
+  } else if (!a.isSphere && b.isSphere) {
+    m = sphereBox(b, a, b.p, a.p, speculativeMargin, featureBase, true);
+  } else {
+    // box-box: unreachable (both static pairs are skipped in emitPair).
+    std::fprintf(stderr, "physics slice: box-box narrowphase is outside the slice\n");
+    std::abort();
+  }
+  if (!m.valid) {
+    return {};
+  }
+  m.a = a.index;
+  m.b = b.index;
+  return m;
+}
+
+// ---------------------------------------------------------------------------
+// Broadphase AABBs (physics3d-solver.ts solverBodyAabb / shapeHalfExtent;
+// ccd=false so no velocity sweep)
+// ---------------------------------------------------------------------------
+
+struct Aabb {
+  double minX, maxX, minY, maxY, minZ, maxZ;
+};
+
+Vec3 shapeHalfExtent(const SBody& b) {
+  if (!b.isSphere) {
+    const Mat3 rot = quatToMat3(b.q);
+    return {
+      std::fabs(rot[0]) * b.half.x + std::fabs(rot[1]) * b.half.y + std::fabs(rot[2]) * b.half.z,
+      std::fabs(rot[3]) * b.half.x + std::fabs(rot[4]) * b.half.y + std::fabs(rot[5]) * b.half.z,
+      std::fabs(rot[6]) * b.half.x + std::fabs(rot[7]) * b.half.y + std::fabs(rot[8]) * b.half.z,
+    };
+  }
+  return {b.radius, b.radius, b.radius};
+}
+
+Aabb solverBodyAabb(const SBody& body) {
+  const Vec3 half = shapeHalfExtent(body);
+  return {
+    body.p.x - half.x, body.p.x + half.x,
+    body.p.y - half.y, body.p.y + half.y,
+    body.p.z - half.z, body.p.z + half.z,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Contact constraints + impulse kernel (physics3d-solver.ts)
+// ---------------------------------------------------------------------------
+
+struct Constraint {
+  int a = 0, b = 0;
+  Vec3 normal{}, t1{}, t2{};
+  Vec3 rA{}, rB{};
+  double penetration = 0.0;
+  double massN = 0.0, massT1 = 0.0, massT2 = 0.0;
+  double biasRate = 0.0, massScale = 1.0, impulseScale = 0.0;
+  double vn0 = 0.0;
+  double accN = 0.0, accT1 = 0.0, accT2 = 0.0, accNStep = 0.0;
+  double mu = 0.0;
+  double restitution = 0.0;
+};
+
+double effectiveMass(
+  const Vec3& axis, const Vec3& rA, const Vec3& rB,
+  const Vec3& imA, const Vec3& imB, const Mat3& iiA, const Mat3& iiB
+) {
+  const double linA = axis.x * axis.x * imA.x + axis.y * axis.y * imA.y + axis.z * axis.z * imA.z;
+  const double linB = axis.x * axis.x * imB.x + axis.y * axis.y * imB.y + axis.z * axis.z * imB.z;
+  const Vec3 raxn = crossV(rA, axis);
+  const Vec3 rbxn = crossV(rB, axis);
+  const double denom = linA + linB + dotV(raxn, mulMat3Vec(iiA, raxn)) + dotV(rbxn, mulMat3Vec(iiB, rbxn));
+  return denom == 0.0 ? 0.0 : 1.0 / denom;
+}
+
+Vec3 normalizeVec3Local(const Vec3& a) {
+  const double l = solverSqrt(dotV(a, a));
+  return l == 0.0 ? Vec3{0.0, 0.0, 0.0} : scaleV(a, 1.0 / l);
+}
+
+void tangentBasis(const Vec3& n, Vec3& t1, Vec3& t2) {
+  t1 = std::fabs(n.x) >= 0.57735
+    ? normalizeVec3Local({n.y, -n.x, 0.0})
+    : normalizeVec3Local({0.0, n.z, -n.y});
+  t2 = crossV(n, t1);
+}
+
+double toInt10(double unit) { return jsRound(unit * 10.0); }
+
+// physics3d-solver.ts applyImpulseScalar (verbatim scalar form)
+void applyImpulseScalar(
+  std::vector<SBody>& bodies, const std::vector<Vec3>& invMass, const std::vector<Mat3>& invInertia,
+  int a, int b, const Vec3& rA, const Vec3& rB,
+  double px, double py, double pz, bool bias
+) {
+  SBody& A = bodies[a];
+  SBody& B = bodies[b];
+  if (solid(A)) {
+    const double cx = rA.y * pz - rA.z * py;
+    const double cy = rA.z * px - rA.x * pz;
+    const double cz = rA.x * py - rA.y * px;
+    const Mat3& m = invInertia[a];
+    const Vec3& inv = invMass[a];
+    Vec3& lin = bias ? A.vb : A.v;
+    Vec3& ang = bias ? A.wb : A.w;
+    lin.x = lin.x - px * inv.x;
+    lin.y = lin.y - py * inv.y;
+    lin.z = lin.z - pz * inv.z;
+    ang.x = ang.x - (m[0] * cx + m[1] * cy + m[2] * cz);
+    ang.y = ang.y - (m[3] * cx + m[4] * cy + m[5] * cz);
+    ang.z = ang.z - (m[6] * cx + m[7] * cy + m[8] * cz);
+  }
+  if (solid(B)) {
+    const double cx = rB.y * pz - rB.z * py;
+    const double cy = rB.z * px - rB.x * pz;
+    const double cz = rB.x * py - rB.y * px;
+    const Mat3& m = invInertia[b];
+    const Vec3& inv = invMass[b];
+    Vec3& lin = bias ? B.vb : B.v;
+    Vec3& ang = bias ? B.wb : B.w;
+    lin.x = lin.x + px * inv.x;
+    lin.y = lin.y + py * inv.y;
+    lin.z = lin.z + pz * inv.z;
+    ang.x = ang.x + (m[0] * cx + m[1] * cy + m[2] * cz);
+    ang.y = ang.y + (m[3] * cx + m[4] * cy + m[5] * cz);
+    ang.z = ang.z + (m[6] * cx + m[7] * cy + m[8] * cz);
+  }
+}
+
+double relativeVelocityAlong(
+  const SBody& A, const SBody& B, const Vec3& rA, const Vec3& rB,
+  double dx, double dy, double dz
+) {
+  const double relX = (B.v.x + (B.w.y * rB.z - B.w.z * rB.y)) - (A.v.x + (A.w.y * rA.z - A.w.z * rA.y));
+  const double relY = (B.v.y + (B.w.z * rB.x - B.w.x * rB.z)) - (A.v.y + (A.w.z * rA.x - A.w.x * rA.z));
+  const double relZ = (B.v.z + (B.w.x * rB.y - B.w.y * rB.x)) - (A.v.z + (A.w.x * rA.y - A.w.y * rA.x));
+  return relX * dx + relY * dy + relZ * dz;
+}
+
+double solveTangentImpulse(
+  std::vector<SBody>& bodies, const std::vector<Vec3>& invMass, const std::vector<Mat3>& invInertia,
+  Constraint& c, const SBody& A, const SBody& B,
+  const Vec3& t, double mass, double acc, double maxF
+) {
+  const double vt = relativeVelocityAlong(A, B, c.rA, c.rB, t.x, t.y, t.z);
+  double dF = mass * -vt;
+  const double clamped = clampNum(acc + dF, -maxF, maxF);
+  dF = clamped - acc;
+  applyImpulseScalar(bodies, invMass, invInertia, c.a, c.b, c.rA, c.rB, t.x * dF, t.y * dF, t.z * dF, false);
+  return clamped;
+}
+
+// physics3d-solver.ts solveContactSoft. NOTE: the normal impulse is applied
+// with bias=false ALWAYS (source line 2370) -- the soft bias folds into real
+// velocity and the relax pass drains it. (The transliteration spec's
+// "into vb/wb when useBias" is wrong; the source wins.)
+void solveContactSoft(
+  std::vector<SBody>& bodies, const std::vector<Vec3>& invMass, const std::vector<Mat3>& invInertia,
+  Constraint& c, double h, bool useBias
+) {
+  const SBody& A = bodies[c.a];
+  const SBody& B = bodies[c.b];
+  const double vn = relativeVelocityAlong(A, B, c.rA, c.rB, c.normal.x, c.normal.y, c.normal.z);
+  double bias = 0.0;
+  double massScale = 1.0;
+  double impulseScale = 0.0;
+  if (c.penetration < 0.0) {
+    bias = c.penetration / h;
+  } else if (useBias) {
+    const double raw = c.biasRate * (c.penetration - SLOP);
+    bias = clampNum(raw, 0.0, MAX_CONTACT_PUSHOUT / h);
+    massScale = c.massScale;
+    impulseScale = c.impulseScale;
+  }
+  double dLambda = massScale * c.massN * (-(vn) + bias) - impulseScale * c.accN;
+  const double newAcc = jsMax(0.0, c.accN + dLambda);
+  dLambda = newAcc - c.accN;
+  c.accN = newAcc;
+  applyImpulseScalar(bodies, invMass, invInertia, c.a, c.b, c.rA, c.rB,
+    c.normal.x * dLambda, c.normal.y * dLambda, c.normal.z * dLambda, false);
+  if (c.penetration < 0.0) {
+    return;
+  }
+  const double maxF = c.mu * c.accN;
+  c.accT1 = solveTangentImpulse(bodies, invMass, invInertia, c, A, B, c.t1, c.massT1, c.accT1, maxF);
+  c.accT2 = solveTangentImpulse(bodies, invMass, invInertia, c, A, B, c.t2, c.massT2, c.accT2, maxF);
+}
+
+void debugDump(const std::vector<SBody>& bodies, const char* phase, int substep) {
+  for (const SBody& b : bodies) {
+    if (!b.isDynamic) {
+      continue;
+    }
+    std::uint64_t bits[6];
+    const double vals[6] = {b.p.x, b.p.y, b.p.z, b.v.x, b.v.y, b.v.z};
+    std::memcpy(bits, vals, sizeof(vals));
+    std::fprintf(stderr, "[cpp %s s%d] idx=%d p=%016llx,%016llx,%016llx v=%016llx,%016llx,%016llx\n",
+      phase, substep, b.index,
+      (unsigned long long)bits[0], (unsigned long long)bits[1], (unsigned long long)bits[2],
+      (unsigned long long)bits[3], (unsigned long long)bits[4], (unsigned long long)bits[5]);
+  }
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// One rigid step over the slice world (solveRigidStep specialized: no joints,
+// empty warm cache, no CCD, no sleeping) + quantized readback (runRigidSolver).
+// ---------------------------------------------------------------------------
+
+void stepPhysicsSlice(std::vector<PhysBody>& bodies) {
+  const bool debug = std::getenv("PHYS_SLICE_DEBUG") != nullptr;
+
+  // normalizeBodies: canonical lexicographic id order (plain byte-wise <,
+  // identical to JS UTF-16 compare for ASCII ids).
+  std::sort(bodies.begin(), bodies.end(), [](const PhysBody& l, const PhysBody& r) {
+    return l.id < r.id;
+  });
+
+  // buildSolverBody
+  std::vector<SBody> sb(bodies.size());
+  for (std::size_t i = 0; i < bodies.size(); i += 1) {
+    const PhysBody& src = bodies[i];
+    SBody& b = sb[i];
+    b.index = static_cast<int>(i);
+    b.isDynamic = src.dynamic;
+    b.sleeping = false;
+    b.p = {src.x, src.y, src.z};
+    b.v = {src.vx, src.vy, src.vz};
+    b.w = {0.0, 0.0, 0.0};
+    b.vb = {0.0, 0.0, 0.0};
+    b.wb = {0.0, 0.0, 0.0};
+    const double mass = 1.0;
+    const double baseInvMass = src.dynamic ? 1.0 / mass : 0.0;
+    b.invMassVec = {baseInvMass, baseInvMass, baseInvMass};
+    b.isSphere = src.isSphere;
+    b.radius = src.radius;
+    b.half = {src.halfX, src.halfY, src.halfZ};
+    b.invInertiaLocal = src.dynamic ? deriveInverseInertia(b, mass) : Vec3{0.0, 0.0, 0.0};
+    b.angularLock = {0.0, 0.0, 0.0};  // no orientation on any slice body
+    b.layer = src.layer;
+    b.mask = src.mask;
+  }
+
+  const double dt = DT;
+  const double h = dt / SUBSTEPS;
+
+  // 1. reset pseudo-velocities; zero locked axes (invMass components are all
+  // nonzero for dynamics here; angular lock zeroes w).
+  for (SBody& b : sb) {
+    b.vb = {0.0, 0.0, 0.0};
+    b.wb = {0.0, 0.0, 0.0};
+    if (!solid(b)) {
+      continue;
+    }
+    b.v = {
+      b.invMassVec.x == 0.0 ? 0.0 : b.v.x,
+      b.invMassVec.y == 0.0 ? 0.0 : b.v.y,
+      b.invMassVec.z == 0.0 ? 0.0 : b.v.z,
+    };
+    b.w = {
+      b.angularLock.x == 0.0 ? 0.0 : b.w.x,
+      b.angularLock.y == 0.0 ? 0.0 : b.w.y,
+      b.angularLock.z == 0.0 ? 0.0 : b.w.z,
+    };
+  }
+
+  // 2. broadphase sort-and-sweep + narrowphase manifolds.
+  std::vector<Manifold> manifolds;
+  auto emitPair = [&](int i, int j) {
+    const SBody& A = sb[i];
+    const SBody& B = sb[j];
+    if (!A.isDynamic && !B.isDynamic) {
+      return;
+    }
+    // noCollide (trigger/sensor) and noCollidePairs: absent from the slice.
+    if ((static_cast<std::int32_t>(A.mask) & B.layer) == 0 || (static_cast<std::int32_t>(B.mask) & A.layer) == 0) {
+      return;
+    }
+    const double margin = 0.0;  // no ccd body in the slice
+    const Manifold manifold = generateManifold(A, B, margin);
+    if (manifold.valid) {
+      manifolds.push_back(manifold);
+    }
+  };
+  {
+    std::vector<Aabb> aabbs(sb.size());
+    for (std::size_t i = 0; i < sb.size(); i += 1) {
+      aabbs[i] = solverBodyAabb(sb[i]);
+    }
+    std::vector<int> order(sb.size());
+    for (std::size_t i = 0; i < sb.size(); i += 1) {
+      order[i] = static_cast<int>(i);
+    }
+    std::sort(order.begin(), order.end(), [&](int l, int r) {
+      if (aabbs[l].minX != aabbs[r].minX) {
+        return aabbs[l].minX < aabbs[r].minX;
+      }
+      return l < r;
+    });
+    for (std::size_t sweepA = 0; sweepA < order.size(); sweepA += 1) {
+      const int i = order[sweepA];
+      const Aabb& boundsI = aabbs[i];
+      for (std::size_t sweepB = sweepA + 1; sweepB < order.size(); sweepB += 1) {
+        const int j = order[sweepB];
+        const Aabb& boundsJ = aabbs[j];
+        if (boundsJ.minX > boundsI.maxX) {
+          break;
+        }
+        if (boundsJ.minY > boundsI.maxY || boundsJ.maxY < boundsI.minY || boundsJ.minZ > boundsI.maxZ || boundsJ.maxZ < boundsI.minZ) {
+          continue;
+        }
+        emitPair(std::min(i, j), std::max(i, j));
+      }
+    }
+  }
+  std::sort(manifolds.begin(), manifolds.end(), [](const Manifold& l, const Manifold& r) {
+    if (l.a != r.a) {
+      return l.a < r.a;
+    }
+    return l.b < r.b;
+  });
+
+  // 3. wake pass: nothing sleeps in a fresh world -- no-op.
+
+  // 4. build contact constraints (+ warm start: cache empty, accumulators 0).
+  std::vector<Vec3> invMass(sb.size());
+  std::vector<Mat3> invInertia(sb.size());
+  for (std::size_t i = 0; i < sb.size(); i += 1) {
+    invMass[i] = invMassOf(sb[i]);
+    invInertia[i] = worldInvInertiaLocked(sb[i]);
+  }
+  std::vector<Constraint> constraints;
+  constraints.reserve(manifolds.size());
+  for (const Manifold& m : manifolds) {
+    const SBody& A = sb[m.a];
+    const SBody& B = sb[m.b];
+    Vec3 t1{}, t2{};
+    tangentBasis(m.normal, t1, t2);
+    // matFriction = matRestitution = 0 on every slice body.
+    const double combinedMu = std::floor((toInt10(0.0) + toInt10(0.0)) / 2.0) / 10.0;
+    const double combinedRest = jsMax(toInt10(0.0), toInt10(0.0)) / 10.0;
+    const bool softStatic = !A.isDynamic || !B.isDynamic;
+    const double hertz = (CONTACT_HERTZ_FRACTION * SUBSTEPS / dt) * (softStatic ? STATIC_HERTZ_SCALE : 1.0);
+    const double omega = TWO_PI * hertz;
+    const double a1 = 2.0 * CONTACT_ZETA + omega * h;
+    const double a2 = h * omega * a1;
+    const double a3 = 1.0 / (1.0 + a2);
+    const double biasRate = omega / a1;
+    const double massScale = a2 * a3;
+    const double impulseScale = a3;
+    const ContactPoint& pt = m.point;
+    Vec3 rA = pt.rA;
+    Vec3 rB = pt.rB;
+    if (pt.penetration < 0.0) {
+      // speculative pullback -- unreachable with margin 0, kept verbatim.
+      const double half = -pt.penetration * 0.5;
+      rA = {pt.rA.x - m.normal.x * half, pt.rA.y - m.normal.y * half, pt.rA.z - m.normal.z * half};
+      rB = {pt.rB.x + m.normal.x * half, pt.rB.y + m.normal.y * half, pt.rB.z + m.normal.z * half};
+    }
+    Constraint c;
+    c.a = m.a;
+    c.b = m.b;
+    c.normal = m.normal;
+    c.t1 = t1;
+    c.t2 = t2;
+    c.rA = rA;
+    c.rB = rB;
+    c.penetration = pt.penetration;
+    c.massN = effectiveMass(m.normal, rA, rB, invMass[m.a], invMass[m.b], invInertia[m.a], invInertia[m.b]);
+    c.massT1 = effectiveMass(t1, rA, rB, invMass[m.a], invMass[m.b], invInertia[m.a], invInertia[m.b]);
+    c.massT2 = effectiveMass(t2, rA, rB, invMass[m.a], invMass[m.b], invInertia[m.a], invInertia[m.b]);
+    c.biasRate = biasRate;
+    c.massScale = massScale;
+    c.impulseScale = impulseScale;
+    c.vn0 = relativeVelocityAlong(A, B, rA, rB, m.normal.x, m.normal.y, m.normal.z);
+    c.accN = 0.0;   // matchWarm on an empty cache
+    c.accT1 = 0.0;
+    c.accT2 = 0.0;
+    c.accNStep = 0.0;
+    c.mu = combinedMu;
+    c.restitution = combinedRest;
+    constraints.push_back(c);
+  }
+
+  // 5. TGS-Soft sub-step loop.
+  for (int substep = 0; substep < SUBSTEPS; substep += 1) {
+    for (SBody& b : sb) {
+      if (solid(b) && b.invMassVec.y != 0.0) {
+        b.v.y = b.v.y + GRAVITY_Y * b.gravityScale * h;
+      }
+    }
+    // (no joints) warm-start apply with the current accumulators.
+    for (Constraint& c : constraints) {
+      applyImpulseScalar(
+        sb, invMass, invInertia, c.a, c.b, c.rA, c.rB,
+        c.normal.x * c.accN + (c.t1.x * c.accT1 + c.t2.x * c.accT2),
+        c.normal.y * c.accN + (c.t1.y * c.accT1 + c.t2.y * c.accT2),
+        c.normal.z * c.accN + (c.t1.z * c.accT1 + c.t2.z * c.accT2),
+        false);
+    }
+    for (int iter = 0; iter < VELOCITY_ITERATIONS; iter += 1) {
+      for (Constraint& c : constraints) {
+        solveContactSoft(sb, invMass, invInertia, c, h, true);
+      }
+    }
+    for (SBody& b : sb) {
+      if (!solid(b)) {
+        continue;
+      }
+      b.p = addV(b.p, scaleV(addV(b.v, b.vb), h));
+      // hasOrientation=false: no quaternion integration.
+    }
+    for (Constraint& c : constraints) {
+      const SBody& A = sb[c.a];
+      const SBody& B = sb[c.b];
+      const Vec3 dpA = solid(A) ? scaleV(addV(A.v, A.vb), h) : ZERO_VEC;
+      const Vec3 dpB = solid(B) ? scaleV(addV(B.v, B.vb), h) : ZERO_VEC;
+      const Vec3 rotA = solid(A) ? scaleV(crossV(addV(A.w, A.wb), c.rA), h) : ZERO_VEC;
+      const Vec3 rotB = solid(B) ? scaleV(crossV(addV(B.w, B.wb), c.rB), h) : ZERO_VEC;
+      const Vec3 rel = subV(addV(dpB, rotB), addV(dpA, rotA));
+      c.penetration -= dotV(rel, c.normal);
+      c.rA = addV(c.rA, rotA);
+      c.rB = addV(c.rB, rotB);
+    }
+    for (SBody& b : sb) {
+      b.vb = {0.0, 0.0, 0.0};
+      b.wb = {0.0, 0.0, 0.0};
+    }
+    const int relaxIterations = VELOCITY_ITERATIONS * RELAX_ITERATION_SCALE;
+    for (int iter = 0; iter < relaxIterations; iter += 1) {
+      for (Constraint& c : constraints) {
+        solveContactSoft(sb, invMass, invInertia, c, h, false);
+      }
+    }
+    for (Constraint& c : constraints) {
+      c.accNStep += c.accN;
+    }
+    if (debug) {
+      debugDump(sb, "substep", substep);
+    }
+  }
+
+  // 5b. restitution pass (combined restitution is always 0 in the slice; the
+  // guard short-circuits every constraint, kept verbatim).
+  for (Constraint& c : constraints) {
+    if (c.restitution <= 0.0 || c.vn0 >= -RESTITUTION_THRESHOLD || c.accN <= 0.0) {
+      continue;
+    }
+    const SBody& A = sb[c.a];
+    const SBody& B = sb[c.b];
+    const double vn = relativeVelocityAlong(A, B, c.rA, c.rB, c.normal.x, c.normal.y, c.normal.z);
+    double dLambda = c.massN * (-c.restitution * c.vn0 - vn);
+    const double newAcc = jsMax(0.0, c.accN + dLambda);
+    dLambda = newAcc - c.accN;
+    c.accN = newAcc;
+    c.accNStep += dLambda;
+    applyImpulseScalar(sb, invMass, invInertia, c.a, c.b, c.rA, c.rB,
+      c.normal.x * dLambda, c.normal.y * dLambda, c.normal.z * dLambda, false);
+  }
+
+  // 6. warm-cache store: not observable through position/velocity readback of
+  // a single step -- omitted.
+
+  // 7. damping + axis-lock zeroing. (lowVelFrames bookkeeping and step 8
+  // islandSleep are omitted: from a fresh world lowVelFrames <= 1 < 20, so no
+  // body can sleep within this step and v/w are never zeroed by sleep.)
+  for (SBody& b : sb) {
+    if (!solid(b)) {
+      continue;
+    }
+    b.v = scaleV(b.v, b.linearDamping);
+    b.w = scaleV(b.w, b.angularDamping);
+    b.v = {
+      b.invMassVec.x == 0.0 ? 0.0 : b.v.x,
+      b.invMassVec.y == 0.0 ? 0.0 : b.v.y,
+      b.invMassVec.z == 0.0 ? 0.0 : b.v.z,
+    };
+    b.w = {
+      b.angularLock.x == 0.0 ? 0.0 : b.w.x,
+      b.angularLock.y == 0.0 ? 0.0 : b.w.y,
+      b.angularLock.z == 0.0 ? 0.0 : b.w.z,
+    };
+  }
+
+  if (debug) {
+    debugDump(sb, "final", -1);
+  }
+
+  // Readback (runRigidSolver): dynamic bodies get quantized position+velocity;
+  // statics pass through untouched.
+  for (std::size_t i = 0; i < bodies.size(); i += 1) {
+    if (!bodies[i].dynamic) {
+      continue;
+    }
+    bodies[i].x = quantizeDistance(sb[i].p.x);
+    bodies[i].y = quantizeDistance(sb[i].p.y);
+    bodies[i].z = quantizeDistance(sb[i].p.z);
+    bodies[i].vx = quantizeDistance(sb[i].v.x);
+    bodies[i].vy = quantizeDistance(sb[i].v.y);
+    bodies[i].vz = quantizeDistance(sb[i].v.z);
+  }
+}