@series-inc/rundot-syncplay 5.26.0-beta.2 → 5.26.0-beta.3

package/core/src/physics/index.mjs

@@ -9,6 +9,55 @@ import {
 } from './mass-properties.mjs';
 
 const PHYSICS_ABI_VERSION = 14;
+
+/**
+ * Mirrors `kBroadphaseCapacity` (native/physics/physics.cpp:1858).
+ * recordContactTelemetry silently returns at this count, so the exported contact
+ * count saturates here and a step that reaches it may be missing contacts. No
+ * overflow flag crosses the ABI, so this boundary is the only signal available.
+ */
+export const PHYSICS_CONTACT_TELEMETRY_CAP = 100_000;
+
+/**
+ * Post-step contact contract, published so other runtimes (notably the native
+ * C++ player) consume the same semantics without reimplementing physics.
+ */
+export const PHYSICS_CONTACT_CONTRACT = Object.freeze({
+  entry: Object.freeze([
+    'pair', 'anchorX', 'anchorY', 'anchorZ',
+    'normalImpulse', 'tangentImpulse1', 'tangentImpulse2',
+  ]),
+  ordering: 'contactCache is sorted by pair id; ordering is canonical world state and feeds checksums',
+  authority: Object.freeze({
+    solid: 'cpp-telemetry',
+    triggerOrSensor: 'js-detect-contacts',
+    note: 'the solver never resolves triggers or sensors, so telemetry cannot report them',
+  }),
+  warmStart: 'contactCache is returned to the solver next step via rundot_kinetix_physics_set_contact_cache',
+  budgets: Object.freeze({
+    contactTelemetry: Object.freeze({
+      limit: PHYSICS_CONTACT_TELEMETRY_CAP,
+      onOverflow: 'silently-truncates-in-cpp; detected here by count saturation and raised',
+      signal: 'KINETIX_PHYSICS_CONTACT_TELEMETRY_SATURATED',
+    }),
+    broadphasePairs: Object.freeze({
+      limit: 1 << 20,
+      onOverflow: 'falls-back-to-all-pairs-in-cpp; lossless, no signal needed',
+      signal: null,
+    }),
+  }),
+  errors: Object.freeze(['KINETIX_PHYSICS_CONTACT_TELEMETRY_SATURATED']),
+});
+
+/**
+ * Tripwire against obviously-wrong geometry (a mis-scaled voxel cook, a units
+ * error), NOT a technical limit — the marshaling path has been exercised to
+ * 12.6M elements without failing. Set far above any realtime-usable size: at
+ * 1M elements (a ~577x577 heightfield) a single body already costs ~22ms/tick,
+ * so anything reaching this ceiling is broken rather than merely slow. See
+ * SYNCPLAY-PHYSICS.md for the practical per-step budget, which is much lower.
+ */
+export const PHYSICS_MAX_SHAPE_GEOMETRY_ELEMENTS = 1_000_000;
 const PHYSICS_BODY_STRIDE = 44;
 const PHYSICS_JOINT_STRIDE = 48;
 const PHYSICS_JOINT_TELEMETRY_STRIDE = 5;
@@ -183,6 +232,23 @@ function cloneOptionalNumber(source, target, key, minimum = Number.NEGATIVE_INFI
   target[key] = value;
 }
 
