@absolutejs/rapier3d 0.9.0 → 0.11.0

package/README.md

@@ -282,3 +282,25 @@ changes the native default policy for newly created coordinates.
 For an explicitly undamped diagnostic, read the vector, replace it with a zero
 vector of the same length, and verify the readback. This is a diagnostic control,
 not a recommendation to remove damping from every game mechanism.
+
+## Coupled articulation impacts (0.10)
+
+Coupled contacts can disturb each other: a single late restitution sweep can leave order-dependent velocities when two bodies strike one light articulation. Version 0.10 repeats the existing normal/restitution solve to a projected velocity residual, with a bounded iteration budget. In these adaptive phases, a local double-precision normal-impulse accumulator retains corrections that would otherwise round away. Native velocities, response matrices, warmstart storage, persistent snapshots, and the JavaScript API retain their existing formats. This is not a double-precision engine or an energy clamp.
+
+Adaptive compression applies only to one-group, single-worker, generic-only frictionless contacts, with no soft/FEM bodies or independent joint rows. The configured PGS count remains a minimum; the cap is the larger of that count and 256. Adaptive restitution applies only to one-group, single-worker, generic-only contacts and is capped at 256 sweeps. Both stop at a projected velocity residual of `1e-6 * lengthUnit`. Ordinary and mixed/parallel contact paths retain their previous iteration policy. Reaching the cap is not a guarantee of convergence for arbitrary mass ratios or scenes.
+
+The added regression cases cover opposing impacts, creation-order reversal, restitution 0/0.5/1, unequal masses, timestep and substep changes. Existing integration, contact preparation, damping defaults and geometry are unchanged; known general articulation integration limitations remain.
+
+Accuracy has a CPU cost. A bounded CPU-only paired benchmark of 1/8/32 disconnected heavy-light-heavy impacts measured candidate median step times of 0.62/2.48/7.87 ms, versus 0.41/0.84/1.72 ms for 0.9.0, whose velocity error in that fixture was about 6.94 m/s. The candidate error was below 0.000002 m/s. These are host-specific step measurements excluding rendering and snapshot restoration, not a frame-rate guarantee. Production scenes still need physics budgets and profiling. Detailed qualification and limitations are in `absolutejs/research/contact-convergence/`.
+
+## Adaptive contact observations (0.11)
+
+Enable `world.profilerEnabled`, complete a step, then call `world.contactConvergence()` for an owned `ContactConvergenceStats` object. The result is `null` before a completed profiled step, while profiling is disabled, after toggling profiling until another step completes, and after snapshot restoration. Reading or mutating this returned object cannot change the world. No profiling data is serialized into physical world snapshots.
+
+Fields are `compressionSolves`, `compressionIterations`, `compressionLimitHits`, `maxCompressionResidual`, and `restitutionSolves`, `restitutionIterations`, `restitutionLimitHits`, `maxRestitutionResidual`. Counts accumulate across eligible solve phases within the full step, including CCD passes and solver substeps. They count phases/groups, not physical islands or individual contacts. Zero solves means no eligible adaptive path was executed; it does not certify that all contacts converged. Ordinary and mixed/parallel paths are outside these adaptive observations.
+
+Residual fields are the maximum **terminal** projected normal-velocity error among measured phases, in native world length units per second. A limit hit means the phase exhausted its configured budget while still above the existing `1e-6 * lengthUnit` threshold. The API reports that fact; it does not change tolerances, budgets, impulses or physical policy. The configured compression minimum may exceed 256 and is still honored.
+
+The added diagnostics exactly preserve physical result records across 548 paired collision/free-motion cases versus 0.10.0. Profiler-on/off snapshot parity and CCD aggregation are also tested. In the 20/1/20 kg fixture, the counters reveal 164 compression passes and 256 restitution sweeps, with a terminal restitution residual near 2.15e-6 m/s. A tiny physical error can therefore coexist with an exhausted iteration budget. Treat that as useful evidence, not as zero or automatic failure of the simulation.
+
+Unprofiled paired median costs at 1/8/32 islands were 0.65/2.49/7.09 ms versus 0.66/2.45/7.28 ms for 0.10.0 in the qualification run. These host-specific small samples do not establish a speedup or frame-rate guarantee. Query allocation occurs only when the caller requests observations.

package/absolutejs/README.md

@@ -282,3 +282,25 @@ changes the native default policy for newly created coordinates.
 For an explicitly undamped diagnostic, read the vector, replace it with a zero
 vector of the same length, and verify the readback. This is a diagnostic control,
 not a recommendation to remove damping from every game mechanism.
