Getting started

Build the repository, render an effect to a file, then play it live in a browser.

Requirements

• Rust via rustup. rust-toolchain.toml pins the nightly toolchain and the wasm32-unknown-unknown target; 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.

cargo test --workspace

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-cli -- sheet fire/campfire --out out
cargo run -p pixfx-cli -- render fire/campfire --gif --scale 4 --out out

sheet writes fire_campfire.png, fire_campfire_color.png, fire_campfire_light.png and fire_campfire.json into out/. render --gif writes fire_campfire.gif, each pixel enlarged 4 times. See Command line and Sprite sheet format.

Play it in a browser

The canvas demo shows the candle, campfire and brazier on a ground, with a figure standing between the campfire's back and front layers:

wasm-pack build crates/pixfx-canvas --target web --out-dir demo/pkg
cd crates/pixfx-canvas/demo && python3 -m http.server 8766 --bind 127.0.0.1

Open http://127.0.0.1:8766/. Click the canvas to restart the nearest effect.

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/. Both demos must be served over HTTP: browsers do not load WebAssembly modules from file://.

Use it in your page

Copy the files wasm-pack wrote (pixfx_canvas.js and pixfx_canvas_bg.wasm) next to your page and import them:

<canvas id="fx" width="512" height="512" style="image-rendering: pixelated"></canvas>
<script type="module">
  import init, { Stage } from "./pkg/pixfx_canvas.js";

  await init();
  const stage = new Stage(document.getElementById("fx"), 4); // one game pixel = 4×4 canvas pixels
  stage.background("#13101b");                                // light only shows over a dark ground
  stage.play("fire/campfire", 64, 112, { seed: 3 });           // origin at game pixel (64, 112)
  stage.start();
</script>

That is the whole integration for a page that only shows effects. Games that draw sprites between an effect's layers own the loop instead; see Canvas renderer.

Whole-repo check

What to run before a commit:

cargo fmt --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace
wasm-pack test --node crates/pixfx-wasm
wasm-pack test --node crates/pixfx-canvas