Getting started
Build the repository, render an effect to a file, then play it live in a browser.
Requirements
- Rust via rustup.
rust-toolchain.tomlpins the nightly toolchain and thewasm32-unknown-unknowntarget; rustup installs both on first build. - wasm-pack for any browser build (
cargo install wasm-pack). - Node and a pixelfx checkout, only for parity checks.
- bun, only for the Phaser plugin.
- trunk and a local gpui fork, only for gpui.
Commands on this site run from the repository root.
Build and test
The root workspace holds every crate except crates/pixfx-gpui, so a fresh clone builds and tests with nothing else installed. Each crate tests itself:
cargo test -p pixfx-core
Optional: cargo's intermediate build files can go in one shared directory with export CARGO_BUILD_BUILD_DIR=$PWD/target/build-dir. Nothing needs it.
Render an effect to files
cargo run -p pixfx-export --example sprite_sheet -- fire/campfire --out out
cargo run -p pixfx-export --example gif -- fire/campfire --scale 4 --out out
sprite_sheet writes fire_campfire.png, fire_campfire_color.png, fire_campfire_light.png and fire_campfire.json into out/. gif writes fire_campfire.gif, each pixel enlarged 4 times. See Scripts and Sprite sheet format.
Play it in a browser
The Canvas 2D demo shows a campfire, braziers and a candle following a walker, painted on worker threads; click for an explosion:
cd packages/pixfx-web && bun install && bun run build:wasm
cd ../pixfx-canvas2d && bun install && bunx vite demo
Open the URL Vite prints.
The JS engine demo plays the campfire by reading its pixels each frame:
wasm-pack build crates/pixfx-wasm --target web --out-dir demo/pkg
cd crates/pixfx-wasm/demo && python3 -m http.server 8765 --bind 127.0.0.1
Open http://127.0.0.1:8765/. Pages must be served over HTTP: browsers do not load WebAssembly modules from file://.
Use it in your page
Build the Canvas 2D bundle (cd packages/pixfx-canvas2d && bun run build), copy its dist/ next to your page as pkg/, and import it:
<canvas id="fx" width="512" height="512" style="image-rendering: pixelated"></canvas>
<script type="module">
import { createPixfx, loadPixfx } from "./pkg/pixfx-canvas2d.js";
await loadPixfx();
const ctx = document.getElementById("fx").getContext("2d");
const pixfx = createPixfx(ctx, { scale: 4 }); // one game pixel = 4×4 canvas pixels
pixfx.play("fire/campfire", 64, 112, { seed: 3 }); // origin at game pixel (64, 112)
let last = performance.now();
requestAnimationFrame(function frame(now) {
pixfx.update((now - last) / 1000);
last = now;
ctx.fillStyle = "#13101b"; // light only shows over a dark ground
ctx.fillRect(0, 0, 512, 512);
pixfx.draw();
requestAnimationFrame(frame);
});
</script>
Games that draw sprites between an effect's layers call drawLayer("back") and drawLayer("front") around them; see Canvas 2D shell. With a bundler, install pixfx-canvas2d as a package instead.
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