Skip to content

particles

stable

A 2D particle emitter system with configurable velocity, lifetime, color gradients, size interpolation, gravity, emission shapes, directional spread, and blend modes.

use plugin particles::{ParticleEmitter.new, set_position, set_velocity_range, …}
19 functions Graphics
/ filter jk navigate Esc clear
Functions (19)
  1. ParticleEmitter.new Create a new particle emitter
  2. set_position Set emitter world position
  3. set_velocity_range Set min/max velocity components
  4. set_lifetime Set particle lifetime in seconds
  5. set_max_particles Set maximum live particle count
  6. emit Spawn a burst of N particles immediately
  7. update Advance simulation by delta time
  8. get_particles Get all live particle data as a table
  9. alive_count Count currently live particles
  10. reset Clear all particles and counters
  11. set_color Set start and end RGBA color gradient
  12. set_size Set start and end particle size
  13. set_gravity Set gravity acceleration vector
  14. set_shape Set emitter spawn area shape
  15. set_emission_rate Set continuous particles-per-second rate
  16. set_spread_angle Set directional spread in degrees
  17. set_direction Set base emission direction in degrees
  18. get_stats Get alive count and emission statistics
  19. set_blend_mode Set blend mode (alpha or additive)

ParticleEmitter.new() → ParticleEmitter

Create a new particle emitter

Creates a new particle emitter with defaults: position (0,0), velocity range (−1 to 1), lifetime 1s, max 1000 particles, white-to-transparent color gradient, and omnidirectional spread.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_position(400.0, 300.0)
emitter.set_lifetime(2.0)
emitter.emit(50)

set_position(self, x, y) → nil

Set emitter world position

Moves the emitter to world coordinates (x, y). Newly spawned particles originate from this point, offset by the configured emitter shape.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_position(200.0, 150.0)
emitter.emit(30)

set_velocity_range(self, min_vx, min_vy, max_vx, max_vy) → nil

Set min/max velocity components

Sets the axis-aligned velocity box for new particles. Each axis is sampled independently in [min, max]. When set_spread_angle is below 360°, speed magnitude is derived instead.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_velocity_range(-50.0, -100.0, 50.0, -10.0)
emitter.emit(40)

set_lifetime(self, seconds) → nil

Set particle lifetime in seconds

Sets how many seconds each particle lives before being removed from simulation.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_lifetime(1.5)
emitter.emit(20)

set_max_particles(self, n) → nil

Set maximum live particle count

Caps the maximum number of simultaneously live particles. Spawn calls are silently ignored when the cap is reached.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_max_particles(500)
emitter.emit(1000)
print("Alive: {emitter.alive_count()}")

emit(self, count) → nil

Spawn a burst of N particles immediately

Immediately spawns count particles using the current emitter settings. Use alongside update for burst effects. For continuous emission, use set_emission_rate instead.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_position(320.0, 240.0)
emitter.emit(100)

update(self, dt) → nil

Advance simulation by delta time

Advances the simulation by dt seconds: applies gravity, moves particles, decrements lifetimes, removes dead particles, and auto-emits if set_emission_rate is configured.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_emission_rate(60.0)
emitter.update(0.016)
print("Alive: {emitter.alive_count()}")

get_particles(self) → table

Get all live particle data as a table

Returns all live particles as a table. Each entry has x, y, vx, vy, life, size, r, g, b, a fields computed from the particle's current interpolated state.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.emit(5)
let pts = emitter.get_particles()
print("First particle x: {pts[1]["x"]}")

alive_count(self) → int

Count currently live particles

Returns the number of currently live particles without allocating a full particle data table.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.emit(25)
print("Alive: {emitter.alive_count()}")

reset(self) → nil

Clear all particles and counters

Removes all particles and resets the emission accumulator and total-emitted counter to zero.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.emit(100)
emitter.reset()
print("Alive after reset: {emitter.alive_count()}")

set_color(self, start_r, start_g, start_b, start_a, end_r, end_g, end_b, end_a) → nil

Set start and end RGBA color gradient

Sets the RGBA color gradient for particles (values 0.0–1.0). Each particle interpolates from the start color at spawn to the end color at death.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_color(1.0, 0.5, 0.0, 1.0, 1.0, 0.0, 0.0, 0.0)
emitter.emit(80)

set_size(self, start_size, end_size) → nil

Set start and end particle size

Sets the particle size interpolation. Each particle interpolates from start_size at spawn to end_size at death.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_size(8.0, 1.0)
emitter.emit(50)

set_gravity(self, gx, gy) → nil

Set gravity acceleration vector

Sets the gravity acceleration applied per second. Positive gy pulls downward in screen space. Use (0.0, 0.0) for zero-gravity.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_gravity(0.0, 98.0)
emitter.emit(60)
emitter.update(1.0)

set_shape(self, shape, param1?, param2?) → nil

Set emitter spawn area shape

Sets the spawn area shape. Valid shapes: "point" (no params), "circle" (radius), "rect" (width, height). Particles spawn at a random position within the shape centered on the emitter position.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_shape("circle", 40.0)
emitter.emit(100)

let emitter2 = ParticleEmitter.new()
emitter2.set_shape("rect", 200.0, 10.0)
emitter2.emit(80)

set_emission_rate(self, particles_per_second) → nil

Set continuous particles-per-second rate

Configures continuous emission. Each update(dt) call auto-spawns the correct fractional number of particles based on elapsed time.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_emission_rate(120.0)
emitter.update(0.016)
print("Alive: {emitter.alive_count()}")

set_spread_angle(self, degrees) → nil

Set directional spread in degrees

Sets the angular spread of emission. 360.0 means omnidirectional (default). Values below 360 concentrate particles toward the direction set by set_direction.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_direction(270.0)
emitter.set_spread_angle(45.0)
emitter.emit(60)

set_direction(self, degrees) → nil

Set base emission direction in degrees

Sets the base emission direction in degrees (0 = right, 90 = down, 270 = up). Only meaningful when set_spread_angle is below 360.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_direction(270.0)
emitter.set_spread_angle(30.0)
emitter.set_velocity_range(0.0, 0.0, 150.0, 150.0)
emitter.emit(50)

get_stats(self) → table

Get alive count and emission statistics

Returns a table with alive (int), total_emitted (int), and avg_lifetime (float, average time already elapsed for live particles).

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_emission_rate(100.0)
emitter.update(0.5)
let stats = emitter.get_stats()
print("Alive: {stats["alive"]}, Total: {stats["total_emitted"]}")

set_blend_mode(self, mode) → nil

Set blend mode (alpha or additive)

Sets the blend mode hint for the renderer. "alpha" is standard transparency (default). "additive" brightens underlying pixels, ideal for fire, magic, or glowing effects.

zolo▶ Playground
use plugin particles::{ParticleEmitter}

let emitter = ParticleEmitter.new()
emitter.set_blend_mode("additive")
emitter.set_color(0.2, 0.5, 1.0, 0.8, 0.0, 0.0, 0.5, 0.0)
emitter.emit(200)
View source code
enespt-br