Canvas 2D shell
pixfx-canvas2d plays pixfx effects on a Canvas 2D context, among your own drawing. Effects are painted on worker threads. Each effect draws in two layers: its back layer goes under what you draw between the two calls, its front layer over it. Colour is drawn normally and light is added ("lighter").
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-canvas2d && bun install
cd /path/to/your-game && bun add ../pixfx-rs/packages/pixfx-canvas2d
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"] } };
A page without a bundler loads dist/pixfx-canvas2d.js from bun run build; the worker and the wasm sit beside it in dist/assets/.
Use
import { createPixfx, loadPixfx } from "pixfx-canvas2d";
await loadPixfx(); // once, before createPixfx()
const ctx = canvas.getContext("2d");
if (!ctx) throw new Error("no 2d context");
const pixfx = createPixfx(ctx, { scale: 4 }); // one game pixel is 4×4 canvas pixels
pixfx.play("fire/campfire", 168, 160);
const hero = { x: 100, y: 142, active: true };
pixfx.play("fire/candle", 0, 0).follow(hero);
let last = performance.now();
requestAnimationFrame(function frame(now) {
pixfx.update((now - last) / 1000); // effects play; frames still to paint go to the workers
last = now;
drawBackground(ctx);
const [sx, sy] = pixfx.feel.shake; // the view's shake, in game pixels
ctx.save();
ctx.translate(sx * 4, sy * 4);
pixfx.drawLayer("back");
drawHero(ctx);
pixfx.drawLayer("front");
ctx.restore();
requestAnimationFrame(frame);
});
API
createPixfx(ctx, { scale? })
ctx is a CanvasRenderingContext2D; scale is canvas pixels per game pixel, a whole number (default 1). Positions are game pixels, drawn in the context's current transform. Call it after loadPixfx() resolved.
play(id, x, y, opts?) → PixfxEffect
Place the effect's origin at game pixel (x, y). Every option is the engine's (seed, flip, angle, light, palette, the effect's own; see options). An unknown id or a bad option throws and creates nothing. The effect has stop(), destroy(), follow(target, dx?, dy?) and setPosition(x, y), and emits "complete", "destroy" and "cue", as in the Phaser plugin.
update(dt) → seconds played
Advance every effect by dt seconds of your loop and send the frames still to paint to the workers. Returns the seconds the effects played: 0 in a hit-stop, less in slow motion. Until a worker sends a frame back, an effect shows the last one it had.
drawLayer("back" | "front"), draw()
drawLayer draws the effects' back (depth 0) or front (depth 1) layer. draw() draws every depth, lowest first, for effects played with other depths or a page with nothing between the layers.
warp()
After drawing everything a heavy blow's ring should bend, bend the canvas by the screen ripples alive now. Nothing bends at shake strength 0.
drawPicture(picture)
Draw a picture Rust painted outside the effects: fighters (new Sprites(w, h), then picture()) or scene light (new Lighting(w, h).paint(lights, glows)). The package re-exports the engine's effects, meta, Fx, Body, FightFeel, lookColors, Sprites, Lighting, stepLights and putOutLight, usable once loadPixfx() resolved.
feel
The answer to impacts: shake ([dx, dy] game pixels), roll (radians), flash (0 to 1), timeScale, and the game's own impacts addTrauma(k), freeze(secs), slow(secs, speed). setShakeStrength(k) and setFlashStrength(k) are the player's settings (1 as designed, 0 off); setEnabled(false) leaves the answer to your game, which reads the "cue" events. You apply shake, roll and flash where your view is drawn.
stats(), destroy()
stats() counts effects, textures and images. destroy() ends every effect and frees what it held.
How it draws
Workers paint each frame and send its colour and light bytes back; each fills a small OffscreenCanvas (colour on the left, light on the right) with putImageData. drawLayer draws the colour half with source-over, then the light half with "lighter", enlarged by scale with image smoothing off. The Rust scene decides which frame each effect shows, where and in what order; frames identical effects share are painted once.
Light is drawn as light over transparency: it adds exactly its light to an opaque canvas, and shows as that light's colour on a transparent one.
Demo and checks
bunx vite demo # campfire, braziers, a candle following a walker; click for an explosion
bun run check # tsc, eslint, bun test (real wasm)
bun run check:browser # Chrome: fires show and animate, a paused loop holds them, shake, destroy frees