pixi-particles-engine 0.1.7 → 0.1.9

package/dist/esm/behaviours/alpha-curve-behaviour.js

@@ -1,4 +1,4 @@
-import { Curve } from "./curved-behaviour/curve-sampler";
+import { Curve } from "./curved-behaviour/curve-sampler.js";
 /**
  * Alpha over lifetime driven by a curve.
  *

package/dist/esm/behaviours/curved-behaviour/curve-sampler.js

@@ -1,4 +1,4 @@
-import { Utils } from "../../utils";
+import { Utils } from "../../utils.js";
 /**
  * Lightweight curve sampler for keyframed 1D values over normalized time [0..1].
  *

package/dist/esm/behaviours/movement-behaviours/gravity-behaviour.js

@@ -1,4 +1,4 @@
-import { Curve } from "../curved-behaviour/curve-sampler";
+import { Curve } from "../curved-behaviour/curve-sampler.js";
 /**
  * Applies an acceleration (gx, gy) scaled by a curve over lifetime.
  *

package/dist/esm/behaviours/movement-behaviours/movement-curve-behaviour.js

@@ -1,4 +1,4 @@
-import { Curve } from "../curved-behaviour/curve-sampler";
+import { Curve } from "../curved-behaviour/curve-sampler.js";
 /**
  * Drives particle velocity directly using curves over lifetime.
  *

package/dist/esm/behaviours/movement-behaviours/radial-burst-behaviour.js

@@ -1,4 +1,4 @@
-import { Utils } from "../../utils";
+import { Utils } from "../../utils.js";
 /**
  * Initializes particle velocity on spawn in a radial/cone burst.
  *

package/dist/esm/behaviours/scale-curve-behaviour.js

@@ -1,4 +1,4 @@
-import { Curve } from "./curved-behaviour/curve-sampler";
+import { Curve } from "./curved-behaviour/curve-sampler.js";
 /**
  * Uniform scale over lifetime driven by a curve.
  *

package/dist/esm/emitter.js

@@ -1,5 +1,5 @@
 import { ParticleContainer, Ticker } from "pixi.js";
-import { PxParticle } from "./px-particle";
+import { PxParticle } from "./px-particle.js";
 /**
  * Emitter is a ParticleContainer that owns a pool of {@link PxParticle} instances.
  *

package/dist/esm/index.js

@@ -1,19 +1,19 @@
-export * from "./behaviour";
-export * from "./emitter";
-export * from "./texture-provider";
-export * from "./behaviours/alpha-behaviour";
-export * from "./behaviours/alpha-curve-behaviour";
-export * from "./behaviours/scale-curve-behaviour";
-export * from "./behaviours/curved-behaviour/curve-key-frame";
-export * from "./behaviours/curved-behaviour/curve-sampler";
-export * from "./behaviours/movement-behaviours/gravity-behaviour";
-export * from "./behaviours/movement-behaviours/movement-curve-behaviour";
-export * from "./behaviours/movement-behaviours/radial-burst-behaviour";
-export * from "./behaviours/spawn-behaviours/circle-spawn-behaviour";
-export * from "./behaviours/spawn-behaviours/rectangle-spawn-behaviour";
-export * from "./behaviours/static-behaviours/static-rotation-behaviour";
-export * from "./behaviours/static-behaviours/static-scale-behaviour";
-export * from "./texture-providers/animated-texture-provider";
-export * from "./texture-providers/single-texture-provider";
-export * from "./texture-providers/weighted-texture-provider";
+export * from "./behaviour.js";
+export * from "./emitter.js";
+export * from "./texture-provider.js";
+export * from "./behaviours/alpha-behaviour.js";
+export * from "./behaviours/alpha-curve-behaviour.js";
+export * from "./behaviours/scale-curve-behaviour.js";
+export * from "./behaviours/curved-behaviour/curve-key-frame.js";
+export * from "./behaviours/curved-behaviour/curve-sampler.js";
+export * from "./behaviours/movement-behaviours/gravity-behaviour.js";
+export * from "./behaviours/movement-behaviours/movement-curve-behaviour.js";
+export * from "./behaviours/movement-behaviours/radial-burst-behaviour.js";
+export * from "./behaviours/spawn-behaviours/circle-spawn-behaviour.js";
+export * from "./behaviours/spawn-behaviours/rectangle-spawn-behaviour.js";
+export * from "./behaviours/static-behaviours/static-rotation-behaviour.js";
+export * from "./behaviours/static-behaviours/static-scale-behaviour.js";
+export * from "./texture-providers/animated-texture-provider.js";
+export * from "./texture-providers/single-texture-provider.js";
+export * from "./texture-providers/weighted-texture-provider.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pixi-particles-engine",
-    "version": "0.1.7",
+    "version": "0.1.9",
     "description": "High-performance PixiJS v8 particle engine with behaviours and pooling",
     "license": "MIT",
     "repository": {
@@ -31,12 +31,13 @@
     },
     "files": [
         "dist",
+        "src",
         "README.md",
         "LICENSE"
     ],
     "scripts": {
         "build": "npm run build:esm && npm run build:cjs",
-        "build:esm": "tsc -p tsconfig.esm.json && node scripts/write-esm-package-json.cjs",
+        "build:esm": "tsc -p tsconfig.esm.json && node scripts/fix-esm-specifiers.cjs && node scripts/write-esm-package-json.cjs",
         "build:cjs": "tsc -p tsconfig.cjs.json",
         "prepare": "npm run build",
         "prepublishOnly": "npm run build"

package/src/behaviour.ts

@@ -0,0 +1,74 @@
+import { ParticleProperties } from "pixi.js";
+import { Emitter } from "./emitter";
+import { PxParticle } from "./px-particle";
+
+/**
+ * A Behaviour is a modular unit of particle logic.
+ *
+ * Behaviours can:
+ * - Initialize particle state at spawn (velocity, alpha, scale, etc)
+ * - Update particle state each frame (curves, gravity, drag, color fade, etc)
+ * - Clean up any per-particle state when the particle is recycled
+ *
+ * Lifecycle:
+ * - init(emitter) is called once when the behaviour is added to an emitter
+ * - onSpawn(p, emitter) is called each time a particle is spawned
+ * - update(p, dt, emitter) is called every frame for each active particle
+ * - onKill(p, emitter) is called when a particle dies and returns to the pool
+ */
+export interface Behaviour {
+    /**
+     * Execution order relative to other behaviours.
+     *
+     * Lower priority runs earlier.
+     * When priorities are equal, execution order is stable and follows registration order.
+     *
+     * Use priority to ensure correct ordering when behaviours depend on each other
+     * (e.g. apply movement first, then apply alpha/scale curves).
+     */
+    readonly priority?: number;
+
+    /**
+     * Dynamic property requirements for this behaviour.
+     *
+     * PixiJS ParticleContainer uses `dynamicProperties` to decide which attributes
+     * must be re-uploaded to the GPU each frame.
+     *
+     * If your behaviour changes a property over time that affects rendering,
+     * declare it here so the emitter enables the correct dynamicProperties.
+     *
+     * Examples:
+     * - Changing `alpha` over time → requires: { color: true }
+     * - Changing `scaleX/scaleY` over time → may require: { vertex: true } (depends on Pixi internals)
+     * - Changing `rotation` over time → requires: { rotation: true }
+     *
+     * NOTE:
+     * If your behaviour only sets values ON SPAWN and never changes them after,
+     * you usually do NOT need to require dynamic properties.
+     */
+    readonly requires?: ParticleProperties;
+
+    /**
+     * Optional: called once when the behaviour is registered on an emitter.
+     * Useful for caching references, precomputing curves, or validating options.
+     */
+    init?(emitter: Emitter): void;
+
+    /**
+     * Optional: called when a particle is spawned (taken from pool and activated).
+     * Use this to initialize per-particle state for this behaviour.
+     */
+    onSpawn?(p: PxParticle, emitter: Emitter): void;
+
+    /**
+     * Optional: called every frame for each active particle.
+     * `dt` is delta time in seconds (already clamped by the emitter).
+     */
+    update?(p: PxParticle, dt: number, emitter: Emitter): void;
+
+    /**
+     * Optional: called when the particle is killed and returned to the pool.
+     * Use this to clear any per-particle state allocated by the behaviour.
+     */
+    onKill?(p: PxParticle, emitter: Emitter): void;
+}

