pixi-particles-engine 0.1.8 → 0.1.10

package/src/texture-provider.ts

@@ -0,0 +1,66 @@
+import { ParticleProperties, Texture } from "pixi.js";
+import { PxParticle } from "./px-particle";
+
+/**
+ * TextureProvider decides which {@link Texture} a particle uses.
+ *
+ * It is called in two different phases:
+ * 1) Pool creation: `initialTexture()` (required by Pixi to construct the particle)
+ * 2) Spawn / simulation: `textureForSpawn()` and optional `update()`
+ *
+ * Providers may be stateless (single texture) or stateful (animated textures, weighted random, etc).
+ * Keep provider methods lightweight: they can be called very frequently.
+ */
+export interface TextureProvider {
+    /**
+     * Dynamic property requirements for this provider.
+     *
+     * PixiJS ParticleContainer can skip updating GPU buffers unless you mark certain fields as dynamic.
+     * If your provider changes something over time that affects rendering (e.g. UVs for animation),
+     * declare it here so the emitter enables the correct `dynamicProperties`.
+     *
+     * Example:
+     *   requires: { uvs: true }
+     */
+    readonly requires?: ParticleProperties;
+
+    /**
+     * Called once per pooled particle, at pool initialization time.
+     *
+     * Pixi requires a texture to construct each Particle, so this must always return a valid Texture.
+     * The texture returned here is just an initial placeholder; it can be replaced on spawn.
+     */
+    initialTexture(): Texture;
+
+    /**
+     * Called every time a particle is spawned.
+     *
+     * Must return a valid texture. May depend on:
+     * - random selection (weighted sets)
+     * - emitter state
+     * - particle state (reused pooled particle)
+     *
+     */
+    textureForSpawn?(p: PxParticle): Texture;
+
+    /**
+     * Optional per-frame hook.
+     *
+     * Use this when the texture can change during the particle's life:
+     * - animated textures (flipbook)
+     * - texture swapping
+     *
+     * If you mutate anything that affects rendering (like UVs), ensure `requires`
+     * contains the correct dynamicProperties.
+     */
+    update?(p: PxParticle, dt: number): void;
+
+    /**
+     * Optional recycle hook.
+     *
+     * Called when a particle is killed and returned to the pool.
+     * Use this to clear any provider-specific state stored on the particle
+     * (e.g. animation frame index, timers, cached references).
+     */
+    onKill?(p: PxParticle): void;
+}

package/src/texture-providers/animated-texture-provider.ts

@@ -0,0 +1,146 @@
+import { Texture } from "pixi.js";
+import { TextureProvider } from "../texture-provider";
+import { PxParticle } from "../px-particle";
+
+/**
+ * Configuration for AnimatedTextureProvider.
+ *
+ * Frames are generated using:
+ *   `${texturePrefix}${frameNumber}`
+ *
+ * Example:
+ *   texturePrefix: "Explosion_"
+ *   numberOfFrames: 16
+ *   padLength: 3
+ *
+ * Generates:
+ *   Explosion_000
+ *   Explosion_001
+ *   ...
+ *   Explosion_015
+ */
+export interface AnimatedTextureProviderOptions {
+    /**
+     * Prefix used to construct frame aliases.
+     */
+    texturePrefix: string;
+
+    /** Total number of frames in the animation sequence. */
+    numberOfFrames: number;
+
+    /** Optional starting frame index (default: 0). */
+    firstFrame?: number;
+
+    /**
+     * Optional zero-padding length.
+     * If omitted, defaults to numberOfFrames digit length.
+     *
+     * Example:
+     *   numberOfFrames = 16 → default padLength = 2
+     *   frame 3 → "03"
+     */
+    padLength?: number;
+
+    /** Frames per second (default: 60). */
+    fps?: number;
+
+    /**
+     * If true, animation loops.
+     * If false, animation stops at the last frame.
+     * Default: true.
+     */
+    loop?: boolean;
+}
+
+/**
+ * Flipbook-style animated texture provider.
+ *
+ * Each particle cycles through a pre-generated array of textures
+ * based on elapsed time and configured FPS.
+ *
+ * This is NOT a Pixi AnimatedSprite.
+ * Instead, it swaps particle.texture manually each frame.
+ *
+ * Because UVs change when textures change, this provider declares:
+ *   requires = { uvs: true }
+ *
+ * so the Emitter enables the correct ParticleContainer dynamicProperties.
+ */
+export class AnimatedTextureProvider implements TextureProvider {
+    /** UV updates are required because textures change during lifetime. */
+    public readonly requires = { uvs: true };
+
+    /** Preloaded frame textures. */
+    private readonly frames: Texture[];
+
+    /** Frames per second for animation playback. */
+    private readonly fps: number;
+
+    /** Whether animation loops. */
+    private readonly loop: boolean;
+
+    constructor(options: AnimatedTextureProviderOptions) {
+        const start = options.firstFrame ?? 0;
+
+        const padLength = options.padLength ?? options.numberOfFrames.toString().length;
+
+        this.frames = [];
+
+        for (let i = start; i < options.numberOfFrames + start; i++) {
+            const alias = `${options.texturePrefix}${i.toString().padStart(padLength, "0")}`;
+            this.frames.push(Texture.from(alias));
+        }
+
+        if (this.frames.length === 0) {
+            throw new Error("AnimatedTextureProvider: no frames generated");
+        }
+
+        this.fps = options.fps ?? 60;
+        this.loop = options.loop ?? true;
+    }
+
+    /**
+     * Used when constructing pooled particles.
+     * Returns the first frame as a placeholder texture.
+     */
+    public initialTexture(): Texture {
+        return this.frames[0];
+    }
+
+    /**
+     * Called each time a particle is spawned.
+     *
+     * Initializes per-particle animation state
+     * and resets animation to first frame.
+     */
+    public textureForSpawn(p: PxParticle): Texture {
+        p.animatedParticleState = { t: 0 };
+        return this.frames[0];
+    }
+
+    /**
+     * Per-frame update hook.
+     *
+     * Advances animation time and selects the appropriate frame.
+     */
+    public update(p: PxParticle, dt: number): void {
+        if (!p.animatedParticleState || this.frames.length <= 1) return;
+
+        p.animatedParticleState.t += dt;
+
+        const time = p.animatedParticleState.t;
+        const rawFrame = Math.floor(time * this.fps);
+
+        const idx = this.loop ? rawFrame % this.frames.length : Math.min(rawFrame, this.frames.length - 1);
+
+        p.texture = this.frames[idx];
+    }
+
+    /**
+     * Called when particle is recycled.
+     * Clears animation state to avoid stale data in pooled particles.
+     */
+    public onKill(p: PxParticle): void {
+        p.animatedParticleState = undefined;
+    }
+}

