Particle System

The Particle System node is the top-level container for Grafit's GPU particle engine. It acts as a group node — double-click to enter and place child nodes (Emitters, Fields, Lights, Colliders, Shape, Velocity, Spawn, Type, and Debug) inside. The entire simulation runs on the GPU via Metal compute shaders, supporting up to 50,000 particles at interactive frame rates on Apple Silicon. The system outputs an offscreen texture through the Image port, which can be routed to a Canvas node for compositing into the output viewport.

The Particle System manages the full lifecycle: spawning, physics simulation, field forces, collisions, trigger events, lighting, trail computation, depth sorting, and multi-pass rendering. It supports 3D perspective with configurable camera distance, billboard rendering, bloom post-processing, and per-emitter visual passes.

Container Architecture

The Particle System is a group node, similar to a Macro Group. When you double-click it in the graph editor, you navigate inside where you can place child nodes:

• Particle Emitter — spawns particles with configurable properties
• Particle Field — applies forces (gravity, turbulence, attractors, etc.)
• Particle Collider — defines collision surfaces (planes, spheres, boxes, lines)
• Particle Light — illuminates particles with directional, point, or spot lights
• Particle Shape — configures emission shape geometry (connect to Emitter)
• Particle Velocity — configures initial particle velocity (connect to Emitter)
• Particle Spawn — configures emission timing and rate (connect to Emitter)
• Particle Type — configures visual rendering mode (connect to Emitter)
• Particle Debug — displays real-time statistics overlay

Processing Pipeline

Each frame, the Particle System executes the following phases:

1. Phase 1 — Process data-producing child nodes (Shape, Velocity, Spawn, Type, Collider) so their outputs are available for emitters.
2. Phase 1.5 — Route trigger events from the previous frame's GPU computation to emitter output ports (On Death, On Collision, On Lifetime).
3. Phase 2 — Build GPU uniforms for all emitters, fields, colliders, and lights. Collect per-emitter visual settings (blend mode, PBR materials, textures, trail parameters).
4. GPU Simulation — Dispatch the Metal compute kernel to spawn new particles, integrate physics, apply fields, resolve collisions, and update trails.
5. Render — Execute multi-pass rendering with per-emitter visual types, blend modes, and textures. 3D passes render first (with depth), then 2D passes.
6. Bloom — If enabled, apply bloom post-processing (extract bright pixels, Gaussian blur, composite).

System Transform

The Position, Rotation, and Scale inputs build a system transform matrix that is applied at render time, not during simulation. This means all existing particles move when the system transform changes, not just newly spawned ones. The simulation itself runs in local space (identity transform).

Time Control

The system supports three time modes:

• Internal timer (default): Accumulates real frame deltas, scaled by Time Scale.
• External time: When External Time >= 0, the system uses the external value as absolute time, ignoring the internal clock. Useful for synchronizing particles to music or external data.
• Pause: Set Time Scale to 0 to freeze the simulation while keeping particles visible.

Limits

• Real-time particle effects: fire, smoke, sparks, rain, snow, dust
• Data visualization with particle-based representations
• Interactive art installations driven by external data (EEG, MIDI, OSC)
• Music-reactive particle systems synchronized via External Time
• 3D particle scenes with perspective, lighting, and shadows
• Cascading particle chains using the trigger system (fireworks, explosions)

• Start with one Emitter inside the system. Add Shape, Velocity, Spawn, and Type nodes connected to the Emitter to configure behavior.
• The system transform (Position/Rotation/Scale) affects all particles uniformly. Use individual Emitter positions for localized spawn points.
• Camera Distance controls 3D perspective strength. Set to 0 for flat 2D rendering, increase for dramatic depth effects.
• Bloom works best with emissive particles or additive blending. Set the Emitter's Emissive input above 0 and enable Bloom on the system.
• Use the Particle Debug node inside the system to monitor alive count, GPU timing, memory usage, and trigger events in real time.
• Keep Max Particles as low as possible for your effect. Lower counts mean less GPU memory and faster simulation.
• The Alive Count output has one-frame latency because it reads back from the GPU asynchronously, avoiding CPU stalls.