pixi-particles-engine 0.1.0

package/dist/emitter.js

@@ -0,0 +1,340 @@
+import { ParticleContainer, Ticker } from "pixi.js";
+import { PxParticle } from "./px-particle";
+/**
+ * Emitter is a ParticleContainer that owns a pool of {@link PxParticle} instances.
+ *
+ * Core responsibilities:
+ * - Keep a pool of particles to avoid allocations during gameplay.
+ * - Emit particles according to the selected EmissionMode.
+ * - Update active particles each tick (movement, behaviours, textures).
+ * - Recycle dead particles back into the pool.
+ */
+export class Emitter extends ParticleContainer {
+    constructor(options, textureProvider) {
+        super({
+            label: "Emitter",
+            ...options.containerOptions,
+            /**
+             * Important optimization:
+             * We enable only the dynamic properties that are actually needed
+             * (based on behaviours + texture provider requirements).
+             */
+            dynamicProperties: Emitter.computeDynamicProperties(options.behaviours ?? [], textureProvider),
+        });
+        /** Inactive particle pool (reused). */
+        this.pool = [];
+        /** Active particles currently simulated and rendered. */
+        this.active = [];
+        /**
+         * Sorted behaviours (priority + stable insertion order).
+         * Behaviours are applied in order every frame.
+         */
+        this.behaviours = [];
+        this.nextBehaviourOrder = 0;
+        /** Accumulator used to compute spawn counts in rate mode. */
+        this.emitAcc = 0;
+        /** Accumulator used to track time between waves in wave mode. */
+        this.waveAcc = 0;
+        this.tickerAttached = false;
+        this.maxParticles = options.maxParticles;
+        this.mode = options.mode;
+        this.ratePerSecond = options.ratePerSecond;
+        this.waveInterval = options.waveInterval;
+        this.particlesPerWave = options.particlesPerWave;
+        this.lifetime = options.lifetime;
+        this.emitting = options.emitting;
+        this.maxDeltaSeconds = options.maxDeltaSeconds ?? 0.1;
+        this.addAtBack = options.addAtBack;
+        this.textureProvider = textureProvider;
+        // Register behaviours (sorted by priority + stable order).
+        if (options.behaviours) {
+            for (const behaviour of options.behaviours) {
+                this.addBehaviour(behaviour);
+            }
+        }
+        /**
+         * Pre-allocate particles upfront:
+         * - avoids runtime allocations / GC spikes
+         * - allows "maxParticles" to be a hard cap
+         *
+         * Each pooled particle gets an initial texture (required by Pixi Particle).
+         * The actual texture may be replaced on spawn by the provider.
+         */
+        for (let i = 0; i < this.maxParticles; i++) {
+            const p = new PxParticle({ texture: this.textureProvider.initialTexture() });
+            this.pool.push(p);
+        }
+        /**
+         * In manual mode we do NOT attach to a ticker.
+         * User code calls emitBurst/emitWave and also needs to call updateEmitter manually
+         * (or you can provide a separate public update method if you prefer).
+         *
+         * NOTE: currently updateEmitter is still public and can be called manually.
+         */
+        this.ticker = options.ticker ?? Ticker.shared;
+        if (this.mode !== "manual") {
+            this.attachTicker();
+        }
+    }
+    /**
+     * Adds a behaviour and inserts it into the sorted execution order.
+     * Priority controls order; ties are resolved by insertion order.
+     */
+    addBehaviour(b) {
+        this.behaviours.push({
+            b,
+            order: this.nextBehaviourOrder++,
+            prio: b.priority ?? 0,
+        });
+        // lower priority runs earlier
+        this.behaviours.sort((a, c) => a.prio - c.prio || a.order - c.order);
+        // Optional init hook for behaviour to cache references or precompute curves.
+        b.init?.(this);
+        return this;
+    }
+    /**
+     * Ticker callback: advances simulation and handles emission.
+     *
+     * The emitter uses ticker.deltaMS (milliseconds between frames) converted to seconds.
+     * We clamp dt to maxDeltaSeconds to avoid large jumps and excessive spawning.
+     */
+    updateEmitter(ticker) {
+        const maxDt = this.maxDeltaSeconds;
+        let dt = ticker.deltaMS / 1000;
+        // Clamp dt for stability (e.g. tab in background).
+        if (dt > maxDt)
+            dt = maxDt;
+        if (dt <= 0)
+            return;
+        // Spawn new particles if enabled.
+        if (this.emitting)
+            this.emitParticles(dt);
+        /**
+         * Update particles & kill dead ones.
+         * Iterate backwards so we can remove by index safely.
+         */
+        for (let i = this.active.length - 1; i >= 0; i--) {
+            const p = this.active[i];
+            // Texture provider may animate / swap textures per frame.
+            this.textureProvider.update?.(p, dt);
+            // Base integrator: apply velocity and angular velocity.
+            // Behaviours can also modify velocity, position, rotation, etc.
+            p.age += dt;
+            p.x += p.vx * dt;
+            p.y += p.vy * dt;
+            p.rotation += p.angleV * dt;
+            // Apply behaviours in sorted order.
+            for (const entry of this.behaviours)
+                entry.b.update?.(p, dt, this);
+            // Kill particle if it exceeded its lifetime.
+            if (p.age >= p.life) {
+                this.killAtIndex(i);
+            }
+        }
+    }
+    /**
+     * Emits particles according to the emitter's mode.
+     * This method is called automatically each tick when emitting=true.
+     */
+    emitParticles(dt) {
+        if (this.mode === "rate") {
+            const rate = this.ratePerSecond ?? 0;
+            if (rate <= 0)
+                return;
+            /**
+             * Accumulate fractional time and convert into "how many particles should we emit".
+             * This produces stable emission even with variable frame rates.
+             */
+            this.emitAcc += dt;
+            const want = Math.floor(this.emitAcc * rate);
+            if (want <= 0)
+                return;
+            // Keep the remainder time after spawning `want` particles.
+            this.emitAcc -= want / rate;
+            for (let i = 0; i < want; i++)
+                this.spawnOne();
+            return;
+        }
+        if (this.mode === "wave") {
+            const interval = this.waveInterval ?? 0.25;
+            const perWave = this.particlesPerWave ?? 1;
+            if (interval <= 0 || perWave <= 0)
+                return;
+            // Emit full waves when the accumulated time crosses the interval.
+            this.waveAcc += dt;
+            while (this.waveAcc >= interval) {
+                this.waveAcc -= interval;
+                for (let i = 0; i < perWave; i++)
+                    this.spawnOne();
+            }
+            return;
+        }
+    }
+    /**
+     * Spawns a single particle from the pool.
+     *
+     * IMPORTANT:
+     * - If the pool is empty, spawning is skipped (hard cap).
+     * - Texture is selected by TextureProvider at spawn time.
+     * - Behaviours' onSpawn hooks initialize per-particle state.
+     */
+    spawnOne() {
+        const p = this.pool.pop();
+        if (!p)
+            return;
+        if (this.textureProvider.textureForSpawn)
+            p.texture = this.textureProvider.textureForSpawn(p);
+        p.onSpawn();
+        // Allow behaviours to initialize the particle for this spawn.
+        for (const behaviour of this.behaviours)
+            behaviour.b.onSpawn?.(p, this);
+        // Add particle to the container (front or back).
+        if (this.addAtBack) {
+            this.addParticleAt(p, 0);
+        }
+        else {
+            this.addParticle(p);
+        }
+        // Randomize lifetime in [min, max].
+        const { min, max } = this.lifetime;
+        p.life = min + Math.random() * Math.max(0, max - min);
+        this.active.push(p);
+    }
+    /**
+     * Kills and recycles a particle at a given index in the active list.
+     *
+     * Order of operations:
+     * 1) behaviour kill hooks (reverse order, mirroring teardown)
+     * 2) provider kill hook
+     * 3) reset particle instance
+     * 4) remove from container + active list
+     * 5) return to pool
+     */
+    killAtIndex(activeIndex) {
+        const p = this.active[activeIndex];
+        // Call behaviours' teardown in reverse to match common init/apply ordering expectations.
+        for (let i = this.behaviours.length - 1; i >= 0; i--) {
+            this.behaviours[i].b.onKill?.(p, this);
+        }
+        this.textureProvider.onKill?.(p);
+        p.onKill();
+        this.removeParticle(p);
+        /**
+         * Remove from active list using "swap remove":
+         * - O(1)
+         * - does not preserve ordering (fine for particle sims)
+         */
+        const last = this.active.length - 1;
+        if (activeIndex !== last)
+            this.active[activeIndex] = this.active[last];
+        this.active.pop();
+        this.pool.push(p);
+    }
+    /**
+     * Immediately kills all active particles and resets emission accumulators.
+     * Useful when restarting an effect or changing scenes.
+     */
+    clearParticles() {
+        this.emitAcc = 0;
+        this.waveAcc = 0;
+        while (this.active.length > 0) {
+            this.killAtIndex(this.active.length - 1);
+        }
+    }
+    /**
+     * Manual emission helpers.
+     * Only relevant if mode === "manual" or emitting === false.
+     */
+    emitBurst(count) {
+        for (let i = 0; i < count; i++)
+            this.spawnOne();
+    }
+    emitWave() {
+        const n = this.particlesPerWave ?? 0;
+        for (let i = 0; i < n; i++)
+            this.spawnOne();
+    }
+    /**
+     * Computes ParticleContainer dynamicProperties from:
+     * - TextureProvider.requires
+     * - each Behaviour.requires
+     *
+     * Keeping these minimal is important for performance:
+     * enabling extra dynamic properties can increase per-frame GPU uploads.
+     */
+    static computeDynamicProperties(behaviours, provider) {
+        const props = {
+            position: false,
+            rotation: false,
+            vertex: false,
+            uvs: false,
+            color: false,
+        };
+        // Texture provider may require updates like uvs (animated textures) or vertex.
+        if (provider.requires) {
+            for (const key in provider.requires) {
+                props[key] = true;
+            }
+        }
+        // Behaviours declare which GPU-updated properties they touch over time.
+        for (const b of behaviours) {
+            if (!b.requires)
+                continue;
+            for (const key in b.requires) {
+                props[key] = true;
+            }
+        }
+        return props;
+    }
+    /**
+     * Attaches the emitter update loop to the configured ticker.
+     */
+    attachTicker() {
+        if (this.tickerAttached)
+            return;
+        if (!this.updateEmitterBound) {
+            this.updateEmitterBound = this.updateEmitter.bind(this);
+        }
+        if (!this.ticker) {
+            this.ticker = Ticker.shared;
+        }
+        this.ticker.add(this.updateEmitterBound);
+        this.tickerAttached = true;
+    }
+    /**
+     * Detaches the emitter update loop from the ticker.
+     */
+    detachTicker() {
+        if (!this.tickerAttached)
+            return;
+        if (!this.ticker || !this.updateEmitterBound)
+            return;
+        this.ticker.remove(this.updateEmitterBound);
+        this.tickerAttached = false;
+    }
+    /**
+     * Changes the emission mode at runtime.
+     *
+     * - Switching to "manual" detaches the ticker.
+     * - Switching to "rate" or "wave" attaches the ticker.
+     *
+     */
+    setMode(mode) {
+        if (this.mode === mode)
+            return;
+        const wasManual = this.mode === "manual";
+        const willBeManual = mode === "manual";
+        this.mode = mode;
+        if (!wasManual && willBeManual) {
+            this.detachTicker();
+        }
+        else if (wasManual && !willBeManual) {
+            this.attachTicker();
+        }
+    }
+    destroy(options) {
+        this.detachTicker();
+        super.destroy(options);
+    }
+}
+//# sourceMappingURL=emitter.js.map

