feat(stress): add a deterministic particle demo with sequenced music

Move Storm Eagle playback and source assets to Stress Console and keep Dummy Boy silent. Exercise VM math, seeded Random and persistent typed particles with a projected tunnel, bounded 512-sprite heavy workload, reproducible replays and measured costs.
This commit is contained in:
2026-11-20 22:15:47 +00:00
parent 8510c5b00d
commit c2bf8d055c
42 changed files with 20688 additions and 232 deletions
+11 -4
View File
@@ -1,11 +1,18 @@
# Dummy Boy
Regenerate this cartridge with:
Dummy Boy is a silent visual fixture. It clears the frame and draws a centered
square whose fill color cycles deterministically across frames. It requires only
the `gfx2d` capability and has no asset pack or audio commands.
From the runtime root:
```sh
cargo run -p pbxgen-dummy-boy
cargo run -p prometeu-host-desktop-winit -- test-cartridges/dummy-boy
cargo test -p pbxgen-dummy-boy
```
Dummy Boy is a minimal visual Game cartridge used by runtime switch tests. It
clears the frame and draws a centered square whose fill color cycles
deterministically across frames.
Regeneration removes this fixture's obsolete `assets.pa` if present. The tests
check generator output, six visual frames and silent headless audio.
The musical workload lives in [Stress Console](../stress-console/README.md).
+140
View File
@@ -0,0 +1,140 @@
# Stress Console
Stress Console runs a procedural particle vortex and projected tunnel in guest
bytecode while a Storm Eagle arrangement plays on the independent audio clock.
It is an integration workload for the VM, numeric intrinsics, deterministic RNG,
typed state, compositor and sample-based sequencer.
From the runtime root:
```sh
cargo run -p pbxgen-stress
cargo run --release -p prometeu-host-desktop-winit -- test-cartridges/stress-console
cargo test -p pbxgen-stress -p pbxgen-dummy-boy
```
The tracked cartridge and generator default to the heavy preset and seed
`1347571533`. To generate another reproducible load without replacing it:
```sh
cargo run -p pbxgen-stress -- --preset normal --seed 42 --output /tmp/stress-normal
cargo run --release -p prometeu-host-desktop-winit -- /tmp/stress-normal
```
| Preset | Particles | Substeps per particle/frame | Accepted sprite submissions/frame |
| --- | ---: | ---: | ---: |
| light | 64 | 1 | 192 |
| normal | 128 | 2 | 256 |
| heavy (default) | 384 | 4 | 512 |
Preset selection happens when generating the cartridge; there is no switch during
playback.
These are workload settings, not new hardware limits. Every substep executes;
light/normal leave room within the existing 512 sprite slots; heavy fills all
512 slots. Positions outside the viewport are clipped normally, so accepted
submissions are not a count of visible objects. A separate test exercises overflow; the presentation checks
submission status and logs failures instead of deliberately overflowing.
## Guest algorithm and coverage
An array roots reusable Particle structs with x/y position, x/y velocity,
lifetime and palette. A separate rooted Random object supplies initial state
and particle rebirth. The live object count is particles + 2 and remains stable
while particles are reused. The RNG seed is explicit; there is no host entropy.
The softened vortex uses centre attraction, tangential acceleration, sine/cosine
perturbation and damping. Each substep calculates distance and angle, updates
clamped velocity, computes speed and advances clamped positions. Position travel
uses a 1.5 multiplier per simulation pass, so particles move faster while the
force clock, tunnel and music keep their own timing. Speed changes
the sprite shape. Lifetimes expire after 45..224 logical frames; rebirth uses
new random values in the existing struct. Increasing substeps increases real
numerical work, with a smaller integration step. Presets need not produce the
same trajectory as one another.
Eight rings of sixteen markers form a rotating, twisted tunnel. The guest
projects ring depth and angle onto the existing 2D compositor; there is no new
3D renderer. Four scene layers provide a dark backdrop and sparse star fields,
with parallax 1, 0.75, 0.5 and 0.25. Camera motion, transparent glow/star glyphs,
palettes, sprite priorities and four readable text overlays run together. Particles
and tunnel markers use sprites; stars/backdrop use scene tiles. Two `fill_rect`
commands and four `draw_text` calls draw the overlay with graphics primitives
and do not consume sprite slots.
| Surface | Executed workload / validation |
| --- | --- |
| Math | Float arithmetic; `mathf.sin/cos/atan2/sqrt/clamp/to_i32`, `vec2.dot/length`, integer clamp and explicit numeric conversions |
| Random | Native `random.new/next/nextf/range`; initialization and rebirth; same-seed replay and changed-seed divergence |
| Typed state | Guest array and struct references, typed field reads/writes, persistent roots, bounded reusable objects |
| VM | Nested loops, branches, globals/locals, virtual budget slices and native calls |
| Graphics | GlyphBank 100 and SceneBank 1 in slot 0 of each type; four layers, camera, palettes/alpha, tunnel and particle sprites, overlay |
| Logging | One level-2 message per 60 logical frames; level-3 report for failed composer submissions |
| Audio | MusicBank 201 in Music slot 0; Music A, eight instruments, envelopes/modulation, stereo pan and shared echo |
| Lifecycle | Initial setup and music play once per session; pause/resume and Stress/Home/Dummy/Home/Stress consumers |
The simulation uses a fixed logical-frame step of 1/60. It does not read wall
clock time. Music timing comes from audio processing, so slow graphics never
change sequence tempo. Exact beat synchronization of the visual is not claimed.
The generator emits PBX and static artwork; all particle simulation, RNG draws
and animated projection run inside the VM, including headless execution.
## Music and assets
The self-contained MusicBank holds a 72-beat B-minor arrangement, approximately
168 BPM (357143 integer microseconds per quarter), about 25.7 seconds per loop.
It uses the owner-supplied transcription and a subset of MegaManX-SF-3.0 samples
by CliffyJiffy. Bass, drums and articulation are arranged for the fixture; this
is not an exact reproduction of the original recording. Volume is 180; shared
echo uses 167 ms, feedback 0.22, wet 0.18 and dry 1.0.
PCM16 and IMA ADPCM samples share the bank on cartridge; loading materializes
resident PCM16. The bank occupies 90,810 cartridge bytes and materializes 60,358 PCM sample
bytes. Its canonical decoded size is 112,224 bytes, excluding host allocator
and ownership overhead. The complete tracked cartridge runs without Studio,
SoundFont software or downloaded source banks.
See the [audio sources and regeneration contract](../../crates/tools/pbxgen-stress/music/README.md)
for WAVs, authoring JSON, packer integration and optional rendered WAV export.
[Dummy Boy](../dummy-boy/README.md) remains a small silent visual fixture.
## Reproducible verification and measurements
```sh
cargo test -p pbxgen-stress --release -- --nocapture
cargo run -p pbxgen-stress --release --example demo_measure -- 120 /tmp/stress-measure
```
The measurement example writes `report.json`, three generated cartridges and a
native RGB PPM capture per preset. It reports initialization separately from
steady frames; mean, p50, p95 and maximum real times; virtual cycles separately;
sprite admission and host slices; state/frame hashes; VM quota usage/peaks; and audio voices.
Each steady headless frame also processes 800 stereo audio frames. The separate
native-only measurement uses the real VM and SpriteController while counting
other host calls. VM quota arrays follow RuntimeResource order: GuestBytes,
HandleSlots, AuxiliaryBytes, TemporaryBytes, StringBytes, StringAllocations,
IndividualStringBytes, CallDepth. They are not process RSS or total console RAM.
Tests inspect actual guest storage and observe executed intrinsic calls using
debugger breakpoints. Numeric replay hashes for all presets and six native visual frames of the
normal preset are pinned; debug/release runs compare the same baselines. A 230-frame run exercises
rebirth without growing the heap. Other tests compare more than two musical
loops sample-for-sample with and without representative graphics checkpoints,
including explicit pause/resume. Those checkpoints are not a sustained 60 FPS
benchmark.
The companion [measurement record](../../crates/tools/pbxgen-stress/examples/MEASUREMENTS.md)
reports one executed host configuration and its limitations.
## Limits
This demo does not qualify every intrinsic edge case, Random statistics, GC
under allocation churn, quota failures, input, save/memcard, dynamic bank
replacement, SFX, Music B, crossfade or all 32 audio voices. Those remain separate
subsystem tests/benchmarks. Storm Eagle peaks at approximately ten voices.
Headless timings include software composition and diagnostics. They do not
measure physical callback deadlines, GPU presentation, VSync, power or handheld
performance. No ARM handheld guarantee follows from a desktop run. The earlier
1152-request/512-admission grid has been replaced; it is no longer this cartridge's
normal workload.
Binary file not shown.
+1 -1
View File
@@ -5,5 +5,5 @@
"title": "Stress Console",
"app_version": "0.1.0",
"app_mode": "Game",
"capabilities": ["composer", "gfx2d", "log", "asset"]
"capabilities": ["composer", "gfx2d", "log", "asset", "audio"]
}
Binary file not shown.