Particles¶
Wasabi2d includes a basic particle system that can easily update and render hundreds of particles. Particles can be textured, move, and change color over time. Finally they have finite lifetimes after which they are removed.
Particles are always created within a particle group which contains some global parameters that affect particles.
It is intended that you create only one particle group per effect type, then use it for all particles/emitters for that effect.
- Layer.add_particle_group(texture: str = None, grow: float = 1.0, max_age: float = np.inf, gravity: Tuple[float, float] = (0, 0), drag: float = 1.0)¶
Create a particle group. The parameters correspond to attributes of the group object, as documented below.
Particle Group Configuration¶
- particle_group.texture¶
The image used for each particle. Textures must be in a directory named
images/
and must be named in lowercase with underscores. This restriction ensures that games written with wasabi2d will work on with case sensitive and insensitive filenames.If
texture
isNone
, particles will be drawn as squares.
- particle_group.grow¶
A growth rate for particles. The size will change by a factor of
grow
every 1 second. Factors smaller than 1.0 will shrink over time; factors greater will grow.
- particle_group.max_age¶
The lifetime for particles in seconds. Particles older than this will be removed.
If you don’t set this, particles will stick around until you delete the group.
- particle_group.gravity¶
Global “gravity” vector, ie. constant acceleration applied to all particles.
Vectors that point downwards (eg.
(0, 100)
) would cause particles to fall under gravity.Vectors that point upwards (eg.
(0, -100)
) would cause particles to rise, perhaps because they are buoyant.Units are pixels per second per second.
- particle_group.drag¶
A drag factor.
All velocities will be multiplied by this factor every second. For example, a
drag
of0.5
will cause particles to lose half their speed every second.This will slow particles to a stop, unless they hit their
max_age
, or unlessgravity
is set. If gravity is set they will eventually hit a “terminal velocity” in the direction of the gravity vector.
- particle_group.spin_drag¶
A drag factor for angular velocity (spin).
All spins will be multiplied by this factor every second.
- particle_group.add_color_stop(age: float, color: Any)¶
Add a color stop for particles at age (in seconds).
Particles will fade between the colors of the stops as their age increases.
Use multiple stops to create a color gradient. For example, to fade from red to transparent after 2s:
group.add_color_stop(0, (1, 0, 0, 1)) group.add_color_stop(2, (1, 0, 0, 0))
Emitting particles¶
Particle groups don’t contain any particles when created. To actually create
particles, call .emit()
or create an emitter object.
- ParticleGroup.emit(num: int, *, pos: Tuple[float, float], pos_spread: float = 0, vel: Tuple[float, float] = (0, 0), vel_spread: float = 0, color: Any = (1, 1, 1, 1), size: float = 1.0, size_spread: float = 0.0, spin: float = 0.0, spin_spread: float = 0.0, angle: float = 0.0, angle_spread: float = 0.0, age_spread: float = 0.0)¶
Emit num particles.
- Parameters
num – The number of particles to emit.
Several parameters configure properties of the particles to emit:
- Parameters
pos – The center position at which to emit particles.
vel – The velocity with with particles will move, in pixels per second.
color – A per-emission color for the particles. This will be multiplied with the color ramp configured for the whole particle group.
size – The diameter of the particles to emit, in pixels.
angle – The rotation of the emitted particles, in radians.
spin – The rate of rotation (angular velocity) of particles, in radians per second.
Several of the above properties are allowed to be randomised over a normal distribution. The value above gives the mean of the distribution. If a
_spread
parameter is given it will give the standard deviation for the distribution.- Parameters
pos_spread – The standard deviation for particle positions, in pixels.
vel_spread – The standard deviation for particle velocities, in pixels per second.
size_spread – The standard deviation for particle sizes, in pixels.
angle_spread – The standard deviation for the angle of particles, in radians.
spin_spread – The standard deviation for the rate of rotation of particles, in radians per second.
Emitters¶
emit()
is useful for single emissions of particles, such as explosions
or impacts, but often you want a jet of particles. Rather than calling
emit()
every frame you can create a persistent object that emits particles.
This works well with groups, which let you attach the emitter to other graphics.
- ParticleGroup.add_emitter(**kargs) Emitter ¶
New in version 1.4.
Create a persistent emitter object that emits particles at a certain rate in particles per second. The Emitter object is Transformable and can be grouped.
Every attribute below may be given in the constructor or set on the emitter object after construction.
The key property is rate:
- Parameters
rate (float) – The number of particles emitted by this emitter per second. The flow of particles is randomly distributed (using a Poisson distribution) to meet this rate, ie. the interval between particles varies but averages out to rate.
To stop emitting particles from an emitter temporarily, set
rate
to0
.Angle parameters are very slightly different to
emit()
because of the overlap with the standard Transformable angle property:- Parameters
angle (float) – The rotation of the emitter object, in radians (ie. the rotation of the vel vector).
emit_angle (float) – The rotation of the emitted particles, in radians.
emit_angle_spread (float) – The standard deviation for the angle of particles, in radians.
The other properties are shared with emit:
- Parameters
vel – The velocity with with particles will move, in pixels per second.
color – A per-emission color for the particles. This will be multiplied with the color ramp configured for the whole particle group.
size – The diameter of the particles to emit, in pixels.
angle – The rotation of the emitted particles, in radians.
spin – The rate of rotation (angular velocity) of particles, in radians per second.
pos_spread – The standard deviation for particle positions, in pixels.
vel_spread – The standard deviation for particle velocities, in pixels per second.
size_spread – The standard deviation for particle sizes, in pixels.
spin_spread – The standard deviation for the rate of rotation of particles, in radians per second.
- Emitter.delete()¶
Remove the emitter object.