avbd-babylon 0.4.1 → 0.4.3

package/README.md

@@ -77,7 +77,7 @@ JavaScript examples. Run `npm start`, then open the
 | Main thread versus dedicated worker and shared memory     | [Copyable worker example and commands](#worker-and-shared-memory-benchmarks), [worker page](tests/workers.html), [worker runner](scripts/benchmark-workers.mjs)                                              |
 | Batched body edits, pose reads and queries                | [Bulk-edit examples](#bulk-edits-and-gpu-dispatches), [measurement code](tests/native-edit-performance.js), [runner](scripts/check-native-performance.mjs)                                                   |
 | CPU compatibility versus WebGPU                           | [Settings and results](#backend-differences-and-benchmarks), [measurement code](tests/compatibility-performance.js), [runner](scripts/benchmark-backends.mjs)                                                |
-| Sleeping and waking in large connected scenes             | [Sleeping example](#queries-callbacks-and-sleeping), [connected-wall runner](scripts/benchmark-connected-sleep.mjs)                                                                                          |
+| Sleeping and waking in large connected scenes             | [Sleeping example](#queries-callbacks-and-sleeping), [per-scene on/off runner](scripts/benchmark-scene-sleep.mjs), [connected-wall runner](scripts/benchmark-connected-sleep.mjs)                                                                                          |
 | Sleeping stability while grabbing and settling            | [28K ring check](scripts/check-sleep-stability.mjs), [jointed-drop timing and view check](scripts/check-jointed-settling.mjs), [saved jointed-drop results](test-results/jointed-settling.json) |
 | Ships, buoyancy and water                                 | [Scene explanation](#ships-water-and-destruction), [scene builder](demo/naval/scene.js), [runner](scripts/benchmark-naval.mjs)                                                                               |
 | Grid versus HPLOC++ collisions                            | [Collision guide](docs/HPLOC.md), [paired scene measurements](tests/performance.js), [tree refit runner](scripts/benchmark-hploc-refit.mjs)                                                                  |
@@ -112,7 +112,11 @@ The [startup check](scripts/check-demo-startup.mjs) initializes every demo in a
 paused worker with `--all` and records setup times separately from simulation
 performance. Shader caches, device checks and scene size affect those times.
 The scene view shows loading messages during setup, even with its performance
-panel collapsed. Worker startup reports also list the time spent in each setup phase.
+panel collapsed, and stays visible until the first GPU frame completes. Worker
+startup reports also list the time spent in each setup phase.
+The web demo loads the selected demo and renderer on demand. Worker controls use
+a small generated scene catalogue; scene construction and physics stay in the
+worker. First use still includes GPU device setup and shader compilation.
 
 ## Install
 
@@ -124,7 +128,7 @@ npm install avbd-babylon @babylonjs/core
 
 For local development, run `npm install` and `npm run build` in this repository,
 then run `npm install /absolute/path/to/avbd` in your Babylon project. `npm pack`
-creates an installable `avbd-babylon-0.2.0.tgz` archive too.
+creates an installable archive named for the current package version too.
 
 The package includes ESM, TypeScript declarations and a browser global build.
 Babylon 9 is an optional peer dependency; integration examples are checked with
@@ -316,7 +320,12 @@ scene selector and controls stay on the page. Choose Main thread, or add
 are available through the scene editing link in the sidebar.
 
 Every AVBD example has a Sleeping toggle for comparing the same scene with and
-without sleeping. Large rigid scenes enable it by default. Add `sleeping=1` or
+without sleeping. Demo defaults use paired measurements of sleeping on and off;
+size alone does not mean sleeping is faster. The [per-scene results](test-results/solver-performance.html#scene-sleeping)
+show active and later physics costs on an RTX 4070 Laptop GPU. Run
+`npm run benchmark:scene-sleep` to repeat the comparison and regenerate the
+demo presets. These defaults affect the demos; package callers choose their
+world's sleeping policy. Add `sleeping=1` or
 `sleeping=0` to choose explicitly; moving water and wind still keep affected
 bodies awake. The half-million wall demos keep the original two-ball benchmark
 until you click **Bowl every row**, which launches balls into all sixteen lanes.
@@ -2204,13 +2213,44 @@ fallingBox.body.wakeUp();
 console.log(await physics.readSleepStats());
 ```
 
-Impulses, teleports, constraint edits, new bodies and removed supports wake the
-world. Desktop WebGPU worlds with at least 4,096 bodies automatically track connected
+`speedThreshold` is the maximum motion allowed before the quiet timer resets.
+In 3D it combines linear speed with rotational speed at the body's radius, so a
+large spinning body stays awake. With meters as world units, `0.03` means about
+3 cm/second; `timeThreshold: 0.5` requires half a second of quiet motion.
+Choose a speed small enough to be visually negligible at your scene's scale.
+Contact forces can remain large: sleeping stacks still carry gravity and weight.
+Sleep permission, these thresholds and the demo Sleeping toggle stay manual;
+the demo presets only choose the initial on/off setting.
+Switching examples loads that example's preset. A manual toggle is remembered
+for that example during the visit; an explicit `sleeping=0` or `sleeping=1` URL
+overrides only the scene named in the URL. Automatic presets are not saved as
+URL overrides.
+The shared demo settings are in
+[sleepPolicy.js](demo/shared/runtime/sleepPolicy.js): `0.03` world units/second,
+with a `0.3` second quiet period in 3D and `0.5` seconds in 2D. Individual scenes
+can supply their own values; the 2D sleeping pile uses `0.25` seconds and the
+slingshot uses `0.3`. The rook's support-aware policy uses linear speed below
+`0.02`, angular speed below `0.04` radians/second and two seconds of quiet.
+
+For dense Babylon piles, `minimumColors` and `minimumColorRounds` can reserve
+additional parallel-solve scheduling headroom when many bodies wake together.
+The [mixed collider gallery](demo/mixed-colliders/index.js) sets both to `32`
+through `AvbdPhysics.create()`. These options preserve the timestep, iterations
+and contact equations; native 3D solvers accept them too.
+
+Impulses, teleports, body-property edits, new bodies and removed supports wake
+the world. Adding or removing constraints and updating grab anchors wake their
+connected bodies. Desktop WebGPU worlds with at least 4,096 bodies automatically track connected
 groups, so an impact wakes the touched group while unrelated piles stay asleep.
 The static floor does not connect separate piles. Contact and joint connections
 let eligible members settle together. Awake groups rebuild their connections
 each step so separated debris can settle independently. Sleeping groups retain
-their support history. Moving a grab anchor wakes the held body. Smaller worlds and mobile compatibility paths use
+their support history. Creating, moving or releasing a grab keeps unrelated
+sleeping groups asleep. Grabbing one brick wakes its connected group, which can
+include most of a wall. Impacts restore the group's normal masses and contacts
+before solving that same step. A connected wall can remain awake while any of its
+members are moving or losing support, even when most bricks look still.
+Smaller worlds and mobile compatibility paths use
 whole-world impact waking. Set `sleeping: { islands: true }` to opt into connected
 groups in a smaller 3D world, or `islands: false` to use whole-world waking. Under
 gravity, unsupported slow-moving bodies stay awake; supports extend upward