package/dist/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"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","sourcesContent":["import { ParticleContainer, ParticleContainerOptions, ParticleProperties, Ticker } from \"pixi.js\";\r\nimport { Behaviour } from \"./behaviour\";\r\nimport { TextureProvider } from \"./texture-provider\";\r\nimport { PxParticle } from \"./px-particle\";\r\n\r\n/**\r\n * How this emitter produces particles over time:\r\n * - \"rate\": continuously emits at a fixed particles-per-second\r\n * - \"wave\": emits discrete bursts (\"waves\") every interval\r\n * - \"manual\": user code calls emitBurst/emitWave; no ticker hookup\r\n */\r\nexport type EmissionMode = \"rate\" | \"wave\" | \"manual\";\r\n\r\n/**\r\n * Configuration passed to {@link Emitter}.\r\n *\r\n * Notes:\r\n * - In \"rate\" mode, you must provide `ratePerSecond`\r\n * - In \"wave\" mode, you should provide `waveInterval` and `particlesPerWave`\r\n * - In \"manual\" mode, the emitter will NOT auto-update; you trigger emission yourself\r\n */\r\nexport interface EmitterOptions {\r\n    /**\r\n     * Options forwarded to PixiJS ParticleContainer.\r\n     * You can set blendMode, position, etc.\r\n     *\r\n     * NOTE: dynamicProperties are computed automatically based on behaviours + texture provider.\r\n     */\r\n    containerOptions?: ParticleContainerOptions;\r\n\r\n    /** Maximum number of particles alive at the same time. Also defines the pool size. */\r\n    maxParticles: number;\r\n\r\n    /** Emission strategy (rate / wave / manual). */\r\n    mode: EmissionMode;\r\n\r\n    /**\r\n     * Particles per second when mode === \"rate\".\r\n     */\r\n    ratePerSecond?: number;\r\n\r\n    /**\r\n     * Seconds between waves when mode === \"wave\".\r\n     * If omitted, a default is used.\r\n     */\r\n    waveInterval?: number;\r\n\r\n    /**\r\n     * How many particles are spawned each wave when mode === \"wave\".\r\n     * If omitted, defaults to 1.\r\n     */\r\n    particlesPerWave?: number;\r\n\r\n    /** Particle lifetime in seconds. Each particle chooses a random value in [min, max]. */\r\n    lifetime: { min: number; max: number };\r\n\r\n    /**\r\n     * If true, the emitter automatically emits according to its mode.\r\n     * If false, particles can still be spawned using manual methods.\r\n     */\r\n    emitting?: boolean;\r\n\r\n    /**\r\n     * Clamp delta-time to avoid huge simulation jumps (tab pause, breakpoint, slow frame, etc).\r\n     * This prevents spawning a massive burst and \"teleporting\" particles.\r\n     */\r\n    maxDeltaSeconds?: number;\r\n\r\n    /**\r\n     * Behaviours are modular systems applied to particles.\r\n     * Typical responsibilities:\r\n     * - initialize properties at spawn (velocity, scale, alpha, etc)\r\n     * - update properties each frame (curves, gravity, drag, etc)\r\n     *\r\n     * Behaviours can also declare \"requires\" to enable ParticleContainer dynamicProperties.\r\n     */\r\n    behaviours?: Behaviour[];\r\n\r\n    /**\r\n     * If true, particles are added at index 0 (behind existing children).\r\n     * Useful for layering (e.g. smoke behind sparks).\r\n     */\r\n    addAtBack?: boolean;\r\n\r\n    /**\r\n     * Optional custom ticker (e.g. your app ticker).\r\n     * If omitted, uses Ticker.shared.\r\n     */\r\n    ticker?: Ticker;\r\n}\r\n\r\n/**\r\n * Internally we keep behaviours in a stable sorted array:\r\n * - prio: behaviour priority (lower runs earlier)\r\n * - order: insertion order to break ties (stable ordering)\r\n */\r\ntype SortedBehaviour = { b: Behaviour; order: number; prio: number };\r\n\r\n/**\r\n * ParticleContainer dynamicProperties config.\r\n * Pixi uses this to know which particle attributes must be re-uploaded to GPU each frame.\r\n */\r\ntype DynamicProps = ParticleProperties & Record<string, boolean>;\r\n\r\n/**\r\n * Emitter is a ParticleContainer that owns a pool of {@link PxParticle} instances.\r\n *\r\n * Core responsibilities:\r\n * - Keep a pool of particles to avoid allocations during gameplay.\r\n * - Emit particles according to the selected EmissionMode.\r\n * - Update active particles each tick (movement, behaviours, textures).\r\n * - Recycle dead particles back into the pool.\r\n */\r\nexport class Emitter extends ParticleContainer {\r\n    /** Pool capacity / maximum concurrent particles. */\r\n    private maxParticles: number;\r\n\r\n    /** Current emission mode. */\r\n    private mode: EmissionMode;\r\n\r\n    /** Particles per second for mode=\"rate\". */\r\n    public ratePerSecond?: number;\r\n\r\n    /** Wave interval (seconds) for mode=\"wave\". */\r\n    public waveInterval?: number;\r\n\r\n    /** Particles per wave for mode=\"wave\". */\r\n    public particlesPerWave?: number;\r\n\r\n    /** Lifetime range (seconds) used for each spawned particle. */\r\n    private lifetime: { min: number; max: number };\r\n\r\n    /**\r\n     * If true, emission is automatic (rate/wave).\r\n     * If false, update still runs but no new particles are spawned.\r\n     */\r\n    public emitting?: boolean;\r\n\r\n    /** Delta clamp to keep simulation stable on long frames. */\r\n    private maxDeltaSeconds: number;\r\n\r\n    /** Whether new particles should be added behind existing particles. */\r\n    public addAtBack?: boolean;\r\n\r\n    /** Ticker driving updates when not in manual mode. */\r\n    private ticker: Ticker;\r\n\r\n    /** Responsible for choosing textures and (optionally) updating animated textures. */\r\n    private textureProvider: TextureProvider;\r\n\r\n    /** Inactive particle pool (reused). */\r\n    private readonly pool: PxParticle[] = [];\r\n\r\n    /** Active particles currently simulated and rendered. */\r\n    private readonly active: PxParticle[] = [];\r\n\r\n    /**\r\n     * Sorted behaviours (priority + stable insertion order).\r\n     * Behaviours are applied in order every frame.\r\n     */\r\n    private behaviours: SortedBehaviour[] = [];\r\n    private nextBehaviourOrder = 0;\r\n\r\n    /** Accumulator used to compute spawn counts in rate mode. */\r\n    private emitAcc = 0;\r\n\r\n    /** Accumulator used to track time between waves in wave mode. */\r\n    private waveAcc = 0;\r\n\r\n    private updateEmitterBound?: (ticker: Ticker) => void;\r\n    private tickerAttached = false;\r\n\r\n    constructor(options: EmitterOptions, textureProvider: TextureProvider) {\r\n        super({\r\n            label: \"Emitter\",\r\n            ...options.containerOptions,\r\n\r\n            /**\r\n             * Important optimization:\r\n             * We enable only the dynamic properties that are actually needed\r\n             * (based on behaviours + texture provider requirements).\r\n             */\r\n            dynamicProperties: Emitter.computeDynamicProperties(options.behaviours ?? [], textureProvider),\r\n        });\r\n\r\n        this.maxParticles = options.maxParticles;\r\n        this.mode = options.mode;\r\n        this.ratePerSecond = options.ratePerSecond;\r\n        this.waveInterval = options.waveInterval;\r\n        this.particlesPerWave = options.particlesPerWave;\r\n        this.lifetime = options.lifetime;\r\n        this.emitting = options.emitting;\r\n        this.maxDeltaSeconds = options.maxDeltaSeconds ?? 0.1;\r\n        this.addAtBack = options.addAtBack;\r\n\r\n        this.textureProvider = textureProvider;\r\n\r\n        // Register behaviours (sorted by priority + stable order).\r\n        if (options.behaviours) {\r\n            for (const behaviour of options.behaviours) {\r\n                this.addBehaviour(behaviour);\r\n            }\r\n        }\r\n\r\n        /**\r\n         * Pre-allocate particles upfront:\r\n         * - avoids runtime allocations / GC spikes\r\n         * - allows \"maxParticles\" to be a hard cap\r\n         *\r\n         * Each pooled particle gets an initial texture (required by Pixi Particle).\r\n         * The actual texture may be replaced on spawn by the provider.\r\n         */\r\n        for (let i = 0; i < this.maxParticles; i++) {\r\n            const p = new PxParticle({ texture: this.textureProvider.initialTexture() });\r\n            this.pool.push(p);\r\n        }\r\n\r\n        /**\r\n         * In manual mode we do NOT attach to a ticker.\r\n         * User code calls emitBurst/emitWave and also needs to call updateEmitter manually\r\n         * (or you can provide a separate public update method if you prefer).\r\n         *\r\n         * NOTE: currently updateEmitter is still public and can be called manually.\r\n         */\r\n        this.ticker = options.ticker ?? Ticker.shared;\r\n        if (this.mode !== \"manual\") {\r\n            this.attachTicker();\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Adds a behaviour and inserts it into the sorted execution order.\r\n     * Priority controls order; ties are resolved by insertion order.\r\n     */\r\n    private addBehaviour(b: Behaviour): this {\r\n        this.behaviours.push({\r\n            b,\r\n            order: this.nextBehaviourOrder++,\r\n            prio: b.priority ?? 0,\r\n        });\r\n\r\n        // lower priority runs earlier\r\n        this.behaviours.sort((a, c) => a.prio - c.prio || a.order - c.order);\r\n\r\n        // Optional init hook for behaviour to cache references or precompute curves.\r\n        b.init?.(this);\r\n        return this;\r\n    }\r\n\r\n    /**\r\n     * Ticker callback: advances simulation and handles emission.\r\n     *\r\n     * The emitter uses ticker.deltaMS (milliseconds between frames) converted to seconds.\r\n     * We clamp dt to maxDeltaSeconds to avoid large jumps and excessive spawning.\r\n     */\r\n    public updateEmitter(ticker: Ticker): void {\r\n        const maxDt = this.maxDeltaSeconds;\r\n        let dt = ticker.deltaMS / 1000;\r\n\r\n        // Clamp dt for stability (e.g. tab in background).\r\n        if (dt > maxDt) dt = maxDt;\r\n        if (dt <= 0) return;\r\n\r\n        // Spawn new particles if enabled.\r\n        if (this.emitting) this.emitParticles(dt);\r\n\r\n        /**\r\n         * Update particles & kill dead ones.\r\n         * Iterate backwards so we can remove by index safely.\r\n         */\r\n        for (let i = this.active.length - 1; i >= 0; i--) {\r\n            const p = this.active[i];\r\n\r\n            // Texture provider may animate / swap textures per frame.\r\n            this.textureProvider.update?.(p, dt);\r\n\r\n            // Base integrator: apply velocity and angular velocity.\r\n            // Behaviours can also modify velocity, position, rotation, etc.\r\n            p.age += dt;\r\n            p.x += p.vx * dt;\r\n            p.y += p.vy * dt;\r\n            p.rotation += p.angleV * dt;\r\n\r\n            // Apply behaviours in sorted order.\r\n            for (const entry of this.behaviours) entry.b.update?.(p, dt, this);\r\n\r\n            // Kill particle if it exceeded its lifetime.\r\n            if (p.age >= p.life) {\r\n                this.killAtIndex(i);\r\n            }\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Emits particles according to the emitter's mode.\r\n     * This method is called automatically each tick when emitting=true.\r\n     */\r\n    private emitParticles(dt: number): void {\r\n        if (this.mode === \"rate\") {\r\n            const rate = this.ratePerSecond ?? 0;\r\n            if (rate <= 0) return;\r\n\r\n            /**\r\n             * Accumulate fractional time and convert into \"how many particles should we emit\".\r\n             * This produces stable emission even with variable frame rates.\r\n             */\r\n            this.emitAcc += dt;\r\n            const want = Math.floor(this.emitAcc * rate);\r\n            if (want <= 0) return;\r\n\r\n            // Keep the remainder time after spawning `want` particles.\r\n            this.emitAcc -= want / rate;\r\n\r\n            for (let i = 0; i < want; i++) this.spawnOne();\r\n            return;\r\n        }\r\n\r\n        if (this.mode === \"wave\") {\r\n            const interval = this.waveInterval ?? 0.25;\r\n            const perWave = this.particlesPerWave ?? 1;\r\n            if (interval <= 0 || perWave <= 0) return;\r\n\r\n            // Emit full waves when the accumulated time crosses the interval.\r\n            this.waveAcc += dt;\r\n            while (this.waveAcc >= interval) {\r\n                this.waveAcc -= interval;\r\n                for (let i = 0; i < perWave; i++) this.spawnOne();\r\n            }\r\n            return;\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Spawns a single particle from the pool.\r\n     *\r\n     * IMPORTANT:\r\n     * - If the pool is empty, spawning is skipped (hard cap).\r\n     * - Texture is selected by TextureProvider at spawn time.\r\n     * - Behaviours' onSpawn hooks initialize per-particle state.\r\n     */\r\n    private spawnOne(): void {\r\n        const p = this.pool.pop();\r\n        if (!p) return;\r\n\r\n        if (this.textureProvider.textureForSpawn) p.texture = this.textureProvider.textureForSpawn(p);\r\n\r\n        p.onSpawn();\r\n\r\n        // Allow behaviours to initialize the particle for this spawn.\r\n        for (const behaviour of this.behaviours) behaviour.b.onSpawn?.(p, this);\r\n\r\n        // Add particle to the container (front or back).\r\n        if (this.addAtBack) {\r\n            this.addParticleAt(p, 0);\r\n        } else {\r\n            this.addParticle(p);\r\n        }\r\n\r\n        // Randomize lifetime in [min, max].\r\n        const { min, max } = this.lifetime;\r\n        p.life = min + Math.random() * Math.max(0, max - min);\r\n\r\n        this.active.push(p);\r\n    }\r\n\r\n    /**\r\n     * Kills and recycles a particle at a given index in the active list.\r\n     *\r\n     * Order of operations:\r\n     * 1) behaviour kill hooks (reverse order, mirroring teardown)\r\n     * 2) provider kill hook\r\n     * 3) reset particle instance\r\n     * 4) remove from container + active list\r\n     * 5) return to pool\r\n     */\r\n    private killAtIndex(activeIndex: number): void {\r\n        const p = this.active[activeIndex];\r\n\r\n        // Call behaviours' teardown in reverse to match common init/apply ordering expectations.\r\n        for (let i = this.behaviours.length - 1; i >= 0; i--) {\r\n            this.behaviours[i].b.onKill?.(p, this);\r\n        }\r\n\r\n        this.textureProvider.onKill?.(p);\r\n\r\n        p.onKill();\r\n\r\n        this.removeParticle(p);\r\n\r\n        /**\r\n         * Remove from active list using \"swap remove\":\r\n         * - O(1)\r\n         * - does not preserve ordering (fine for particle sims)\r\n         */\r\n        const last = this.active.length - 1;\r\n        if (activeIndex !== last) this.active[activeIndex] = this.active[last];\r\n        this.active.pop();\r\n\r\n        this.pool.push(p);\r\n    }\r\n\r\n    /**\r\n     * Immediately kills all active particles and resets emission accumulators.\r\n     * Useful when restarting an effect or changing scenes.\r\n     */\r\n    public clearParticles(): void {\r\n        this.emitAcc = 0;\r\n        this.waveAcc = 0;\r\n\r\n        while (this.active.length > 0) {\r\n            this.killAtIndex(this.active.length - 1);\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Manual emission helpers.\r\n     * Only relevant if mode === \"manual\" or emitting === false.\r\n     */\r\n    public emitBurst(count: number): void {\r\n        for (let i = 0; i < count; i++) this.spawnOne();\r\n    }\r\n\r\n    public emitWave(): void {\r\n        const n = this.particlesPerWave ?? 0;\r\n        for (let i = 0; i < n; i++) this.spawnOne();\r\n    }\r\n\r\n    /**\r\n     * Computes ParticleContainer dynamicProperties from:\r\n     * - TextureProvider.requires\r\n     * - each Behaviour.requires\r\n     *\r\n     * Keeping these minimal is important for performance:\r\n     * enabling extra dynamic properties can increase per-frame GPU uploads.\r\n     */\r\n    private static computeDynamicProperties(behaviours: Behaviour[], provider: TextureProvider): DynamicProps {\r\n        const props: DynamicProps = {\r\n            position: false,\r\n            rotation: false,\r\n            vertex: false,\r\n            uvs: false,\r\n            color: false,\r\n        };\r\n\r\n        // Texture provider may require updates like uvs (animated textures) or vertex.\r\n        if (provider.requires) {\r\n            for (const key in provider.requires) {\r\n                props[key] = true;\r\n            }\r\n        }\r\n\r\n        // Behaviours declare which GPU-updated properties they touch over time.\r\n        for (const b of behaviours) {\r\n            if (!b.requires) continue;\r\n\r\n            for (const key in b.requires) {\r\n                props[key] = true;\r\n            }\r\n        }\r\n\r\n        return props;\r\n    }\r\n\r\n    /**\r\n     * Attaches the emitter update loop to the configured ticker.\r\n     */\r\n    private attachTicker(): void {\r\n        if (this.tickerAttached) return;\r\n        if (!this.updateEmitterBound) {\r\n            this.updateEmitterBound = this.updateEmitter.bind(this);\r\n        }\r\n\r\n        if (!this.ticker) {\r\n            this.ticker = Ticker.shared;\r\n        }\r\n\r\n        this.ticker.add(this.updateEmitterBound);\r\n        this.tickerAttached = true;\r\n    }\r\n\r\n    /**\r\n     * Detaches the emitter update loop from the ticker.\r\n     */\r\n    private detachTicker(): void {\r\n        if (!this.tickerAttached) return;\r\n        if (!this.ticker || !this.updateEmitterBound) return;\r\n        this.ticker.remove(this.updateEmitterBound);\r\n        this.tickerAttached = false;\r\n    }\r\n\r\n    /**\r\n     * Changes the emission mode at runtime.\r\n     *\r\n     * - Switching to \"manual\" detaches the ticker.\r\n     * - Switching to \"rate\" or \"wave\" attaches the ticker.\r\n     *\r\n     */\r\n    public setMode(mode: EmissionMode): void {\r\n        if (this.mode === mode) return;\r\n\r\n        const wasManual = this.mode === \"manual\";\r\n        const willBeManual = mode === \"manual\";\r\n\r\n        this.mode = mode;\r\n\r\n        if (!wasManual && willBeManual) {\r\n            this.detachTicker();\r\n        } else if (wasManual && !willBeManual) {\r\n            this.attachTicker();\r\n        }\r\n    }\r\n\r\n    public override destroy(options?: any): void {\r\n        this.detachTicker();\r\n        super.destroy(options);\r\n    }\r\n}\r\n"]}

