t3d-particle

This is a particle system based on t3d.js. Inspired by ShaderParticleEngine. Added support for mesh particles.

Examples

Usage

Creating

Here is a simple example to create particles:

// Creating a particle group.
const particleGroup = new ParticleGroup({
    texture: {
        value: t3d.Texture2D.fromSrc('./resources/img/smokeparticle.png')
    },
    maxParticleCount: 2000
});

// Creating a particle emitter.
const particleEmitter = new ParticleEmitter({
    type: ParticleProperties.distributions.BOX,
    maxAge: {
        value: 2
    },
    position: {
        value: new t3d.Vector3(0, 0, -50),
        spread: new t3d.Vector3(0, 0, 0)
    },
    acceleration: {
        value: new t3d.Vector3(0, -10, 0),
        spread: new t3d.Vector3(10, 0, 10)
    },
    velocity: {
        value: new t3d.Vector3(0, 25, 0),
        spread: new t3d.Vector3(10, 7.5, 10)
    },
    color: {
        value: [new t3d.Color3(1, 1, 1), new t3d.Color3(1, 0, 0)]
    },
    size: {
        value: 1
    },
    particleCount: 1000
});

// To add an emitter to a group
particleGroup.addEmitter(particleEmitter);

// To render the group, add the particle group's mesh object to your scene:
scene.add(particleGroup.mesh);

You can also create mesh particles by:

const particleGroup = new MeshParticleGroup({/*...GroupOptions...*/});

const particleEmitter = new MeshParticleEmitter({/*...Emitter...*/});

// ...

A full options to configure an ParticleGroup:

texture(Object): describing the texture used by particle.

fixedTimeStep(Number): If no dt (or deltaTime) value is passed to this group's tick() function, this number will be used to move the particle simulation forward. Value in SECONDS. Default is 0.016s.

maxParticleCount(Number): Maximum number of particles.

hasPerspective(Number): Whether the distance a particle is from the camera should affect the particle's size. Default is true. Only for ParticleGroup.

colorize(Boolean): Whether the particles in this group should be rendered with color, or whether the only color of particles will come from the provided texture. Default is true. Only for ParticleGroup.

scale(Number): The scale factor to apply to this group's particle sizes. Useful for setting particle sizes to be relative to renderer size. Default is 300. Only for ParticleGroup.

geometry(Geometry): Useful for group's particles geometry information. Only for MeshParticleGroup.

A full options to configure an ParticleEmitter:

type(Number): The default distribution this emitter should use to control its particle's spawn position and force behaviour. Default is 1.1 will be distributed within a box. 2 will be distributed on a sphere. 3 will be distributed on a 2d-disc shape. 4 will be distributed along a line.

particleCount(Number): The total number of particles this emitter will hold. Default is 100.

duration(Number|null): The duration in seconds that this emitter should live for. If not specified, the emitter will emit particles indefinitely. Default is null.

isStatic(Boolean): Whether this emitter should be not be simulated (true). Default is false.

activeMultiplier(Object): A value between 0 and 1 describing what percentage of this emitter's particlesPerSecond should be emitted, where 0 is 0%, and 1 is 100%. Default is 1.

direction(Number): The direction of the emitter. If value is 1, emitter will start at beginning of particle's lifecycle.If value is -1, emitter will start at end of particle's lifecycle and work it's way backwards. Default is 1. Only for ParticleEmitter.

isLookAtCamera(Boolean): Whether particle is always facing the camera. Default is false. Only for MeshParticleEmitter.

isLookAtCameraOnlyY(Boolean): Whether particle locks the Y-axis. Default is false. Only for MeshParticleEmitter.

maxAge(Object): An object describing the particle's maximum age in seconds.
| | | | | --- | --- | :--: | | value(Number) | A number between 0 and 1 describing the amount of maxAge to apply to all particles. | Default is 2s | | spread(Number) | A number describing the maxAge variance on a per-particle basis. | Default is 0 |

position(Object): An object describing this emitter's position.
| | | | | --- | --- | :--: | | value(Vector3) | A t3d.Vector3 instance describing this emitter's base position. | Default is Vector3(0,0,0) | | spread(Vector3) | A t3d.Vector3 instance describing this emitter's position variance on a per-particle basis. | Default is Vector3(0,0,0) | | spreadClamp(Vector3) | A t3d.Vector3 instance describing the numeric multiples the particle's should be spread out over. | Default is Vector3(0,0,0) | | radius(Number) | This emitter's base radius. | Default is 10 | | radiusScale(Vector3) | A t3d.Vector3 instance describing the radius's scale in all three axes. Allows a SPHERE or DISC to be squashed or stretched. | Default is Vector3(0,0,0) | | distribution(Number or Function) | A specific distribution to use when radiusing particles. Overrides the type option. | Default is type option. | | randomise(Boolean) | When a particle is re-spawned, whether it's position should be re-randomised or not. Can incur a performance hit. | Default is false |

velocity(Object): An object describing this particle velocity.
| | | | | --- | --- | :--: | | value(Vector3) | A t3d.Vector3 instance describing this emitter's base velocity. | Default is Vector3(0,0,0) | | spread(Vector3) | A t3d.Vector3 instance describing this emitter's velocity variance on a per-particle basis.Note that when using a SPHERE or DISC distribution, only the x-component of this vector is used. | Default is Vector3(0,0,0) | | distribution(Number or Function) | A specific distribution to use when calculating a particle's velocity. Overrides the type option. | Default is type option. | | randomise(Boolean) | When a particle is re-spawned, whether it's velocity should be re-randomised or not. Can incur a performance hit. | Default is false |

