Rapier3d

The callback receives a restricted solver view: normal, count, point, distance, friction, restitution, and tangent velocity. It does not promise original subshape identifiers or geometric surface normals. The flipped convention matches contactPair. Do not step, free, or mutate the world inside either callback. Nested read-only solver queries are supported; callback exceptions release query wrappers before propagating. Solver distances are the engine's cached contact update distances, not a continuous or post-step exact penetration guarantee.

contactPair exposes geometric manifolds; solverContactPair exposes solver manifolds. Version 0.6 improves velocity-driven kinematics. Version 0.8 corrects previous-simplex witness preservation and reduces force-free rotation roundoff, as described below. Contact and CCD policy defaults remain unchanged. Runtime motion still needs independent geometric and energy checks.

Use Bun 1.4.4+absolute.1, Rust 1.94.0 with wasm32-unknown-unknown, and Python 3.12. Run bun install --frozen-lockfile, then bash absolutejs/scripts/build-native.sh. Cargo's exact lockfile is versioned, compilation defaults to one job (override with CARGO_BUILD_JOBS), and the wasm-bindgen 0.2.129 CLI archive is checksum verified before extraction. Caches and generated build output are reproducible; modified source and selected test receipts are committed. dist/provenance.json records the resulting WASM hash.

API packaging verifies the post-bindgen native bytes against absolutejs/native-kernel.json before writing the distribution. A shared Cargo cache containing a research kernel therefore fails closed. Rebuild stable native source after research builds. Do not update the qualification hash merely to make a build pass: a changed kernel requires physical qualification and a recorded release decision. API-only releases retain the qualified native hash. See absolutejs/research/native-build-guard/ for positive and negative controls.

world.integrationParameters.contactClustering exposes the existing engine switch. It defaults to true, exactly as upstream. Set it only between steps; disabling it may increase solver workload and is not a general penetration fix. Snapshot restore preserves the setting. The game is not instructed to turn it off by this release.

The independent every-step cube/cavity audit demonstrates the distinction: about 0.459mm current penetration is visible in live anchors when the cached distance is zero. Disabling clustering retains about 0.469mm peak penetration in that case. Neither extra telemetry nor changing clustering is presented as a physics cure.

CCD timing now accumulates activation/impact-planning and motion-clamping work across all passes in a step. The TOI timer also accumulates instead of resetting for every clamp pass. Both are recorded only with profiling enabled. The timing fix leaves contact equations and trajectories unchanged; package tests compare profiled/unprofiled poses and official upstream trajectories.

Property — Default — Meaning

contactRecycling — true — Reuse contact manifolds while relative poses stay within the native reuse bounds.

Use this for bounded explicit diagnostics, not every render/physics tick. It allocates shape queries and returns a world-space native shape contact, not a solver manifold, continuous sweep or authored-material overlap bound. Collision filters, hooks and contact skin are not applied. Native unsupported shape pairs can return null as well as separated pairs; null is not a general disjointness proof. Existing contactCollider retains its stored-collider-pose semantics.

The distinction matters for rotating contacts: projecting current anchors onto a stored normal can report no penetration while a fresh shape query finds overlap. Both observations are useful, but answer different questions. Release 0.5.0 keeps the 0.4.0 native kernel byte-for-byte unchanged; it does not include the private relative-motion, EPA or clamp-graph solver experiments.

No API changes are required. This changes motion involving velocity-driven kinematic bodies, including the contact response of bodies they touch. Floating point rounding remains; this is not a general contact or continuous-collision accuracy guarantee. Native qualification records, independent analytic path controls, negative tests against 0.5.0, and bounded CPU observations are retained in absolutejs/research/kinematic-precision/. The private tagged contact research is excluded from this release.

Direct rotation evaluation adds CPU work for velocity-driven kinematic bodies. Profile kinematic-heavy scenes; increasing solver subdivisions is not a free accuracy improvement. The recorded CPU probes are not browser FPS guarantees.

The frozen metadata includes package version, qualified kernel release, native WASM SHA-256/byte count, upstream/binding versions and whether the kernel changes the pinned upstream solver. The same values are available as RAPIER.buildInfo and the root named buildInfo export. Package and kernel releases can differ when an API-only upgrade reuses a qualified kernel. The lightweight subpath contains metadata only and works before init(). It reports the packaged kernel; supplying custom bytes to init(input) does not change that identity and must be recorded separately.

The rotation correction applies only the computed gyroscopic momentum increment. Principal-axis and isotropic force-free bodies therefore avoid artificial spin-up from repeatedly reconstructing the entire velocity through inertia and its inverse. Genuine asymmetric precession remains active and is checked against a converged double-precision Euler/RK4 reference.

In the recorded 336-case, 0.1-second free-spin matrix, worst relative energy error falls from about 0.004033 to 0.000562. One tilted long-box control has about 1.305 ppm more energy error. These measurements cover specific shapes, rates and iteration budgets; they are not a universal energy-error bound, a performance claim, or a substitute for coupled-contact acceptance. f32 conditioning and time integration errors remain.

setGeneralizedDamping(jointHandle, values) returns true on success. It rejects wrong lengths, negative/nonfinite values, native float overflow and removed handles without mutation. Coordinate order is the native generalized order; read the vector again after adding, removing or changing joints. The setter does not wake sleeping bodies; wake the affected bodies explicitly. Neither method 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.

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.

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.

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.

The focused native suite covers 2,688 tensor/aggregation cases in f32 and f64. The package tests also reconstruct two- and three-collider physical tensors across scale, orientation and insertion order. The small-object baseline could exceed 50% relative tensor error; this is a reproduced fixture, not an estimate of error across all objects. Angular integration and articulated COM-transport limitations are separate and remain under investigation.

