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. diff --git a/doc/en/scripting.md b/doc/en/scripting.md index cf4d0bed..7f5f3dda 100644 --- a/doc/en/scripting.md +++ b/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) diff --git a/doc/en/scripting/builtins/librules.md b/doc/en/scripting/builtins/librules.md new file mode 100644 index 00000000..c4b1c377 --- /dev/null +++ b/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 |