Particle Effects Guide (Pro)

Back to System Functions

LunarBasic particle systems are fixed-capacity native simulations intended for effects such as sparks, smoke, rain, trails, explosions, and large attraction or repulsion fields.

Quick start

particles = CreateParticleSystem(20000)
SetParticleLife particles, 0.4, 1.2
SetParticleSpeed particles, 80, 180
SetParticleDirection particles, -110, -70
SetParticleGravity particles, 0, 240
SetParticleBounds particles, 0, 0, ScreenWidth(), ScreenHeight(), 0.7

Do
    EmitParticles particles, 10, MouseX(), MouseY()
    UpdateParticles particles, FrameDelta()
    DrawParticles particles
    Flip()
Loop

Long-range forces

SetParticleAttraction enables attraction or repulsion between every particle. LunarBasic uses a symmetric direct calculation for small groups. Larger groups use an adaptive quadtree multipole approximation: occupied regions subdivide as needed, nearby particles are evaluated directly, and well-separated groups are represented by their aggregate field.

This game-oriented solver follows the adaptive spatial strategy described by Carrier, Greengard, and Rokhlin while using a low-constant monopole evaluation appropriate for real-time effects. It avoids exposing expansion order or tree-list controls in BASIC.

Performance guidance

Create systems once and reuse them. Emission and updates do not allocate per particle.
Use attraction only when the visual effect needs particle-to-particle forces.
Set an image hotspot at its center before assigning the image to a system.
Call FreeParticleSystem when leaving a level or permanently destroying an effect.