Quick Start
microScript programming
API reference
A simple particle system, heavily inspired by Godot's 2D particle systems.
You can create a ParticleSystem
object, and pass to its constructor an
object with all the settings as you want them:
ps = new ParticleSystem( object
num_particles = 5
speed = 100
direction = 180
color = new Color(255, 0, 128)
gravity = new Vector2(0, -1)
end)
Then you can tell it to start emitting particles by creating instances (more on instances below).
ps.add_instance(x, y)
And you also need to update and draw it:
update = function()
ps.update()
end
draw = function()
ps.draw()
end
One particle system can have multiple instances of itself, so if you need several particle effects that share the exact same settings, you can tell your system to create more instances:
ps.add_instance(x, y)
That will create a new instance (or reuse a pooled one) and make it start emitting. It will also return the instance, in case you need it.
If you know beforehand roughly how many instances you'll be using, you can pass that as the first argument to the ParticleSystem's constructor, so the system can preemptively create that many instances and fill the instance pool.
ps = new ParticleSystem( 10, smoke_settings )
That way they'll be sitting in memory ready to be used.
If you want to extend or shrink the instance pool on the fly, you can use
set_num_instances()
. The particle system will create or discard instances
as needed to meet your desired amount.
ps.set_num_instances(5)
These are the particle settings that you pass to the ParticleSystem
constructor.
Some options have a "random variation percentage". This means the particle system will add or subtract a random amount (up to the percentage you specify) from the base value. The percentage is a value between 0 and 1.
property | default | description |
---|---|---|
num_particles (number) |
20 |
the number of particles in the system |
emit_timeout (number) |
-1 |
the time (in seconds) until the system stops emitting partiles. Set to -1 to emit forever. |
explosiveness (number) |
0.0 |
how explosive the system is: the higher, the more particles are emitted quicker (percentage, between 0 .. 1) |
spawn_extents (Vector2) |
(0, 0) |
the range in which particles can spawn in either axis. E.g., (5, 5) means the spawn area is extended 5 pixels to the left, 5 pixels to the right, and the same thing vertically. |
sprite (string) |
the name of the sprite to use for the particles. (Note: at least for now, the sprite should be square.) | |
blending (string) |
normal |
the blending mode used to draw the particles |
color (Color/list/Gradient) |
Gradient(white) |
the color of the particles, or a list of colors, or a Gradient. A list of colors will be converted to an evenly distributed gradient. |
gravity (Vector2) |
(0, -1) |
the gravity direction vector |
size (number/list) |
[1, 1] |
the size of the particles (in pixels), or a list with two sizes: the initial size (at birth) and the final size (at death). |
lifetime (number/list) |
[2, 0.0] |
the amount of time (in seconds) that particles stay alive, and optionally a random variation percentage |
direction (number/list) |
[0, 0.0] |
the angle (in degrees) to shoot the particles toward, and optionally a random variation percentage. (In microStudio 0º = right .) |
speed (number/list) |
[50, 0.0] |
the speed of the particles, and optionlly a random variation percentage |
If you use many particle systems, you can use the included systems
manager, Particles
. You can create and update systems through it:
init = function()
ps1 = Particles.new_system( smoke_settings )
ps2 = Particles.new_system( sparks_settings )
ps3 = Particles.new_system( rain_settings )
ps4 = Particles.new_system( fire_settings )
end
update = function()
// no need to manually update or draw any of the above systems, in this case
Particles.update()
end
draw = function()
Particles.draw()
end
Very cool and very useful! Suggestion: add a property to set the blending mode ; being able to use "additive" blending mode for some particle effects would be nice.
Thanks! :)
Also, good idea. Gonna do that.
tq