package/src/behaviours/alpha-behaviour.ts

@@ -0,0 +1,29 @@
+import { PxParticle } from "../px-particle";
+import { Behaviour } from "../behaviour";
+import { Emitter } from "../emitter";
+
+/**
+ * Linearly fades alpha from startAlpha -> endAlpha over particle lifetime.
+ */
+export class AlphaBehaviour implements Behaviour {
+    public readonly requires = { color: true };
+
+    public readonly priority = 50;
+
+    public startAlpha = 1;
+    public endAlpha = 0;
+
+    constructor(startAlpha = 1, endAlpha = 0) {
+        this.startAlpha = startAlpha;
+        this.endAlpha = endAlpha;
+    }
+
+    public onSpawn(p: PxParticle, _emitter: Emitter): void {
+        p.alpha = this.startAlpha;
+    }
+
+    public update(p: PxParticle, _dt: number, _emitter: Emitter): void {
+        const t = p.life > 0 ? Math.min(1, Math.max(0, p.age / p.life)) : 1;
+        p.alpha = this.startAlpha + (this.endAlpha - this.startAlpha) * t;
+    }
+}

package/src/behaviours/alpha-curve-behaviour.ts

@@ -0,0 +1,34 @@
+import { Behaviour } from "../behaviour";
+import { PxParticle } from "../px-particle";
+import { CurveKeyframe, CurveOptions } from "./curved-behaviour/curve-key-frame";
+import { Curve } from "./curved-behaviour/curve-sampler";
+import { Emitter } from "../emitter";
+
+/**
+ * Alpha over lifetime driven by a curve.
+ *
+ * Keyframes are sampled using normalized lifetime t in [0..1].
+ * Output is clamped to [0..1].
+ */
+export class AlphaCurveBehaviour implements Behaviour {
+    /** Alpha changes over time, so ParticleContainer must treat color as dynamic. */
+    public readonly requires = { color: true };
+
+    public readonly priority = 50;
+
+    private curve: Curve;
+
+    constructor(keyframes: CurveKeyframe[], opts?: CurveOptions) {
+        // Always clamp alpha to [0..1]
+        this.curve = new Curve(keyframes, { ...opts, clamp: { min: 0, max: 1 } });
+    }
+
+    public onSpawn(p: PxParticle) {
+        p.alpha = this.curve.sample(0);
+    }
+
+    public update(p: PxParticle, _dt?: number, _emitter?: Emitter) {
+        const t = p.life > 0 ? p.age / p.life : 1;
+        p.alpha = this.curve.sample(t);
+    }
+}

