avbd-babylon 0.4.1 → 0.4.3

package/dist/babylonAvbd.d.ts

@@ -45,6 +45,10 @@ export interface AvbdWorldOptions {
   solverMode?: AvbdSolverMode;
   /** Automatically batch a closed jointless world of up to 32 bodies. */
   smallGroups?: boolean;
+  /** Advanced: reserve 0–64 parallel solve groups for dense or waking contacts. */
+  minimumColors?: number;
+  /** Advanced: minimum coloring rounds, an even integer from 0–32. */
+  minimumColorRounds?: number;
   bvh?: { rebuildInterval?: number };
   /** Optional GPU sleeping. Large worlds wake conservative connected groups on impact. */
   sleeping?: boolean | AvbdSleepOptions;

package/dist/nativeScenes.d.ts

@@ -242,7 +242,9 @@ export interface AvbdGpuParameters2D extends AvbdGpuParameters {
 }
 /** 3D tracks current awake groups and retains sleeping support connections. */
 export interface AvbdSleepOptions {
+  /** Combined linear and radius-scaled angular motion, world units/second. Default 0.03. */
   speedThreshold?: number;
+  /** Seconds continuously below the speed threshold while supported. Default 0.5. */
   timeThreshold?: number;
   /** 3D: automatic for large desktop worlds; false selects whole-world waking. */
   islands?: boolean;

package/docs/BABYLON_API.md

@@ -81,6 +81,12 @@ compatibility. These names identify internal implementations, not quality
 levels or paper results. Overrides preserve live GPU state; first use may
 compile pipelines. Start with the automatic default.
 
+For dense piles that gain many dynamic contacts at once, `minimumColors` reserves
+parallel solve groups (integer 0–64) and `minimumColorRounds` reserves coloring
+rounds (even integer 0–32). Pass them to `AvbdPhysics.create()` before initialization.
+The mixed collider gallery uses `32` for both. These control work scheduling;
+they do not change solver iterations or contact equations.
+
 Box, sphere and capsule collisions are native. Capsules use an exact rounded
 segment along local Y; height includes both caps and X/Z diameters must match.
 `CYLINDER` and `CONVEX_HULL` use a polygonal convex hull, with a 32-vertex limit. Mesh geometry,
@@ -147,7 +153,13 @@ reserve storage; `readContactEvents()` reports dropped events or a full pair
 table. End events do not retain an old position. Callbacks run asynchronously.
 
 `sleeping: true` or `{ speedThreshold: 0.03, timeThreshold: 0.5 }` enables an
-optional GPU policy. Supported quiet bodies sleep. Large desktop 3D worlds
+optional GPU policy. Supported quiet bodies sleep. Speed combines translation
+and radius-scaled rotation in world units/second; `0.03` is 3 cm/second if units
+are meters. The quiet timer resets above that speed. Thresholds remain manual
+so applications can choose values appropriate to their size and camera distance.
+Sleeping preserves the body's physical mass while skipping its movement solve;
+impacts and support removal restore dynamic participation.
+Large desktop 3D worlds
 automatically wake conservative connected groups on impact, keeping unrelated
 piles asleep; the shared static floor does not join them. `islands:true` opts
 into group waking in smaller worlds, and `islands:false` selects whole-world
@@ -155,8 +167,10 @@ waking. Awake groups rebuild their connections from current contacts; sleeping
 groups retain the support connections omitted by collision detection. A group
 settles together after its eligible members stay quiet, so sleeping one course
 does not repeatedly disturb the courses above it. Contact waking checks closing
-speed at each contact point, including rotation. Updating a grab anchor wakes
-the held body; ordinary edits and changes to supports wake the world.
+speed at each contact point, including rotation. Adding or removing constraints
+and updating a grab anchor wake their endpoints and sleeping connected groups;
+unrelated groups stay asleep. Ordinary body edits and changes to supports wake
+the world. A connected group can stay awake while any member moves or loses support.
 Unsupported bodies
 under gravity stay awake. `wakeAll()`, `body.wakeUp()` and `readSleepStats()` are
 available. Suspended jointed objects are not guaranteed to sleep. Defaults and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avbd-babylon",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "GPU AVBD rigid-body physics with a Babylon.js aggregate API",
   "main": "./dist/avbd.js",
   "types": "./dist/avbd.d.ts",
@@ -15,7 +15,7 @@
     "test": "node scripts/test-gpu.mjs",
     "test:reference": "node --experimental-transform-types --test reference/three-avbd/tests/*.test.ts",
     "test:gpu": "node scripts/test-gpu.mjs",
-    "test:sleeping": "node scripts/build.mjs && node scripts/check-lab-sleep.mjs && node scripts/check-sleep-stability.mjs --drag && node scripts/check-jointed-settling.mjs",
+    "test:sleeping": "node scripts/build.mjs && node scripts/check-lab-sleep.mjs && node scripts/check-sleep-stability.mjs --drag && node scripts/check-sleeping-impact-scenes.mjs && node scripts/check-jointed-settling.mjs",
     "test:all": "node scripts/test-all.mjs",
     "test:complete": "node scripts/test-all.mjs --strict",
     "test:scenes": "node scripts/build.mjs && node scripts/check-scenes.mjs",
@@ -44,6 +44,7 @@
     "benchmark:backends": "node scripts/build.mjs && node scripts/benchmark-backends.mjs",
     "benchmark:native": "node scripts/benchmark-package.mjs",
     "benchmark:sleeping": "node scripts/benchmark-package.mjs",
+    "benchmark:scene-sleep": "node scripts/benchmark-scene-sleep.mjs && node scripts/build.mjs && node scripts/report-solver.mjs",
     "benchmark:connected-sleep": "node scripts/benchmark-connected-sleep.mjs",
     "benchmark:small-groups": "node scripts/benchmark-small-groups.mjs",
     "benchmark:native-edits": "node scripts/check-native-performance.mjs",

package/tests/README.md

@@ -26,6 +26,7 @@ run on the host because they inspect files and JavaScript APIs.
 | `npm run test:fracture`             | Voronoi partition, breakable face bonds, wrecking-ball impact and persistent rubble                                                                                   |
 | `npm run test:reference`            | Explicitly requested upstream CPU comparison; excluded from normal validation                                                                                         |
 | `npm run benchmark:native`          | 2D/3D movement/spin, property edits, grouped queries, sleeping and selected reads; three repeats                                                                      |
+| `npm run benchmark:scene-sleep`     | Every demo scene: paired sleeping-on/off runs, complete physics timings during motion and later settling, and generated demo defaults |
 | `npm run benchmark:connected-sleep` | 505,923-body walls: all-awake overhead and later impacts with whole-world versus automatic connected-group waking; two alternating paired runs                        |
 | `npm run benchmark:small-groups`    | 9- and 32-body closed worlds: automatic workgroup movement versus separate dispatches, three paired runs and exact final body-state comparisons                       |
 | `npm run benchmark:native-edits`    | 100K motion updates, 10K property edits and 64 ray queries in 2D/3D; API overhead and GPU completion                                                                  |
@@ -38,7 +39,8 @@ Set `AVBD_TEST_BROWSER` to a Chromium executable if browser discovery fails.
 
 `node scripts/check-galton-startup.mjs` measures startup of the 40,000-marble
 playground and verifies default worker execution, an explicit main-thread choice,
-and automatic fallback when workers are unavailable. `test:playgrounds` also
+and automatic fallback when workers are unavailable. It also checks that page
+dependencies stay small before starting the worker. `test:playgrounds` also
 checks that at least 99.5% of marbles reach the bins, compares GPU counts with real
 body positions, and measures the shape of the distribution.
 
@@ -48,7 +50,9 @@ poses with direct drawing, Babylon, shared-input workers and CPU compatibility.
 and bounded catch-up under load. `check-lab-sleep.mjs` checks live sleeping
 toggles, large-scene defaults and bowling balls in all sixteen wall lanes.
 `check-sleep-stability.mjs --drag` follows the 28K brick ring for 900 steps and
-checks that repeated grab-anchor updates leave resting debris asleep.
+checks that creating a grab and repeatedly updating its anchor leave a distant,
+disconnected sleeper asleep with unchanged poses. GPU regressions also check
+grab release and stale gravity predictions beside an awake resting body.
 `check-jointed-settling.mjs` measures GPU collision and movement time while the
 34K jointed drop lands, comparing sleeping off, whole-world waking and automatic
 group sleeping. It checks contact capacity and solve-group conflicts on every
@@ -61,6 +65,9 @@ scene defaults and URL settings with CPU, WebGPU, Babylon and worker execution.
 The showcase exposes steps per second beside solving iterations. Both settings
 remain fixed while a benchmark measurement runs.
 
+`check-runtime-efficiency.mjs` also checks that workers finish explicit GPU
+cleanup before termination, with a bounded fallback for an unresponsive worker.
+
 `node scripts/check-demo-startup.mjs --all` initializes every scene in a paused
 worker and saves setup times separately from frame performance. Browser and driver
 caches can warm during the run. `node scripts/check-slingshot-input.mjs` uses real