3D Particles

What it does

An emitter is an object in your world. It lives in a scene, can follow another object at an offset and sorts with everything else. Its live particles draw as quads through the same renderer as your meshes, one instanced draw for the whole emitter, so there is no second pipeline to set up, and they are sorted by distance from the camera across emitters, so smoke does not draw over the flame it rises from.

A particle can face the camera, stay upright like a flame, lie flat like a shockwave ring or stretch along its velocity like a spark. By default particles take the scene's lights, so a puff of smoke catches a lantern, and soft particles fade a large quad as it nears the geometry behind it, so smoke meets the floor without a hard line.

Every value that can vary is an op, the same vocabulary particles-2d uses: a constant, a random range, a pick, a curve over the particle's life, keyframes or a callback. Particles are born in real 3D shapes or on a model's own surface, sampled by area so a model's tiny faces do not get as many sparks as its flank, and they are pushed by forces written as data. Effects, several emitters together, are data too: registered by the vfx3d-* packs or by your game, then placed, aimed, scaled or attached to an object with one call.

Features

• Emitters as world objects — position, layer, follow with an offset, world or local space, and a yaw, pitch and roll that turn the emit zone and the launch direction.
• Four facings — camera, upright, velocity with a stretch, and flat, with normal or additive blending.
• Lit and soft — particles take the scene's lights unless lit: false, and fade softly into surfaces behind.
• Ops for every value — constants, ranges, random picks, curves with easing, keyframes and callbacks, as in 2D.
• 3D emit zones — point, sphere, box, disc, cylinder, cone, ring, line, path and rect, filled by volume, surface or edge, with launch along the outward normal or in order round a path.
• Mesh surfaces — game.particles3d.surface builds an area-weighted sampler once, and it survives the object moving, turning and scaling.
• Cone launch — a direction and a spread fill a cone evenly, from a jet to every way at once.
• Forces as data — acceleration, drag, gusting wind, attract, vortex, orbit, curl noise and turbulence, plus sway for drifting snow and twinkle, at its own twinkleFreq, for fireflies.
• Rate over distance — a moving emitter lays particles evenly along its path whatever the frame rate, and lays none across a teleport or a move made with jump().
• Bursts, death zones and sub-effects — timed bursts with a probability, zones that kill inside or outside, killBelowY, and effects spawned on a particle's birth or death.
• Effects by name — game.particles3d.effect places, scales, aims or attaches a registered effect, and registerVfx3d adds your own.

Good for

• 3D action and shooter games — muzzle flashes, sparks from a hit that die at the floor, blasts and debris.
• Driving games — exhaust aimed backwards from a car, and dust laid behind each wheel by the distance it rolls.
• Weather round the player — rain, snow, leaves and ash from vfx3d-weather that follow the player.
• Fantasy and RPG worlds — campfires and torches, spells that orbit or swirl, motes shed from a statue's surface.
• Atmosphere in a scene — steam from a kettle, mist, and embers or fireflies that twinkle.

Make it yours

Every emitter is an Emitter3dConfig, and every varying value in it can change over life or at random, so the same pack makes a lazy smoke column and a violent blast. Effects take a position, a follow and offset, a scale that sizes every speed, distance, zone and force together so the motion keeps its shape, a yaw, pitch and roll, a layer and a timeScale. An emitter handle has live rate, emitting, timeScale and lit, so a fire can be damped in play. You register your own effects with registerVfx3d, under names of their own, beside the ready-made ones. The one pack option, maxEmitters, caps only the sub-effects particles spawn.

Two very different uses: a kept spark emitter with no rate, moved to each hit and fired with burst(40), its additive sparks stretched along their flight and killed at the floor; and a statue that sheds motes from its own surface, launched along the surface normals and lit by the lamps around it.

A quick look

A kept emitter of sparks, moved to each hit and fired as a burst, and a ready-made campfire placed and scaled:

const sparks = game.particles3d.emitter({
    x: 0, y: 1, z: 0, rate: 0, max: 200,
    frame: 'particle:spark', blend: 'add', facing: 'velocity', stretch: 0.04, lit: false,
    lifespan: [0.3, 0.7], speed: [4, 9], angle: [0, 360], elevation: [20, 70],
    gravityY: -9.8, killBelowY: 0, size: 0.12, alpha: { start: 1, end: 0 }, color: ['#fff3c0', '#ff8a2a'],
});
sparks.emitter.moveTo(hit.x, hit.y, hit.z);
sparks.emitter.burst(40);
const fire = game.particles3d.effect('campfire', { x: 4, y: 0, z: -2, scale: 1.5 });

Works with

• render-3d — required; the particles draw through the renderer that is already there.
• particle-textures and color — required; the particle pictures the effects draw with, and the colour ramps.
• vfx3d-fire, vfx3d-smoke, vfx3d-explosion, vfx3d-magic, vfx3d-weather, vfx3d-lightning — ready-made effects by name.
• core-3d — includes this pack, so most 3D games have it already.
• particles-gpu-3d — for standing fields of tens of thousands to a million, simulated on the GPU.
• trails-3d for ribbons behind moving things, and wisps-3d for a standing smoke column without particles.
• particles-2d — the same op vocabulary for 2D games.

Good to know

• It simulates on the CPU, the right trade at a few thousand particles an emitter; particles-gpu-3d reaches hundreds of thousands.
• Particles are quads and cast no shadows: ribbons are trails-3d and beams of light beams-3d.
• Sorting is by each particle's centre, so two large quads that cross can still order oddly.
• An emitter's rotation turns its zone, its launch and a flat quad's plane only; gravity, force positions and death zones stay in world axes.
• A mesh emit zone samples the geometry it is given, so an animated or skinned model sheds particles from its bind pose.