package/dist/index.d.ts

@@ -0,0 +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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oDAAoD,CAAC;AACnE,cAAc,2DAA2D,CAAC;AAC1E,cAAc,yDAAyD,CAAC;AACxE,cAAc,sDAAsD,CAAC;AACrE,cAAc,yDAAyD,CAAC;AACxE,cAAc,0DAA0D,CAAC;AACzE,cAAc,uDAAuD,CAAC;AACtE,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+CAA+C,CAAC"}

package/dist/index.js

@@ -0,0 +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";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oDAAoD,CAAC;AACnE,cAAc,2DAA2D,CAAC;AAC1E,cAAc,yDAAyD,CAAC;AACxE,cAAc,sDAAsD,CAAC;AACrE,cAAc,yDAAyD,CAAC;AACxE,cAAc,0DAA0D,CAAC;AACzE,cAAc,uDAAuD,CAAC;AACtE,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+CAA+C,CAAC","sourcesContent":["export * from \"./behaviour\";\r\nexport * from \"./emitter\";\r\nexport * from \"./texture-provider\";\r\nexport * from \"./behaviours/alpha-behaviour\";\r\nexport * from \"./behaviours/alpha-curve-behaviour\";\r\nexport * from \"./behaviours/scale-curve-behaviour\";\r\nexport * from \"./behaviours/curved-behaviour/curve-key-frame\";\r\nexport * from \"./behaviours/curved-behaviour/curve-sampler\";\r\nexport * from \"./behaviours/movement-behaviours/gravity-behaviour\";\r\nexport * from \"./behaviours/movement-behaviours/movement-curve-behaviour\";\r\nexport * from \"./behaviours/movement-behaviours/radial-burst-behaviour\";\r\nexport * from \"./behaviours/spawn-behaviours/circle-spawn-behaviour\";\r\nexport * from \"./behaviours/spawn-behaviours/rectangle-spawn-behaviour\";\r\nexport * from \"./behaviours/static-behaviours/static-rotation-behaviour\";\r\nexport * from \"./behaviours/static-behaviours/static-scale-behaviour\";\r\nexport * from \"./texture-providers/animated-texture-provider\";\r\nexport * from \"./texture-providers/single-texture-provider\";\r\nexport * from \"./texture-providers/weighted-texture-provider\";\r\n"]}

