@absolutejs/rapier3d 0.17.0 → 0.21.0

package/README.md

@@ -596,3 +596,153 @@ regressions, 237 package tests, GPU-disabled browser checks, native one/two-work
 controls, no-std, 24 tree/rate comparisons, four generated/excavated requests,
 18 flat-tree cases and an independent build matching all shipped files.
 Evidence: `absolutejs/research/rotational-contact/`.
+
+### Numerical contact softness
+
+`world.integrationParameters.contactSoftness` and `staticContactSoftness` read
+or atomically replace `{ naturalFrequency, dampingRatio }`. The first controls
+dynamic contacts (native default 30 Hz / 10); the second controls contacts with
+a fixed body (native default 60 Hz / 10). Change them between steps. Reads
+return owned copies; values must be representable finite native coefficients,
+with positive frequency and nonnegative damping. Both values are validated
+before either changes. Snapshots preserve both settings. Bounded step profiles
+record each distinct settings pair once in a bounded `contactSettings` table;
+samples carry `native.contactSettingsIndex`. Reports deeply own that table,
+including after the world is freed. This avoids repeating configuration in
+every sample and keeps telemetry within existing event budgets.
+
+These are numerical regularization parameters, not measured material elasticity.
+Higher frequency can reduce transient penetration but may produce jitter or
+prevent sleeping. Qualify motion, contact, sleeping and cost across actual
+scenarios before changing a product's policy. Defaults are unchanged.
+
+### 0.18.0 contact correction and adoption limits
+
+The collision library rejects an exactly duplicated CSO point before it can
+form a degenerate tetrahedron and lose a valid terrain contact. Both friction
+builders select static/dynamic coefficients directly, avoiding dependence on
+an unused coefficient through floating-point cancellation.
+
+Native defaults remain unchanged. In the game's actual tree matrix, the
+collision correction fixes one missed-contact case but makes another case
+exceed the game's clearance limit at default softness (-21.007 mm). The game
+therefore qualifies an explicit 600 Hz / 10 static-contact policy alongside
+this engine: all 24 tree/rate cases and 18 cut-tree cases pass and sleep.
+This is a bounded product policy, not a universal stiffness recommendation.
+The default-policy failure is retained in the investigation records.
+
+Qualification: 242 package tests, 847 game tests, four generated/excavated
+terrain requests, GPU-disabled browser controls, native serial/two-worker
+checks, no-std, and independent builds matching all shipped files. Three
+ordinary CPU controls are within roughly 1% of 0.17.0 in this run. See
+`absolutejs/research/contact-softness-controls/` for measured fixture costs,
+source hashes, intermediate failures and scope limitations.
+
+### Queued 0.19.0: explicit quadratic resistance
+
+`solveQuadraticDragImpulse` analytically integrates one quadratic relative-flow
+resistance channel with positive supplied effective inverse mass. It returns the
+signed impulse, implicit relative speed, dissipated energy and separate body /
+reservoir work. It is pure and does not infer shape, exposure or coefficients.
+Use consistent units and the complete effective mass response; verify native
+application precision. See `absolutejs/research/quadratic-drag-2026-10-31/README.md`
+for the derivation, scope and evidence. Native engine qualification stays 0.18.0.
+
+Default inertia-matrix getter results now own their six coefficients. Later
+native getters cannot overwrite a matrix already returned to the caller. Passing
+an explicit matrix target still reuses that target as documented.
+
+`solveQuadraticDragPatches` evaluates up to 4,096 explicit resistance patches in
+double precision at a fixed pose and returns combined linear/angular impulses.
+It reports body/reservoir work and dissipation, owns its outputs and preserves
+inputs. Free-body inverse mass/inertia and patch exposure are caller supplied;
+this is not an articulated-fluid or full CFD model. Patch order and timestep
+convergence remain measurable approximation limits.
+
+## Prepared solver schedules (0.20.0)
+
+The opt-in `world.solverSchedule()` query returns owned observations from the last
+completed profiled step. Like `ccdSubsteps()`, it returns `null` before such a
+step, when profiling is disabled or toggled, and after snapshot restoration.
+`createPhysicsStepProfiler` retains distinct owned records in `solverSchedules`, referenced by each
+sample's `native.solverScheduleIndex` (omitted means entry 0). The table is always
+present and cannot exceed the retained sample
+count; repeated observations do not repeat the full record.
+
+`groupVisits` counts prepared nonempty rigid-body solve groups across CCD passes.
+`rigidBodyVisits` sums their rigid-body slots, while `rigidBodySubsteps` weights
+those slots by each group's prepared substep count. These are visits, not unique
+body identities. `minSubsteps`/`maxSubsteps` report the group range;
+`minSubstepDt`/`maxSubstepDt` are durations in seconds. All four range fields are
+`null` when no nonempty rigid group was prepared. Soft-particle-only work and
+internal PGS sweeps are outside these counts.
+
+This reads the actual group layout, including additional iterations propagated
+through constraint-connected bodies. It does not change that layout, force
+sampling, native timestep or contact policy. It is not a per-body mapping, elapsed
+CPU timing, proof of force/energy accuracy, or forecast of the next step. In
+particular, a previous group's substep count must not silently select gameplay
+fluid-force timing when contact connectivity or CCD can change.
+
+The native observer is qualified by independent native builds and exact full-state
+comparisons across 18 fixtures / 9,240 steps against 0.19.0. Sampled local CPU
+costs and limits are recorded in `absolutejs/research/solver-schedule/`.
+The previous private artifacts remain archived; release availability is separate
+from source qualification.
+
+### Bounded diagnostic profile transport
+
+`encodePhysicsStepProfile(profile)` converts a readable report into an owned,
+versioned numeric packet. `decodePhysicsStepProfile(value)` validates an unknown
+packet and reconstructs owned readable observations. For example:
+
+```ts
+const packet = encodePhysicsStepProfile(profiler.snapshot());
+const restored = decodePhysicsStepProfile(JSON.parse(JSON.stringify(packet)));
+```
+
+The codec preserves every defined observation without rounding, including null
+measurements, failed samples, signed zero and explicit versus omitted default
+schedule references. It excludes arbitrary application metadata and user strings.
+The format tag is `absolutejs-physics-step-profile/1`; one fixed `'-0'` cell tag
+preserves signed zero through JSON. Arrays are bounded to 256 entries, tuple
+lengths and enums are fixed, and indices/scalars are validated. Malformed packets
+throw `TypeError`. This is transport validation, not a claim of native provenance
+or physical correctness. Apply normal metadata redaction outside the codec.
+
+Readable `PhysicsStepProfile` remains the simulation-facing API. In 0.20 its
+always-present `solverSchedules` table and optional sample index are part of that
+schema; older readable profiles without this table are not silently upgraded.
+Keep the format tag with stored packets and decode before displaying their fields.
+
+## Convex boundary export (0.21)
+
+`collider.convexMeshData()` returns an owned `{vertices: Float32Array,
+indices: Uint32Array}` pair from one native hull reconstruction. Use it when both
+buffers are needed; separate `vertices()` and `indices()` calls each reconstruct
+the hull. The query observes the current shape, so replacing a collider's shape
+requires no cache invalidation. Mutating returned arrays does not change the
+collider.
+
+```ts
+const mesh = collider.convexMeshData();
+if (mesh) {
+  // Positions are in collider-local coordinates; indices describe triangles.
+  uploadBoundary(mesh.vertices, mesh.indices);
+}
+```
+
+Nonconvex shapes return `undefined`. Rounded convex shapes return the inner
+polyhedron, excluding the round radius. The mesh is a reconstructed boundary of
+the stored Float32 points, not a copy of internal contact faces. Reconstruction
+uses double precision and exact-sign dimension checks for thin point clouds;
+returned positions remain original Float32 coordinates. It does not upgrade the
+physics engine's storage or solver to double precision. Boundary measurements
+and native mass measurements remain distinct; applications must continue to
+validate both.
+
+`buildInfo.convexExportPrecision` identifies this reconstruction as `float64`.
+The f32 and f64 collision-library dependencies use the same recorded source pin.
+Captured export, browser-worker, simulation-parity and CPU timing evidence lives
+in `absolutejs/research/convex-export/`. Release availability is separate from source qualification; publication may be
+deferred. The unchanged physical engine retains its existing settling limits.

