avbd-babylon 0.4.0 → 0.4.2

package/dist/nativeScenes.d.ts

@@ -240,12 +240,14 @@ export interface AvbdGpuParameters2D extends AvbdGpuParameters {
   vbd: boolean;
   vbdStiffness: number;
 }
-/** 3D can retain conservative connected groups between explicit world edits. */
+/** 3D tracks current awake groups and retains sleeping support connections. */
 export interface AvbdSleepOptions {
   speedThreshold?: number;
   timeThreshold?: number;
-  /** 3D: automatic for large jointless desktop worlds; false selects whole-world waking. */
+  /** 3D: automatic for large desktop worlds; false selects whole-world waking. */
   islands?: boolean;
+  /** 3D island mode: build contacts once and sleep stationary, supported groups at startup. */
+  startAsleep?: boolean;
 }
 export interface AvbdGpuOptions {
   bodyBuffer?: GPUBuffer;

package/docs/BABYLON_API.md

@@ -147,15 +147,31 @@ 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 jointless desktop 3D worlds
+optional GPU policy. Supported quiet bodies sleep. 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
-waking. Explicit edits wake the world and reset group history. Unsupported bodies
+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. 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
 paper-comparison benchmarks keep sleeping disabled.
 
+For a 3D assembly placed at rest, use
+`{ islands: true, startAsleep: true }`. Native solver initialization takes one
+support-validation physics step and sleeps stationary groups connected to
+stationary solid support. Moving, floating and sleep-excluded groups stay awake.
+Babylon applies this check on its first physics step. This option is intended
+for assembled stacks, rather than objects already in motion. Interactive
+half-million walls use it; timing comparisons with the paper keep sleeping off.
+
 Closed jointless 3D worlds with at most 32 bodies automatically batch movement
 iterations in one GPU workgroup. Body poses stay in shared memory, with the
 same contact order, reductions and equations. Adding a joint or exceeding the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avbd-babylon",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "GPU AVBD rigid-body physics with a Babylon.js aggregate API",
   "main": "./dist/avbd.js",
   "types": "./dist/avbd.d.ts",
@@ -15,6 +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: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",

package/tests/README.md

@@ -7,6 +7,7 @@ run on the host because they inspect files and JavaScript APIs.
 | Command                             | Scope                                                                                                                                                                 |
 | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `npm test`                          | GPU numerical and stability regressions                                                                                                                               |
+| `npm run test:sleeping`              | Local grab waking, rotating impacts, startup sleeping, long 28K-ring settling and the 34K jointed drop through landing and settling |
 | `npm run test:complete`             | GPU suite, shared pipeline contract, package, pinned-source integrity and live Babylon example                                                                        |
 | `npm run test:pipelines`            | Same 2D/3D package application calls on CPU and WebGPU: bulk edits, queries, joints, triggers, bounce, sleeping, scene attachment and disposal                        |
 | `npm run test:cpu`                  | CPU compatibility scene views, controls, screenshots and physics measurements                                                                                         |
@@ -37,7 +38,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.
 
@@ -46,13 +48,25 @@ poses with direct drawing, Babylon, shared-input workers and CPU compatibility.
 `check-lab-timing.mjs` checks fixed-step clocks at 30–240 display frames per second
 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.
-These checks run through `test:playgrounds` and `test:web`.
+`check-sleep-stability.mjs --drag` follows the 28K brick ring for 900 steps and
+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
+step, then measures the rendered worker view separately. These longer checks run
+through `test:sleeping` and `test:web`; the live toggle checks also run through
+`test:playgrounds`.
 
 `check-lab-step-rate.mjs` checks live physics step-rate changes, retained poses,
 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