package/dist/px-particle.d.ts

@@ -0,0 +1,61 @@
+import { Particle, ParticleOptions } from "pixi.js";
+/**
+ * Internal state used by AnimatedTextureProvider.
+ *
+ * `t` tracks elapsed time (seconds) inside the animation.
+ * This allows providers to compute frame index based on lifetime progression.
+ */
+export type AnimatedParticleState = {
+    t: number;
+};
+/**
+ * PxParticle extends PixiJS {@link Particle} with simulation state.
+ *
+ * Why this exists:
+ * - Pixi's Particle handles rendering efficiently.
+ * - We extend it to attach simulation data (velocity, lifetime, etc).
+ * - Instances are pooled and reused by the Emitter.
+ *
+ * IMPORTANT:
+ * Particles are never destroyed during runtime.
+ * They are recycled via onKill() and reused via onSpawn().
+ */
+export declare class PxParticle extends Particle {
+    /** Seconds since spawn. */
+    age: number;
+    /** Total lifetime in seconds (randomized per spawn by the emitter). */
+    life: number;
+    /** Velocity in pixels per second (X axis). */
+    vx: number;
+    /** Velocity in pixels per second (Y axis). */
+    vy: number;
+    /** Angular velocity in radians per second. */
+    angleV: number;
+    /**
+     * Optional provider-specific animation state.
+     * Used by AnimatedTextureProvider (if present).
+     */
+    animatedParticleState?: AnimatedParticleState;
+    constructor(options: ParticleOptions);
+    /**
+     * Resets the particle into pooled (inactive) state.
+     *
+     * Called when:
+     * - The particle exceeds its lifetime
+     * - The emitter clears particles
+     *
+     * This must leave the particle in a clean state so it can safely be reused.
+     */
+    onKill(): void;
+    /**
+     * Prepares the particle for active simulation.
+     *
+     * Called when:
+     * - The emitter spawns this particle from the pool
+     *
+     * Resets all visual and simulation state to defaults.
+     * Behaviours will then modify properties as needed.
+     */
+    onSpawn(): void;
+}
+//# sourceMappingURL=px-particle.d.ts.map