package/absolutejs/README.md

@@ -596,3 +596,153 @@ regressions, 237 package tests, GPU-disabled browser checks, native one/two-work
 controls, no-std, 24 tree/rate comparisons, four generated/excavated requests,
 18 flat-tree cases and an independent build matching all shipped files.
 Evidence: `absolutejs/research/rotational-contact/`.
+
+### Numerical contact softness
+
+`world.integrationParameters.contactSoftness` and `staticContactSoftness` read
+or atomically replace `{ naturalFrequency, dampingRatio }`. The first controls
+dynamic contacts (native default 30 Hz / 10); the second controls contacts with
+a fixed body (native default 60 Hz / 10). Change them between steps. Reads
+return owned copies; values must be representable finite native coefficients,
+with positive frequency and nonnegative damping. Both values are validated
+before either changes. Snapshots preserve both settings. Bounded step profiles
+record each distinct settings pair once in a bounded `contactSettings` table;
+samples carry `native.contactSettingsIndex`. Reports deeply own that table,
+including after the world is freed. This avoids repeating configuration in
+every sample and keeps telemetry within existing event budgets.
+
+These are numerical regularization parameters, not measured material elasticity.
+Higher frequency can reduce transient penetration but may produce jitter or
+prevent sleeping. Qualify motion, contact, sleeping and cost across actual
+scenarios before changing a product's policy. Defaults are unchanged.
+
+### 0.18.0 contact correction and adoption limits
+
+The collision library rejects an exactly duplicated CSO point before it can
+form a degenerate tetrahedron and lose a valid terrain contact. Both friction
+builders select static/dynamic coefficients directly, avoiding dependence on
+an unused coefficient through floating-point cancellation.
+
+Native defaults remain unchanged. In the game's actual tree matrix, the
+collision correction fixes one missed-contact case but makes another case
+exceed the game's clearance limit at default softness (-21.007 mm). The game
+therefore qualifies an explicit 600 Hz / 10 static-contact policy alongside
+this engine: all 24 tree/rate cases and 18 cut-tree cases pass and sleep.
+This is a bounded product policy, not a universal stiffness recommendation.
+The default-policy failure is retained in the investigation records.
+
+Qualification: 242 package tests, 847 game tests, four generated/excavated
+terrain requests, GPU-disabled browser controls, native serial/two-worker
+checks, no-std, and independent builds matching all shipped files. Three
+ordinary CPU controls are within roughly 1% of 0.17.0 in this run. See
+`absolutejs/research/contact-softness-controls/` for measured fixture costs,
+source hashes, intermediate failures and scope limitations.
+
+### Queued 0.19.0: explicit quadratic resistance
+
+`solveQuadraticDragImpulse` analytically integrates one quadratic relative-flow
+resistance channel with positive supplied effective inverse mass. It returns the
+signed impulse, implicit relative speed, dissipated energy and separate body /
+reservoir work. It is pure and does not infer shape, exposure or coefficients.
+Use consistent units and the complete effective mass response; verify native
+application precision. See `absolutejs/research/quadratic-drag-2026-10-31/README.md`
+for the derivation, scope and evidence. Native engine qualification stays 0.18.0.
+
+Default inertia-matrix getter results now own their six coefficients. Later
+native getters cannot overwrite a matrix already returned to the caller. Passing
+an explicit matrix target still reuses that target as documented.
+
+`solveQuadraticDragPatches` evaluates up to 4,096 explicit resistance patches in
+double precision at a fixed pose and returns combined linear/angular impulses.
+It reports body/reservoir work and dissipation, owns its outputs and preserves
+inputs. Free-body inverse mass/inertia and patch exposure are caller supplied;
+this is not an articulated-fluid or full CFD model. Patch order and timestep
+convergence remain measurable approximation limits.
+
+## Prepared solver schedules (0.20.0)
+
+The opt-in `world.solverSchedule()` query returns owned observations from the last
+completed profiled step. Like `ccdSubsteps()`, it returns `null` before such a
+step, when profiling is disabled or toggled, and after snapshot restoration.
+`createPhysicsStepProfiler` retains distinct owned records in `solverSchedules`, referenced by each
+sample's `native.solverScheduleIndex` (omitted means entry 0). The table is always
+present and cannot exceed the retained sample
+count; repeated observations do not repeat the full record.
+
+`groupVisits` counts prepared nonempty rigid-body solve groups across CCD passes.
+`rigidBodyVisits` sums their rigid-body slots, while `rigidBodySubsteps` weights
+those slots by each group's prepared substep count. These are visits, not unique
+body identities. `minSubsteps`/`maxSubsteps` report the group range;
+`minSubstepDt`/`maxSubstepDt` are durations in seconds. All four range fields are
+`null` when no nonempty rigid group was prepared. Soft-particle-only work and
+internal PGS sweeps are outside these counts.
+
+This reads the actual group layout, including additional iterations propagated
+through constraint-connected bodies. It does not change that layout, force
+sampling, native timestep or contact policy. It is not a per-body mapping, elapsed
+CPU timing, proof of force/energy accuracy, or forecast of the next step. In
+particular, a previous group's substep count must not silently select gameplay
+fluid-force timing when contact connectivity or CCD can change.
+
+The native observer is qualified by independent native builds and exact full-state
+comparisons across 18 fixtures / 9,240 steps against 0.19.0. Sampled local CPU
+costs and limits are recorded in `absolutejs/research/solver-schedule/`.
+The previous private artifacts remain archived; release availability is separate
+from source qualification.
+
+### Bounded diagnostic profile transport
+
+`encodePhysicsStepProfile(profile)` converts a readable report into an owned,
+versioned numeric packet. `decodePhysicsStepProfile(value)` validates an unknown
+packet and reconstructs owned readable observations. For example:
+
+```ts
+const packet = encodePhysicsStepProfile(profiler.snapshot());
+const restored = decodePhysicsStepProfile(JSON.parse(JSON.stringify(packet)));
+```
+
+The codec preserves every defined observation without rounding, including null
+measurements, failed samples, signed zero and explicit versus omitted default
+schedule references. It excludes arbitrary application metadata and user strings.
+The format tag is `absolutejs-physics-step-profile/1`; one fixed `'-0'` cell tag
+preserves signed zero through JSON. Arrays are bounded to 256 entries, tuple
+lengths and enums are fixed, and indices/scalars are validated. Malformed packets
+throw `TypeError`. This is transport validation, not a claim of native provenance
+or physical correctness. Apply normal metadata redaction outside the codec.
+
+Readable `PhysicsStepProfile` remains the simulation-facing API. In 0.20 its
+always-present `solverSchedules` table and optional sample index are part of that
+schema; older readable profiles without this table are not silently upgraded.
+Keep the format tag with stored packets and decode before displaying their fields.
+
+## Convex boundary export (0.21)
+
+`collider.convexMeshData()` returns an owned `{vertices: Float32Array,
+indices: Uint32Array}` pair from one native hull reconstruction. Use it when both
+buffers are needed; separate `vertices()` and `indices()` calls each reconstruct
+the hull. The query observes the current shape, so replacing a collider's shape
+requires no cache invalidation. Mutating returned arrays does not change the
+collider.
+
+```ts
+const mesh = collider.convexMeshData();
+if (mesh) {
+  // Positions are in collider-local coordinates; indices describe triangles.
+  uploadBoundary(mesh.vertices, mesh.indices);
+}
+```
+
+Nonconvex shapes return `undefined`. Rounded convex shapes return the inner
+polyhedron, excluding the round radius. The mesh is a reconstructed boundary of
+the stored Float32 points, not a copy of internal contact faces. Reconstruction
+uses double precision and exact-sign dimension checks for thin point clouds;
+returned positions remain original Float32 coordinates. It does not upgrade the
+physics engine's storage or solver to double precision. Boundary measurements
+and native mass measurements remain distinct; applications must continue to
+validate both.
+
+`buildInfo.convexExportPrecision` identifies this reconstruction as `float64`.
+The f32 and f64 collision-library dependencies use the same recorded source pin.
+Captured export, browser-worker, simulation-parity and CPU timing evidence lives
+in `absolutejs/research/convex-export/`. Release availability is separate from source qualification; publication may be
+deferred. The unchanged physical engine retains its existing settling limits.