+
+## Coupled articulation impacts (0.10)
+
+Coupled contacts can disturb each other: a single late restitution sweep can leave order-dependent velocities when two bodies strike one light articulation. Version 0.10 repeats the existing normal/restitution solve to a projected velocity residual, with a bounded iteration budget. In these adaptive phases, a local double-precision normal-impulse accumulator retains corrections that would otherwise round away. Native velocities, response matrices, warmstart storage, persistent snapshots, and the JavaScript API retain their existing formats. This is not a double-precision engine or an energy clamp.
+
+Adaptive compression applies only to one-group, single-worker, generic-only frictionless contacts, with no soft/FEM bodies or independent joint rows. The configured PGS count remains a minimum; the cap is the larger of that count and 256. Adaptive restitution applies only to one-group, single-worker, generic-only contacts and is capped at 256 sweeps. Both stop at a projected velocity residual of `1e-6 * lengthUnit`. Ordinary and mixed/parallel contact paths retain their previous iteration policy. Reaching the cap is not a guarantee of convergence for arbitrary mass ratios or scenes.
+
+The added regression cases cover opposing impacts, creation-order reversal, restitution 0/0.5/1, unequal masses, timestep and substep changes. Existing integration, contact preparation, damping defaults and geometry are unchanged; known general articulation integration limitations remain.
+
+Accuracy has a CPU cost. A bounded CPU-only paired benchmark of 1/8/32 disconnected heavy-light-heavy impacts measured candidate median step times of 0.62/2.48/7.87 ms, versus 0.41/0.84/1.72 ms for 0.9.0, whose velocity error in that fixture was about 6.94 m/s. The candidate error was below 0.000002 m/s. These are host-specific step measurements excluding rendering and snapshot restoration, not a frame-rate guarantee. Production scenes still need physics budgets and profiling. Detailed qualification and limitations are in `absolutejs/research/contact-convergence/`.
+
+## Adaptive contact observations (0.11)
+
+Enable `world.profilerEnabled`, complete a step, then call `world.contactConvergence()` for an owned `ContactConvergenceStats` object. The result is `null` before a completed profiled step, while profiling is disabled, after toggling profiling until another step completes, and after snapshot restoration. Reading or mutating this returned object cannot change the world. No profiling data is serialized into physical world snapshots.
+
+Fields are `compressionSolves`, `compressionIterations`, `compressionLimitHits`, `maxCompressionResidual`, and `restitutionSolves`, `restitutionIterations`, `restitutionLimitHits`, `maxRestitutionResidual`. Counts accumulate across eligible solve phases within the full step, including CCD passes and solver substeps. They count phases/groups, not physical islands or individual contacts. Zero solves means no eligible adaptive path was executed; it does not certify that all contacts converged. Ordinary and mixed/parallel paths are outside these adaptive observations.
+
+Residual fields are the maximum **terminal** projected normal-velocity error among measured phases, in native world length units per second. A limit hit means the phase exhausted its configured budget while still above the existing `1e-6 * lengthUnit` threshold. The API reports that fact; it does not change tolerances, budgets, impulses or physical policy. The configured compression minimum may exceed 256 and is still honored.
+
+The added diagnostics exactly preserve physical result records across 548 paired collision/free-motion cases versus 0.10.0. Profiler-on/off snapshot parity and CCD aggregation are also tested. In the 20/1/20 kg fixture, the counters reveal 164 compression passes and 256 restitution sweeps, with a terminal restitution residual near 2.15e-6 m/s. A tiny physical error can therefore coexist with an exhausted iteration budget. Treat that as useful evidence, not as zero or automatic failure of the simulation.
+
+Unprofiled paired median costs at 1/8/32 islands were 0.65/2.49/7.09 ms versus 0.66/2.45/7.28 ms for 0.10.0 in the qualification run. These host-specific small samples do not establish a speedup or frame-rate guarantee. Query allocation occurs only when the caller requests observations.

package/dist/build-info.mjs

@@ -1 +1 @@
-var e=Object.freeze({schemaVersion:1,scope:"package",packageName:"@absolutejs/rapier3d",packageVersion:"0.9.0",qualifiedKernelRelease:"0.9.0",upstream:"b716d375efc0201003f0cd9ef7168eee0b62c177",engine:"0.36.0",collisionLibraryVersion:"0.31.1",collisionSource:"git+https://github.com/absolutejs/parry?rev=dbd99a8dfce020da3698056471262435d56d3f69#dbd99a8dfce020da3698056471262435d56d3f69",bindings:"0.21.0",bindgen:"0.2.129",wasmSha256:"f4e4606942e43e6af0ed2bed313005f9f4b89b0f716f569818e81742f77926ae",wasmBytes:3294044,solverChanges:!1});export{e as buildInfo};
+var e=Object.freeze({schemaVersion:1,scope:"package",packageName:"@absolutejs/rapier3d",packageVersion:"0.11.0",qualifiedKernelRelease:"0.11.0",upstream:"b716d375efc0201003f0cd9ef7168eee0b62c177",engine:"0.36.0",collisionLibraryVersion:"0.31.1",collisionSource:"git+https://github.com/absolutejs/parry?rev=dbd99a8dfce020da3698056471262435d56d3f69#dbd99a8dfce020da3698056471262435d56d3f69",bindings:"0.21.0",bindgen:"0.2.129",wasmSha256:"352f0e9ff982bd9486e3771bf65fab1944f81ca53f7a5f5d43bee56acdaff6a0",wasmBytes:3298167,solverChanges:!0});export{e as buildInfo};

package/dist/provenance.json

@@ -2,15 +2,15 @@
   "schemaVersion": 1,
   "scope": "package",
   "packageName": "@absolutejs/rapier3d",
-  "packageVersion": "0.9.0",
-  "qualifiedKernelRelease": "0.9.0",
+  "packageVersion": "0.11.0",
+  "qualifiedKernelRelease": "0.11.0",
   "upstream": "b716d375efc0201003f0cd9ef7168eee0b62c177",
   "engine": "0.36.0",
   "collisionLibraryVersion": "0.31.1",
   "collisionSource": "git+https://github.com/absolutejs/parry?rev=dbd99a8dfce020da3698056471262435d56d3f69#dbd99a8dfce020da3698056471262435d56d3f69",
   "bindings": "0.21.0",
   "bindgen": "0.2.129",
-  "wasmSha256": "f4e4606942e43e6af0ed2bed313005f9f4b89b0f716f569818e81742f77926ae",
-  "wasmBytes": 3294044,
-  "solverChanges": false
+  "wasmSha256": "352f0e9ff982bd9486e3771bf65fab1944f81ca53f7a5f5d43bee56acdaff6a0",
+  "wasmBytes": 3298167,
+  "solverChanges": true
 }