add doc/en/particles.md

doc/en/main-page.md

@@ -17,3 +17,4 @@ Documentation for the engine of version 0.24.
 - [Scripting](scripting.md)
 - [World generator engine](world-generator.md)
 - [XML UI building](xml-ui-layouts.md)
+- [Particles](particles.md)

doc/en/particles.md

@@ -0,0 +1,65 @@
+# Particles
+
+Particles are a table, all fields of which are optional.
+
+| Field           | Description                                                           | Default         |
+| --------------- | --------------------------------------------------------------------- | --------------- |
+| texture         | Particle texture.                                                     | ""              |
+| frames          | Animation frames (array of texture names). Must be in a single atlas. | {}              |
+| lighting        | Lighting.                                                             | true            |
+| collision       | Collision detection.                                                  | true            |
+| max_distance    | Maximum distance from the camera at which particles may spawn.        | 16.0            |
+| spawn_interval  | Particle spawn interval in seconds.                                   | 1.0             |
+| lifetime        | Average lifetime of particles in seconds.                             | 5.0             |
+| lifetime_spread | Maximum deviation of particle lifetime (from 0.0 to 1.0).             | 0.2             |
+| velocity        | Initial linear velocity of particles.                                 | {0, 0, 0}       |
+| acceleration    | Particles acceleration.                                               | {0, -16, 0}     |
+| explosion       | Force of particles explosion on spawn.                                | {2, 2, 2}       |
+| size            | Size of particles.                                                    | {0.1, 0.1, 0.1} |
+| spawn_shape     | Shape of particle spawn area. (ball/sphere/box)                       | ball            |
+| spawn_spread    | Size of particle spawn area.                                          | {0, 0, 0}       |
+| random_sub_uv   | Size of random texture subregion (1 - entire texture will be used).   | 1.0             |
+
+## *gfx.particles* library
+
+```lua
+gfx.particles.emit(
+    -- emitter position: static coordinates or entity uid
+    origin: vec3 | int,
+    -- particle count (-1 - infinite)
+    count: int,
+    -- particle settings table
+    preset: table,
+    -- additional particle settings table
+    [optional] extension: table
+) -> int
+```
+
+Creates a particle emitter, returning its id.
+
+```lua
+gfx.particles.stop(id: int)
+```
+
+Stops the emitter permanently. The emitter will be deleted
+automatically later.
+
+```lua
+gfx.particles.is_alive(id: int) -> bool
+```
+
+Checks if the emitter is running. Returns false if it is stopped or if the emitter does not exist.
+
+```lua
+gfx.particles.get_origin(id: int) -> vec3 | int
+```
+
+Returns the static position or uid of the entity the emitter is bound to.
+
+Returns nil if the emitter does not exist.
+
+``lua
+gfx.particles.set_origin(id: int, origin: vec3 | int)
+```
+
+Sets the static position or uid of the entity the emitter will be bound to.