avbd-babylon 0.3.0 → 0.4.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 +3355 -2795
- package/dist/avbd.d.ts +1 -0
- package/dist/avbd.global.js +595 -136
- package/dist/avbd.js +595 -136
- package/dist/babylonAvbd.d.ts +31 -6
- package/dist/native.js +1 -1
- package/dist/nativeScenes.d.ts +81 -8
- package/dist/utilities.d.ts +161 -0
- package/dist/utilities.js +1 -0
- package/docs/BABYLON_API.md +34 -5
- package/docs/HPLOC.md +119 -115
- package/docs/README.md +503 -465
- package/docs/RELEASE.md +191 -176
- package/package.json +148 -124
- package/tests/README.md +333 -218
package/tests/README.md
CHANGED
|
@@ -1,218 +1,333 @@
|
|
|
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
|
|
8
|
-
|
|
|
9
|
-
| `npm test`
|
|
10
|
-
| `npm run test:complete`
|
|
11
|
-
| `npm run test:pipelines`
|
|
12
|
-
| `npm run test:cpu`
|
|
13
|
-
| `npm run test:web`
|
|
14
|
-
| `npm run test:package`
|
|
15
|
-
| `npm run test:types`
|
|
16
|
-
| `npm run test:
|
|
17
|
-
| `npm run test:
|
|
18
|
-
| `npm run test:
|
|
19
|
-
| `npm run test:
|
|
20
|
-
| `npm run test:
|
|
21
|
-
| `npm run test:
|
|
22
|
-
| `npm run
|
|
23
|
-
| `npm run test:
|
|
24
|
-
| `npm run
|
|
25
|
-
| `npm run
|
|
26
|
-
| `npm run
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
and
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
`npm run
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
and
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
`npm run
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
`
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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:playgrounds` | Tornado debris and mortar breakage, domino chain propagation, 40,000-marble normal-distribution checks, worker/rendering controls, stable forts and slingshot victory |
|
|
17
|
+
| `npm run test:castle` | Mortar settling, local impacts, rotating debris and responsive layout |
|
|
18
|
+
| `npm run test:cloth` | Thirty-second limb/net checks, central cloth tearing and screenshots |
|
|
19
|
+
| `npm run test:features` | 2D/3D hinge stops, motor reversal/braking, sensors, live masks and casts |
|
|
20
|
+
| `npm run test:mobile-contacts` | 3D floor contacts, device-verified fallback selection, 8/9 binding limits and mobile drawing |
|
|
21
|
+
| `npm run test:connected-phone` | Physical Android GPU: prepared native/Babylon APIs, floor contacts, 2D/3D features and grid/HPLOC++ collisions |
|
|
22
|
+
| `npm run test:connected-demos` | Physical Android: ten production scenes, screenshots, short GPU/completion timings, hinges, sensors, terrain, cloth and 40K marble flow |
|
|
23
|
+
| `npm run test:renderers` | Every canonical scene and the slingshot in Babylon; shared-state renderer benchmark checks |
|
|
24
|
+
| `npm run benchmark:renderers` | Direct WebGPU versus Babylon: GPU drawing/copies, CPU submission and completion; three repeats |
|
|
25
|
+
| `npm run test:fracture` | Voronoi partition, breakable face bonds, wrecking-ball impact and persistent rubble |
|
|
26
|
+
| `npm run test:reference` | Explicitly requested upstream CPU comparison; excluded from normal validation |
|
|
27
|
+
| `npm run benchmark:native` | 2D/3D movement/spin, property edits, grouped queries, sleeping and selected reads; three repeats |
|
|
28
|
+
| `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 |
|
|
29
|
+
| `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 |
|
|
30
|
+
| `npm run benchmark:native-edits` | 100K motion updates, 10K property edits and 64 ray queries in 2D/3D; API overhead and GPU completion |
|
|
31
|
+
|
|
32
|
+
The [benchmark source index](../README.md#benchmark-sample-code) links to the
|
|
33
|
+
copyable examples, scene builders and measurement runners. The
|
|
34
|
+
[demo source guide](../demo/README.md) shows where each demo is configured and initialized.
|
|
35
|
+
|
|
36
|
+
Set `AVBD_TEST_BROWSER` to a Chromium executable if browser discovery fails.
|
|
37
|
+
|
|
38
|
+
`node scripts/check-galton-startup.mjs` measures startup of the 40,000-marble
|
|
39
|
+
playground and verifies default worker execution, an explicit main-thread choice,
|
|
40
|
+
and automatic fallback when workers are unavailable. `test:playgrounds` also
|
|
41
|
+
checks that at least 99.5% of marbles reach the bins, compares GPU counts with real
|
|
42
|
+
body positions, and measures the shape of the distribution.
|
|
43
|
+
|
|
44
|
+
`check-galton-pegs.mjs` checks mouse and touch retraction, restoration and live
|
|
45
|
+
poses with direct drawing, Babylon, shared-input workers and CPU compatibility.
|
|
46
|
+
`check-lab-timing.mjs` checks fixed-step clocks at 30–240 display frames per second
|
|
47
|
+
and bounded catch-up under load. `check-lab-sleep.mjs` checks live sleeping
|
|
48
|
+
toggles, large-scene defaults and bowling balls in all sixteen wall lanes.
|
|
49
|
+
These checks run through `test:playgrounds` and `test:web`.
|
|
50
|
+
|
|
51
|
+
`check-lab-step-rate.mjs` checks live physics step-rate changes, retained poses,
|
|
52
|
+
scene defaults and URL settings with CPU, WebGPU, Babylon and worker execution.
|
|
53
|
+
The showcase exposes steps per second beside solving iterations. Both settings
|
|
54
|
+
remain fixed while a benchmark measurement runs.
|
|
55
|
+
|
|
56
|
+
`node scripts/check-demo-startup.mjs --all` initializes every scene in a paused
|
|
57
|
+
worker and saves setup times separately from frame performance. Browser and driver
|
|
58
|
+
caches can warm during the run. `node scripts/check-slingshot-input.mjs` uses real
|
|
59
|
+
browser mouse, touch and keyboard events to check aiming, the trajectory line,
|
|
60
|
+
release, touch cancellation and reloading in direct, Babylon and worker views.
|
|
61
|
+
|
|
62
|
+
`npm run test:terrain` checks terrain cooking, floor and roof contacts, mesh
|
|
63
|
+
imports and Babylon transforms. `npm run test:workers` also checks paused
|
|
64
|
+
redrawing, camera input, resizing, queue backpressure, shared status readbacks
|
|
65
|
+
and pixel-identical batched rendering. `npm run benchmark:hploc-refit` measures
|
|
66
|
+
the leaf-bound update separately at 2K, 100K and 510K bodies; its timings describe
|
|
67
|
+
that kernel rather than the whole physics step.
|
|
68
|
+
|
|
69
|
+
The runner uses an isolated temporary profile and a real WebGPU adapter. Missing
|
|
70
|
+
WebGPU, validation errors or failed assertions fail the command; they are not
|
|
71
|
+
silently skipped. Results and screenshots are generated under `test-results/`.
|
|
72
|
+
|
|
73
|
+
Run `node scripts/clean-results.mjs` to preview obsolete artifacts, or
|
|
74
|
+
`npm run clean:results` to remove them. Cleanup keeps current validation
|
|
75
|
+
summaries, the published reports, their measurement inputs and every image linked
|
|
76
|
+
from the reports or main README. Generate reports with `npm run test:web` before cleaning. Deletions are
|
|
77
|
+
restricted to `test-results/`; package sources and demo assets are untouched.
|
|
78
|
+
|
|
79
|
+
`npm run clean:dist` removes generated validation wrappers and local debug
|
|
80
|
+
maps after testing. It retains the package builds and assets referenced by
|
|
81
|
+
`index.html` and all browser test pages. Test commands regenerate their own
|
|
82
|
+
temporary bundles when needed. Preview with `node scripts/clean-dist.mjs`.
|
|
83
|
+
|
|
84
|
+
After fixing a report or screenshot check, resume the browser suite with
|
|
85
|
+
`npm run test:web -- --from=check-improvements` (or another check name).
|
|
86
|
+
This preserves preceding passed checks from the saved suite report. Run the
|
|
87
|
+
whole suite again after solver or scene changes that affect those checks.
|
|
88
|
+
|
|
89
|
+
## Physics coverage
|
|
90
|
+
|
|
91
|
+
Renderer comparisons use one physics world on one GPU device. Both renderers
|
|
92
|
+
draw each completed step with the same camera, geometry and visual shaders;
|
|
93
|
+
their order alternates. Measurements use 960 × 540 pixels
|
|
94
|
+
and one engine/device throughout an all-scene run, with fresh physics worlds
|
|
95
|
+
for each scene and repeat. Repeated runs are combined in the visible bars;
|
|
96
|
+
their individual timings remain available in the details. Antialiasing
|
|
97
|
+
and debug overlays are off. Babylon uses thin instances and merged hull geometry,
|
|
98
|
+
with GPU storage copies instead of CPU pose downloads or matrix updates.
|
|
99
|
+
The check verifies finite poses, contact capacity and unchanged selected body
|
|
100
|
+
records. Drawing, GPU copies, CPU submission and queue completion are reported
|
|
101
|
+
separately. They do not measure displayed FPS. Use
|
|
102
|
+
`npm run benchmark:renderers -- --all` for every canonical workload.
|
|
103
|
+
Saved results identify the RTX 4070 Laptop GPU; visitor runs use their own GPU.
|
|
104
|
+
|
|
105
|
+
GPU tests check analytic free fall, resting heights, friction, angular inertia,
|
|
106
|
+
collider pairs, rotations, mixed stacks, sleeping, support removal and local
|
|
107
|
+
100K-wall impacts. Canonical 2D GPU checks cover stacks, pyramids, friction,
|
|
108
|
+
motors, cantilevers, heavy ropes, fracture and dragging. Shape checks cover
|
|
109
|
+
analytic 2D circle/capsule contacts, finite lines, infinite planes, shape casts,
|
|
110
|
+
exact area mass/inertia and live GPU body commands. Convex polygon checks cover
|
|
111
|
+
point-cloud construction, centroid inertia, all mixed collider pairings in both
|
|
112
|
+
index orders, clipped resting contacts, exact ray/disk casts and live geometry
|
|
113
|
+
storage growth. Native 2D Babylon checks verify fixed stepping, single attachment,
|
|
114
|
+
detachment and scene-owned solver disposal. Shared native 2D/3D checks verify
|
|
115
|
+
ordered command batches, automatic packing of object setters, adjacent setter
|
|
116
|
+
coalescing, packed velocity uploads, CPU/GPU buffer reuse, concurrent selected reads,
|
|
117
|
+
live off-centre impulses, teleport contact invalidation, preservation of sensor
|
|
118
|
+
flags, masks, sleeping and renderer-independent fixed stepping. A ten-second mixed-shape
|
|
119
|
+
scene check also verifies containment, desktop/mobile drawing and its playable
|
|
120
|
+
benchmark preview. Fabric checks cover
|
|
121
|
+
spring stiffness, implicit movement, anchors and rigid-object impacts. Babylon
|
|
122
|
+
checks exercise aggregates, scene stepping, disposal, forces, teleports, hulls
|
|
123
|
+
and collision filters against live GPU state.
|
|
124
|
+
|
|
125
|
+
Batching checks additionally cover linear/angular masks, reusable packed motion
|
|
126
|
+
arrays, atomic property validation, sparse mask/trigger updates before queries,
|
|
127
|
+
single-submission native and Babylon stepping with sleep and bounce enabled,
|
|
128
|
+
motor warm-start preservation, removal ordering, cached pass-constant invalidation,
|
|
129
|
+
and concurrent query-pool reuse/disposal. Closed small-world tests compare every
|
|
130
|
+
body field through zero iterations, dense contacts, bounce, triggers, teleports
|
|
131
|
+
and the automatic fallback when joints are added. Connected-group sleep tests
|
|
132
|
+
check complete pile waking, unchanged neighboring sleepers on a shared floor,
|
|
133
|
+
and support removal with grid and HPLOC collisions. Sleep and bounce uniform checks compare
|
|
134
|
+
all body fields and sleep records against unconditional uploads while changing
|
|
135
|
+
the timestep, gravity, support, masks and contact capacity. Native API benchmarks measure 100K motion
|
|
136
|
+
edits, 10K property changes with per-body versus grouped flushing, and 64 separate
|
|
137
|
+
versus grouped rays. These API/query measurements exclude solving and rendering.
|
|
138
|
+
|
|
139
|
+
Release API checks cover atomic validation, native 3D masks, disposable 2D
|
|
140
|
+
constraints, live motor reversal and zero torque, required/preferred device
|
|
141
|
+
limits and stopping the Babylon scene loop after device loss. Both dimensions
|
|
142
|
+
hold movement and joint forces on collision overflow or solve-group conflicts,
|
|
143
|
+
then resume after capacity recovery. 2D protection is also tested with sensors
|
|
144
|
+
and restitution enabled. Package checks install the actual tarball in a temporary
|
|
145
|
+
consumer and verify that Babylon is not automatically installed.
|
|
146
|
+
|
|
147
|
+
2D policy checks cover grounded stacks, sleeping exclusions, live spawning,
|
|
148
|
+
same-step reciprocal impacts, impulses, support removal, masks, sensor floors,
|
|
149
|
+
unsupported slow falls and powered joints. Angular checks cover both stops,
|
|
150
|
+
live edits, equal-angle locks, free full turns, two-body angular momentum and
|
|
151
|
+
post stabilization. Browser checks exercise both policy scenes and the slingshot
|
|
152
|
+
demo at 1K/5K/10K bricks, including pointer launch, reloading, sleep toggling and
|
|
153
|
+
desktop/mobile screenshots. The package benchmark also compares sleeping off/on
|
|
154
|
+
for a 10,000-box 2D stack, including the cost of checks while everything is awake.
|
|
155
|
+
|
|
156
|
+
The ragdoll-net regression uses the production 1/240-second timestep and
|
|
157
|
+
checks for wholly submerged limbs, ragdolls straddling the visible sheet,
|
|
158
|
+
and capsule-to-triangle intersections deeper than 5 mm every quarter-second
|
|
159
|
+
through 30 simulated seconds. The tearable sheet check requires an
|
|
160
|
+
intact, stretched sheet before impact, a central tear with all four attachments
|
|
161
|
+
and the outer fabric intact, the ball passing through, finite
|
|
162
|
+
poses and valid rotations. Detached fabric checks require retained material,
|
|
163
|
+
mass and live bodies as the pieces fall and settle on the floor. These scenes
|
|
164
|
+
use discrete collisions with rigid patches.
|
|
165
|
+
|
|
166
|
+
Storage growth, resets, warm starts and deterministic repeated runs are checked.
|
|
167
|
+
Forced contact overflows and conflicting solve groups must hold motion until
|
|
168
|
+
capacity recovers. The optimized contact layouts retain friction, rotations,
|
|
169
|
+
joint forces and solving rounds. Cached adjacency checks exercise short lists,
|
|
170
|
+
long-list fallback and joints against the independent sorting implementation.
|
|
171
|
+
|
|
172
|
+
HPLOC++ tests cover empty and partial treelets, duplicate Morton keys, mixed
|
|
173
|
+
rotated shapes, filters, large statics, teleports, added bodies and capacity
|
|
174
|
+
recovery. Pair sets are checked against the grid. See [tree design](../docs/HPLOC.md).
|
|
175
|
+
The five active GPU fixtures under `tests/legacy/` provide additional independent
|
|
176
|
+
regressions; unused CPU engines and retired demo code are not required.
|
|
177
|
+
|
|
178
|
+
Pinned sources, fixtures and the six upstream test files under
|
|
179
|
+
`reference/three-avbd/` are preserved and checked against their recorded hashes.
|
|
180
|
+
The upstream CPU suite is available for explicit comparisons only. Browser
|
|
181
|
+
scene checks supplement numerical assertions; they do not claim line coverage
|
|
182
|
+
or prove that every possible scene is stable.
|
|
183
|
+
|
|
184
|
+
## Browser scene and performance checks
|
|
185
|
+
|
|
186
|
+
`npm run benchmark:particles` measures the D20 surface-only particle test with
|
|
187
|
+
sprites visible, searches for sustained 60 FPS, and repeats counts near the
|
|
188
|
+
boundary. GPU collision and sprite passes are timed separately. Results and
|
|
189
|
+
the method are saved in [the particle capacity report](../test-results/particle-capacity.html).
|
|
190
|
+
`tests/gpu-utilities.js` checks exact particle state across one- and two-dimensional
|
|
191
|
+
dispatches, partial groups, valid counters, surface hits and invalid uploads.
|
|
192
|
+
|
|
193
|
+
`npm run test:workers` checks CPU and GPU worker trajectories, Babylon rendering,
|
|
194
|
+
pointer ordering and operation without shared-memory headers.
|
|
195
|
+
`npm run benchmark:workers` compares matched main-thread, message-worker and
|
|
196
|
+
shared-input execution; open [the interactive comparison](workers.html) to play
|
|
197
|
+
or measure a selected scene. GPU timestamps, CPU work and page delay are separate.
|
|
198
|
+
Recorded results name the measured hardware; shared input is optional.
|
|
199
|
+
|
|
200
|
+
`npm run test:terrain` validates heightfields and concave mesh terrain, floor/roof
|
|
201
|
+
contacts, raycasts and removal on CPU, GPU grid and HPLOC paths. It also checks
|
|
202
|
+
Babylon registration, imported OBJ geometry, smooth source-mesh drawing, worker
|
|
203
|
+
execution and terrain screenshots. `npm run test:naval` checks
|
|
204
|
+
floating, settling under sail forces, local damage, material buoyancy, sinking and persistent fragments, with desktop
|
|
205
|
+
and narrow-layout captures. Naval water physics requires WebGPU.
|
|
206
|
+
|
|
207
|
+
`npm run benchmark:naval` measures the grid and HPLOC collision paths with the
|
|
208
|
+
same water resolution, timestep, iterations and ship geometry. Physics GPU time,
|
|
209
|
+
water GPU time and drawing GPU time are measured separately. Browser timings
|
|
210
|
+
vary; repeat runs before comparing small differences.
|
|
211
|
+
|
|
212
|
+
`check-scenes.mjs` visits the full GPU catalog, advances each scene, checks
|
|
213
|
+
finite positions, rotations and solver counters, and saves screenshots and
|
|
214
|
+
frame/physics/drawing timings. Dedicated checks cover the castle, 100K local
|
|
215
|
+
impact, dense 2D scenes, half-million walls, fabric, mixed colliders and D20
|
|
216
|
+
particle sprites. Preview checks verify that playing stops before measurement
|
|
217
|
+
and resumes afterward. Report checks verify navigation, plain-English labels,
|
|
218
|
+
loaded screenshots and desktop/mobile layout.
|
|
219
|
+
|
|
220
|
+
Open `/tests/performance.html` after `npm start`. Choose a scene and play it,
|
|
221
|
+
or run one scene or the whole catalog. The app automatically selects the GPU
|
|
222
|
+
work layout and collision path. Timestamp-query support is required for GPU
|
|
223
|
+
measurements. Each fixed step is measured separately with drawing and sleeping
|
|
224
|
+
disabled; every step checks contact storage and solve-group conflicts.
|
|
225
|
+
Downloads include GPU stages, CPU submission, initial scene construction,
|
|
226
|
+
solver settings, chosen work layouts and correctness counters. CPU submission
|
|
227
|
+
is elapsed time in `gpu.step()`; it can include browser/driver overhead and is
|
|
228
|
+
not the GPU timestamp or a pure JavaScript instruction count.
|
|
229
|
+
|
|
230
|
+
The saved reports identify their RTX 4070 Laptop GPU. A live run measures the
|
|
231
|
+
current computer. The AVBD paper's desktop RTX 4090 numbers are separate and
|
|
232
|
+
use reconstructed scenes, not an identical hardware/asset comparison.
|
|
233
|
+
|
|
234
|
+
Internal profiling tools `profile-solver.mjs` and `profile-paired.mjs` retain
|
|
235
|
+
engineering overrides. Paired runs alternate order every step and preserve all
|
|
236
|
+
samples. Do not run GPU workloads concurrently. `AVBD_PROFILE_SCENES`,
|
|
237
|
+
`AVBD_PROFILE_VARIANTS`, `AVBD_PROFILE_WARMUP`, `AVBD_PROFILE_SAMPLES` and
|
|
238
|
+
`AVBD_PROFILE_REPEATS` configure these tools. Public benchmarks use production
|
|
239
|
+
automatic selection rather than presenting competing solver versions.
|
|
240
|
+
|
|
241
|
+
`npm run benchmark:gpu-uploads` measures CPU preparation and uploads for the
|
|
242
|
+
WebGPU solver's settings in both dimensions. It isolates that overhead from GPU
|
|
243
|
+
physics and drawing. Stable 2D settings need no upload; a normal 3D step uploads
|
|
244
|
+
the changing generation word. Live setting changes still update their exact
|
|
245
|
+
GPU values. The GPU regression suite checks the serialized words against the
|
|
246
|
+
pinned layouts, including changed flags, wind, timestep and replacement buffers.
|
|
247
|
+
|
|
248
|
+
`npm run benchmark:gpu-scheduling` measures stable GPU color bucketing in 2D and
|
|
249
|
+
3D, with 256, 1,024, 2,416, 100K and 510K bodies, varied color counts and sparse/dense moving
|
|
250
|
+
sets. It compares every rank, histogram word and counter against the pinned
|
|
251
|
+
kernel before timing. Large worlds select bitset ranks automatically. The body
|
|
252
|
+
ordering, collision work, equations and iteration count remain the same. These
|
|
253
|
+
are kernel timings, not total physics or frame-rate improvements.
|
|
254
|
+
|
|
255
|
+
`node scripts/benchmark-workers.mjs --gpu` refreshes just the WebGPU worker
|
|
256
|
+
comparisons and preserves the existing CPU compatibility rows.
|
|
257
|
+
|
|
258
|
+
`npm run benchmark:movement` compares movement-solver batching with the same
|
|
259
|
+
contact equations, timestep and iterations in 100K columns, the 110K ring and
|
|
260
|
+
the half-million walls. Two runs reverse GPU-world creation order and alternate
|
|
261
|
+
execution order every step. Every resulting body-state value must match exactly;
|
|
262
|
+
every step checks contact capacity and conflicting solve groups. GPU timestamps
|
|
263
|
+
separate moving bodies from updating contact forces, with drawing and sleeping
|
|
264
|
+
disabled. Results are saved in `test-results/movement-solve-performance.json`.
|
|
265
|
+
Large rigid worlds select parallel point updates automatically; the shared-point
|
|
266
|
+
layout also uses compact symmetric Newton matrices and packs frequently read
|
|
267
|
+
pose fields during solving. GPU regressions check the restored public buffer
|
|
268
|
+
byte for byte, including partial tiles, unused capacity and appended bodies.
|
|
269
|
+
They also cover zero iterations, failed-step recovery, wind, joints, motors,
|
|
270
|
+
springs, bounce, sensor rebuilds, mode changes, mobile compatibility layouts
|
|
271
|
+
and million-manifold dispatch limits.
|
|
272
|
+
|
|
273
|
+
`npm run benchmark:gpu-encoding` measures CPU command setup for the WebGPU
|
|
274
|
+
feature encoder in 2D and 3D. It compares reused typed and plain offset arrays
|
|
275
|
+
with identical bindings, dispatches and resulting body fields. Alternating
|
|
276
|
+
four-step batches wait for GPU completion before the next sample. The first
|
|
277
|
+
60 batches warm up the code; the next 60 are measured. These are small CPU
|
|
278
|
+
costs, separate from GPU physics and frame rate. Results are saved in
|
|
279
|
+
`test-results/command-encoding-performance.json`. GPU regressions also compare
|
|
280
|
+
the feature encoder against the pinned encoder through combined/split passes,
|
|
281
|
+
joint contacts, VBD and post stabilization. Repeated buffer bindings are skipped
|
|
282
|
+
within a pass and restored after scan, tree and sleeping helpers.
|
|
283
|
+
|
|
284
|
+
WebGL2 is an experimental repository/demo backend, excluded from the npm
|
|
285
|
+
package. The package contract runs only CPU and WebGPU; `npm run test:webgl`
|
|
286
|
+
also runs the shared contract separately against experimental WebGL2.
|
|
287
|
+
|
|
288
|
+
`npm run test:webgl-collisions` compares GPU WebGL2 broadphase and shape
|
|
289
|
+
contacts with exhaustive pairs and the WebGPU equations, including masks,
|
|
290
|
+
large shapes, cell boundaries and overflow.
|
|
291
|
+
|
|
292
|
+
`npm run test:webgl` checks graph coloring, solver stages, complete settling
|
|
293
|
+
worlds, hulls, capsules, joints, welds, motors, springs, ordered body edits,
|
|
294
|
+
nonzero restitution and sleeping/waking in both dimensions. Shared API checks
|
|
295
|
+
also exercise triggers, masking, shape queries, live weld-frame capture and fabric.
|
|
296
|
+
`npm run test:webgl-scenes` checks controls, finite poses, collision counters and
|
|
297
|
+
screenshots across the 2D/3D benchmark previews. WebGL2 worlds retain every contact
|
|
298
|
+
point and the selected equations, timestep and iteration count. Large scenes
|
|
299
|
+
can exceed the contact-texture memory budget; they are reported explicitly.
|
|
300
|
+
|
|
301
|
+
`npm run test:compatibility` builds the package and website, then runs the shared
|
|
302
|
+
API, CPU demos and WebGL2 checks. Browser benchmarks select the backend separately
|
|
303
|
+
from drawing. WebGL2's GPU elapsed queries are separate from submission/completion
|
|
304
|
+
time; unsupported GPU timers leave those fields empty.
|
|
305
|
+
|
|
306
|
+
`npm run test:cpu` includes the slingshot's CPU and WebGPU paths. The checks launch
|
|
307
|
+
and boost a ball, add a new ball and constraint, verify finite live poses, and
|
|
308
|
+
capture each renderer. CPU scene drawing also covers rounded rope links and
|
|
309
|
+
chainmail rings at the same dimensions as the WebGPU scene.
|
|
310
|
+
|
|
311
|
+
`npm run benchmark:sleeping` runs the separate sleeping and selective-pose-copy
|
|
312
|
+
comparisons through the browser controls, with three independent repeats and
|
|
313
|
+
screenshots. The resting stacks have 16,384 boxes in 3D and 10,000 in 2D; times include sleep/wake and
|
|
314
|
+
support checks. Results report asleep counts, awake overhead and settled pose
|
|
315
|
+
differences. This benchmark does not change the always-awake paper comparison.
|
|
316
|
+
|
|
317
|
+
`npm run test:compatibility-performance` checks backend selection, GPU timer labels,
|
|
318
|
+
playable previews and measurements without WebGPU. The `--package` option on
|
|
319
|
+
`check-backend-contract.mjs` checks the built ESM package rather than source imports.
|
|
320
|
+
|
|
321
|
+
WebGL2 scene checks include all 33 original demos and the added collider, hinge,
|
|
322
|
+
trigger, cloth and demolition examples. The behavior checks verify 60 advancing
|
|
323
|
+
steps in the joint grid, both stack dimensions and tearable cloth; explicit 2D
|
|
324
|
+
collision exclusions are checked separately. These checks cover finite runs;
|
|
325
|
+
the largest workloads use WebGPU and may exceed WebGL2's contact-texture budget.
|
|
326
|
+
|
|
327
|
+
`npm run benchmark:backends` records the same 2D stack, 2D joint grid, 3D stack
|
|
328
|
+
and 3D pyramid on WebGPU, experimental WebGL2 and CPU. Each backend uses 60 warmup steps,
|
|
329
|
+
60 measured steps and three fresh-world repeats; order rotates between repeats.
|
|
330
|
+
Drawing and sleeping are disabled. GPU elapsed time and JavaScript CPU time are
|
|
331
|
+
reported separately from submission, initialization and completed-step waiting.
|
|
332
|
+
The raw runs and combined summaries are saved in `test-results/backend-comparison.json`;
|
|
333
|
+
the README compares the mean physics times side by side.
|