package/dist/build-info.mjs

@@ -1 +1 @@
-var e=Object.freeze({schemaVersion:1,scope:"package",packageName:"@absolutejs/rapier3d",packageVersion:"0.17.0",qualifiedKernelRelease:"0.17.0",upstream:"b716d375efc0201003f0cd9ef7168eee0b62c177",engine:"0.36.0",collisionLibraryVersion:"0.31.1",collisionSource:"git+https://github.com/absolutejs/parry?rev=8c68a625c15930ca8b685f30861aedf5d59c3726#8c68a625c15930ca8b685f30861aedf5d59c3726",bindings:"0.21.0",bindgen:"0.2.129",wasmSha256:"0dad2a033f7d46e262a08a370429dc6e23ea95009f824c14a76302a15a8f73a8",wasmBytes:3362690,solverChanges:!0});export{e as buildInfo};
+var e=Object.freeze({schemaVersion:1,scope:"package",packageName:"@absolutejs/rapier3d",packageVersion:"0.21.0",qualifiedKernelRelease:"0.21.0",upstream:"b716d375efc0201003f0cd9ef7168eee0b62c177",engine:"0.36.0",collisionLibraryVersion:"0.31.1",collisionSource:"git+https://github.com/absolutejs/parry?rev=6afbe26a23a4d89903c6a33d0a0c0d98d9af7b72#6afbe26a23a4d89903c6a33d0a0c0d98d9af7b72",convexExportPrecision:"float64",bindings:"0.21.0",bindgen:"0.2.129",wasmSha256:"f1a909f788cc332e4ed8a4af3da1f38c84fd9bd995aa1ffe85dd9bee36f04050",wasmBytes:3411245,solverChanges:!0});export{e as buildInfo};

