[CSM] Add functions to create particles and particlespawners. (#6072)

1 files changed, 64 insertions, 0 deletions

diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt
index 435cc5b2e..566b86255 100644
--- a/doc/client_lua_api.txt
+++ b/doc/client_lua_api.txt
@@ -787,6 +787,16 @@ Call these functions only at load time!
     * You should use a minetest.register_on_connect(function() ... end) to perform
       a successful channel join on client startup.
 
+### Particles
+* `minetest.add_particle(particle definition)`
+
+* `minetest.add_particlespawner(particlespawner definition)`
+    * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
+    * Returns an `id`, and -1 if adding didn't succeed
+
+* `minetest.delete_particlespawner(id)`
+    * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
+
 ### Misc.
 * `minetest.parse_json(string[, nullvalue])`: returns something
     * Convert a string containing JSON data into the Lua equivalent
@@ -1318,3 +1328,57 @@ Displays distance to selected world position.
 * `number:` An integer containing the RGB value of the color used to draw the text.
 * `world_pos`: World position of the waypoint.
 
+### Particle definition (`add_particle`)
+
+    {
+        pos = {x=0, y=0, z=0},
+        velocity = {x=0, y=0, z=0},
+        acceleration = {x=0, y=0, z=0},
+    --  ^ Spawn particle at pos with velocity and acceleration
+        expirationtime = 1,
+    --  ^ Disappears after expirationtime seconds
+        size = 1,
+        collisiondetection = false,
+    --  ^ collisiondetection: if true collides with physical objects
+        collision_removal = false,
+    --  ^ collision_removal: if true then particle is removed when it collides,
+    --  ^ requires collisiondetection = true to have any effect
+        vertical = false,
+    --  ^ vertical: if true faces player using y axis only
+        texture = "image.png",
+    --  ^ Uses texture (string)
+        animation = {Tile Animation definition},
+    --  ^ optional, specifies how to animate the particle texture
+        glow = 0
+    --  ^ optional, specify particle self-luminescence in darkness
+    }
+
+### `ParticleSpawner` definition (`add_particlespawner`)
+
+    {
+        amount = 1,
+        time = 1,
+    --  ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
+        minpos = {x=0, y=0, z=0},
+        maxpos = {x=0, y=0, z=0},
+        minvel = {x=0, y=0, z=0},
+        maxvel = {x=0, y=0, z=0},
+        minacc = {x=0, y=0, z=0},
+        maxacc = {x=0, y=0, z=0},
+        minexptime = 1,
+        maxexptime = 1,
+        minsize = 1,
+        maxsize = 1,
+    --  ^ The particle's properties are random values in between the bounds:
+    --  ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
+    --  ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
+        collisiondetection = false,
+    --  ^ collisiondetection: if true uses collision detection
+        collision_removal = false,
+    --  ^ collision_removal: if true then particle is removed when it collides,
+    --  ^ requires collisiondetection = true to have any effect
+        vertical = false,
+    --  ^ vertical: if true faces player using y axis only
+        texture = "image.png",
+    --  ^ Uses texture (string)
+    }