Command line

The pixfx binary renders effects to sprite sheets and GIFs, and checks ports against pixelfx.

Run it

From the repository, through cargo:

cargo run -p pixfx-cli -- <command> ...

Or install the binary once and call pixfx directly:

cargo install --path crates/pixfx-cli
pixfx sheet fire/candle

Usage:

pixfx parity <id> [--pixelfx DIR] [--out DIR]
pixfx sheet <id> [--out DIR]
pixfx render <id> --gif [--scale N] [--out DIR]

Output files are named after the id with / replaced by _: fire/candle becomes fire_candle. Each command prints the id and the path it wrote.

sheet

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

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

render --gif

Write a looping GIF, composited over a dark backdrop (rgb(20, 18, 28)), since GIF has no partial transparency.

pixfx render fire/campfire --gif --scale 4 --out out

Flag	Default	Meaning
`--gif`		Required; GIF is the only render format.
`--scale N`	`4`	Each pixel becomes N×N. At least 1. The scaled size must fit GIF's 65535-pixel limit.
`--out DIR`	`target/out`	Directory to write into.

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

parity

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

pixfx 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.
`--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, pixelfx on the left and pixfx on the right.

Exit codes

Code	Meaning
`0`	Success; for `parity`, PASS.
`1`	`parity` ran and FAILed the gate.
`2`	Could not run: bad arguments, an unknown effect id, a write error, or a pixelfx render that failed. The message starts with `pixfx:` on stderr.

Options

The CLI renders with default options (the effect's default seed, palette and own options) and margin 0, so its output matches pixelfx's own sheets. To export with other options or a glow margin, call render_frames and the export functions from Rust.