+/**
+ * Flat geometry element count without materializing the geometry — an oversized
+ * shape must fail before it allocates the array that would have blown up. The
+ * per-child term must match `childStrideValues` in shapeGeometryValues; an
+ * over-count here would reject shapes that marshal fine.
+ */
+function shapeGeometryElementCount(shape) {
+  if (shape.type === 'mesh' || shape.type === 'hull') return shape.vertices.length * 3;
+  if (shape.type === 'heightfield') return 3 + shape.columns * shape.rows * 3;
+  if (shape.type === 'compound') {
+    let total = 0;
+    for (const child of shape.children) total += 18 + shapeGeometryElementCount(child.shape);
+    return total;
+  }
+  return 0;
+}
+
 function normalizeBody(body) {
   if (!isRecord(body) || typeof body.id !== 'string' || body.id.length === 0 || body.id.includes('|')) {
     fail('KINETIX_PHYSICS_BODY_ID_INVALID');
@@ -190,6 +256,11 @@ function normalizeBody(body) {
   if (body.kind !== 'static' && body.kind !== 'dynamic' && body.kind !== 'kinematic') {
     fail('KINETIX_PHYSICS_BODY_KIND_INVALID');
   }
+  const shape = cloneShape(body.shape);
+  const geometryElements = shapeGeometryElementCount(shape);
+  if (geometryElements > PHYSICS_MAX_SHAPE_GEOMETRY_ELEMENTS) {
+    fail(`KINETIX_PHYSICS_SHAPE_GEOMETRY_TOO_LARGE ${body.id} ${geometryElements}`);
+  }
   const normalized = {
     id: body.id,
     kind: body.kind,
@@ -199,7 +270,7 @@ function normalizeBody(body) {
     vx: finite(body.vx, 'VX'),
     vy: finite(body.vy, 'VY'),
     vz: finite(body.vz, 'VZ'),
-    shape: cloneShape(body.shape),
+    shape,
     layer: bitMask(body.layer ?? 1, 'LAYER'),
     mask: bitMask(body.mask ?? 1, 'MASK'),
   };
@@ -404,7 +475,23 @@ function minMaxVertices(vertices) {
   return { minX, minY, minZ, maxX, maxY, maxZ };
 }
 
+/**
+ * Bounds are a pure function of a frozen shape, and marshalBodyData recomputes
+ * them per static body per step via shapeLocalCenter — recursing over every
+ * compound child each time. Identity-keyed memoization is sound and removes
+ * that entirely.
+ */
+let shapeLocalBoundsCache = new WeakMap();
+
 function shapeLocalBounds(shape) {
+  const memoized = shapeLocalBoundsCache.get(shape);
+  if (memoized !== undefined) return memoized;
+  const computed = computeShapeLocalBounds(shape);
+  shapeLocalBoundsCache.set(shape, computed);
+  return computed;
+}
+
+function computeShapeLocalBounds(shape) {
   if (shape.type === 'box') {
     return {
       minX: -shape.halfX,
@@ -769,11 +856,21 @@ function bodiesContactingAny(bodies, changedBodies) {
   return affectedIds;
 }
 
+/**
+ * Values already deep-frozen by us. Without this, createWorld re-walks every
+ * static body's full shape tree on every step — the dominant per-step cost once
+ * checksums are off (32 statics x 16 compound children: 0.80 -> 0.13 ms/tick).
+ * A frozen value cannot change, so a hit is always sound.
+ */
+let deepFrozenValues = new WeakSet();
+
 function deepFreeze(value, seen = new WeakSet()) {
   if (!isRecord(value) && !Array.isArray(value)) return value;
+  if (deepFrozenValues.has(value)) return value;
   if (seen.has(value)) return value;
   seen.add(value);
   for (const child of Object.values(value)) deepFreeze(child, seen);
+  deepFrozenValues.add(value);
   return Object.freeze(value);
 }
 
@@ -1052,11 +1149,25 @@ function shapeGeometryValues(shape) {
   return undefined;
 }
 
+/**
+ * Bounded append. `push(...values)` passes every element as a call argument and
+ * overflows the engine's argument limit around ~100k elements, surfacing as an
+ * opaque RangeError from inside stepPhysicsWorld rather than a typed physics
+ * error. Geometry is 3 values per element, so a 192x192 heightfield is enough.
+ */
+function appendGeometryValues(target, values) {
+  const base = target.length;
+  target.length = base + values.length;
+  for (let index = 0; index < values.length; index += 1) {
+    target[base + index] = values[index];
+  }
+}
+
 function shapeFields(shape, geometryValues) {
   const materialize = (cached) => {
     if (cached.geometry !== undefined) {
       const geometryOffset = geometryValues.length / 3;
-      geometryValues.push(...cached.geometry);
+      appendGeometryValues(geometryValues, cached.geometry);
       return Object.freeze([
         cached.shapeKind,
         geometryOffset,
@@ -1110,7 +1221,7 @@ function shapeFields(shape, geometryValues) {
   }
   if (geometry !== undefined) {
     const geometryOffset = geometryValues.length / 3;
-    geometryValues.push(...geometry);
+    appendGeometryValues(geometryValues, geometry);
     return Object.freeze([shapeKind, geometryOffset, geometry.length / 3, geometryFormat]);
   }
   return fields;
@@ -1434,7 +1545,10 @@ function nativeContactTelemetry(bodies) {
     const bodyA = bodies[values[offset]];
     const bodyB = bodies[values[offset + 1]];
     if (bodyA === undefined || bodyB === undefined) continue;
-    telemetry.set(bodyA.id + '|' + bodyB.id, {
+    // pairKey, not raw concatenation: cache membership now depends on these keys
+    // matching JS pair keys, which today holds only because C++ normalizes pairs
+    // with min/max on indices and createPhysicsWorld sorts bodies by id.
+    telemetry.set(pairKey(bodyA, bodyB), {
       normalImpulse: values[offset + 2],
       tangentImpulse1: values[offset + 3],
       tangentImpulse2: values[offset + 4],
@@ -2731,27 +2845,44 @@ export function stepPhysicsWorld(world, options) {
     && (bodyById.get(contact.a)?.kind === 'dynamic' || bodyById.get(contact.b)?.kind === 'dynamic'));
   const preSolverContacts = preContacts.filter((contact) => !contact.trigger && !contact.sensor
     && (bodyById.get(contact.a)?.kind === 'dynamic' || bodyById.get(contact.b)?.kind === 'dynamic'));
-  const activePairs = currentContacts.map((contact) => contact.pair);
-  const activePairMetadata = currentContacts.map((contact) => ({
+  if (nativeTelemetry.size >= PHYSICS_CONTACT_TELEMETRY_CAP) {
+    fail(`KINETIX_PHYSICS_CONTACT_TELEMETRY_SATURATED ${PHYSICS_CONTACT_TELEMETRY_CAP}`);
+  }
+  // The solver owns solid contacts: telemetry holds exactly the pairs it
+  // resolved, so membership comes from there rather than a second JS narrowphase.
+  // Sorted because contactCache is canonical world state and feeds checksums.
+  const contactCache = [...nativeTelemetry.entries()]
+    .filter(([pair]) => !disabledPairs.has(pair))
+    .map(([pair, measured]) => ({
+      pair,
+      anchorX: measured.anchorX,
+      anchorY: measured.anchorY,
+      anchorZ: measured.anchorZ,
+      normalImpulse: measured.normalImpulse,
+      tangentImpulse1: measured.tangentImpulse1,
+      tangentImpulse2: measured.tangentImpulse2,
+    }))
+    .sort((left, right) => (left.pair < right.pair ? -1 : left.pair > right.pair ? 1 : 0));
+  // Events union telemetry with JS detection. Telemetry omits static-static and
+  // both-asleep pairs, so filtering to it would drop their events and re-fire a
+  // spurious `enter` on wake; JS alone misses solver contacts it did not detect.
+  const contactByPair = new Map(currentContacts.map((contact) => [contact.pair, contact]));
+  const reconciledContacts = [...currentContacts, ...contactCache
+    .filter((entry) => !contactByPair.has(entry.pair))
+    .map((entry) => {
+      const [a, b] = entry.pair.split('|');
+      return { pair: entry.pair, a, b, trigger: false, sensor: false };
+    })]
+    .sort((left, right) => (left.pair < right.pair ? -1 : left.pair > right.pair ? 1 : 0));
+  const activePairs = reconciledContacts.map((contact) => contact.pair);
+  const activePairMetadata = reconciledContacts.map((contact) => ({
     pair: contact.pair,
     a: contact.a,
     b: contact.b,
     trigger: contact.trigger,
     sensor: contact.sensor,
   }));
-  const contactCache = solverContacts.map((contact) => {
-    const measured = nativeTelemetry.get(contact.pair);
-    return {
-      pair: contact.pair,
-      anchorX: measured?.anchorX ?? contact.point.x,
-      anchorY: measured?.anchorY ?? contact.point.y,
-      anchorZ: measured?.anchorZ ?? contact.point.z,
-      normalImpulse: measured?.normalImpulse ?? 0,
-      tangentImpulse1: measured?.tangentImpulse1 ?? 0,
-      tangentImpulse2: measured?.tangentImpulse2 ?? 0,
-    };
-  });
-  const events = currentContacts.map((contact) => ({
+  const events = reconciledContacts.map((contact) => ({
     type: world.activePairs.includes(contact.pair) ? 'stay' : 'enter',
     pair: contact.pair,
     a: contact.a,
@@ -2816,6 +2947,10 @@ export function stepPhysicsWorld(world, options) {
     postPhysicsScheduledQueryResults,
     broadphasePairs,
     narrowphaseContacts: solverContacts.length,
+    // Read from the solver's exported contact count rather than derived from
+    // contactCache, so the two remain independently checkable and callers can
+    // see how close a step is running to PHYSICS_CONTACT_TELEMETRY_CAP.
+    contactTelemetryCount: nativeTelemetry.size,
     solverCorrections,
     checksum: stepOptions.computeChecksum ? worldChecksum({ nextWorld, events: visibleEvents, scheduledQueryResults, solverCorrections }) : '',
   });
@@ -3167,6 +3302,8 @@ export function resetPhysics3DCache() {
   staticGeometryCache.clear();
   staticGeometryCacheBytes = 0;
   staticGeometryIdentityCache = new WeakMap();
+  deepFrozenValues = new WeakSet();
+  shapeLocalBoundsCache = new WeakMap();
 }
 
 export const createDeterministicPhysicsWorld3D = createPhysicsWorld;