pixi-particles-engine 0.1.8 → 0.1.10

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/rotation-curve-behaviour.ts

@@ -0,0 +1,32 @@
+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";
+
+/**
+ * Rotation over lifetime driven by a curve.
+ *
+ * Keyframes are sampled using normalized lifetime t in [0..1].
+ * Output is clamped to [0..1].
+ */
+export class RotationCurveBehaviour implements Behaviour {
+    public readonly requires = { color: true };
+
+    public readonly priority = 50;
+
+    private curve: Curve;
+
+    constructor(keyframes: CurveKeyframe[], opts?: CurveOptions) {
+        this.curve = new Curve(keyframes);
+    }
+
+    public onSpawn(p: PxParticle) {
+        p.angleVScale = this.curve.sample(0);
+    }
+
+    public update(p: PxParticle, _dt?: number, _emitter?: Emitter) {
+        const t = p.life > 0 ? p.age / p.life : 1;
+        p.angleVScale = this.curve.sample(t);
+    }
+}

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,37 @@
+import { PxParticle } from "../../px-particle";
+import { Behaviour } from "../../behaviour";
+
+/**
+ * Spawns particles inside a circular ring centered at (0, 0).
+ *
+ * Outer radius:
+ *   radius
+ *
+ * Inner empty radius:
+ *   innerRadius
+ *
+ * Particles spawn only between the outer and inner circles.
+ *
+ * Uses sqrt(random) to maintain uniform area distribution.
+ */
+export class CircleSpawnBehaviour implements Behaviour {
+    public readonly priority = -100;
+
+    constructor(
+        public radius: number,
+        public innerRadius: number = 0,
+    ) {}
+
+    public onSpawn(p: PxParticle) {
+        const angle = Math.random() * Math.PI * 2;
+
+        const outerR2 = this.radius * this.radius;
+        const innerR2 = this.innerRadius * this.innerRadius;
+
+        // Uniform distribution across ring area
+        const r = Math.sqrt(innerR2 + Math.random() * (outerR2 - innerR2));
+
+        p.x = Math.cos(angle) * r;
+        p.y = Math.sin(angle) * r;
+    }
+}

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

@@ -0,0 +1,60 @@
+import { PxParticle } from "../../px-particle";
+import { Behaviour } from "../../behaviour";
+
+/**
+ * Spawns particles inside a rectangular border/ring centered at (0, 0).
+ *
+ * Outer size:
+ *   width x height
+ *
+ * Inner empty area:
+ *   innerWidth x innerHeight
+ *
+ * Particles spawn only in the area between the outer and inner rectangles.
+ */
+export class RectangleSpawnBehaviour implements Behaviour {
+    public readonly priority = -100;
+
+    constructor(
+        public width: number,
+        public height: number,
+
+        // Optional inner empty rectangle
+        public innerWidth: number = 0,
+        public innerHeight: number = 0,
+    ) {}
+
+    public onSpawn(p: PxParticle) {
+        const outerHW = this.width * 0.5;
+        const outerHH = this.height * 0.5;
+
+        const innerHW = this.innerWidth * 0.5;
+        const innerHH = this.innerHeight * 0.5;
+
+        // No inner hole -> normal rectangle spawn
+        if (this.innerWidth <= 0 || this.innerHeight <= 0) {
+            p.x = this.rand(-outerHW, outerHW);
+            p.y = this.rand(-outerHH, outerHH);
+            return;
+        }
+
+        // Pick a random point until it lands outside the inner rectangle
+        while (true) {
+            const x = this.rand(-outerHW, outerHW);
+            const y = this.rand(-outerHH, outerHH);
+
+            const insideInner = x > -innerHW && x < innerHW && y > -innerHH && y < innerHH;
+
+            if (!insideInner) {
+                p.x = x;
+                p.y = y;
+                return;
+            }
+        }
+    }
+
+    /** 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,99 @@
+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 `angleVBase`, which the emitter integrates each tick.
+ *
+ * Supports:
+ *
+ * - Fixed value:
+ *    2
+ *
+ * - Random range:
+ *    { min: -3, max: 3 }
+ *
+ * - Random range with minimum absolute magnitude:
+ *    { min: -3, max: 3, minAbs: 2 }
+ *
+ *    Result:
+ *      [-3 .. -2] U [2 .. 3]
+ */
+export class StaticRotationBehaviour implements Behaviour {
+    public readonly priority = -60;
+
+    public readonly requires = { rotation: true };
+
+    /**
+     * @param speed
+     *  - number → fixed angular velocity
+     *  - object → randomized angular velocity
+     */
+    constructor(
+        public speed:
+            | number
+            | {
+                  min: number;
+                  max: number;
+
+                  /**
+                   * Optional minimum absolute value.
+                   *
+                   * Example:
+                   *   min=-3
+                   *   max=3
+                   *   minAbs=2
+                   *
+                   * Produces:
+                   *   [-3..-2] U [2..3]
+                   */
+                  minAbs?: number;
+              },
+    ) {}
+
+    public onSpawn(p: PxParticle) {
+        const s = typeof this.speed === "number" ? this.speed : this.randomRange(this.speed.min, this.speed.max, this.speed.minAbs);
+
+        p.angleVBase = s;
+    }
+
+    private randomRange(min: number, max: number, minAbs?: number): number {
+        // Normal range
+        if (minAbs == null || minAbs <= 0) {
+            return min + Math.random() * (max - min);
+        }
+
+        // If the excluded center does not intersect range,
+        // fallback to normal random
+        if (min >= minAbs || max <= -minAbs) {
+            return min + Math.random() * (max - min);
+        }
+
+        const leftMin = min;
+        const leftMax = Math.min(-minAbs, max);
+
+        const rightMin = Math.max(minAbs, min);
+        const rightMax = max;
+
+        const leftSize = Math.max(0, leftMax - leftMin);
+        const rightSize = Math.max(0, rightMax - rightMin);
+
+        const total = leftSize + rightSize;
+
+        if (total <= 0) {
+            return 0;
+        }
+
+        const pick = Math.random() * total;
+
+        // Left segment
+        if (pick < leftSize) {
+            return leftMin + Math.random() * leftSize;
+        }
+
+        // Right segment
+        return rightMin + Math.random() * rightSize;
+    }
+}

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;
+    }
+}