pixfx

Parity and tests

Two checks keep the pixels honest: parity compares ports with pixelfx itself, and the determinism test pins native and wasm builds to one set of frame hashes.

Parity against pixelfx

Parity renders an effect with pixelfx (under Node) and with its pixfx port, then compares every pixel of every frame of both layers. It needs Node and a pixelfx checkout:

git clone https://github.com/patch-gg/pixelfx /tmp/pixelfx
git -C /tmp/pixelfx checkout 044e12a
cargo run -p pixfx-export --example parity -- fire/candle --pixelfx /tmp/pixelfx --out target/parity

Output:

fire/candle: colour 0.00% differ, light 0.00% differ → PASS

The reference render comes from tools/pixelfx-ref.mjs, which runs pixelfx's own renderFrames with no backdrop and no stand-in actor, at the effect's default options, edge fade applied.

Current results

Against pixelfx commit 044e12a (version 0.3.1). A later pixelfx may have changed an effect.

EffectColourLightResult
fire/candle0 pixels0 pixelsPASS
fire/campfire0 pixels0 pixelsPASS
fire/brazier0 pixels0 pixelsPASS

The ledger

An effect that ships below the gate must be listed in parity/LEDGER.md, one line each: <id> · <date> · colour x% light y% · approved by owner, after the owner has approved it by eye. The ledger is empty.

Determinism

Frame hashes of each effect, for seeds 1, 2 and 7 and frames first, second, a quarter, middle and last, are checked against its own entry in crates/pixfx-effects/tests/goldens/frame_hashes.json, natively and in wasm. A hash is FNV-1a 64 over every colour word then every light word. The test is ignored by default; built with one effect's feature it checks that effect alone.

cargo test -p pixfx-effects --no-default-features --features fire-candle --test determinism -- --ignored
cargo test -p pixfx-effects --test determinism -- --ignored
wasm-pack test --node crates/pixfx-effects --test determinism -- --include-ignored

Record new goldens on a native target only, after a deliberate change; effects the build leaves out keep theirs:

PIXFX_BLESS=1 cargo test -p pixfx-effects --test determinism -- --ignored

A failure names each effect that differs, with its hashes and the golden's.

Other tests

WhereCovers
crates/pixfx-core/testsPainter, instances and time steps, compositing, simulation helpers.
crates/pixfx-effects/tests/fire.rsFire effects' behaviour.
crates/pixfx-export/testsSheets, bakes, the parity comparison and its options.
crates/pixfx-wasm/tests/web.rsThe JS bindings, under wasm-pack test --node.
crates/pixfx-scene/testsThe scene's decisions: placement, shared frames, the frame budget, the view, hit-stop.
packages/pixfx-web/testsThe JS runtime under bun test against the real wasm, including frames painted on workers against frames painted on the spot.

Tests

Each crate and package tests itself, and there is no repo-wide gate: run the tests of what you changed, as its AGENTS.md lists under "Before you finish" (cargo test -p <crate>, bun run check in a package). Working on one effect, build it alone, so nothing else compiles or runs:

cargo test -p pixfx-effects --no-default-features --features fire-candle --all-targets