Files
prometeu-runtime/test-cartridges/stress-console/README.md
T
bquarkz c2bf8d055c 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.
2026-11-20 22:15:47 +00:00

7.7 KiB

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:

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:

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 for WAVs, authoring JSON, packer integration and optional rendered WAV export. Dummy Boy remains a small silent visual fixture.

Reproducible verification and measurements

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 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.