Particle System

The engine's flagship subsystem — 100M+ GPU particles with full physics, thermal simulation, chemistry, SPH fluids, SDF collision, flocking, and volumetric rendering. Everything runs on compute shaders via vGPU.

Architecture Overview

The particle system has three distinct layers:

┌─────────────────────────────────────────────┐
│  Editor / Game API                           │
│  EditorParticles.js — orchestrates per-frame │
├─────────────────────────────────────────────┤
│  Rendering Layer (engine/render/particles/)  │
│  SDF Billboard · Half-Res Composite · Beams  │
│  Bonds · Decals · Distortion · Mesh · Trail  │
├─────────────────────────────────────────────┤
│  Simulation Layer (engine/sim/particles/)    │
│  ParticleSimWorld — main compute shader      │
│  + 30 advanced subsystems (GPU compute)      │
├─────────────────────────────────────────────┤
│  Emitter System (ParticleEmitterSystem.js)   │
│  Presets, spawn shapes, rate control          │
└─────────────────────────────────────────────┘

Per-Frame Pipeline

Each frame in EditorParticles.js:

1. Emit — Spawn new particles from active emitters into GPU buffers
2. Alive-list compaction — GPU scan writes alive particle indices (skip dead slots)
3. Main sim — GPU compute: gravity, curl noise, forces, integration, lifetime
4. Advanced systems — Thermal, SPH, flocking, bonds, chemistry, constraints
5. Sort — Radix sort by camera distance for correct alpha blending
6. Collisions — SDF collision against entity meshes + ground plane
7. Light extraction — GPU compute finds hottest particles → async readback → LightManager
8. Render — SDF billboard at half-res → additive composite onto scene

Emitter System

ParticleEmitterSystem.js manages emitter presets and controls particle spawning.

Matter States

Spawn Shapes

ParticleSpawnShapes.js provides configurable emission geometries:

• Point — All particles from a single position
• Sphere — Surface or volume of a sphere
• Box — Axis-aligned box volume
• Cone — Directional cone emission
• Ring — Torus-shaped emission
• Mesh surface — Emit from mesh triangles (MeshToParticlesCompute.js)

GPU Simulation

The core simulation runs in ParticleSimWorld.js — a massive compute shader that processes all particles each frame. It reads from and writes to several GPU buffers:

Buffer Layout

Advanced Subsystems

Initialized via initAllAdvancedSystems(), these modules extend the core sim:

Performance Optimizations

Alive-List Compaction

Instead of dispatching threads for all slots (including dead particles), a GPU scan builds an alive list of active particle indices. The main sim then dispatches only aliveCount threads via indirect dispatch.

Radix Sort

Replaced bitonic sort with 4-bit radix sort. For 100M particles: 24 dispatches (8 passes × 3) vs bitonic's ~289 dispatches. Drop-in replacement via ParticleRadixSort.js.

FBM Noise Pre-bake

ParticleNoiseTexture.js pre-bakes 4-octave FBM curl noise into a 3D texture. The sim shader does a single textureSampleLevel instead of computing 4 octaves per particle per frame.

Neighbor Grid

Spatial hashing grid for O(1) neighbor queries. Used by SPH, flocking, and bond systems. Rebuilds each frame on GPU.

Rendering

SDF Billboard Renderer

The primary particle renderer (ParticleSdfRenderer.js) draws each particle as a camera-facing quad and raymarches a signed distance field in the fragment shader to produce volumetric shapes.

The fragment shader branches by matter phase:

• Solid (0) — Matte diffuse + subtle specular, opaque sphere
• Liquid (1) — Broad specular, Fresnel reflection, transparent center
• Gas (2) — Volumetric raymarch with Beer-Lambert transmittance, Henyey-Greenstein phase function, depth-based self-shadowing
• Plasma (3) — Pure emissive glow, no diffuse

Lifetime Effects

Color, size, and alpha are modulated over lifetime via GPU textures:

• Color gradient — rgba8unorm 1D texture, sampled with textureSampleLevel
• Lifetime curves — rgba32float texture (alpha, size, velocity curves), sampled with textureLoad (unfilterable format)

Blackbody Rendering

Hot particles use the Tanner Helland blackbody approximation (CIE 1931) instead of a linear ramp. Very hot particles (thermalGlow > 0.5) get an emissive bloom boost.

Additional Renderers

Audio Integration

ParticleAudioBridge.js maps particle substance properties (temperature, density, velocity) to procedural audio parameters. Fire crackles, water splashes, and wind howls are all generated from particle state — no pre-recorded samples needed.

Key Files