Pixi shell
pixfx-pixi plays pixfx effects in a Pixi 8 application. Effects are painted on worker threads and show up as Pixi sprites: a back pair and a front pair, each a colour sprite and an additive light sprite, so your sprites can stand between them.
Requires pixi.js ^8.22.0. It runs on pixfx-web, the runtime every pixfx JS shell shares.
Install
cd pixfx-rs/packages/pixfx-web && bun install && bun run build:wasm
cd ../pixfx-pixi && bun install
cd /path/to/your-game && bun add ../pixfx-rs/packages/pixfx-pixi
pixfx-web loads its wasm and its worker through new URL(..., import.meta.url); tell Vite to serve it as source:
// vite.config.js
export default { optimizeDeps: { exclude: ["pixfx-web"] } };
Use
import { Application, Container } from "pixi.js";
import { createPixfx, loadPixfx } from "pixfx-pixi";
await loadPixfx();
const app = new Application();
await app.init({ width: 1344, height: 720, background: "#17131c", roundPixels: true });
const world = app.stage.addChild(new Container());
world.scale.set(4);
const fx = world.addChild(new Container());
const pixfx = createPixfx(app, { container: fx, camera: world });
pixfx.play("fire/campfire", 168, 160);
pixfx.play("fire/candle", 0, 0).follow(hero);
Option of createPixfx | Meaning |
|---|---|
container | Where the effects' sprites go, sorted by zIndex. Default: a new container on app.stage. |
camera | What the shake moves and tilts about the screen's centre, put back after each render. Default: app.stage. |
play(id, x, y, opts?) places the effect's origin at (x, y) in container. depth: {back, front} sets the sprites' zIndex; every other option is the engine's, as in the Phaser plugin. The returned PixfxEffect and pixfx.feel work as there.
Effects advance on app.ticker, after the game's own callbacks and before the render: ticker.speed scales them, ticker.stop() freezes them. pixfx.destroy() ends every effect and frees its sprites. On WebGL every frame is a region of a few atlas pages, filled straight from the bytes the workers painted.
Demo and checks
bunx vite demo # campfire, braziers, a candle following a walker; click for an explosion with shake
bun run check # tsc, eslint, bun test
bun run check:browser # Chrome: show, animate, freeze, shake and destroy