GameParticleSystem

GameParticleSystem is a Babylon.js TypeScript library that enhances the Solid Particle System (SPS) by adding functionality similar to the Sprite Particle System, including gradient-based control over many particle properties. This library focuses on composition rather than inheritance, making it easy to integrate and extend.

Features

• Gradient-based Properties: Add color, size, rotation, angular speed, velocity, drag, and other properties that change dynamically over the particle's lifetime.
• Particle Emission Control: Define emission rates, lifetimes, and total particle limits.
• Runtime Updates: Modify particle properties and gradients dynamically during runtime.
• Floating Origin Support: Maintain particle positions relative to a changing origin, useful for large worlds.
• Lifecycle Observables: Events for when the system completes all emissions (onDoneObservable).
• Custom Initialization: Set initial positions and directions for particles with user-defined functions.

Installation

Install the library using npm:

npm install game-particle-system

Usage

Here’s a basic example of how to use GameParticleSystem:

import { Engine, Scene, Vector3, Color4 } from "@babylonjs/core";
import { GameParticleSystem } from "game-particle-system";

// Create a Babylon.js scene
const canvas = document.getElementById("renderCanvas") as HTMLCanvasElement;
const engine = new Engine(canvas, true);
const scene = new Scene(engine);

// Create a GameParticleSystem
const particleSystem = new GameParticleSystem("particles", scene, 1, 1, 1000);

// Set initial particle properties
particleSystem.initialPositionFunction = (particle) => {
  particle.position = new Vector3(Math.random(), Math.random(), Math.random());
  return particle;
};
particleSystem.initialDirectionFunction = (particle) => {
  particle.direction = new Vector3(Math.random(), Math.random(), Math.random());
  return particle;
};

// Configure gradients
particleSystem.colorGradients = [
  { gradient: 0, color: new Color4(1, 0, 0, 1) },
  { gradient: 1, color: new Color4(0, 0, 1, 0) },
];
particleSystem.sizeGradients = [
  { gradient: 0, factor: 1 },
  { gradient: 1, factor: 0.5 },
];

// Start the particle system
particleSystem.emitRate = 100;
particleSystem.begin();

// Render loop
engine.runRenderLoop(() => {
  scene.render();
});

API Overview

Constructor

new GameParticleSystem(
  name: string,
  scene: Scene,
  type: number | ((system: SolidParticleSystem) => void) = 1,
  size: number = 1,
  count: number = 1000
);

• name: The name of the particle system.
• scene: The Babylon.js scene.
• type: The type of solid particles to create or a custom initialization function.
• size: The size of the particles.
• count: The number of particles in the system.

Properties

• emitRate: Number of particles emitted per second.
• emitCount: Total particles to emit before stopping.
• colorGradients: Gradients for particle colors.
• sizeGradients: Gradients for particle sizes.
• stopped: Whether emissions are stopped.
• done: Whether the system is done emitting and all particles are EOL (end of life).
• onDoneObservable: Triggered when the system completes all emissions.

Methods

• begin(): Starts the particle emission.
• updateSpeed: Adjusts the update frequency (default is 1/60).

Development

Clone the repository and install dependencies:

git clone https://github.com/abraini-Nascent/game-particle-system.git
cd game-particle-system
npm install

To build and test:

npm run build
npm test

License

This library is open-source and available under the MIT License.