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>
| Script | Writes |
|---|---|
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 bench | What 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, diff | An 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
| File | Contents |
|---|---|
fire_candle.png | RGBA. Colour with light added, over transparency. Use it where you cannot blend additively. |
fire_candle_color.png | RGBA. The colour layer alone. |
fire_candle_light.png | RGB. The light layer alone, to draw additively over the colour sheet. |
fire_candle.json | Aseprite-style "array" JSON with beanfx's fields. See Sprite sheet format. |
| Flag | Default | Meaning |
|---|---|---|
--out DIR | target/out | Directory to write into; created if missing. |
--palette WORD | as designed | A palette preset: fire, ice, poison, holy, shadow, arcane, blood, electric, nature, gold. |
--num NAME=V | as designed | One 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
| Flag | Default | Meaning |
|---|---|---|
--scale N | 4 | Each 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
| Flag | Default | Meaning |
|---|---|---|
--pixelfx DIR | $PIXELFX, else ./pixelfx | A pixelfx checkout. Needs Node on the path. |
--opt key=value | An 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 DIR | target/parity | Where 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
| Code | Meaning |
|---|---|
0 | Success; for parity, PASS. |
1 | parity ran and FAILed the gate (or critique and diff found an error or a difference). |
2 | Could 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.