From c340eba358623597ba06faa3873526ee15021525 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Wed, 16 Oct 2024 02:23:29 +0300
Subject: [PATCH] update doc/en/**

---
 doc/en/scripting.md                       | 274 +---------------------
 doc/en/scripting/builtins/libgui.md       |  41 ++++
 doc/en/scripting/builtins/libhud.md       |  50 ++++
 doc/en/scripting/builtins/libinventory.md |  56 +++++
 doc/en/scripting/builtins/libtime.md      |  13 +
 doc/en/scripting/builtins/libworld.md     |  40 ++++
 6 files changed, 207 insertions(+), 267 deletions(-)
 create mode 100644 doc/en/scripting/builtins/libgui.md
 create mode 100644 doc/en/scripting/builtins/libhud.md
 create mode 100644 doc/en/scripting/builtins/libinventory.md
 create mode 100644 doc/en/scripting/builtins/libtime.md
 create mode 100644 doc/en/scripting/builtins/libworld.md

diff --git a/doc/en/scripting.md b/doc/en/scripting.md
index c0fdcb5e..2ed46bdb 100644
--- a/doc/en/scripting.md
+++ b/doc/en/scripting.md
@@ -10,14 +10,19 @@ Subsections:
 - [Entities and components](scripting/ecs.md)
 - [Libraries](#)
     - [block](scripting/builtins/libblock.md)
-    - [item](scripting/builtins/libitem.md)
-    - [entities](scripting/builtins/libentities.md)
     - [cameras](scripting/builtins/libcameras.md)
+    - [entities](scripting/builtins/libentities.md)
+    - [gui](scripting/builtins/libgui.md)
+    - [hud](scripting/builtins/libhud.md)
+    - [inventory](scripting/builtins/libinventory.md)
+    - [item](scripting/builtins/libitem.md)
     - [mat4](scripting/builtins/libmat4.md)
     - [pack](scripting/builtins/libpack.md)
     - [player](scripting/builtins/libplayer.md)
     - [quat](scripting/builtins/libquat.md)
+    - [time](scripting/builtins/libtime.md)
     - [vec2, vec3, vec4](scripting/builtins/libvecn.md)
+    - [world](scripting/builtins/libworld.md)
 - [Module core:bit_converter](scripting/modules/core_bit_converter.md)
 - [Module core:data_buffer](scripting/modules/core_data_buffer.md)
 - [Module core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)
@@ -40,268 +45,3 @@ not part of Lua syntax.
 require "packid:module_name" -- load Lua module from pack-folder/modules/
 -- no extension included, just name
 ```
-
-## *world* library
-
-## Библиотека *world*
-
-```python
-world.get_list() -> tables array {
-    name: str,
-    icon: str
-}
-```
-
-Retuns worlds information: name and preview/icon (loading automatically).
-
-```python
-world.get_day_time() -> number
-```
-
-Returns current day time in range \[0.0-1.0\] where 0.0 and 1.0 - midnight, 0.5 - noon.
-
-```python
-world.set_day_time(time: number)
-```
-
-Set day time value.
-
-```python
-world.set_day_time_speed(value: number)
-```
-
-Sets the specified speed for game time.
-
-```python
-world.get_day_time_speed() -> number
-```
-
-Returns the speed for game time.
-
-```python
-world.get_total_time() -> number
-```
-
-Returns total time passed in the world
-
-```python
-world.get_seed() -> int
-```
-
-Returns world seed.
-
-``` python
-world.is_day() -> boolean
-```
-
-Proves that this is the current time during the day. From 0.2(8 am) to 0.8(8 pm)
-
-``` python
-world.is_night() -> bool
-```
-
-Checks that it is the current time at night. From 0.8(8 pm) to 0.2(8 am)
-
-```python
-world.exists() -> bool
-```
-
-Checks the existence of a world by name.
-
-
-## *gui* library
-
-The library contains functions for accessing the properties of UI elements. Instead of gui, you should use an object wrapper that provides access to properties through the __index, __newindex meta methods:
-
-Example:
-
-```lua
-print(document.some_button.text) -- where 'some_button' is an element id
-document.some_button.text = "new text"
-```
-
-```python
-gui.str(text: str, context: str) -> str
-```
-
-Returns translated text.
-
-```python
-gui.get_viewport() -> {int, int}
-```
-
-Returns size of the main container (window).
-
-```python
-gui.get_env(document: str) -> table
-```
-
-Returns environment (global variables table) of the specified document.
-
-```python
-gui.get_locales_info() -> table of tables where
- key - locale id following isolangcode_ISOCOUNTRYCODE format
- value - table {
-  name: str # name of the locale in its language
- }
-```
-
-Returns information about all loaded locales (res/texts/\*).
-
-## *inventory* library
-
-Library for inventories interaction.
-
-```python
-inventory.get(invid: int, slot: int) -> int, int
-```
-
-Requires an inventory ID and slot index. Returns item ID and count. ID = 0 (core:empty) means that slot is empty.
-
-```python
-inventory.set(invid: int, slot: int, itemid: int, count: int)
-```
-
-Set slot content.
-
-```python
-inventory.size(invid: int) -> int
-```
-
-Returns inventory size (slots number). Throws an exception if there's no inventory having specified ID.
-
-```python
-inventory.add(invid: int, itemid: int, count: int) -> int
-```
-
-Add an item to the specified inventory. Returns remaining count if could not to add fully.
-
-```python
-inventory.get_block(x: int, y: int, z: int) -> int
-```
-
-Returns block inventory ID or 0.
-
-```python
-inventory.bind_block(invid: int, x: int, y: int, z: int)
-```
-
-Bind inventory to the specified block.
-
-```python
-inventory.unbind_block(x: int, y: int, z: int)
-```
-
-Unbind inventory from the specified block.
-
-> [!WARNING]
-> Unbound inventories will be deleted on world close.
-
-```python
-inventory.clone(invid: int) -> int
-```
-
-Create inventory copy. Returns the created copy ID.
-
-```python
-inventory.move(invA: int, slotA: int, invB: int, slotB: int)
-```
-
-Move item from slotA of invA to slotB of invB. invA may be the same as invB.
-If slotB will be chosen automaticly if argument is not specified.
-
-## *hud* library
-
-
-```python
-hud.open_inventory()
-```
-
-Open player inventory
-
-```python
-hud.close_inventory()
-```
-
-Close inventory
-
-```python
-hud.open_block(x: int, y: int, z: int) -> int, str
-```
-
-Open block UI and inventory. Throws an exception if block has no UI layout.
-
-Returns block inventory ID (if *"inventory-size"=0* a virtual inventory will be created), and UI layout ID.
-
-```python
-hud.show_overlay(layoutid: str, playerinv: bool)
-```
-
-Show overlay with layout specified. Shows player inventory also if playerinv is **true**
-
-> [!NOTE]
-> Only one block may be open at same time
-
-```python
-hud.open_permanent(layoutid: str)
-```
-
-Add element to the screen. The element will be removed on world close only.
-**inventory** element will be bound to the player inventory.
-
-```python
-hud.close(layoutid: str)
-```
-
-Remove an element from the screen
-
-
-```python
-hud.get_block_inventory() -> int
-```
-
-Get open block inventory ID or 0.
-
-```python
-hud.get_player() -> int
-```
-
-Gives the ID of the player that the UI is bound to.
-
-```python
-hud.pause()
-```
-
-Opens the pause menu
-
-```python
-hud.resume()
-```
-
-Closes the pause menu.
-
-```python
-hud.is_paused() -> bool
-```
-
-Returns true if pause menu is open.
-
-```python
-hud.is_inventory_open() -> bool
-```
-
-Returns true if inventory is open or overlay is shown.
-
-### *time* library
-
-```python
-time.uptime() -> float
-```
-
-Returns time elapsed since the engine started.
-
-```python
-time.delta() -> float
-```
-
-Returns time elapsed since the last frame.
diff --git a/doc/en/scripting/builtins/libgui.md b/doc/en/scripting/builtins/libgui.md
new file mode 100644
index 00000000..5ec2490f
--- /dev/null
+++ b/doc/en/scripting/builtins/libgui.md
@@ -0,0 +1,41 @@
+# *gui* library
+
+The library contains functions for accessing the properties of UI elements. Instead of gui, you should use an object wrapper that provides access to properties through the __index, __newindex meta methods:
+
+Example:
+
+```lua
+print(document.some_button.text) -- where 'some_button' is an element id
+document.some_button.text = "new text"
+```
+
+```python
+gui.str(text: str, context: str) -> str
+```
+
+Returns translated text.
+
+```python
+gui.get_viewport() -> {int, int}
+```
+
+Returns size of the main container (window).
+
+```python
+gui.get_env(document: str) -> table
+```
+
+Returns environment (global variables table) of the specified document.
+
+```lua
+gui.get_locales_info() -> table of tables {
+  name: str
+ }
+-- where
+--   key - locale id following isolangcode_ISOCOUNTRYCODE format
+--   value - table {
+--       name: str # locale display name
+--   }
+```
+
+Returns information about all loaded locales (res/texts/\*).
diff --git a/doc/en/scripting/builtins/libhud.md b/doc/en/scripting/builtins/libhud.md
new file mode 100644
index 00000000..b823ab50
--- /dev/null
+++ b/doc/en/scripting/builtins/libhud.md
@@ -0,0 +1,50 @@
+# *hud* library
+
+```lua
+-- Open player inventory.
+hud.open_inventory()
+
+-- Close inventory.
+hud.close_inventory()
+
+-- Open block UI and inventory. 
+-- Throws an exception if block has no UI layout.
+-- Returns block inventory ID (if *"inventory-size"=0* a virtual 
+-- inventory will be created), and UI layout ID.
+hud.open_block(x: int, y: int, z: int) -> int, str
+```
+
+> [!NOTE]
+> Only one block may be open at same time
+
+```lua
+-- Show overlay with layout specified.
+-- Shows player inventory also if playerinv is true.
+hud.show_overlay(layoutid: str, playerinv: bool)
+
+-- Add element to the screen. 
+-- The element will be removed on world close only.
+-- inventory element will be bound to the player inventory.
+hud.open_permanent(layoutid: str)
+
+-- Remove an element from the screen.
+hud.close(layoutid: str)
+
+-- Get open block inventory ID or 0.
+hud.get_block_inventory() -> int
+
+-- Gives the ID of the player that the UI is bound to.
+hud.get_player() -> int
+
+-- Opens the pause menu
+hud.pause()
+
+-- Closes the pause menu.
+hud.resume()
+
+-- Returns true if pause menu is open.
+hud.is_paused() -> bool
+
+-- Returns true if inventory is open or overlay is shown.
+hud.is_inventory_open() -> bool
+```
diff --git a/doc/en/scripting/builtins/libinventory.md b/doc/en/scripting/builtins/libinventory.md
new file mode 100644
index 00000000..a719878a
--- /dev/null
+++ b/doc/en/scripting/builtins/libinventory.md
@@ -0,0 +1,56 @@
+# *inventory* library
+
+Library for inventories interaction.
+
+```lua
+-- ID = 0 (core:empty) means that slot is empty.
+inventory.get(
+    -- inventory ID
+    invid: int,
+    -- slot index
+    slot: int
+) -> int, int
+-- Returns item ID and count. 
+
+-- Set slot content.
+inventory.set(
+    -- inventory ID
+    invid: int,
+    -- slot index
+    slot: int,
+    -- item index
+    itemid: int,
+    -- item count
+    count: int
+)
+
+-- Returns inventory size (slots number). 
+-- Throws an exception if there's no inventory having specified ID.
+inventory.size(invid: int) -> int
+
+-- Add an item to the specified inventory. 
+-- Returns remaining count if could not to add fully.
+inventory.add(invid: int, itemid: int, count: int) -> int
+
+-- Returns block inventory ID or 0.
+inventory.get_block(x: int, y: int, z: int) -> int
+
+-- Bind inventory to the specified block.
+inventory.bind_block(invid: int, x: int, y: int, z: int)
+
+-- Unbind inventory from the specified block.
+inventory.unbind_block(x: int, y: int, z: int)
+```
+
+> [!WARNING]
+> Unbound inventories will be deleted on world close.
+
+```lua
+-- Create inventory copy. Returns the created copy ID.
+inventory.clone(invid: int) -> int
+
+-- Move item from slotA of invA to slotB of invB. 
+-- invA may be the same as invB.
+-- If slotB will be chosen automaticly if argument is not specified.
+inventory.move(invA: int, slotA: int, invB: int, slotB: int)
+```
diff --git a/doc/en/scripting/builtins/libtime.md b/doc/en/scripting/builtins/libtime.md
new file mode 100644
index 00000000..8fcd4035
--- /dev/null
+++ b/doc/en/scripting/builtins/libtime.md
@@ -0,0 +1,13 @@
+# *time* library
+
+```python
+time.uptime() -> float
+```
+
+Returns time elapsed since the engine started.
+
+```python
+time.delta() -> float
+```
+
+Returns time elapsed since the last frame.
diff --git a/doc/en/scripting/builtins/libworld.md b/doc/en/scripting/builtins/libworld.md
new file mode 100644
index 00000000..143fded1
--- /dev/null
+++ b/doc/en/scripting/builtins/libworld.md
@@ -0,0 +1,40 @@
+# *world* library
+
+```lua
+world.get_list() -> tables array {
+    -- world name
+    name: str,
+    -- world icon/preview (loading automatically)
+    icon: str
+}
+
+-- Returns current day time in range \[0.0-1.0\] 
+-- where 0.0 and 1.0 - midnight, 0.5 - noon.
+world.get_day_time() -> number
+
+-- Set day time value.
+world.set_day_time(time: number)
+
+-- Sets the specified day time cycle speed.
+world.set_day_time_speed(value: number)
+
+-- Returns the day time cycle speed.
+world.get_day_time_speed() -> number
+
+-- Returns total time passed in the world.
+world.get_total_time() -> number
+
+-- Returns world seed.
+world.get_seed() -> int
+
+-- Proves that this is the current time during the day 
+-- from 0.333(8 am) to 0.833(8 pm).
+world.is_day() -> boolean
+
+-- Checks that it is the current time at night
+-- from 0.833(8 pm) to 0.333(8 am).
+world.is_night() -> bool
+
+-- Checks the existence of a world by name.
+world.exists() -> bool
+```