@absolutejs/rapier3d 0.10.0 → 0.12.0

package/dist/types/pipeline/index.d.ts

@@ -5,3 +5,4 @@ export * from "./event_queue";
 export * from "./physics_hooks";
 export * from "./debug_render_pipeline";
 export * from "./query_pipeline";
+export * from "./step_profile";

package/dist/types/pipeline/step_profile.d.ts

@@ -0,0 +1,65 @@
+import type { World, ContactConvergenceStats } from "./world";
+import type { EventQueue } from "./event_queue";
+import type { PhysicsHooks } from "./physics_hooks";
+export interface PhysicsStepSample {
+    /** Zero-based index among calls made through this recorder. */
+    step: number;
+    outcome: "completed" | "threw";
+    /** Time inside World.step, excluding profile capture and recorder bookkeeping. */
+    wallTimeMs: number | null;
+    captureStatus: "captured" | "step-threw" | "capture-failed";
+    native: {
+        lengthUnit: number;
+        timestep: number;
+        solverIterations: number;
+        ccdSubsteps: number;
+        timings: {
+            stepMs: number;
+            collisionDetectionMs: number;
+            solverMs: number;
+            assemblyMs: number;
+            resolutionMs: number;
+            ccdMs: number;
+        };
+        convergence: ContactConvergenceStats;
+    } | null;
+}
+export interface PhysicsStepProfile {
+    sampleEvery: number;
+    sampleStartStep: number;
+    maxSamples: number;
+    attemptedSteps: number;
+    completedSteps: number;
+    failedSteps: number;
+    timedSteps: number;
+    /** Null if a finite sum could not be represented. */
+    totalWallTimeMs: number | null;
+    maxWallTimeMs: number | null;
+    slowestStep: number | null;
+    timingErrors: number;
+    captureErrors: number;
+    samplesOmittedForBudget: number;
+    /** Owned bounded samples. They do not estimate all unsampled native phases. */
+    samples: PhysicsStepSample[];
+}
+export interface PhysicsStepProfileOptions {
+    /** Capture every Nth managed call, default 32; integer 1..1,000,000. */
+    sampleEvery?: number;
+    /** First managed call eligible for capture, default 0; integer 0..1,000,000,000. */
+    sampleStartStep?: number;
+    /** Maximum retained/captured native profiles, default 32; integer 0..256. */
+    maxSamples?: number;
+    /** Monotonic milliseconds; defaults to performance.now. Failures are recorded. */
+    now?: () => number;
+}
+/** Borrow a world for explicitly managed steps. No listeners, render loop, timer,
+ * transport, or world ownership is created. Each sampled call restores the
+ * previous profiler setting, including on an exception. Unselected calls leave
+ * the setting alone. World.step exceptions propagate unchanged after accounting.
+ * Attach the actual engine/build identity when exporting a snapshot.
+ */
+export declare function createPhysicsStepProfiler(world: World, options?: PhysicsStepProfileOptions): {
+    step(eventQueue?: EventQueue, hooks?: PhysicsHooks): void;
+    /** Deep-owned report; no live native query is performed here. */
+    snapshot(): PhysicsStepProfile;
+};

package/dist/types/pipeline/world.d.ts

@@ -10,6 +10,22 @@ import { PhysicsHooks } from "./physics_hooks";
 import { DebugRenderBuffers, DebugRenderPipeline } from "./debug_render_pipeline";
 import { KinematicCharacterController, PidAxesMask, PidController } from "../control";
 import { DynamicRayCastVehicleController } from "../control";
+/** Last profiled step's restricted adaptive contact solves, including CCD passes.
+ * Counts describe solve groups/phases, not individual contacts or physical islands.
+ * Residuals are projected normal velocity errors in world units per second.
+ */
+export interface ContactConvergenceStats {
+    compressionSolves: number;
+    compressionIterations: number;
+    compressionLimitHits: number;
+    /** Maximum terminal residual across eligible compression phases. */
+    maxCompressionResidual: number;
+    restitutionSolves: number;
+    restitutionIterations: number;
+    restitutionLimitHits: number;
+    /** Maximum terminal residual across eligible restitution phases. */
+    maxRestitutionResidual: number;
+}
 /**
  * The physics world.
  *
@@ -568,6 +584,13 @@ export declare class World {
      * This count does not expose internal substep durations or time of impact.
      */
     ccdSubsteps(): number | null;
+    /** Owned observations from the last completed profiled step; null before
+     * that step, after toggling profiling, when disabled, or after restoration.
+     * Zero solves means no eligible adaptive path, not proof of convergence.
+     * A limit hit means the phase exhausted its budget above tolerance.
+     * Reading or modifying the returned object does not affect simulation.
+     */
+    contactConvergence(): ContactConvergenceStats | null;
     /**
      * The time spent in milliseconds by the last step to run the entire simulation step.
      *

package/dist/types/rapier_wasm3d.d.ts

@@ -895,6 +895,7 @@ export class RawPhysicsPipeline {
     free(): void;
     [Symbol.dispose](): void;
     ccd_substeps(): number | undefined;
+    contact_convergence(): Float64Array | undefined;
     is_profiler_enabled(): boolean;
     constructor();
     set_profiler_enabled(enabled: boolean): void;
@@ -2402,6 +2403,7 @@ export interface InitOutput {
     readonly rawnarrowphase_intersection_pairs_with: (a: number, b: number, c: number) => void;
     readonly rawnarrowphase_new: () => number;
     readonly rawphysicspipeline_ccd_substeps: (a: number) => number;
+    readonly rawphysicspipeline_contact_convergence: (a: number, b: number) => void;
     readonly rawphysicspipeline_is_profiler_enabled: (a: number) => number;
     readonly rawphysicspipeline_new: () => number;
     readonly rawphysicspipeline_set_profiler_enabled: (a: number, b: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rapier3d",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Rapier 3D with corrected contact witnesses, rotation precision and solver diagnostics",
   "type": "module",
   "license": "Apache-2.0",