From bd5f746dbc22f5b4e7775d80a838a59a3970d14b Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sat, 9 Nov 2024 20:37:23 +0300
Subject: [PATCH] add doc/en/particles.md

---
 doc/en/main-page.md |  1 +
 doc/en/particles.md | 65 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 doc/en/particles.md

diff --git a/doc/en/main-page.md b/doc/en/main-page.md
index ab766093..06636ea0 100644
--- a/doc/en/main-page.md
+++ b/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)
diff --git a/doc/en/particles.md b/doc/en/particles.md
new file mode 100644
index 00000000..8b7a37e7
--- /dev/null
+++ b/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.