Particle Effects System

Particle Effects System

CPU-simulated, fully controllable particle system for effects like fire, smoke, sparks, and explosions.

Architecture

The particle system is:

• CPU-simulated — Full programmatic control, heavily multithreaded


• Not GPU-based — Easier to control and extend than GPU particles


• Fully programmable — Iterate particles, emit manually, react to collisions

Particle Components

A complete particle effect requires:

ParticleEffect Component

var effect = Components.Get<ParticleEffect>();
effect.Play(); // Start emission
effect.Stop(); // Stop new particles (existing finish their lifetime)
effect.Emit(10); // Burst emit 10 particles immediately

ParticleEmitter

• Rate — Particles per second
• Burst — Instant spawn count
• Shape — Point, sphere, box, cone emission shapes
• Velocity — Initial particle velocity

ParticleSpriteRenderer

• Material/texture
• Size over lifetime
• Color over lifetime
• Rotation

Custom ParticleController

public class FireController : ParticleController
{
    public override void Simulate(ref Particle particle, float delta)
    {
        // Custom simulation logic
        particle.Position += Vector3.Up * delta * 10;
        particle.Size *= 0.99f; // Shrink over time
        
        // Collision
        if (particle.Collided)
        {
            particle.Velocity = particle.CollisionNormal * 0.5f;
        }
    }
}

Key Features

Emitting from Code

public class Explosion : Component
{
    [ResourceType("vpcf")]
    public string ExplosionEffect { get; set; }
    
    void Detonate()
    {
        // Spawn particle effect
        Particles.Play(ExplosionEffect, WorldPosition);
        
        // Or with more control:
        var effect = Particles.Create(ExplosionEffect);
        effect.WorldPosition = WorldPosition;
        effect.SetControlPoint(0, WorldPosition); // Position
        effect.SetControlPoint(1, Vector3.Up * 100); // Direction/vector
        effect.Play();
    }
}

Control Points

Pass data to effects:

• CP0 — Usually effect position


• CP1 — Direction, velocity, or second position


• CP2-CP7 — Additional data as needed

Particle Properties

Each particle has:

• Position, velocity, rotation


• Size (start, current, end)


• Color (start, current, end)


• Lifetime, age


• Sprite frame

Performance

• Multithreaded simulation
• Efficient culling
• LOD system for distant effects
• Auto-destruct when complete

Use Cases

• Fire & Smoke — Animated sprites with lifetime curves
• Sparks — Small particles with bounce physics
• Explosions — Burst emit with shockwave ring
• Weather — Rain, snow, dust with velocity
• Magic — Color-changing, orbiting particles
• Trails — Ribbon-like continuous emission