@zappar/threejs-particle-system v0.0.1-beta.0

@zappar/threejs-particle-system

This is a powerful JavaScript library for creating and managing particle emitters in 3D space using the THREE library. It gives you fine-grained control over particle behaviour, distribution, and appearance. With options for various emitter types, color, opacity, size, angle and many other parameters, this library allows you to simulate complex particle systems such as fire, smoke, stars, or even abstract visual effects.

Key Features

• Emitter Types: Choose from 'BOX', 'SPHERE', 'DISC', or 'LINE' distributions to control the spawn position and force behaviour of the particles.
• Particle Count and Duration: Define the total number of particles an emitter holds and the duration for which the emitter lives. You can even specify emitters to run indefinitely.
• Velocity and Acceleration: Customise the base and variance of the velocity and acceleration of each particle.
• Drag and Wiggle: Apply drag to particles and make them wiggle over time. A great feature to simulate fire embers or create whimsical effects.
• Rotation: Static or dynamic rotation of particles around a defined axis of rotation, with optional randomisation on re-spawning.
• Color and Opacity: Define the color and opacity of a particle over its lifetime. - Both color and opacity support value-over-lifetime properties, meaning you can describe specific value changes over a particle's lifetime.
• Size and Angle: Adjust the size and angle of particles, both also support value-over-lifetime properties.
• Texture and Blending: Define the texture of particles. Apply blending modes to enhance the visual appearance of your particles.
• Billboarding: Choose between spherical, cylindrical or directional billboarding for your different emitter effects.

You may also be interested in:

• Zapapr for three.js (website, NPM)
• Zappar for A-Frame (website, NPM)
• Zappar for React+three.js (website, NPM)
• Zappar for Unity (website)
• Zappar for JavaScript (website, NPM), if you'd like to build content with a different 3D rendering platform
• ZapWorks Studio (website), a full 3D development environment built for AR, VR and MR

Getting Started

Starting Development

You can use this library by installing from NPM for use in a module project.

NPM Package

Run the following NPM command inside your project directory:

npm install --save @zappar/threejs-particle-system

Then import the library into your JavaScript or TypeScript files:

import * as ParticleSystem from "@zappar/threejs-particle-system";

Example Project

import * as THREE from 'three';
import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
import * as ParticleSystem from "@zappar/threejs-particles";
import './index.css'

// Define the URL for the rain particle texture
const rainParticle = new URL('./rain-particle.png', import.meta.url).href;

// Initialize scene, camera and clock
const clock = new THREE.Clock();
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.01, 1000);

// Initialize renderer and append it to the body
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Initialize camera controls
const controls = new OrbitControls(camera, renderer.domElement);

// Function to setup the EmitterGroup
const setupEmitterGroup = (billboard?: 'spherical' | 'cylindrical' | 'directional'): ParticleSystem.EmitterGroup => {
// Create a new EmitterGroup
const _emitterGroup = new ParticleSystem.EmitterGroup({
  billboard,
  maxParticleCount: 2000,
  texture: {value: new THREE.TextureLoader().load(rainParticle)}
});

// Define a new Emitter
const emitter = new ParticleSystem.Emitter({
  particleCount: 200,
  size: { value: 2.0 },
  velocity: {
    value: new THREE.Vector3(0, 0, 0),
    spread: new THREE.Vector3(0, 0, 0)
  },
  acceleration: {
    value: new THREE.Vector3(0, 0, 0),
  },
  position: {
    value: new THREE.Vector3(0, 0, 0),
    spread: new THREE.Vector3(10, 10, 10)
  },
});

// Add the emitter to the group and set its position and scale
_emitterGroup.addEmitter(emitter);
_emitterGroup.mesh.position.set(0, 0, 0);
_emitterGroup.mesh.scale.set(1, 1, 1);

// Return the EmitterGroup
return _emitterGroup;
}

// Initialize the EmitterGroup
const emitterGroup = setupEmitterGroup();

// Add the EmitterGroup to the scene
scene.add(emitterGroup.mesh);

// Set initial camera position
camera.position.z = 5;

// Define the animation loop
const animation = function () {
// Update emitter group, controls and render the scene
emitterGroup.tick(clock.getDelta());
controls.update();
renderer.render(scene, camera);
};

// Set the animation loop
renderer.setAnimationLoop(animation);

Particle Emitter settings

Particle Group settings

Links and Resources

• Website

• Forum