pixfx

Phaser plugin

pixfx-phaser plays pixfx effects in Phaser 4 scenes. Effects show up as ordinary Phaser images: a back pair and a front pair, each a colour image and an additive light image, so your sprites can stand between them.

Requires Phaser ^4.2.1. The engine is the pixfx wasm module; drawing runs on worker threads by default.

Install

The package is not on npm yet. Build the engine once, then link the package into your game:

cd pixfx-rs/packages/pixfx-phaser
bun install
bun run build:wasm          # wasm-pack → wasm/ (git-ignored), shipped beside the JS
cd /path/to/your-game
bun add ../pixfx-rs/packages/pixfx-phaser

The package exports its TypeScript source (src/index.ts); Vite compiles it with the game. The .wasm file sits next to its JS glue and is loaded through new URL(..., import.meta.url), so Vite bundles it with no plugin.

A linked local package carries its own dev copy of Phaser in its node_modules. Tell Vite to use the game's copy, or the bundle holds two Phasers (2.8 MB instead of 1.5 MB, measured):

// vite.config.js of the game
export default { resolve: { dedupe: ["phaser"] } };

Load the engine and register the plugin

import Phaser from "phaser";
import { PixfxPlugin, loadPixfx } from "pixfx-phaser";

await loadPixfx(); // once, before any scene calls play()

new Phaser.Game({
  pixelArt: true,
  zoom: 4,
  scene: [MyScene],
  plugins: { scene: [{ key: "pixfx", plugin: PixfxPlugin, mapping: "pixfx" }] },
});

class MyScene extends Phaser.Scene {
  declare pixfx: PixfxPlugin;
  create() {
    this.pixfx.play("fire/campfire", 150, 170);
  }
}

play() before loadPixfx() has resolved throws pixfx: call await loadPixfx() before play().

Worker threads

loadPixfx() starts worker threads that draw the effects, one per core the main thread leaves free (1 to 4), each with its own copy of the engine. The main thread only decides and uploads; a worker simulates, paints, crops and converts each frame, and transfers the bytes. The pixels are exactly those the engine paints on the main thread. Until a worker sends a frame back the effect shows its last one, with at most one frame out per effect, so a slow phone drops frames instead of falling behind. Each effect stays in one worker for its life. play() still checks the id and options on the main thread and throws at once; "complete" and cues come from the main thread's clock. On WebGL every frame is a region of a few atlas pages, so the images go out in few batches.

await loadPixfx({ workers: 2 }); // a fixed number of workers
await loadPixfx({ workers: 0 }); // draw on the main thread

Without Worker support, effects draw on the main thread. Options apply to the first call; later calls return the loaded engine. Vite bundles the worker from new Worker(new URL(...), { type: "module" }), with no plugin.

Play an effect

scene.pixfx.play(id, x, y, opts?) places the effect's origin at world (x, y) and returns a PixfxEffect. One effect pixel is one world unit; camera zoom and pixelArt enlarge it, and positions snap to whole pixels. An unknown id or a bad option throws and creates nothing.

OptionMeaning
seedNon-negative integer; same seed and same steps give the same pixels.
flip, angle, palettePassed to the effect; see Options.
lightGlow strength, 0 or more: 0 is no glow, default 1.
depth: {back, front}Depths of the back and front images. Default {back: 0, front: 1}.
scrollFactorCamera scroll factor of the images: 1 world space (default), 0 screen space (HUD effects).

Other numeric or array options are passed to the effect (height, wood, ...). margin is refused: the plugin sizes it.

PixfxEffect

CallDoes
stop()Let it end: loops fade out, one-shots are cut short. Does nothing once finished.
destroy()Remove at once.
follow(obj, dx?, dy?)Track a game object each frame. If obj is destroyed, the effect stops (fades) where obj last was.
setDepths(back, front)Move the image pairs in the display list; put your sprite at a depth between them.
setPosition(x, y)Move; stops following.

Events: "complete" when the effect finishes on its own (after stop(), or at the end of a one-shot), and "destroy" after destroy(), never both. When either fires, the effect's textures, images and engine instance are already freed.

const torch = this.pixfx.play("fire/candle", 0, 0, { depth: { back: 9, front: 11 } });
torch.follow(this.player, 6, -2);   // the player sits at depth 10
torch.once("complete", () => console.log("torch out"));
this.time.delayedCall(5000, () => torch.stop());

Scene time

Effects advance on scene time: the scene update delta × scene.time.timeScale. A paused or sleeping scene freezes them; timeScale 0.25 plays them at quarter speed. Scene shutdown (restart, stop) or destroy frees every effect. scene.pixfx.stats() returns {engines, textures, images} still alive.

Game feel

Some effects fire cues at the frame of their impact: a camera shake, a hit-stop, a screen ripple, a flash or a sound. scene.pixfx.feel answers them for the scene. A hit-stop freezes the scene's effects. The shake moves and tilts the main camera's view for the render only, leaving its scroll, follow and rotation as the game set them. The flash lifts the view toward white. Sounds are the game's to play.

const feel = this.pixfx.feel;
feel.setShakeStrength(settings.shake);   // 1 as designed, 0 holds the camera still
feel.setFlashStrength(settings.flash);   // 0 never flashes, for photosensitive players
feel.on("cue", (c) => {
  if (c.cue.type === "sound") this.sound.play(c.cue.name, { pan: c.pan ?? 0 });
});

// in update(time, delta): freeze and slow the game's own world with the effects
this.player.x += this.player.vx * feel.timeScale * delta / 1000;
CallDoes
timeScaleHow fast play ran in the last scene update: 0 in a hit-stop, a fraction in slow motion, 1 otherwise.
addTrauma(k)The game's own impact shakes the camera: k (0 to 1) is added to the trauma.
freeze(secs)The game's own hit-stop; freezes do not add up, the longest wins.
slow(secs, speed)Play at speed (0 to 1) of real time for secs seconds, after any freeze.
setEnabled(on)Off: effects play every second of scene time, nothing shakes or flashes, and "cue" events still fire for the game's own answer.
shake, roll, flash, trauma, frozenThis frame's camera offset [dx, dy] in game pixels, tilt in radians, white lift 0 to 1, shake 0 to 1, and whether a hit-stop holds play.

"cue" fires as (cue, effect) on feel for every effect, and on each PixfxEffect for its own, whether or not the answer is on. A ripple's x/y and a sound's x are world positions; pan is -1 to 1 across the screen.

Limitation: transparent render targets

Light images use Phaser's BlendModes.ADD. In Phaser 4.2.1's WebGL renderer that is src·1 + dst·dstAlpha: over an opaque scene it adds exactly the light, but over a transparent render target (a transparent canvas, or a transparent RenderTexture) it adds nothing. Draw effects over an opaque background.

Demo

bun run build:wasm
bunx vite demo                   # dev server; open the printed URL
bunx vite build demo             # or build to demo/dist and serve that

?renderer=webgl (default) or ?renderer=canvas. Keys: P pause/resume, S time scale 1 ↔ 0.25, X stop the campfire, D destroy the walker the candle follows, R restart the scene. window.pixfxDemo exposes scene, game, engine, stats() and the events log for checks.

A stress page (demo/stress.html) and a Chrome performance runner (bun run perf, bun run perf:check) measure frame times with many effects.

Develop

bun run check   # tsc, eslint, bun test