package/dist/px-particle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"px-particle.d.ts","sourceRoot":"","sources":["../src/px-particle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAChC,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACpC,2BAA2B;IACpB,GAAG,SAAK;IAEf,uEAAuE;IAChE,IAAI,SAAK;IAEhB,8CAA8C;IACvC,EAAE,SAAK;IAEd,8CAA8C;IACvC,EAAE,SAAK;IAEd,8CAA8C;IACvC,MAAM,SAAK;IAElB;;;OAGG;IACI,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;gBAEzC,OAAO,EAAE,eAAe;IAWpC;;;;;;;;OAQG;IACI,MAAM,IAAI,IAAI;IAWrB;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;CAqBzB"}

package/dist/px-particle.js

@@ -0,0 +1,76 @@
+import { Particle } from "pixi.js";
+/**
+ * PxParticle extends PixiJS {@link Particle} with simulation state.
+ *
+ * Why this exists:
+ * - Pixi's Particle handles rendering efficiently.
+ * - We extend it to attach simulation data (velocity, lifetime, etc).
+ * - Instances are pooled and reused by the Emitter.
+ *
+ * IMPORTANT:
+ * Particles are never destroyed during runtime.
+ * They are recycled via onKill() and reused via onSpawn().
+ */
+export class PxParticle extends Particle {
+    constructor(options) {
+        // Center anchor by default
+        options.anchorX = 0.5;
+        options.anchorY = 0.5;
+        super(options);
+        /** Seconds since spawn. */
+        this.age = 0;
+        /** Total lifetime in seconds (randomized per spawn by the emitter). */
+        this.life = 1;
+        /** Velocity in pixels per second (X axis). */
+        this.vx = 0;
+        /** Velocity in pixels per second (Y axis). */
+        this.vy = 0;
+        /** Angular velocity in radians per second. */
+        this.angleV = 0;
+        // Start in pooled/inactive state.
+        this.onKill();
+    }
+    /**
+     * Resets the particle into pooled (inactive) state.
+     *
+     * Called when:
+     * - The particle exceeds its lifetime
+     * - The emitter clears particles
+     *
+     * This must leave the particle in a clean state so it can safely be reused.
+     */
+    onKill() {
+        this.age = 0;
+        this.life = 1;
+        this.vx = 0;
+        this.vy = 0;
+        this.angleV = 0;
+        this.animatedParticleState = undefined;
+    }
+    /**
+     * Prepares the particle for active simulation.
+     *
+     * Called when:
+     * - The emitter spawns this particle from the pool
+     *
+     * Resets all visual and simulation state to defaults.
+     * Behaviours will then modify properties as needed.
+     */
+    onSpawn() {
+        this.age = 0;
+        this.life = 1;
+        this.vx = 0;
+        this.vy = 0;
+        this.angleV = 0;
+        this.animatedParticleState = undefined;
+        // Reset visual state
+        this.alpha = 1;
+        this.tint = 0xffffff;
+        this.rotation = 0;
+        this.scaleX = 1;
+        this.scaleY = 1;
+        this.x = 0;
+        this.y = 0;
+    }
+}
+//# sourceMappingURL=px-particle.js.map

