pixfx documentation
pixfx is a set of pixel-art effects and the Rust engine that draws them. An effect is written once and produces the same pixels natively and in WebAssembly.
What you can do with it
- Render. Run an effect natively and write sprite sheets (composite, colour and light PNGs plus a beanfx-layout JSON), or a looping GIF. See Command line.
- Play live. Run the same effect in a browser through a Canvas 2D renderer that owns its loop, through plain JS bindings, inside a Phaser 4 scene, or inside a gpui window.
The effects are ports of pixelfx (JavaScript). The ported effects match pixelfx exactly: fire/candle, fire/campfire and fire/brazier render with 0 differing pixels against pixelfx commit 044e12a.
Pick a package
| You want to | Use | Page |
|---|---|---|
| Export sheets or GIFs for an engine that plays sprite sheets | pixfx CLI | Command line, Sheet format |
| Show effects on a web page or a canvas game | pixfx-canvas | Canvas renderer |
| Use effects in a Phaser 4 game | pixfx-phaser | Phaser plugin |
| Read raw frames in JS and draw them yourself (WebGL, a worker, tests) | pixfx-wasm | JS engine |
| Render, hash or export frames from Rust | pixfx-core, pixfx-effects, pixfx-export | Rust API |
| Paint effects in a gpui app | pixfx-gpui | gpui |
Crates and packages
| Path | What it is |
|---|---|
crates/pixfx-core | The engine: frame with colour and additive light, painter, Effect/Instance, render_frames, composite, frame_hash. |
crates/pixfx-effects | The effects and their registry, EFFECTS and effect(id). |
crates/pixfx-cli | The pixfx binary: sheet, render --gif, parity. |
crates/pixfx-export | Sprite sheets, beanfx-layout JSON and GIFs. |
crates/pixfx-wasm | The engine for JavaScript: effects(), meta(id), new Fx(id, opts). |
crates/pixfx-canvas | A Canvas 2D renderer, Stage, with its own loop or a host-owned one. |
packages/pixfx-phaser | Phaser 4 scene plugin, effects drawn on worker threads. |
crates/pixfx-gpui | Live playback inside gpui. Needs a gpui fork; a separate workspace. |
examples/gpui-web | A gpui web app playing the candle and campfire. |
Next
Getting started builds the repository and plays an effect. Concepts explains colour and light layers, back and front, origins, margins and time steps, which every other page relies on.