Particles¶

SimVX provides a ParticleEmitter node for CPU or GPU-accelerated particle effects. Particles move, scale, and recolor over their lifetime based on configurable settings.

Emitter Properties¶

ParticleEmitter extends Node3D and exposes all configuration as Property descriptors, making them editable in the inspector.

Property	Default	Description
`amount`	`100`	Maximum particle pool size
`lifetime`	`2.0`	Seconds each particle lives
`emission_rate`	`50.0`	Particles emitted per second
`one_shot`	`False`	Emit once then stop
`emitting`	`True`	Whether the emitter is active
`emission_shape`	`"point"`	`"point"`, `"sphere"`, or `"box"`
`emission_radius`	`1.0`	Radius for sphere emission shape
`emission_box`	`(1, 1, 1)`	Half-extents for box emission shape
`initial_velocity`	`(0, 5, 0)`	Starting velocity vector
`velocity_spread`	`0.3`	Randomization factor for velocity direction
`gravity`	`(0, -9.8, 0)`	Gravity applied each frame
`damping`	`0.0`	Velocity damping per second
`start_color`	`(1, 1, 1, 1)`	RGBA at birth
`end_color`	`(1, 1, 1, 0)`	RGBA at death (fades out by default)
`start_scale`	`1.0`	Scale at birth
`end_scale`	`0.0`	Scale at death
`gpu_simulation`	`False`	Offload simulation to a compute shader

Properties¶

alive_count – Number of currently alive particles.
particle_data – NumPy structured array of alive particles (position, velocity, color, scale, lifetime, age). Returns None when no particles are alive.
emitter_config – Dict of emitter parameters for GPU compute dispatch.

Fire Effect Example¶

from simvx.core import ParticleEmitter, Vec3

class FireEmitter(ParticleEmitter):
    amount = 200
    lifetime = 1.5
    emission_rate = 80
    emission_shape = "sphere"
    emission_radius = 0.3
    initial_velocity = (0, 4, 0)
    velocity_spread = 0.2
    gravity = (0, 1.0, 0)          # Hot air rises
    start_color = (1.0, 0.6, 0.1, 1.0)
    end_color = (0.8, 0.1, 0.0, 0.0)
    start_scale = 0.8
    end_scale = 0.0

One-Shot Explosion¶

Set one_shot = True and a high emission_rate to burst all particles at once:

class Explosion(ParticleEmitter):
    amount = 300
    lifetime = 0.8
    emission_rate = 10000   # Emit all 300 in the first frame
    one_shot = True
    emission_shape = "sphere"
    emission_radius = 0.1
    initial_velocity = (0, 8, 0)
    velocity_spread = 1.0   # Scatter in all directions
    gravity = (0, -12, 0)
    start_color = (1.0, 1.0, 0.5, 1.0)
    end_color = (0.5, 0.1, 0.0, 0.0)
    start_scale = 1.2
    end_scale = 0.0

GPU Simulation¶

When gpu_simulation = True, the CPU skips per-particle work and only uploads the emitter_config dict each frame. The graphics backend dispatches a compute shader that reads the config and writes particle positions, colors, and scales directly in GPU memory – zero-copy rendering with no per-particle CPU cost.

API Reference¶

See simvx.core.particles for the complete particle API.