avbd-babylon 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2793 -2562
- package/dist/avbd.d.ts +1 -0
- package/dist/avbd.global.js +232 -138
- package/dist/avbd.js +232 -138
- package/dist/gpuDevice.d.ts +4 -0
- package/dist/native.d.ts +1 -0
- package/dist/native.js +1 -1
- package/dist/nativeScenes.d.ts +3 -0
- package/dist/solverPipeline.d.ts +62 -0
- package/docs/BABYLON_API.md +8 -0
- package/docs/README.md +465 -459
- package/docs/RELEASE.md +176 -122
- package/package.json +124 -116
- package/tests/README.md +218 -168
package/tests/README.md
CHANGED
|
@@ -1,168 +1,218 @@
|
|
|
1
|
-
# GPU validation and browser benchmarks
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
|
8
|
-
|
|
|
9
|
-
| `npm
|
|
10
|
-
| `npm run test:
|
|
11
|
-
| `npm run test:
|
|
12
|
-
| `npm run test:
|
|
13
|
-
| `npm run test:
|
|
14
|
-
| `npm run test:
|
|
15
|
-
| `npm run test:
|
|
16
|
-
| `npm run test:
|
|
17
|
-
| `npm run
|
|
18
|
-
| `npm run test:
|
|
19
|
-
| `npm run test:
|
|
20
|
-
| `npm run
|
|
21
|
-
| `npm run
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
`npm run clean:
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
scene
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
and
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
The
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
1
|
+
# GPU validation and browser benchmarks
|
|
2
|
+
|
|
3
|
+
Numerical and stability validation runs physics on the GPU. Shared API checks
|
|
4
|
+
also run CPU compatibility worlds. Package, type and source-integrity checks
|
|
5
|
+
run on the host because they inspect files and JavaScript APIs.
|
|
6
|
+
|
|
7
|
+
| Command | Scope |
|
|
8
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
9
|
+
| `npm test` | GPU numerical and stability regressions |
|
|
10
|
+
| `npm run test:complete` | GPU suite, shared pipeline contract, package, pinned-source integrity and live Babylon example |
|
|
11
|
+
| `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 |
|
|
12
|
+
| `npm run test:cpu` | CPU compatibility scene views, controls, screenshots and physics measurements |
|
|
13
|
+
| `npm run test:web` | All GPU scene views, benchmarks, motion, controls, screenshots and reports |
|
|
14
|
+
| `npm run test:package` | ESM/global bundles, declarations and production dependencies |
|
|
15
|
+
| `npm run test:types` | Public declarations with real Babylon types and portable API consumers |
|
|
16
|
+
| `npm run test:castle` | Mortar settling, local impacts, rotating debris and responsive layout |
|
|
17
|
+
| `npm run test:cloth` | Thirty-second limb/net checks, central cloth tearing and screenshots |
|
|
18
|
+
| `npm run test:features` | 2D/3D hinge stops, motor reversal/braking, sensors, live masks and casts |
|
|
19
|
+
| `npm run test:mobile-contacts` | 3D floor contacts, device-verified fallback selection, 8/9 binding limits and mobile drawing |
|
|
20
|
+
| `npm run test:connected-phone` | Physical Android GPU: prepared native/Babylon APIs, floor contacts, 2D/3D features and grid/HPLOC++ collisions |
|
|
21
|
+
| `npm run test:renderers` | Every canonical scene and the slingshot in Babylon; shared-state renderer benchmark checks |
|
|
22
|
+
| `npm run benchmark:renderers` | Direct WebGPU versus Babylon: GPU drawing/copies, CPU submission and completion; three repeats |
|
|
23
|
+
| `npm run test:fracture` | Voronoi partition, breakable face bonds, wrecking-ball impact and persistent rubble |
|
|
24
|
+
| `npm run test:reference` | Explicitly requested upstream CPU comparison; excluded from normal validation |
|
|
25
|
+
| `npm run benchmark:native` | 2D/3D movement/spin, property edits, grouped queries, sleeping and selected reads; three repeats |
|
|
26
|
+
| `npm run benchmark:native-edits` | 100K motion updates, 10K property edits and 64 ray queries in 2D/3D; API overhead and GPU completion |
|
|
27
|
+
|
|
28
|
+
Set `AVBD_TEST_BROWSER` to a Chromium executable if browser discovery fails.
|
|
29
|
+
The runner uses an isolated temporary profile and a real WebGPU adapter. Missing
|
|
30
|
+
WebGPU, validation errors or failed assertions fail the command; they are not
|
|
31
|
+
silently skipped. Results and screenshots are generated under `test-results/`.
|
|
32
|
+
|
|
33
|
+
Run `node scripts/clean-results.mjs` to preview obsolete artifacts, or
|
|
34
|
+
`npm run clean:results` to remove them. Cleanup keeps current validation
|
|
35
|
+
summaries, the published reports, their measurement inputs and every image linked
|
|
36
|
+
from the reports or main README. Generate reports with `npm run test:web` before cleaning. Deletions are
|
|
37
|
+
restricted to `test-results/`; package sources and demo assets are untouched.
|
|
38
|
+
|
|
39
|
+
`npm run clean:dist` removes generated validation wrappers and local debug
|
|
40
|
+
maps after testing. It retains the package builds and assets referenced by
|
|
41
|
+
`index.html` and all browser test pages. Test commands regenerate their own
|
|
42
|
+
temporary bundles when needed. Preview with `node scripts/clean-dist.mjs`.
|
|
43
|
+
|
|
44
|
+
After fixing a report or screenshot check, resume the browser suite with
|
|
45
|
+
`npm run test:web -- --from=check-improvements` (or another check name).
|
|
46
|
+
This preserves preceding passed checks from the saved suite report. Run the
|
|
47
|
+
whole suite again after solver or scene changes that affect those checks.
|
|
48
|
+
|
|
49
|
+
## Physics coverage
|
|
50
|
+
|
|
51
|
+
Renderer comparisons use one physics world on one GPU device. Both renderers
|
|
52
|
+
draw each completed step with the same camera, geometry and visual shaders;
|
|
53
|
+
their order alternates. Measurements use 960 × 540 pixels
|
|
54
|
+
and one engine/device throughout an all-scene run, with fresh physics worlds
|
|
55
|
+
for each scene and repeat. Repeated runs are combined in the visible bars;
|
|
56
|
+
their individual timings remain available in the details. Antialiasing
|
|
57
|
+
and debug overlays are off. Babylon uses thin instances and merged hull geometry,
|
|
58
|
+
with GPU storage copies instead of CPU pose downloads or matrix updates.
|
|
59
|
+
The check verifies finite poses, contact capacity and unchanged selected body
|
|
60
|
+
records. Drawing, GPU copies, CPU submission and queue completion are reported
|
|
61
|
+
separately. They do not measure displayed FPS. Use
|
|
62
|
+
`npm run benchmark:renderers -- --all` for every canonical workload.
|
|
63
|
+
Saved results identify the RTX 4070 Laptop GPU; visitor runs use their own GPU.
|
|
64
|
+
|
|
65
|
+
GPU tests check analytic free fall, resting heights, friction, angular inertia,
|
|
66
|
+
collider pairs, rotations, mixed stacks, sleeping, support removal and local
|
|
67
|
+
100K-wall impacts. Canonical 2D GPU checks cover stacks, pyramids, friction,
|
|
68
|
+
motors, cantilevers, heavy ropes, fracture and dragging. Shape checks cover
|
|
69
|
+
analytic 2D circle/capsule contacts, finite lines, infinite planes, shape casts,
|
|
70
|
+
exact area mass/inertia and live GPU body commands. Convex polygon checks cover
|
|
71
|
+
point-cloud construction, centroid inertia, all mixed collider pairings in both
|
|
72
|
+
index orders, clipped resting contacts, exact ray/disk casts and live geometry
|
|
73
|
+
storage growth. Native 2D Babylon checks verify fixed stepping, single attachment,
|
|
74
|
+
detachment and scene-owned solver disposal. Shared native 2D/3D checks verify
|
|
75
|
+
ordered command batches, automatic packing of object setters, adjacent setter
|
|
76
|
+
coalescing, packed velocity uploads, CPU/GPU buffer reuse, concurrent selected reads,
|
|
77
|
+
live off-centre impulses, teleport contact invalidation, preservation of sensor
|
|
78
|
+
flags, masks, sleeping and renderer-independent fixed stepping. A ten-second mixed-shape
|
|
79
|
+
scene check also verifies containment, desktop/mobile drawing and its playable
|
|
80
|
+
benchmark preview. Fabric checks cover
|
|
81
|
+
spring stiffness, implicit movement, anchors and rigid-object impacts. Babylon
|
|
82
|
+
checks exercise aggregates, scene stepping, disposal, forces, teleports, hulls
|
|
83
|
+
and collision filters against live GPU state.
|
|
84
|
+
|
|
85
|
+
Batching checks additionally cover linear/angular masks, reusable packed motion
|
|
86
|
+
arrays, atomic property validation, sparse mask/trigger updates before queries,
|
|
87
|
+
single-submission native and Babylon stepping with sleep and bounce enabled,
|
|
88
|
+
motor warm-start preservation, removal ordering, cached pass-constant invalidation,
|
|
89
|
+
and concurrent query-pool reuse/disposal. Native API benchmarks measure 100K motion
|
|
90
|
+
edits, 10K property changes with per-body versus grouped flushing, and 64 separate
|
|
91
|
+
versus grouped rays. These API/query measurements exclude solving and rendering.
|
|
92
|
+
|
|
93
|
+
Release API checks cover atomic validation, native 3D masks, disposable 2D
|
|
94
|
+
constraints, live motor reversal and zero torque, required/preferred device
|
|
95
|
+
limits and stopping the Babylon scene loop after device loss. Both dimensions
|
|
96
|
+
hold movement and joint forces on collision overflow or solve-group conflicts,
|
|
97
|
+
then resume after capacity recovery. 2D protection is also tested with sensors
|
|
98
|
+
and restitution enabled. Package checks install the actual tarball in a temporary
|
|
99
|
+
consumer and verify that Babylon is not automatically installed.
|
|
100
|
+
|
|
101
|
+
2D policy checks cover grounded stacks, sleeping exclusions, live spawning,
|
|
102
|
+
same-step reciprocal impacts, impulses, support removal, masks, sensor floors,
|
|
103
|
+
unsupported slow falls and powered joints. Angular checks cover both stops,
|
|
104
|
+
live edits, equal-angle locks, free full turns, two-body angular momentum and
|
|
105
|
+
post stabilization. Browser checks exercise both policy scenes and the slingshot
|
|
106
|
+
demo at 1K/5K/10K bricks, including pointer launch, reloading, sleep toggling and
|
|
107
|
+
desktop/mobile screenshots. The package benchmark also compares sleeping off/on
|
|
108
|
+
for a 10,000-box 2D stack, including the cost of checks while everything is awake.
|
|
109
|
+
|
|
110
|
+
The ragdoll-net regression uses the production 1/240-second timestep and
|
|
111
|
+
checks for wholly submerged limbs, ragdolls straddling the visible sheet,
|
|
112
|
+
and capsule-to-triangle intersections deeper than 5 mm every quarter-second
|
|
113
|
+
through 30 simulated seconds. The tearable sheet check requires an
|
|
114
|
+
intact, stretched sheet before impact, a central tear with all four attachments
|
|
115
|
+
and the outer fabric intact, the ball passing through, finite
|
|
116
|
+
poses and valid rotations. Its visual triangles disappear from live GPU
|
|
117
|
+
joint state. These scenes collide with rigid patches; they do not claim
|
|
118
|
+
continuous triangle collision detection.
|
|
119
|
+
|
|
120
|
+
Storage growth, resets, warm starts and deterministic repeated runs are checked.
|
|
121
|
+
Forced contact overflows and conflicting solve groups must hold motion until
|
|
122
|
+
capacity recovers. The optimized contact layouts retain friction, rotations,
|
|
123
|
+
joint forces and solving rounds. Cached adjacency checks exercise short lists,
|
|
124
|
+
long-list fallback and joints against the independent sorting implementation.
|
|
125
|
+
|
|
126
|
+
HPLOC++ tests cover empty and partial treelets, duplicate Morton keys, mixed
|
|
127
|
+
rotated shapes, filters, large statics, teleports, added bodies and capacity
|
|
128
|
+
recovery. Pair sets are checked against the grid. See [tree design](../docs/HPLOC.md).
|
|
129
|
+
The five active GPU fixtures under `tests/legacy/` provide additional independent
|
|
130
|
+
regressions; unused CPU engines and retired demo code are not required.
|
|
131
|
+
|
|
132
|
+
Pinned sources, fixtures and the six upstream test files under
|
|
133
|
+
`reference/three-avbd/` are preserved and checked against their recorded hashes.
|
|
134
|
+
The upstream CPU suite is available for explicit comparisons only. Browser
|
|
135
|
+
scene checks supplement numerical assertions; they do not claim line coverage
|
|
136
|
+
or prove that every possible scene is stable.
|
|
137
|
+
|
|
138
|
+
## Browser scene and performance checks
|
|
139
|
+
|
|
140
|
+
`check-scenes.mjs` visits the full GPU catalog, advances each scene, checks
|
|
141
|
+
finite positions, rotations and solver counters, and saves screenshots and
|
|
142
|
+
frame/physics/drawing timings. Dedicated checks cover the castle, 100K local
|
|
143
|
+
impact, dense 2D scenes, half-million walls, fabric, mixed colliders and D20
|
|
144
|
+
particle sprites. Preview checks verify that playing stops before measurement
|
|
145
|
+
and resumes afterward. Report checks verify navigation, plain-English labels,
|
|
146
|
+
loaded screenshots and desktop/mobile layout.
|
|
147
|
+
|
|
148
|
+
Open `/tests/performance.html` after `npm start`. Choose a scene and play it,
|
|
149
|
+
or run one scene or the whole catalog. The app automatically selects the GPU
|
|
150
|
+
work layout and collision path. Timestamp-query support is required for GPU
|
|
151
|
+
measurements. Each fixed step is measured separately with drawing and sleeping
|
|
152
|
+
disabled; every step checks contact storage and solve-group conflicts.
|
|
153
|
+
Downloads include GPU stages, CPU submission, initial scene construction,
|
|
154
|
+
solver settings, chosen work layouts and correctness counters. CPU submission
|
|
155
|
+
is elapsed time in `gpu.step()`; it can include browser/driver overhead and is
|
|
156
|
+
not the GPU timestamp or a pure JavaScript instruction count.
|
|
157
|
+
|
|
158
|
+
The saved reports identify their RTX 4070 Laptop GPU. A live run measures the
|
|
159
|
+
current computer. The AVBD paper's desktop RTX 4090 numbers are separate and
|
|
160
|
+
use reconstructed scenes, not an identical hardware/asset comparison.
|
|
161
|
+
|
|
162
|
+
Internal profiling tools `profile-solver.mjs` and `profile-paired.mjs` retain
|
|
163
|
+
engineering overrides. Paired runs alternate order every step and preserve all
|
|
164
|
+
samples. Do not run GPU workloads concurrently. `AVBD_PROFILE_SCENES`,
|
|
165
|
+
`AVBD_PROFILE_VARIANTS`, `AVBD_PROFILE_WARMUP`, `AVBD_PROFILE_SAMPLES` and
|
|
166
|
+
`AVBD_PROFILE_REPEATS` configure these tools. Public benchmarks use production
|
|
167
|
+
automatic selection rather than presenting competing solver versions.
|
|
168
|
+
|
|
169
|
+
WebGL2 is an experimental repository/demo backend, excluded from the npm
|
|
170
|
+
package. The package contract runs only CPU and WebGPU; `npm run test:webgl`
|
|
171
|
+
also runs the shared contract separately against experimental WebGL2.
|
|
172
|
+
|
|
173
|
+
`npm run test:webgl-collisions` compares GPU WebGL2 broadphase and shape
|
|
174
|
+
contacts with exhaustive pairs and the WebGPU equations, including masks,
|
|
175
|
+
large shapes, cell boundaries and overflow.
|
|
176
|
+
|
|
177
|
+
`npm run test:webgl` checks graph coloring, solver stages, complete settling
|
|
178
|
+
worlds, hulls, capsules, joints, welds, motors, springs, ordered body edits,
|
|
179
|
+
nonzero restitution and sleeping/waking in both dimensions. Shared API checks
|
|
180
|
+
also exercise triggers, masking, shape queries, live weld-frame capture and fabric.
|
|
181
|
+
`npm run test:webgl-scenes` checks controls, finite poses, collision counters and
|
|
182
|
+
screenshots across the 2D/3D scene browser. WebGL2 worlds retain every contact
|
|
183
|
+
point and the selected equations, timestep and iteration count. Large scenes
|
|
184
|
+
can exceed the contact-texture memory budget; they are reported explicitly.
|
|
185
|
+
|
|
186
|
+
`npm run test:compatibility` builds the package and website, then runs the shared
|
|
187
|
+
API, CPU demos and WebGL2 checks. Browser benchmarks select the backend separately
|
|
188
|
+
from drawing. WebGL2's GPU elapsed queries are separate from submission/completion
|
|
189
|
+
time; unsupported GPU timers leave those fields empty.
|
|
190
|
+
|
|
191
|
+
`npm run test:cpu` includes the slingshot's CPU, WebGPU and WebGL2 paths. The checks launch
|
|
192
|
+
and boost a ball, add a new ball and constraint, verify finite live poses, and
|
|
193
|
+
capture each renderer. CPU scene drawing also covers rounded rope links and
|
|
194
|
+
chainmail rings at the same dimensions as the WebGPU scene.
|
|
195
|
+
|
|
196
|
+
`npm run benchmark:sleeping` runs the separate sleeping and selective-pose-copy
|
|
197
|
+
comparisons through the browser controls, with three independent repeats and
|
|
198
|
+
screenshots. The resting stacks have 16,384 boxes in 3D and 10,000 in 2D; times include sleep/wake and
|
|
199
|
+
support checks. Results report asleep counts, awake overhead and settled pose
|
|
200
|
+
differences. This benchmark does not change the always-awake paper comparison.
|
|
201
|
+
|
|
202
|
+
`npm run test:compatibility-performance` checks backend selection, GPU timer labels,
|
|
203
|
+
playable previews and measurements without WebGPU. The `--package` option on
|
|
204
|
+
`check-backend-contract.mjs` checks the built ESM package rather than source imports.
|
|
205
|
+
|
|
206
|
+
WebGL2 scene checks include all 33 original demos and the added collider, hinge,
|
|
207
|
+
trigger, cloth and demolition examples. The behavior checks verify 60 advancing
|
|
208
|
+
steps in the joint grid, both stack dimensions and tearable cloth; explicit 2D
|
|
209
|
+
collision exclusions are checked separately. These checks cover finite runs;
|
|
210
|
+
the largest workloads use WebGPU and may exceed WebGL2's contact-texture budget.
|
|
211
|
+
|
|
212
|
+
`npm run benchmark:backends` records the same 2D stack, 2D joint grid, 3D stack
|
|
213
|
+
and 3D pyramid on WebGPU, experimental WebGL2 and CPU. Each backend uses 60 warmup steps,
|
|
214
|
+
60 measured steps and three fresh-world repeats; order rotates between repeats.
|
|
215
|
+
Drawing and sleeping are disabled. GPU elapsed time and JavaScript CPU time are
|
|
216
|
+
reported separately from submission, initialization and completed-step waiting.
|
|
217
|
+
The raw runs and combined summaries are saved in `test-results/backend-comparison.json`;
|
|
218
|
+
the README compares the mean physics times side by side.
|