Merge branch 'main' into update-particles

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.

doc/en/scripting.md

@@ -21,6 +21,7 @@ Subsections:
     - [pack](scripting/builtins/libpack.md)
     - [player](scripting/builtins/libplayer.md)
     - [quat](scripting/builtins/libquat.md)
+    - [rules](scripting/builtins/librules.md)
     - [time](scripting/builtins/libtime.md)
     - [utf8](scripting/builtins/libutf8.md)
     - [vec2, vec3, vec4](scripting/builtins/libvecn.md)

doc/en/scripting/builtins/librules.md

@@ -0,0 +1,71 @@
+# *rules* library
+
+```lua
+rules.create(
+    -- rule name
+    name: str,
+    -- default value
+    default: bool,
+    -- value change handler function
+    [optional] handler: function
+) -> int
+```
+
+Creates a rule. If a handler is specified, returns the id for deletion.
+
+> [!NOTE]
+> A rule is created by calling rules.create with a default value.
+> Rules that have not been created can be used, but resetting via rules.reset will result in setting the value to nil.
+
+```lua
+    rules.listen(
+    -- rule name
+    name: str,
+    -- value change handler function
+    handler: function
+) -> int
+```
+
+Adds a rule value change handler.
+
+Returns the id for deletion.
+Also allows subscribing to a rule before it is created.
+
+```lua
+rules.unlisten(name: str, id: int)
+```
+
+Removes a rule handler by id, if it exists.
+
+```lua
+rules.get(name: str) -> bool | nil
+```
+
+Returns the rule value, or nil if it has not been created yet.
+
+```lua
+rules.set(name: str, value: bool)
+```
+
+Sets the rule value by calling handlers. Can be used before
+creating a rule.
+
+```lua
+rules.reset(name: str)
+```
+
+Resets the rule value to the default value.
+
+## Standard Rules
+
+| Name                   | Description                                                 | Default |
+| ---------------------- | ----------------------------------------------------------- | ------- |
+| cheat-commands         | Allow commands whose names are in the console.cheats array. | true    |
+| allow-content-access   | Allow the content access panel.                             | true    |
+| allow-flight           | Allow flight.                                               | true    |
+| allow-noclip           | Allow noclip.                                               | true    |
+| allow-attack           | Allow attacking entities.                                   | true    |
+| allow-destroy          | Allow block destruction.                                    | true    |
+| allow-cheat-movement   | Allow special quick movement keys.                          | true    |
+| allow-debug-cheats     | Allow cheat controls in the debug panel.                    | true    |
+| allow-fast-interaction | Allow fast interaction.                                     | true    |