package/src/behaviours/curved-behaviour/curve-key-frame.ts

@@ -0,0 +1,23 @@
+export type EaseFn = (x: number) => number;
+
+export type CurveKeyframe = {
+    /** Normalized lifetime [0..1]. */
+    time: number;
+
+    /** Value at this time. */
+    value: number;
+
+    /**
+     * Optional easing applied to the segment starting at this keyframe,
+     * i.e. easing used for interpolation from this keyframe -> next keyframe.
+     */
+    ease?: EaseFn;
+};
+
+export type CurveOptions = {
+    /** Default easing used when a segment has no per-keyframe ease. */
+    defaultEase?: EaseFn;
+
+    /** Optional clamp on sampled output. */
+    clamp?: { min: number; max: number };
+};

package/src/behaviours/curved-behaviour/curve-sampler.ts

@@ -0,0 +1,92 @@
+import { Utils } from "../../utils";
+import { CurveKeyframe, EaseFn, CurveOptions } from "./curve-key-frame";
+
+/**
+ * Lightweight curve sampler for keyframed 1D values over normalized time [0..1].
+ *
+ * - Keyframes are clamped to [0..1] and sorted by time.
+ * - Endpoints at t=0 and t=1 are ensured (added if missing).
+ * - Each segment can have its own easing function.
+ */
+export class Curve {
+    /** Cleaned + sorted keyframes (always includes endpoints at 0 and 1). */
+    private keys: CurveKeyframe[];
+
+    /** Default easing used when the keyframe has no `ease`. */
+    private defaultEase?: EaseFn;
+
+    /** Optional output clamp. */
+    private clamp?: { min: number; max: number };
+
+    constructor(keyframes: CurveKeyframe[], opts?: CurveOptions) {
+        this.defaultEase = opts?.defaultEase;
+        this.clamp = opts?.clamp;
+
+        // Normalize and sort keyframes.
+        const cleaned: CurveKeyframe[] = (keyframes ?? [])
+            .map((k) => ({
+                time: Utils.clamp01(k.time),
+                value: k.value,
+                ease: k.ease,
+            }))
+            .sort((a, b) => a.time - b.time);
+
+        // Fallback: flat zero curve.
+        if (cleaned.length === 0) cleaned.push({ time: 0, value: 0 }, { time: 1, value: 0 });
+
+        // Ensure endpoints exist at t=0 and t=1.
+        if (cleaned[0].time !== 0) cleaned.unshift({ time: 0, value: cleaned[0].value });
+
+        if (cleaned[cleaned.length - 1].time !== 1)
+            cleaned.push({
+                time: 1,
+                value: cleaned[cleaned.length - 1].value,
+            });
+
+        this.keys = cleaned;
+    }
+
+    /**
+     * Samples the curve at normalized time t01.
+     * Input is clamped to [0..1].
+     */
+    public sample(t01: number): number {
+        const t = Utils.clamp01(t01);
+
+        // Find which segment [k0..k1] contains t.
+        const i = this.findSegmentIndex(t);
+        const k0 = this.keys[i];
+        const k1 = this.keys[i + 1];
+
+        const span = k1.time - k0.time;
+        if (span <= 0) return this.clampValue(k1.value);
+
+        // Normalize t into segment space [0..1].
+        let u = (t - k0.time) / span;
+        u = Utils.clamp01(u);
+
+        // Apply easing for this segment (if any).
+        const ease = k0.ease ?? this.defaultEase;
+        if (ease) u = Utils.clamp01(ease(u));
+
+        // Linear interpolation between segment endpoints.
+        const v = Utils.lerp(k0.value, k1.value, u);
+        return this.clampValue(v);
+    }
+
+    /**
+     * Finds the segment index i such that t is between keys[i] and keys[i+1].
+     */
+    private findSegmentIndex(t: number): number {
+        for (let i = 0; i < this.keys.length - 2; i++) {
+            if (t <= this.keys[i + 1].time) return i;
+        }
+        return this.keys.length - 2;
+    }
+
+    /** Applies optional output clamp. */
+    private clampValue(v: number): number {
+        if (!this.clamp) return v;
+        return Math.min(this.clamp.max, Math.max(this.clamp.min, v));
+    }
+}

