@particlr/runtime

@particlr/runtime

Plays .prt particle effects in PixiJS v8 (and PixiJS v7, via a separate subpath — see below). Design effects visually in the particlr editor, export a .prt file, play it back with this package. The editor previews through this exact runtime, and playback is deterministic (same document + seed ⇒ same frames) — so what you tune is what you ship.

The editor ships 57 CC0 presets — every frame above was rendered by this package. Open any of them at particlr.com, tune it, export, and play it back here.

Install

npm install @particlr/runtime pixi.js

Use

import { Application } from "pixi.js";
import { parseParticle, Effect } from "@particlr/runtime";
import { PixiParticleRenderer } from "@particlr/runtime/pixi";

const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

const doc = parseParticle(await (await fetch("boom.prt")).text()).doc!;
const fx = new Effect(doc, { seed: 1337 });
const view = new PixiParticleRenderer(fx);
view.container.position.set(400, 300); // where the effect plays
app.stage.addChild(view.container);

app.ticker.add((t) => {
  fx.step(t.deltaMS / 1000); // advance the simulation
  view.sync();               // draw it
});

That's the whole integration. Live example: particlr.com/sample.

Pixi v7

Games still on PixiJS v7 (the v7 → v8 migration is a large lift) can consume the same .prt effects without migrating. The v7 adapter lives on its own subpath — one subpath per major: ./pixi is the v8 adapter, ./pixi7 is the v7 adapter. The pixi.js peer range is ">=7.2.0 <9", and the v7 adapter is developed and golden-tested against pixi.js 7.4.3.

The only differences from the v8 snippet above are the v7 Application idiom (the constructor is synchronous — no await app.init() — and the canvas is app.view, typed as ICanvas, hence the cast) and the import path:

import { Application } from "pixi.js";
import { parseParticle, Effect } from "@particlr/runtime";
import { PixiParticleRenderer } from "@particlr/runtime/pixi7";

const app = new Application({ width: 800, height: 600 });
document.body.appendChild(app.view as HTMLCanvasElement);

const doc = parseParticle(await (await fetch("boom.prt")).text()).doc!;
const fx = new Effect(doc, { seed: 1337 });
const view = new PixiParticleRenderer(fx);
view.container.position.set(400, 300); // where the effect plays
app.stage.addChild(view.container);

app.ticker.add(() => {
  fx.step(app.ticker.deltaMS / 1000); // advance the simulation
  view.sync();                        // draw it
});

The public API is identical to ./pixi — migrating between majors is a one-line import change. The v7 adapter is at full feature parity: flipbooks, trails (including connect ribbons), sub-emitter rendering (driven by the shared core), and dissolve (via a forked v7 particle pipeline). The one hard limit is the renderer: v7 has no WebGPU, so the v7 adapter is WebGL only.

Performance note, measured honestly: v7's ParticleContainer renders full Sprite objects where v8 renders lightweight Particle structs, so the v7 adapter costs more CPU per frame by construction — in our benchmarks (~500 live particles, high churn, real Chromium) the v7 adapter spends ~1.3 ms per frame where v8 spends ~0.1 ms. Both are far under a 60 fps budget; at typical 2D-game particle counts this is not a limiting factor, but if you are pushing tens of thousands of particles, v8 is the faster target.

Builtin textures without Pixi

The five builtin textures (circle-soft, circle-hard, square, spark, smoke) are generated as pure-math straight-alpha RGBA pixel buffers — no canvas, no GPU, no pixi.js. They are the same bytes every adapter uploads. If you are writing a renderer for another engine and only need those buffers, import them from the ./textures subpath, which pulls in zero Pixi code:

import { generateBuiltinTexture, type TextureData } from "@particlr/runtime/textures";

const tex: TextureData = generateBuiltinTexture("circle-soft");
// tex.width, tex.height, tex.pixels (Uint8Array, RGBA, non-premultiplied)

This entry needs no pixi.js peer and runs in bare Node. The ./pixi and ./pixi7 adapters continue to re-export generateBuiltinTexture for existing consumers, so nothing changes for Pixi users.

Stepping semantics

step(dt) is host-driven and defensive (tightened in 0.6.0):

• dt is first scaled by timeScale, then clamped to 1/20 s so a tab unhide or debugger pause cannot explode emitters. When the clamp engages, emitter displacement for that step is scaled by clampedDt/rawDt, so a moving emitter's world-space trail stays continuous instead of teleporting.
• Zero, negative, and NaN dt are silent no-ops — a NaN never enters the simulation. +Infinity is clamped like any large dt.
• Playback is deterministic: same document + same seed + same dt sequence produces the same frames.

Going further

Effect also has a movable emitter for trails (setEmitterPosition), playback control (timeScale, onDone), a host-driven attractor (setAttractor), and per-instance parameters (setParam, setColorParam) — one boom.prt, many weapons. The full API is documented in the shipped TypeScript types, and the .prt format's reference is the bundled JSON Schema: import schema from "@particlr/runtime/particle.schema.json".

License

MIT. See LICENSE.