custom-pixi-particles 5.2.0 → 8.0.0

package/README.md

@@ -1,126 +1,163 @@
 # CustomPIXIParticles by [@lukasz-okuniewicz](http://github.com/lukasz-okuniewicz)
 
-CustomPIXIParticles is a lightweight and flexible library for creating and managing particle effects in PIXI.js applications. It provides a simple API for defining particle emitters, textures, and configurations, allowing developers to create a wide range of visual effects with ease.
+**CustomPIXIParticles** is a lightweight, high-performance library designed for creating and managing customizable particle effects in **PIXI.js** applications. It offers an intuitive API, flexible configuration options, and seamless compatibility with modern PIXI.js versions, making it an essential tool for developers looking to create stunning visual effects.
 
-### Features
-* Easy-to-use API: Create particle emitters with just a few lines of code
-* Flexible configuration: Customize particle behavior, appearance, and animation
-* High performance: Render particles efficiently without impacting application performance
-* Compatible with PIXI.js v7: Works seamlessly with the latest version of PIXI.js
+---
 
-### Versions Compatibility
+### Support My Work
+If you find **CustomPIXIParticles** useful and would like to support my work, you can buy me a coffee. Your contributions help me dedicate more time to improving this library and creating new features for the community. Thank you for your support! ☕💖
 
-| PixiJS | CustomPIXIParticles |
-|---|---|
-| v5.x - v6.x | v4.x |
-| v7.x | v5.x |
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support%20My%20Work-orange?logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/lukasz.okuniewicz)
 