package/src/behaviours/movement-behaviours/gravity-behaviour.ts

@@ -0,0 +1,48 @@
+import { PxParticle } from "../../px-particle";
+import { Behaviour } from "../../behaviour";
+import { CurveKeyframe, CurveOptions } from "../curved-behaviour/curve-key-frame";
+import { Curve } from "../curved-behaviour/curve-sampler";
+
+/**
+ * Applies an acceleration (gx, gy) scaled by a curve over lifetime.
+ *
+ * This modifies velocity every frame:
+ *   v += g * strength(t) * dt
+ *
+ * where t is normalized particle age in [0..1].
+ *
+ * Typical uses:
+ * - Gravity that ramps up/down over lifetime
+ * - Wind that fades in/out
+ * - Custom "pull" forces controlled by a curve
+ *
+ */
+export class GravityCurveBehaviour implements Behaviour {
+    public readonly requires = { position: true };
+    public readonly priority = 0;
+
+    /** Acceleration vector (units: px/s² when strength is 1). */
+    public gx: number;
+    public gy: number;
+
+    /** Strength curve sampled by normalized lifetime. */
+    private strength: Curve;
+
+    constructor(gx: number, gy: number, strengthKeyframes: CurveKeyframe[], opts?: CurveOptions) {
+        this.gx = gx;
+        this.gy = gy;
+        this.strength = new Curve(strengthKeyframes, opts);
+    }
+
+    /**
+     * Called every frame for each particle.
+     * dt is in seconds.
+     */
+    public update(p: PxParticle, dt: number) {
+        const t = p.life > 0 ? p.age / p.life : 1;
+        const s = this.strength.sample(t);
+
+        p.vx += this.gx * s * dt;
+        p.vy += this.gy * s * dt;
+    }
+}

package/src/behaviours/movement-behaviours/movement-curve-behaviour.ts