acceleration(Object): An object describing this particle's acceleration.
| | | | | --- | --- | :--: | | value(Vector3) | A t3d.Vector3 instance describing this emitter's base acceleration. | Default is Vector3(0,0,0) | | spread(Vector3) | A t3d.Vector3 instance describing this emitter's acceleration variance on a per-particle basis. Note that when using a SPHERE or DISC distribution, only the x-component of this vector is used. | Default is Vector3(0,0,0) | | distribution(Number or Function) | A specific distribution to use when calculating a particle's acceleration. Overrides the type option. | Default is type option. | | randomise(Boolean) | When a particle is re-spawned, whether it's acceleration should be re-randomised or not. Can incur a performance hit. | Default is false |

drag(Object): An object describing this particle drag. Drag is applied only to velocity values.
| | | | | --- | --- | :--: | | value(Number) | A number between 0 and 1 describing the amount of drag to apply to all particles. | Default is 0 | | spread(Number) | A number describing the drag variance on a per-particle basis. | Default is 0 | | randomise(Boolean) | When a particle is re-spawned, whether it's drag should be re-randomised or not. Can incur a performance hit. | Default is false |

wiggle(Object): The values of this object will determine whether a particle will wiggle, or jiggle, or wave,...or shimmy, or waggle, or... Well you get the idea.
| | | | | --- | --- | :--: | | value(Number) | A number describing the amount of wiggle to apply to all particles. It's measured in distance. | Default is 0 | | spread(Number) | A number describing the wiggle variance on a per-particle basis. | Default is 0 |

rotation(Object): An object describing this emitter's rotation. It can either be static, or set to rotate from 0 radians to the value of rotation.value over a particle's lifetime. Rotation values affect both a particle's position and the forces applied to it.
| | | | | --- | --- | :--: | | axis(Number) | A t3d.Vector3 instance describing this emitter's axis of rotation. | Default is Vector3(0, 1, 0) | | axisSpread(Number) | A t3d.Vector3 instance describing the amount of variance to apply to the axis of rotation on a per-particle basis. | Default is Vector3() | | angle(Number) | The angle of rotation, given in radians. If rotation.static is true, the emitter will start off rotated at this angle, and stay as such. Otherwise, the particles will rotate from 0 radians to this value over their lifetimes. | Default is 0 | | axisSpread(Number) | The amount of variance in each particle's rotation angle. | Default is 0 | | static(Boolean) | Whether the rotation should be static or not. | Default is false | | center(Number) | A t3d.Vector3 instance describing the center point of rotation. | Default is The value of position.value | | randomise(Number) | When a particle is re-spawned, whether it's rotation should be re-randomised or not. Can incur a performance hit. | Default is false |

color(Object): An object describing a particle's color.
| | | | | --- | --- | :--: | | value(Color3 or Array) | Either a single t3d.Color3 instance, or an array of t3d.Color3 instances to describe the color of a particle over it's lifetime. | Default is Color3(0,0,0) | | spread(Vector3 or Array) | Either a single t3d.Vector3 instance, or an array of t3d.Vector3 instances to describe the color variance of a particle over it's lifetime. | Default is Vector3(0,0,0) | | randomise(Boolean) | When a particle is re-spawned, whether it's color should be re-randomised or not. Can incur a performance hit. | Default is false |

opacity(Object): An object describing a particle's opacity.
| | | | | --- | --- | :--: | | value(Number or Array) | Either a single number, or an array of numbers to describe the opacity of a particle over it's lifetime. | Default is 1 | | spread(Number or Array) | Either a single number, or an array of numbers to describe the opacity variance of a particle over it's lifetime. | Default is 0 | | randomise(Boolean) | When a particle is re-spawned, whether it's opacity should be re-randomised or not. Can incur a performance hit. | Default is false |

size(Object): An object describing a particle's size.
| | | | | --- | --- | :--: | | value(Number or Array) | Either a single number, or an array of numbers to describe the size of a particle over it's lifetime. | Default is 1 | | spread(Number or Array) | Either a single number, or an array of numbers to describe the size variance of a particle over it's lifetime. | Default is 0 | | randomise(Boolean) | When a particle is re-spawned, whether it's size should be re-randomised or not. Can incur a performance hit. | Default is false |

angle(Object): An object describing a particle's angle.
| | | | | --- | --- | :--: | | value(Number or Array) | Either a single number, or an array of numbers to describe the angle of a particle over it's lifetime. | Default is 1 | | spread(Number or Array) | Either a single number, or an array of numbers to describe the angle variance of a particle over it's lifetime. | Default is 0 | | randomise(Boolean) | When a particle is re-spawned, whether it's angle should be re-randomised or not. Can incur a performance hit. | Default is false |

Runtime Changing

// Trigger the setter for this property to force an
// update to the emitter's position attribute.
particleEmitter.position.value = particleEmitter.position.value.set(2, 2, 2);

particleEmitter.rotation.angle += 0.1;

// other properties...