pixfx

Scripts

pixfx ships as source, with no binary to install. Short Rust scripts over the library render effects to sprite sheets, GIFs and baked clips, and check ports against their source. You, or your agent, run them as they are, or change them when their flags do not cover what you need.

Run one

Each script is a cargo example in the crate whose library it calls. Run it from the repository:

cargo run -p pixfx-export --example <script> -- <args>
ScriptWrites
pixfx-export sprite_sheet <id>Composite, colour and light PNGs and the beanfx-layout JSON.
pixfx-export gif <id>A looping GIF.
pixfx-export bake <id>A baked clip that the JS shells play without drawing (loadBaked).
pixfx-export parity <id>The parity check of one effect against its source.
pixfx-effects benchWhat a frame of effects costs natively (run with --release).
pixfx-fighter poses <look>Every pose of a fighter look on one sheet.
pixfx-pixel clean, read, draw, view, critique, sheet, cut, parts, diffAn agent's steps for reading pictures as pixels.

The first lines of each script say what it takes and writes. Output files are named after the id with / replaced by _: fire/candle becomes fire_candle. Each script prints the paths it wrote.

sprite_sheet

Render one loop (or the whole one-shot) at the effect's fps and write a sprite sheet.

cargo run -p pixfx-export --example sprite_sheet -- fire/candle --out out
FileContents
fire_candle.pngRGBA. Colour with light added, over transparency. Use it where you cannot blend additively.
fire_candle_color.pngRGBA. The colour layer alone.
fire_candle_light.pngRGB. The light layer alone, to draw additively over the colour sheet.
fire_candle.jsonAseprite-style "array" JSON with beanfx's fields. See Sprite sheet format.
FlagDefaultMeaning
--out DIRtarget/outDirectory to write into; created if missing.
--palette WORDas designedA palette preset: fire, ice, poison, holy, shadow, arcane, blood, electric, nature, gold.
--num NAME=Vas designedOne of the effect's own number options, once per option: --num hitX=-20 --num hitY=-48.

gif

Write a looping GIF, composited over a dark backdrop (rgb(20, 18, 28)), since GIF has no partial transparency. It takes the same flags as sprite_sheet, and:

cargo run -p pixfx-export --example gif -- fire/campfire --scale 4 --out out
FlagDefaultMeaning
--scale N4Each pixel becomes N×N. At least 1. The scaled size must fit GIF's 65535-pixel limit.

Frame delay is 1/fps rounded to GIF's hundredths of a second.

parity

Render an effect with its source and with its pixfx port and compare every pixel of every frame. See Parity and tests for setup.

cargo run -p pixfx-export --example parity -- fire/candle --pixelfx /tmp/pixelfx --out target/parity
FlagDefaultMeaning
--pixelfx DIR$PIXELFX, else ./pixelfxA pixelfx checkout. Needs Node on the path.
--opt key=valueAn option set on both sides: seed, flip (0 or 1), or a numeric option of the effect. Repeatable.
--actor PNG,PNG...Play the effect on a character, the PNGs its frames; Sprite Fusion sources only. --actor-every N (default 6) render frames per sprite frame.
--out DIRtarget/parityWhere the reference render and the side-by-side GIF go.

It prints <id>: colour x% differ, light y% differ → PASS (or FAIL) and writes <out>/<id>.side.gif, the source on the left and pixfx on the right.

Exit codes

CodeMeaning
0Success; for parity, PASS.
1parity ran and FAILed the gate (or critique and diff found an error or a difference).
2Could not run: bad arguments, an unknown effect id, a write error, or a reference render that failed. The message is on stderr.

Change a script

The scripts render with the effect's default seed and own options and margin 0, so their output matches pixelfx's own sheets. For other options or a glow margin, edit the Options the script builds, or copy it and call render_frames and the export functions yourself. Logic worth testing goes into the library, so every script and game can call it.