@@ -0,0 +1,39 @@
+import { PxParticle } from "../../px-particle";
+import { Behaviour } from "../../behaviour";
+import { CurveKeyframe, CurveOptions } from "../curved-behaviour/curve-key-frame";
+import { Curve } from "../curved-behaviour/curve-sampler";
+
+/**
+ * Drives particle velocity directly using curves over lifetime.
+ *
+ * Each frame:
+ *   vx = vxCurve(t)
+ *   vy = vyCurve(t)
+ *
+ * where t is normalized lifetime in [0..1].
+ *
+ * IMPORTANT:
+ * - This behaviour overwrites velocity every frame.
+ * - Forces like GravityCurveBehaviour should run AFTER this behaviour
+ *   if you want gravity to modify the curve-driven motion.
+ *
+ */
+export class MovementCurveBehaviour implements Behaviour {
+    public readonly requires = { position: true };
+    public readonly priority = -10;
+
+    private vxCurve: Curve;
+    private vyCurve: Curve;
+
+    constructor(vxKeyframes: CurveKeyframe[], vyKeyframes: CurveKeyframe[], opts?: CurveOptions) {
+        this.vxCurve = new Curve(vxKeyframes, opts);
+        this.vyCurve = new Curve(vyKeyframes, opts);
+    }
+
+    public update(p: PxParticle, dt: number) {
+        const t = p.life > 0 ? p.age / p.life : 1;
+
+        p.vx = this.vxCurve.sample(t);
+        p.vy = this.vyCurve.sample(t);
+    }
+}

package/src/behaviours/movement-behaviours/radial-burst-behaviour.ts

@@ -0,0 +1,57 @@
+import { PxParticle } from "../../px-particle";
+import { Behaviour } from "../../behaviour";
+import { Utils } from "../../utils";
+import { ParticleProperties } from "pixi.js";
+
+/**
+ * Initializes particle velocity on spawn in a radial/cone burst.
+ *
+ * - Picks a random angle within [direction - spread/2, direction + spread/2]
+ * - Picks a random speed within [minSpeed, maxSpeed]
+ * - Sets particle velocity (vx, vy) in pixels/sec
+ *
+ * Notes:
+ * - This behaviour does NOT move particles directly; the emitter integrates vx/vy each tick.
+ */
+export class RadialBurstBehaviour implements Behaviour {
+    public readonly priority = -80;
+
+    public requires: ParticleProperties = { position: true };
+
+    /** Minimum initial speed (px/sec). */
+    public minSpeed: number;
+
+    /** Maximum initial speed (px/sec). */
+    public maxSpeed: number;
+
+    /**
+     * Center direction in radians.
+     * Pixi coordinate system:
+     * - 0 = right
+     * - PI/2 = down
+     */
+    public direction: number = 0;
+
+    /**
+     * Cone spread in radians.
+     * - 2π = full circle
+     * - PI/3 ≈ 60° cone
+     */
+    public spread: number = Math.PI * 2;
+
+    constructor(minSpeed: number, maxSpeed: number, direction: number = 0, spread: number = Math.PI * 2) {
+        this.minSpeed = minSpeed;
+        this.maxSpeed = maxSpeed;
+        this.direction = direction;
+        this.spread = spread;
+    }
+
+    public onSpawn(p: PxParticle) {
+        const half = this.spread * 0.5;
+        const angle = this.direction + Utils.rand(-half, half);
+        const speed = Utils.rand(this.minSpeed, this.maxSpeed);
+
+        p.vx = Math.cos(angle) * speed;
+        p.vy = Math.sin(angle) * speed;
+    }
+}

package/src/behaviours/scale-curve-behaviour.ts