This calculation runs when mass properties are recomputed. It is not a render optimization: recompute after geometry/mass changes, not unnecessarily every frame. Qualification records, measured cost and limits are retained under absolutejs/research/inertia-reconstruction/.

A rejected update does not partially mutate state. Nonphysical stored moments, rotation limits and failed/invalid solves are observed explicitly; the existing correction/cap ordering applies for the rest of that island solve. The next solve re-evaluates eligibility. No energy or momentum clamp is introduced.

With world.profilerEnabled = true, world.freeRotationStats() returns owned counts (acceptedSteps, nonphysicalInertiaRejections, rotationLimitRejections, invalidOrFailedSolves), maximum Newton updates, and maximum accepted residual in radians/second. It returns null before a completed profiled step, after restoration, while profiling is disabled or after toggling it. Counts include solver substeps and CCD passes; zero acceptance does not establish conservation. The bounded createPhysicsStepProfiler includes these observations as each sample's native.freeRotation, with the same sample and ownership limits.

world.freeAssemblyStats() reports owned attempt counts after a completed profiled step, with the same freshness rules as freeRotationStats(). The bounded profiler records a deep-owned native.freeAssembly object. Counters distinguish accepted steps, nonphysical-inertia rejections, rotation-limit rejections, and invalid/failed solves. Unsupported assemblies and invalid aggregate construction are excluded before an attempt; these exclusions do not increment rejection counts. Zero counts do not prove conservation. Counts include solver substeps and CCD passes. Qualification includes 198 package tests, 843 game tests, GPU-disabled browser checks, 80 byte-exact snapshot replays and matching independent distribution builds. The synthetic 16-assembly falling benchmark measured about 0.95 additional microseconds per assembly/substep (median paired batch ratio 1.12); this is not a hardware FPS result. Contact coupling, partial-subtree fracture and extreme thin-moment storage remain separate work. See absolutejs/research/aggregate-free-transport/README.md for evidence and limits.

An ordinary free fragment now retains the matched free-rotation path when an unrelated articulation shares its solver batch. Multibody links are excluded from ordinary-body initialization, and existing external-constraint, damping, torque, lock and speed exclusions still apply. This corrects a batch-dependent motion error without applying free-body integration to constrained bodies.

takeSnapshot() now writes the ABSJS3DS envelope, version 1, including ordered pending connectivity edits and dirty impulse-joint state. Saving immediately after a cut therefore retains changes not yet consumed by a simulation step. Native Rust callers can capture/restore the opaque PendingIslandEvents companion with the corresponding serialized world sets. Capture neither flushes edits nor reconstructs the world's connectivity. Snapshot payloads still depend on the native engine layout: retain buildInfo with diagnostic captures; the envelope is not a promise of cross-engine save compatibility. Prior compatible raw captures remain readable for investigation, but edits omitted by their original writer cannot be recovered. All new saves use the versioned format.

Qualification includes 223 package tests, 843 game tests, exact sleeping-wake replays, native feature/worker checks, GPU-disabled browser replay and identical independent builds. Unaffected transport and impact states match published 0.16.0. Sorting has a measured cost: at 256 released bodies, median first-wake step time was 0.82 ms versus 0.98 ms, with about 26 microseconds added per pending snapshot capture. These are bounded CPU fixtures, not hardware FPS claims. See absolutejs/research/snapshot-order/ for original failures and full evidence.

The new rule applies only when both shapes are convex. Composite triangle, heightfield and compound contact recycling retains its prior behavior. A broader candidate regressed real generated-terrain support and was rejected; its captures and controls remain in the research record. Mixed touching/predictive sets and general composite-contact accuracy remain separate qualification work.

Qualification includes 227 package tests, 844 game tests, exact captured replay, one/two-worker native checks, allocation-enabled no-std, GPU-disabled browser checks and 18 full tree-drop cases. Four generated/excavated terrain cases retain all measured physical fields and 491 poses exactly versus 0.16.1. The originally bad flat-floor tree cases improve from roughly 7–12 mm cached penetration to below 0.6 mm; other cases can change within their original limits. These cached measurements are not continuous authored-material penetration guarantees.

This is a two-file solver correction. It changes no public API, snapshot layout, material coefficient, solver budget or admission tolerance. Published Parry c566aabd is unchanged; the separate GJK-normal, persistent triangle-frame and conservative-CCD experiments are excluded. This release does not solve the remaining generated-heightfield or rotational direct-sweep limitations.

Qualification includes 236 package tests, 844 game tests, exact snapshot replay, GPU-disabled browser tests, native one/two-worker controls and allocation-enabled no-std. The 24 paired terrain controls add no rejection, but the existing raw variant-0/1920 rejection remains. Four actual generated/excavated work requests and 18 flat-floor tree cases pass their original limits. Twenty of 24 paired terrain rows retain their measured physical fields exactly; others change. These checks do not establish continuous authored-material separation.

Stalled convex queries preserve the direction associated with the support bound used for classification. This fixes a captured tree/triangle query that reported about 202 mm penetration while independent plane projection bounded required separation to about 0.013 mm. Both corrections are qualified together: the rotational change alone exposed this cached-direction error in the full oak excavation test. The combined engine passes it and all 844 game tests.

Package API, snapshot layout, contact tolerances and solver budgets are unchanged. The raw variant-5/960 terrain clearance rejection remains identically present; physical outcomes elsewhere may change. Bounded CPU control scenes retain identical physical results and comparable timings. The targeted tilted-contact fixture costs about 51% more after extended warmup, about 0.037 ms extra per restored step in that fixture. This is a measured correctness tradeoff, not a browser FPS or general performance guarantee.

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.

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.