package/dist/px-particle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"px-particle.js","sourceRoot":"","sources":["../src/px-particle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,MAAM,SAAS,CAAC;AAYpD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,UAAW,SAAQ,QAAQ;IAsBpC,YAAY,OAAwB;QAChC,2BAA2B;QAC3B,OAAO,CAAC,OAAO,GAAG,GAAG,CAAC;QACtB,OAAO,CAAC,OAAO,GAAG,GAAG,CAAC;QAEtB,KAAK,CAAC,OAAO,CAAC,CAAC;QA1BnB,2BAA2B;QACpB,QAAG,GAAG,CAAC,CAAC;QAEf,uEAAuE;QAChE,SAAI,GAAG,CAAC,CAAC;QAEhB,8CAA8C;QACvC,OAAE,GAAG,CAAC,CAAC;QAEd,8CAA8C;QACvC,OAAE,GAAG,CAAC,CAAC;QAEd,8CAA8C;QACvC,WAAM,GAAG,CAAC,CAAC;QAed,kCAAkC;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC;IAClB,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM;QACT,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACb,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAEd,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACZ,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACZ,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAEhB,IAAI,CAAC,qBAAqB,GAAG,SAAS,CAAC;IAC3C,CAAC;IAED;;;;;;;;OAQG;IACI,OAAO;QACV,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACb,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAEd,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACZ,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACZ,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAEhB,IAAI,CAAC,qBAAqB,GAAG,SAAS,CAAC;QAEvC,qBAAqB;QACrB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;QAErB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAEhB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACX,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;CACJ","sourcesContent":["import { Particle, ParticleOptions } from \"pixi.js\";\r\n\r\n/**\r\n * Internal state used by AnimatedTextureProvider.\r\n *\r\n * `t` tracks elapsed time (seconds) inside the animation.\r\n * This allows providers to compute frame index based on lifetime progression.\r\n */\r\nexport type AnimatedParticleState = {\r\n    t: number; // seconds progressed in animated texture (sprite sheet)\r\n};\r\n\r\n/**\r\n * PxParticle extends PixiJS {@link Particle} with simulation state.\r\n *\r\n * Why this exists:\r\n * - Pixi's Particle handles rendering efficiently.\r\n * - We extend it to attach simulation data (velocity, lifetime, etc).\r\n * - Instances are pooled and reused by the Emitter.\r\n *\r\n * IMPORTANT:\r\n * Particles are never destroyed during runtime.\r\n * They are recycled via onKill() and reused via onSpawn().\r\n */\r\nexport class PxParticle extends Particle {\r\n    /** Seconds since spawn. */\r\n    public age = 0;\r\n\r\n    /** Total lifetime in seconds (randomized per spawn by the emitter). */\r\n    public life = 1;\r\n\r\n    /** Velocity in pixels per second (X axis). */\r\n    public vx = 0;\r\n\r\n    /** Velocity in pixels per second (Y axis). */\r\n    public vy = 0;\r\n\r\n    /** Angular velocity in radians per second. */\r\n    public angleV = 0;\r\n\r\n    /**\r\n     * Optional provider-specific animation state.\r\n     * Used by AnimatedTextureProvider (if present).\r\n     */\r\n    public animatedParticleState?: AnimatedParticleState;\r\n\r\n    constructor(options: ParticleOptions) {\r\n        // Center anchor by default\r\n        options.anchorX = 0.5;\r\n        options.anchorY = 0.5;\r\n\r\n        super(options);\r\n\r\n        // Start in pooled/inactive state.\r\n        this.onKill();\r\n    }\r\n\r\n    /**\r\n     * Resets the particle into pooled (inactive) state.\r\n     *\r\n     * Called when:\r\n     * - The particle exceeds its lifetime\r\n     * - The emitter clears particles\r\n     *\r\n     * This must leave the particle in a clean state so it can safely be reused.\r\n     */\r\n    public onKill(): void {\r\n        this.age = 0;\r\n        this.life = 1;\r\n\r\n        this.vx = 0;\r\n        this.vy = 0;\r\n        this.angleV = 0;\r\n\r\n        this.animatedParticleState = undefined;\r\n    }\r\n\r\n    /**\r\n     * Prepares the particle for active simulation.\r\n     *\r\n     * Called when:\r\n     * - The emitter spawns this particle from the pool\r\n     *\r\n     * Resets all visual and simulation state to defaults.\r\n     * Behaviours will then modify properties as needed.\r\n     */\r\n    public onSpawn(): void {\r\n        this.age = 0;\r\n        this.life = 1;\r\n\r\n        this.vx = 0;\r\n        this.vy = 0;\r\n        this.angleV = 0;\r\n\r\n        this.animatedParticleState = undefined;\r\n\r\n        // Reset visual state\r\n        this.alpha = 1;\r\n        this.tint = 0xffffff;\r\n\r\n        this.rotation = 0;\r\n        this.scaleX = 1;\r\n        this.scaleY = 1;\r\n\r\n        this.x = 0;\r\n        this.y = 0;\r\n    }\r\n}\r\n"]}

package/dist/texture-provider.d.ts

@@ -0,0 +1,62 @@
+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;
+}
+//# sourceMappingURL=texture-provider.d.ts.map