@@ -0,0 +1,36 @@
+import { PxParticle } from "../px-particle";
+import { Behaviour } from "../behaviour";
+import { CurveKeyframe, CurveOptions } from "./curved-behaviour/curve-key-frame";
+import { Curve } from "./curved-behaviour/curve-sampler";
+import { Emitter } from "../emitter";
+
+/**
+ * Uniform scale over lifetime driven by a curve.
+ *
+ * Samples a curve using normalized lifetime t in [0..1] and applies:
+ *   scaleX = scaleY = curve(t)
+ */
+export class ScaleCurveBehaviour implements Behaviour {
+    public readonly requires = { vertex: true };
+
+    public readonly priority = 50;
+
+    private curve: Curve;
+
+    constructor(keyframes: CurveKeyframe[], opts?: CurveOptions) {
+        this.curve = new Curve(keyframes, { ...opts });
+    }
+
+    public onSpawn(p: PxParticle) {
+        const s = this.curve.sample(0);
+        p.scaleX = s;
+        p.scaleY = s;
+    }
+
+    public update(p: PxParticle, _dt?: number, _emitter?: Emitter) {
+        const t = p.life > 0 ? p.age / p.life : 1;
+        const s = this.curve.sample(t);
+        p.scaleX = s;
+        p.scaleY = s;
+    }
+}

package/src/behaviours/spawn-behaviours/circle-spawn-behaviour.ts

@@ -0,0 +1,24 @@
+import { PxParticle } from "../../px-particle";
+import { Behaviour } from "../../behaviour";
+
+/**
+ * Spawns particles uniformly within a circle centered at (0, 0).
+ *
+ * Uses sqrt(random) to achieve uniform distribution by area
+ * (without sqrt you'd get clustering toward the center).
+ *
+ */
+export class CircleSpawnBehaviour implements Behaviour {
+    public readonly priority = -100;
+
+    constructor(private readonly radius: number) {}
+
+    public onSpawn(p: PxParticle) {
+        const angle = Math.random() * Math.PI * 2;
+
+        const r = Math.sqrt(Math.random()) * this.radius;
+
+        p.x = Math.cos(angle) * r;
+        p.y = Math.sin(angle) * r;
+    }
+}

package/src/behaviours/spawn-behaviours/rectangle-spawn-behaviour.ts

@@ -0,0 +1,27 @@
+import { PxParticle } from "../../px-particle";
+import { Behaviour } from "../../behaviour";
+
+/**
+ * Spawns particles uniformly inside a rectangle centered at (0, 0).
+ * */
+export class RectangleSpawnBehaviour implements Behaviour {
+    public readonly priority = -100;
+
+    constructor(
+        private readonly width: number,
+        private readonly height: number,
+    ) {}
+
+    public onSpawn(p: PxParticle) {
+        const hw = this.width * 0.5;
+        const hh = this.height * 0.5;
+
+        p.x = this.rand(-hw, hw);
+        p.y = this.rand(-hh, hh);
+    }
+
+    /** Inclusive-exclusive uniform random. */
+    private rand(min: number, max: number) {
+        return min + Math.random() * (max - min);
+    }
+}

package/src/behaviours/static-behaviours/static-rotation-behaviour.ts

@@ -0,0 +1,28 @@
+import { Behaviour } from "../../behaviour";
+import { PxParticle } from "../../px-particle";
+
+/**
+ * Sets a particle's angular velocity at spawn time.
+ *
+ * Does NOT modify rotation per frame directly.
+ * Instead, it initializes `angleV`, which the emitter integrates each tick.
+ *
+ */
+export class StaticRotationBehaviour implements Behaviour {
+    public readonly priority = -60;
+
+    public readonly requires = { rotation: true };
+
+    /**
+     * @param speed
+     *  - number → fixed angular velocity (radians/sec)
+     *  - {min,max} → randomized angular velocity per particle
+     */
+    constructor(public speed: number | { min: number; max: number }) {}
+
+    public onSpawn(p: PxParticle) {
+        const s = typeof this.speed === "number" ? this.speed : this.speed.min + Math.random() * (this.speed.max - this.speed.min);
+
+        p.angleV = s;
+    }
+}

package/src/behaviours/static-behaviours/static-scale-behaviour.ts

@@ -0,0 +1,21 @@
+import { Behaviour } from "../../behaviour";
+import { PxParticle } from "../../px-particle";
+
+/**
+ * Sets particle scale at spawn time.
+ *
+ */
+export class StaticScaleBehaviour implements Behaviour {
+    public readonly priority = -60;
+
+    public spawnScale: number;
+
+    constructor(spawnScale: number) {
+        this.spawnScale = spawnScale;
+    }
+
+    public onSpawn(p: PxParticle) {
+        p.scaleX = this.spawnScale;
+        p.scaleY = this.spawnScale;
+    }
+}