package/src/texture-providers/single-texture-provider.ts

@@ -0,0 +1,22 @@
+import { Texture } from "pixi.js";
+import { TextureProvider } from "../texture-provider";
+
+/**
+ * Always returns the same texture for every particle.
+ * Useful for simple effects (sparks, smoke puffs, etc).
+ */
+export class SingleTextureProvider implements TextureProvider {
+    /** Key/URL/alias passed to PixiJS Texture.from(). */
+    private readonly textureId: string;
+
+    private readonly texture: Texture;
+
+    constructor(textureId: string) {
+        this.textureId = textureId;
+        this.texture = Texture.from(textureId);
+    }
+
+    public initialTexture(): Texture {
+        return this.texture;
+    }
+}

package/src/texture-providers/weighted-texture-provider.ts

@@ -0,0 +1,52 @@
+import { Texture } from "pixi.js";
+import { TextureProvider } from "../texture-provider";
+import { PxParticle } from "../px-particle";
+
+type WeightedTexture = {
+    /** Key/URL/alias passed to PixiJS Texture.from(). */
+    textureId: string;
+    weight: number;
+};
+
+/**
+ * Chooses a random texture at spawn time using weighted probabilities.
+ *
+ * - Good for variety (different spark shapes, debris pieces, etc.)
+ * - Selection happens only on spawn (not per frame)
+ */
+export class WeightedTextureProvider implements TextureProvider {
+    private readonly fallback: Texture;
+    private readonly items: { texture: Texture; weight: number }[];
+
+    private totalWeight = 0;
+
+    constructor(items: WeightedTexture[], fallbackTextureId: string) {
+        this.fallback = Texture.from(fallbackTextureId);
+
+        // Pre-cache textures and compute total weight (ignoring negatives)
+        this.items = items.map((it) => ({
+            texture: Texture.from(it.textureId),
+            weight: Math.max(0, it.weight),
+        }));
+
+        for (const it of this.items) this.totalWeight += it.weight;
+    }
+
+    public initialTexture(): Texture {
+        return this.fallback;
+    }
+
+    public textureForSpawn(_p: PxParticle): Texture {
+        if (this.totalWeight <= 0 || this.items.length === 0) return this.fallback;
+
+        let r = Math.random() * this.totalWeight;
+
+        for (const it of this.items) {
+            r -= it.weight;
+            if (r <= 0) return it.texture;
+        }
+
+        // Floating point edge-case fallback
+        return this.items[this.items.length - 1]!.texture;
+    }
+}

package/src/utils.ts

@@ -0,0 +1,13 @@
+export class Utils {
+    public static lerp(a: number, b: number, t: number): number {
+        return a + (b - a) * t;
+    }
+
+    public static clamp01(v: number) {
+        return v < 0 ? 0 : v > 1 ? 1 : v;
+    }
+
+    public static rand(min: number, max: number) {
+        return min + Math.random() * (max - min);
+    }
+}