Determinism
Same recipe, same pixels. Learn the guarantees and limits.
ShaderWeave treats determinism as a product feature, not a nice-to-have.
Guarantee
For a fixed:
- engine version
- generator version
- canonical params
- seed
- size (including
pixelRatio) - format
still renders are byte-identical across runs on the same platform class (CPU path).
How it works
- PRNG: Mulberry32 seeded from recipe seed (or params-derived seed when
seed = 0) - Domain offsets: pure functions of
(seed, params)for noise fields - Canonical JSON: stable key ordering before hash
- Cache key includes engine, generator and renderer versions, plus size (
w×h@pr), so revised tools and different resolutions do not reuse stale output
What can differ
| Situation | Behavior |
|---|---|
| Engine version bump | May change pixels; pin engineVersion when you care |
| Generator version bump | May change the tool's appearance; discovery reports its version. Mesh Field is v0.2.1 and Caustic Pool is v0.2.0. Keep rendered files when exact historical output matters. |
| Animated frames | Looping: t=0 and t=1 match; mid-loop is continuous |
| GPU vs CPU (experimental) | Prefer CPU path for golden tests |
| Floating-point platforms | CPU path targets portable IEEE behavior |
Testing pattern
# Golden hash in CI
curl -s .../v1/generate/marble-vein -o got.png
sha256sum got.png
# compare to committed golden
Or assert in unit tests: double-render with the same context → equal buffers (engine test suite does this for every generator).