avbd-babylon 0.4.0 → 0.4.1

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,29 @@ 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. Updating a grab anchor wakes
+the held body; ordinary edits and changes to supports wake the world.
+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.1",
   "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                                                                                         |
@@ -46,7 +47,14 @@ 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 repeated grab-anchor updates leave resting debris asleep.
+`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.