-### Demo 
-[custom-pixi-particles](http://particles.okuniewicz.eu/)
+---
 
-#### Installation:
+## ✨ Features
+- **Simple API**: Effortlessly create particle emitters with minimal code.
+- **Highly Configurable**: Adjust particle behavior, appearance, animation, and more.
+- **Performance Optimized**: Handle thousands of particles with minimal performance overhead.
+- **PIXI.js Compatibility**: Fully compatible with **PIXI.js v7**, with legacy support for v5.x and v6.x.
+- **Real-Time Customization**: Dynamically update textures, positions, configurations, and emitters on the fly.
 
-```
+---
+
+## 🎮 Demo
+Try it out here: [CustomPIXIParticles Live Editor](https://okuniewicz.eu/)
+
+---
+
+## 🛠️ Installation
+
+Install via npm:
+
+```bash
 npm install custom-pixi-particles
 ```
 
-#### Usage:
-Import or require the library:
+---
+
+## 🚀 Quick Start
+Import or Require
 ```javascript
-const customPixiParticles = require('custom-pixi-particles')
-// or
+// ES6 Modules
 import customPixiParticles from 'custom-pixi-particles'
+
+// CommonJS
+const customPixiParticles = require('custom-pixi-particles')
 ```
 
+Create Particle Effects
 ```javascript
-// Define array of textures
+// Define textures and emitter configuration
 const textures = ['texture1.png', 'texture2.png']
-// Define generated emiter config
-const emitterConfig = {...}
-// Create particles
-this.particles = customParticles.create({ textures, emitterConfig })
-// Start to play
-this.particles.play()
-// Add particles to PIXI container
-container.addChild(this.particles)
+const emitterConfig = {
+  // Your configuration object
+}
+
+// Initialize particle emitter
+const particles = customPixiParticles.create({ textures, emitterConfig })
+
+// Add emitter to the PIXI container
+container.addChild(particles)
+
+// Start the emitter
+particles.play()
 ```
 
-### API Reference
-`create`
+---
+
+## 📖 API Reference
+Initializes a particle emitter.
 ```javascript
-// All possible params which can be passed during particles creation
-this.particles = customPixiParticles.create({
-  textures: [String],
-  animatedSpriteZeroPad: Number,
-  animatedSpriteIndexToStart: Number,
-  emitterConfig: Object,
-  finishingTextures: [String],
-  vertices: Boolean,
-  position: Boolean,
-  rotation: Boolean,
-  uvs: Boolean,
-  tint: Boolean,
-  maxParticles: Number,
-  maxFPS: Number,
-  tickerSpeed: Number,
+const particles = customPixiParticles.create({
+  textures: [String],             // Array of particle textures
+  emitterConfig: Object,          // Configuration object for the emitter
+  animatedSpriteZeroPad: Number,  // Zero-padding for animated sprite names
+  animatedSpriteIndexToStart: Number, // Initial frame index for animated sprites
+  finishingTextures: [String],    // Textures used for particle finishing
+  vertices: Boolean,              // Use vertex mode for rendering
+  position: Boolean,              // Allow position-based behavior
+  rotation: Boolean,              // Allow rotation-based behavior
+  uvs: Boolean,                   // Apply UV mapping
+  tint: Boolean,                  // Apply tint to particles
+  maxParticles: Number,           // Maximum particles allowed
+  maxFPS: Number,                 // Cap emitter update frequency
+  tickerSpeed: Number,            // Speed of the PIXI ticker
 })
 ```
 
+### Event Callbacks
+Triggered when the particle animation completes.
 ```javascript
-// Callback function called when the particle animation completes.
-this.particles.onComplete = () => {
-  //...
+particles.onComplete = () => {
+  console.log("Particle animation finished!")
 }
 ```
 
+### Texture Management
+Updates the particle emitter's textures.
 ```javascript
-// Define array of new textures
-const newTextures = ['texture3.png', 'texture4.png']
-// Updates the particle emitter's textures.
-this.particles.setTextures(newTextures)
+particles.setTextures(['texture3.png', 'texture4.png'])
 ```
 
+### Configuration Updates
+Dynamically update emitter configurations.
 ```javascript
-// Updates the particle emitter's configuration.
-this.particles.updateConfig({
-  // Update emitter configuration properties
-})
+particles.updateConfig({ /* New configuration properties */ })
 ```
 
+### State Control
+Starts or resumes the emitter.
 ```javascript
-// Sets the paused state
-pause(isPaused)
-
-// Starts the emitter
-start()
+particles.play()
+```
+Toggles the paused state.
+```javascript
+particles.pause(isPaused)
+```
+Terminates the emitter and stops emission.
+```javascript
+particles.stop()
+```
+Halts all emissions immediately.
+```javascript
+particles.stopImmediately()
+```
+Resets the emitter to its initial state.
+```javascript
+particles.resetEmitter()
+```
 
-// Resets the particle emitters in this class without removing existing particles and plays them
-play()
+### Position Updates
+Dynamically adjust the emitter's position.
+```javascript
+particles.updatePosition({ x: 100, y: 200 })
+```
 
-// Immediately stops emitting particles
-stopImmediately()
+### Pool Management
+Clears internal object pools to free memory.
+```javascript
+particles.clearPool()
+```
 
-// Destroy particles
-destroy()
+---
 
-// Terminates the emitter
-stop()
+## 🖥️ Versions Compatibility
+| PixiJS      | CustomPIXIParticles |
+|-------------|---------------------|
+| v5.x - v6.x | v4.x                |
+| v7.x        | v7.x                |
 
-// Resets the emitters to their initial state
-resetEmitter()
+---
 
-// Update textures used by the emitter
-setTextures(textures)
+## 🛠️ Advanced Editor
+Easily design and fine-tune your particle effects with the CustomPIXIParticles Editor.
+🔗 [CustomPIXIParticles Live Editor](https://okuniewicz.eu/)
 
-// Updates the configuration of the emitter
-updateConfig(config, resetDuration = true)
+---
 
-// Updates the position of the emitter
-updatePosition(position, resetDuration = true)
+## 🤝 Contributing
+Contributions, feature suggestions, and bug reports are welcome! Open an issue or submit a pull request on the [GitHub repository](https://github.com/lukasz-okuniewicz/custom-pixi-particles).
 
-// Clear pools
-clearPool()
-```
+---
 
-### Additional Resources
-Editor for particles: [custom-pixi-particles-editor](https://github.com/lukasz-okuniewicz/custom-pixi-particles-editor)
+With CustomPIXIParticles, you're not just building animations; you're crafting immersive experiences! 🌟

package/package.json

@@ -8,13 +8,13 @@
     "@types/file-saver": "^2.0.7",
     "copy-dir": "^1.3.0",
     "file-saver": "^2.0.5",
-    "pixi.js": "^7.3.2",
-    "prettier": "^3.1.0",
+    "pixi.js": "^8.6.4",
     "gsap": "^3.12.5",
-    "rimraf": "^5.0.5",
+    "prettier": "^3.4.2",
+    "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "tslint": "^6.1.3",
-    "typescript": "^5.3.3"
+    "typescript": "^5.7.2"
   },
   "dependencies": {
     "eventemitter3": "^4.0.7"
@@ -41,5 +41,5 @@
     "lint": "tslint 'src/**/*.ts'",
     "lint:fix": "tslint --fix 'src/**/*.ts'"
   },
-  "version": "5.2.0"
+  "version": "8.0.0"
 }

package/dist/index.d.ts

@@ -1,11 +0,0 @@
-import Renderer from './lib/pixi/Renderer';
-import { ICustomPixiParticlesSettings } from './lib/customPixiParticlesSettingsInterface';
-/**
- * Constructs a renderer for custom pixi particles
- * @class Renderer
- * @param {ICustomPixiParticlesSettings} settings The settings for the renderer
- */
-declare const customPixiParticles: {
-    create(settings: ICustomPixiParticlesSettings): Renderer;
-};
-export { Renderer, customPixiParticles, ICustomPixiParticlesSettings };

package/dist/index.js

@@ -1,28 +0,0 @@
-import Renderer from './lib/pixi/Renderer';
-/**
- * Constructs a renderer for custom pixi particles
- * @class Renderer
- * @param {ICustomPixiParticlesSettings} settings The settings for the renderer
- */
-const customPixiParticles = {
-    create(settings) {
-        const { textures, emitterConfig, animatedSpriteZeroPad = 2, animatedSpriteIndexToStart = 0, finishingTextures = [], vertices = true, position = true, rotation = true, uvs = true, tint = true, maxParticles = 10000, maxFPS = 60, tickerSpeed = 0.02, } = settings;
-        return new Renderer({
-            textures,
-            animatedSpriteZeroPad,
-            animatedSpriteIndexToStart,
-            emitterConfig,
-            finishingTextures,
-            vertices,
-            position,
-            rotation,
-            uvs,
-            tint,
-            maxParticles,
-            maxFPS,
-            tickerSpeed,
-        });
-    },
-};
-export { Renderer, customPixiParticles };
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,qBAAqB,CAAA;AAG1C;;;;GAIG;AACH,MAAM,mBAAmB,GAAG;IAC1B,MAAM,CAAC,QAAsC;QAC3C,MAAM,EACJ,QAAQ,EACR,aAAa,EACb,qBAAqB,GAAG,CAAC,EACzB,0BAA0B,GAAG,CAAC,EAC9B,iBAAiB,GAAG,EAAE,EACtB,QAAQ,GAAG,IAAI,EACf,QAAQ,GAAG,IAAI,EACf,QAAQ,GAAG,IAAI,EACf,GAAG,GAAG,IAAI,EACV,IAAI,GAAG,IAAI,EACX,YAAY,GAAG,KAAK,EACpB,MAAM,GAAG,EAAE,EACX,WAAW,GAAG,IAAI,GACnB,GAAG,QAAQ,CAAA;QACZ,OAAO,IAAI,QAAQ,CAAC;YAClB,QAAQ;YACR,qBAAqB;YACrB,0BAA0B;YAC1B,aAAa;YACb,iBAAiB;YACjB,QAAQ;YACR,QAAQ;YACR,QAAQ;YACR,GAAG;YACH,IAAI;YACJ,YAAY;YACZ,MAAM;YACN,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;CACF,CAAA;AAED,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAgC,CAAA"}

package/dist/lib/Model.d.ts

@@ -1,32 +0,0 @@
-export default class Model {
-    /**
-     * Boolean value indicating whether warping is enabled
-     */
-    warp: boolean;
-    /**
-     * The Z position of the camera
-     */
-    cameraZ: number;
-    /**
-     * The conversion rate for cameraZ
-     */
-    cameraZConverter: number;
-    /**
-     * The speed of warp
-     */
-    warpSpeed: number;
-    /**
-     * The base speed of warp
-     */
-    warpBaseSpeed: number;
-    /**
-     * Update the model with the behaviour object
-     * @param {Object} behaviour - The behaviour object
-     */
-    update(behaviour: any): void;
-    /**
-     * Update the camera position based on the delta time
-     * @param {number} deltaTime - The delta time
-     */
-    updateCamera(deltaTime: number): void;
-}

package/dist/lib/Model.js

@@ -1,44 +0,0 @@
-export default class Model {
-    constructor() {
-        /**
-         * Boolean value indicating whether warping is enabled
-         */
-        this.warp = false;
-        /**
-         * The Z position of the camera
-         */
-        this.cameraZ = 0;
-        /**
-         * The conversion rate for cameraZ
-         */
-        this.cameraZConverter = 0;
-        /**
-         * The speed of warp
-         */
-        this.warpSpeed = 0;
-        /**
-         * The base speed of warp
-         */
-        this.warpBaseSpeed = 0;
-    }
-    /**
-     * Update the model with the behaviour object
-     * @param {Object} behaviour - The behaviour object
-     */
-    update(behaviour) {
-        this.warp = behaviour.warp || false;
-        this.cameraZConverter = behaviour.cameraZConverter;
-        this.warpSpeed = behaviour.warpSpeed;
-        this.warpBaseSpeed = behaviour.warpBaseSpeed;
-    }
-    /**
-     * Update the camera position based on the delta time
-     * @param {number} deltaTime - The delta time
-     */
-    updateCamera(deltaTime) {
-        if (!this.warp)
-            return;
-        this.cameraZ += deltaTime * this.cameraZConverter * this.warpSpeed * this.warpBaseSpeed;
-    }
-}
-//# sourceMappingURL=Model.js.map

package/dist/lib/Model.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Model.js","sourceRoot":"","sources":["../../src/lib/Model.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAO,KAAK;IAA1B;QACE;;WAEG;QACH,SAAI,GAAY,KAAK,CAAA;QAErB;;WAEG;QACH,YAAO,GAAW,CAAC,CAAA;QAEnB;;WAEG;QACH,qBAAgB,GAAW,CAAC,CAAA;QAE5B;;WAEG;QACH,cAAS,GAAW,CAAC,CAAA;QAErB;;WAEG;QACH,kBAAa,GAAW,CAAC,CAAA;IAqB3B,CAAC;IAnBC;;;OAGG;IACH,MAAM,CAAC,SAAc;QACnB,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,IAAI,KAAK,CAAA;QACnC,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC,gBAAgB,CAAA;QAClD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC,SAAS,CAAA;QACpC,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC,aAAa,CAAA;IAC9C,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,SAAiB;QAC5B,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAM;QACtB,IAAI,CAAC,OAAO,IAAI,SAAS,GAAG,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa,CAAA;IACzF,CAAC;CACF"}

package/dist/lib/Particle.d.ts

@@ -1,220 +0,0 @@
-import { Sprite } from 'pixi.js-legacy';
-import { Color, Point } from './util';
-import ThereBack from './util/ThereBack';
-/**
- * Represents a particle object used in particle system simulations
- */
-export default class Particle {
-    static _UID: {
-        value: number;
-    };
-    next: Particle | null;
-    prev: Particle | null;
-    /**
-     * Stores the unique ID of the particle
-     */
-    uid: number;
-    /**
-     * Stores the movement of the particle
-     */
-    movement: Point;
-    /**
-     * Stores the acceleration of the particle
-     */
-    acceleration: Point;
-    /**
-     * Stores the velocity of the particle
-     */
-    velocity: Point;
-    /**
-     * Stores the size of the particle
-     */
-    size: Point;
-    /**
-     * Stores the starting size of the particle
-     */
-    sizeStart: Point;
-    /**
-     * Stores the starting warp size of the particle
-     */
-    warpSizeStart: Point;
-    /**
-     * Stores the ending size of the particle
-     */
-    sizeEnd: Point;
-    /**
-     * Stores the x value of the particle for sin wave
-     */
-    sinXVal: Point;
-    /**
-     * Stores the y value of the particle for sin wave
-     */
-    sinYVal: Point;
-    /**
-     * Stores the color of the particle
-     */
-    color: Color;
-    /**
-     * Stores the starting color of the particle
-     */
-    colorStart: Color;
-    /**
-     * Stores the ending color of the particle
-     */
-    colorEnd: Color;
-    /**
-     * Stores the maximum life time of the particle
-     */
-    maxLifeTime: number;
-    /**
-     * Stores the current life time of the particle
-     */
-    lifeTime: number;
-    /**
-     * Stores the current life progress of the particle
-     */
-    lifeProgress: number;
-    /**
-     * Stores the x position of the particle
-     */
-    x: number;
-    /**
-     * Stores the y position of the particle
-     */
-    y: number;
-    /**
-     * Stores the z position of the particle
-     */
-    z: number;
-    /**
-     * Stores the velocity angle of the particle
-     */
-    velocityAngle: number;
-    /**
-     * Stores the radians per second of the particle
-     */
-    radiansPerSecond: number;
-    /**
-     * Stores the radius of the particle
-     */
-    radius: number;
-    radiusX: number;
-    radiusY: number;
-    /**
-     * Stores the starting radius of the particle
-     */
-    radiusStart: number;
-    /**
-     * Stores the ending radius of the particle
-     */
-    radiusEnd: number;
-    /**
-     * Stores the cosine of the direction of the particle
-     */
-    directionCos: number;
-    /**
-     * Stores the sine of the direction of the particle
-     */
-    directionSin: number;
-    /**
-     * Stores the rotation of the particle
-     */
-    rotation: number;
-    /**
-     * Stores the rotation delta of the particle
-     */
-    rotationDelta: number;
-    /**
-     * Stores the angle of the particle
-     */
-    angle: number;
-    /**
-     * Stores the sprite of the particle
-     */
-    sprite: Sprite;
-    /**
-     * Stores whether the vortices are shown
-     */
-    showVortices: boolean;
-    /**
-     * Stores whether the turbulence is enabled
-     */
-    turbulence: boolean;
-    /**
-     * Stores the finishing texture of the particle
-     */
-    finishingTexture: number;
-    /**
-     * Stores the camera z position of the particle
-     */
-    cameraZ: number;
-    /**
-     * Stores the camera z position converter of the particle
-     */
-    cameraZConverter: number;
-    /**
-     * Stores the warp speed of the particle
-     */
-    warpSpeed: number;
-    /**
-     * Stores the warp base speed of the particle
-     */
-    warpBaseSpeed: number;
-    /**
-     * Stores the warp field of view of the particle
-     */
-    warpFov: number;
-    /**
-     * Stores the warp stretch of the particle
-     */
-    warpStretch: number;
-    /**
-     * Stores the warp distance scale converter of the particle
-     */
-    warpDistanceScaleConverter: number;
-    sizeDifference: {
-        x: number;
-        y: number;
-    };
-    fromAtoB: boolean;
-    fromAtoBTwoWays: boolean;
-    pointA: Point;
-    pointB: Point;
-    there: ThereBack;
-    back: ThereBack;
-    xStart: number;
-    yStart: number;
-    xTarget: number;
-    yTarget: number;
-    thereDuration: number;
-    backDuration: number;
-    progress: number;
-    time: number;
-    thereAmplitude: number;
-    backAmplitude: number;
-    direction: number;
-    /**
-     * Constructs a particle object
-     */
-    constructor();
-    /**
-     * Resets the particle object
-     */
-    reset(): void;
-    /**
-     * Checks if the particle is almost dead
-     *
-     * @return {boolean} True if the particle is almost dead, otherwise false
-     */
-    isAlmostDead(): boolean;
-    /**
-     * Checks if the particle is dead
-     *
-     * @return {boolean} True if the particle is dead, otherwise false
-     */
-    isDead(): boolean;
-    /**
-     * Hides the particle
-     */
-    hide(): void;
-}