package/dist/provenance.json

@@ -2,15 +2,16 @@
   "schemaVersion": 1,
   "scope": "package",
   "packageName": "@absolutejs/rapier3d",
-  "packageVersion": "0.17.0",
-  "qualifiedKernelRelease": "0.17.0",
+  "packageVersion": "0.21.0",
+  "qualifiedKernelRelease": "0.21.0",
   "upstream": "b716d375efc0201003f0cd9ef7168eee0b62c177",
   "engine": "0.36.0",
   "collisionLibraryVersion": "0.31.1",
-  "collisionSource": "git+https://github.com/absolutejs/parry?rev=8c68a625c15930ca8b685f30861aedf5d59c3726#8c68a625c15930ca8b685f30861aedf5d59c3726",
+  "collisionSource": "git+https://github.com/absolutejs/parry?rev=6afbe26a23a4d89903c6a33d0a0c0d98d9af7b72#6afbe26a23a4d89903c6a33d0a0c0d98d9af7b72",
+  "convexExportPrecision": "float64",
   "bindings": "0.21.0",
   "bindgen": "0.2.129",
-  "wasmSha256": "0dad2a033f7d46e262a08a370429dc6e23ea95009f824c14a76302a15a8f73a8",
-  "wasmBytes": 3362690,
+  "wasmSha256": "f1a909f788cc332e4ed8a4af3da1f38c84fd9bd995aa1ffe85dd9bee36f04050",
+  "wasmBytes": 3411245,
   "solverChanges": true
 }