@absolutejs/rapier3d 0.10.0 → 0.12.0

package/README.md

@@ -292,3 +292,62 @@ Adaptive compression applies only to one-group, single-worker, generic-only fric
 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.
+
+## Bounded managed-step profiling
+
+`createPhysicsStepProfiler(world, options)` borrows an initialized world. Call
+`profiler.step(eventQueue?, hooks?)` wherever you would explicitly call
+`world.step()`, then `profiler.snapshot()` to obtain an owned report. It creates no
+render loop, listeners, transport, or ownership of the world/event queue. This is
+suitable for workers and offline jobs as well as application-managed stepping.
+
+```ts
+const profiler = RAPIER.createPhysicsStepProfiler(world, {
+    sampleEvery: 32,
+    sampleStartStep: 0,
+    maxSamples: 16,
+});
+for (let step = 0; step < 960; step++) profiler.step();
+const report = { engine: RAPIER.buildInfo, physics: profiler.snapshot() };
+```
+
+Every managed call records wall time spent inside `World.step`. Selected calls
+also capture native phase timings, CCD substeps, convergence counters and world
+units/settings. Native timings are nested: do not add solver, assembly,
+resolution and CCD durations together. Native samples are observations of those
+selected calls, not estimates of unsampled solver work. The summary wall-time
+sum excludes profiler setup, native capture and report construction; it is not
+whole-job time or an FPS measurement.
+
+The default cadence and capacity are both 32. Sampling stops when capacity is
+reached; `samplesOmittedForBudget` counts later eligible calls. Use
+`sampleStartStep` to inspect a later window. Capacity is bounded to 256; zero
+keeps wall-time accounting without enabling native profiling. A failed selected
+call consumes a slot. There is no unbounded event queue or per-body duplication.
+
+Each selected call restores the previous native profiler setting, including when
+stepping throws. Unselected calls leave it alone. If profiling was already on,
+the caller retains fresh native observations; otherwise turning it back off
+invalidates native live queries, but the owned captured sample remains readable.
+Original step exceptions (including non-Error values) propagate unchanged.
+Clock and native-capture failures are counted instead of stopping a successful
+physical step; missing/invalid observations are null, never invented zero times.
+A custom `now` must return monotonic milliseconds and have no side effects.
+Reports remain usable after freeing the borrowed world. Always attach the actual
+build identity when storing or sending a report through your existing diagnostics
+system. Sampling has a cost: use explicit application policy and measure it.
+
+This API uses the unchanged qualified 0.11.0 native kernel. It does not change
+solver thresholds, contact policies or physical state serialization.

package/absolutejs/README.md

@@ -292,3 +292,62 @@ Adaptive compression applies only to one-group, single-worker, generic-only fric
 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.
+
+## Bounded managed-step profiling
+
+`createPhysicsStepProfiler(world, options)` borrows an initialized world. Call
+`profiler.step(eventQueue?, hooks?)` wherever you would explicitly call
+`world.step()`, then `profiler.snapshot()` to obtain an owned report. It creates no
+render loop, listeners, transport, or ownership of the world/event queue. This is
+suitable for workers and offline jobs as well as application-managed stepping.
+
+```ts
+const profiler = RAPIER.createPhysicsStepProfiler(world, {
+    sampleEvery: 32,
+    sampleStartStep: 0,
+    maxSamples: 16,
+});
+for (let step = 0; step < 960; step++) profiler.step();
+const report = { engine: RAPIER.buildInfo, physics: profiler.snapshot() };
+```
+
+Every managed call records wall time spent inside `World.step`. Selected calls
+also capture native phase timings, CCD substeps, convergence counters and world
+units/settings. Native timings are nested: do not add solver, assembly,
+resolution and CCD durations together. Native samples are observations of those
+selected calls, not estimates of unsampled solver work. The summary wall-time
+sum excludes profiler setup, native capture and report construction; it is not
+whole-job time or an FPS measurement.
+
+The default cadence and capacity are both 32. Sampling stops when capacity is
+reached; `samplesOmittedForBudget` counts later eligible calls. Use
+`sampleStartStep` to inspect a later window. Capacity is bounded to 256; zero
+keeps wall-time accounting without enabling native profiling. A failed selected
+call consumes a slot. There is no unbounded event queue or per-body duplication.
+
+Each selected call restores the previous native profiler setting, including when
+stepping throws. Unselected calls leave it alone. If profiling was already on,
+the caller retains fresh native observations; otherwise turning it back off
+invalidates native live queries, but the owned captured sample remains readable.
+Original step exceptions (including non-Error values) propagate unchanged.
+Clock and native-capture failures are counted instead of stopping a successful
+physical step; missing/invalid observations are null, never invented zero times.
+A custom `now` must return monotonic milliseconds and have no side effects.
+Reports remain usable after freeing the borrowed world. Always attach the actual
+build identity when storing or sending a report through your existing diagnostics
+system. Sampling has a cost: use explicit application policy and measure it.
+
+This API uses the unchanged qualified 0.11.0 native kernel. It does not change
+solver thresholds, contact policies or physical state serialization.

package/dist/build-info.mjs

@@ -1 +1 @@
-var e=Object.freeze({schemaVersion:1,scope:"package",packageName:"@absolutejs/rapier3d",packageVersion:"0.10.0",qualifiedKernelRelease:"0.10.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:"05237bc7c173763fc740d80f6440130e548743c02083542370f17bb3061bf1e3",wasmBytes:3297267,solverChanges:!0});export{e as buildInfo};
+var e=Object.freeze({schemaVersion:1,scope:"package",packageName:"@absolutejs/rapier3d",packageVersion:"0.12.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.10.0",
-  "qualifiedKernelRelease": "0.10.0",
+  "packageVersion": "0.12.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": "05237bc7c173763fc740d80f6440130e548743c02083542370f17bb3061bf1e3",
-  "wasmBytes": 3297267,
+  "wasmSha256": "352f0e9ff982bd9486e3771bf65fab1944f81ca53f7a5f5d43bee56acdaff6a0",
+  "wasmBytes": 3298167,
   "solverChanges": true
 }