Particle System

ParticleEmitterComponent

GPU-accelerated particle system for visual effects like fire, smoke, sparks, and magic effects. Uses triple-buffered GPU uploads for frame-safe rendering.

Emission Properties

Property	Type	Description
emit_rate	Float	Particles emitted per second
max_particles	Int	Maximum particle count in buffer
lifetime	Float	Particle lifetime in seconds
lifetime_variance	Float	Random variance added to lifetime

Shape & Motion

Property	Type	Description
emit_shape	Enum	Emission shape: point, sphere, cone, box
emit_radius	Float	Emission radius for sphere/cone shapes
emit_angle	Float	Cone half-angle in degrees
initial_speed	Float	Initial velocity magnitude
speed_variance	Float	Random variance on initial speed
gravity_multiplier	Float	Gravity effect (0 = no gravity, 1 = full)
drag	Float	Air resistance (0 = none, 1 = heavy)

Appearance

Property	Type	Description
start_size	Float	Particle size at birth
end_size	Float	Particle size at death
start_color	Vec4	Color at birth (RGBA)
end_color	Vec4	Color at death (RGBA, interpolated)

Example: Fire Effect

{
  "op": "AddComponent",
  "params": {
    "entity_name": "Campfire",
    "component_type": "ParticleEmitterComponent",
    "data": {
      "emit_rate": 50,
      "max_particles": 500,
      "lifetime": 1.5,
      "emit_shape": "cone",
      "emit_angle": 15,
      "initial_speed": 3.0,
      "gravity_multiplier": -0.5,
      "start_size": 0.3,
      "end_size": 0.05,
      "start_color": { "x": 1.0, "y": 0.6, "z": 0.1, "w": 1.0 },
      "end_color": { "x": 0.8, "y": 0.2, "z": 0.0, "w": 0.0 }
    }
  }
}

GPU Architecture

The particle system uses triple-buffered GPU uploads to prevent frame overlap:

• Particles are simulated on the CPU (spawn, update, cull)
• Transform and color data is uploaded to GPU buffers each frame
• Triple-buffering (particle_buffers_[frame % 3]) ensures the GPU is never reading a buffer the CPU is writing to