update doc/ru structure & update docs (ru)

2024-06-13 18:41:38 +03:00
parent 607d30fd33
commit dbe98959d1
18 changed files with 55 additions and 16 deletions
@@ -0,0 +1,126 @@
+# События движка
+
+## События блоков
+
+Функции для обработки событий, прописываемые в скрипте блока.
+
+```lua
+function on_placed(x, y, z, playerid)
+```
+
+Вызывается после установки блока игроком
+
+```lua
+function on_broken(x, y, z, playerid)
+```
+
+Вызывается после разрушения блока игроком
+
+```lua
+function on_interact(x, y, z, playerid) -> bool
+```
+
+Вызывается при нажатии на блок ПКМ. Предотвращает установку блоков, если возвращает `true`
+
+```lua
+function on_update(x, y, z)
+```
+
+Вызывается при обновлении блока (если изменился соседний блок)
+
+```lua
+function on_random_update(x, y, z)
+```
+
+Вызывается в случайные моменты времени (рост травы на блоках земли)  
+
+```lua
+function on_blocks_tick(tps: int)
+```
+
+Вызывается tps (20) раз в секунду
+
+## События предметов
+
+Функции для обработки событий, прописываемые в скрипте предмета.
+
+```lua
+function on_use(playerid: int)
+```
+
+Вызывается при нажатии ПКМ не на блок.
+
+```lua
+
+function on_use_on_block(x: int, y: int, z: int, playerid: int)
+
+```
+
+Вызывается при нажатии ПКМ на блок. Предотвращает установку блока, прописанного в `placing-block` если возвращает `true`
+
+```lua
+function on_block_break_by(x: int, y: int, z: int, playerid: int)
+```
+
+Вызывается при нажатии ЛКМ на блок (в т.ч неразрушимый). Предотвращает разрушение блока, если возвращает `true`
+
+## События мира  
+
+События мира для контент-пака прописываются в `scripts/world.lua`
+
+```lua
+function on_world_open()
+```
+
+Вызывается при загрузке мира
+
+```lua
+function on_world_save()
+```  
+
+Вызывается перед сохранением мира
+
+```lua
+function on_world_tick()
+```
+
+Вызывается 20 раз в секунду
+
+```lua
+function on_world_quit()
+```
+
+Вызывается при выходе из мира (после сохранения)
+## События макета
+
+События прописываются в файле `layouts/имя_макета.xml.lua`.
+
+```lua
+function on_open(invid: int, x: int, y: int, z: int)
+```
+
+Вызывается при добавлении элемента на экран.
+- При отсутствии привязки к инвентарю invid будет равен 0.
+- При отсутствии привязки к блоку x, y, z так же будут равны 0. 
+
+```lua
+function on_close(invid: int)
+```
+
+Вызывается при удалении элемента с экрана.
+
+## События HUD  
+
+События связанные с игровым интерфейсом прописываются в файле `scripts/hud.lua`
+
+```lua
+function on_hud_open(playerid: int)
+```
+
+Вызывается после входа в мир, когда становится доступна библиотека hud. Здесь на экран добавляются постоянные элементы.
+
+```lua
+function on_hud_close(playerid: int)
+```
+
+Вызывается при выходе из мира, перед его сохранением.
@@ -0,0 +1,137 @@
+## Библиотека *file*
+
+Библиотека функций для работы с файлами
+
+```python
+file.resolve(путь: str) -> str
+```  
+
+Функция приводит запись `точка_входа:путь` (например `user:worlds/house1`) к обычному пути. (например `C://Users/user/.voxeng/worlds/house1`)
+
+> [!NOTE]
+> Функцию не нужно использовать в сочетании с другими функциями из библиотеки, так как они делают это автоматически
+
+Возвращаемый путь не является каноническим и может быть как абсолютным, так и относительным.
+
+```python
+file.read(путь: str) -> str
+```
+
+Читает весь текстовый файл и возвращает в виде строки
+
+```python
+file.read_bytes(путь: str) -> array of integers
+```
+
+Читает файл в массив байт.
+
+```python
+file.write(путь: str, текст: str) -> nil
+```
+
+Записывает текст в файл (с перезаписью)
+
+```python
+file.write_bytes(путь: str, data: array of integers)
+```
+
+Записывает массив байт в файл (с перезаписью)
+
+```python
+file.length(путь: str) -> int
+```
+
+Возвращает размер файла в байтах, либо -1, если файл не найден
+
+```python
+file.exists(путь: str) -> bool
+```
+
+Проверяет, существует ли по данному пути файл или директория
+
+```python
+file.isfile(путь: str) -> bool
+```
+
+Проверяет, существует ли по данному пути файл
+
+```python
+file.isdir(путь: str) -> bool
+```
+
+Проверяет, существует ли по данному пути директория
+
+```python
+file.mkdir(путь: str) -> bool
+```
+
+Создает директорию. Возвращает true если была создана новая директория
+
+```python
+file.mkdirs(путь: str) -> bool
+```
+
+Создает всю цепочку директорий. Возвращает true если были созданы директории.
+
+```python
+file.find(путь: str) -> str
+```
+
+Ищет файл от последнего пака до res. Путь указывается без префикса. Возвращает путь с нужным префиксом. Если файл не найден, возвращает nil.
+
+```python
+file.remove(путь: str) -> bool
+```
+
+Удаляет файл. Возращает **true** если файл существовал. Бросает исключение при нарушении доступа.
+
+```python
+file.remove_tree(путь: str) -> int
+```
+
+Рекурсивно удаляет файлы. Возвращает число удаленных файлов.
+
+## Библиотека json
+
+Библиотека содержит функции для сериализации и десериализации таблиц:
+
+```python
+json.tostring(object: table, human_readable: bool=false) -> str
+```
+
+Сериализует объект в JSON строку. При значении второго параметра **true** будет использовано многострочное форматирование, удобное для чтения человеком, а не компактное, использующееся по-умолчанию.
+
+```python
+json.parse(code: str) -> table
+```
+
+Парсит JSON строку в таблицу.
+
+## Библиотека toml
+
+Библиотека содержит функции для сериализации и десериализации таблиц:
+
+```python
+toml.tostring(object: table) -> str
+```
+
+Сериализует объект в TOML строку.
+
+```python
+toml.parse(code: str) -> table
+```
+
+Парсит TOML строку в таблицу.
+
+## Сохранение данных в мире
+
+При сохранении данных пака в мире следует использовать функцию  
+```python
+pack.data_file(packid: str, filename: str) -> str
+```
+
+Функция возвращает путь к файлу данных по типу: `world:data/packid/filename`
+
+и создает недостающие директории в пути.
+
+При использовании путей не соответствующим `data/{packid}/...` возможна потеря данных при перезаписи мира.
@@ -0,0 +1,191 @@
+# Вектора
+## Vector2
+### Операции над векторами
+
+
+```lua
+function vector2:round(decimals: number) -> round[vec2]
+```
+Округление компонентов вектора
+```lua
+function vector2:len() -> number
+```
+Длина вектора
+
+```lua
+function vector2:norm() -> number
+```
+Нормализация вектора
+
+```lua
+function vector2:abtw(vector: vec2) -> number
+```
+Угол между двумя векторами в радианах
+
+
+```lua
+function vector2:proj(vector: vec2) -> vec2
+```
+Проекция вектора
+
+```lua
+function vector2:dot(vector: vec2) -> number
+```
+Векторное (внутреннее) произведение
+
+```lua
+function vector2:lerp(
+                     --Целевой вектор
+                     b: vec2, 
+                     --Интерполяционный коэффициент (от 0 до 1)
+                     t: number
+                     ) -> vec2
+```
+Линейная интерполяция вектора
+
+```lua
+function vector2:dist(vector: vec2) -> number
+```
+Дистанция между двумя векторами
+
+```lua
+function vector2:cross(vector: vec2) -> number
+```
+Векторное (внешнее) произведение
+
+```lua
+function vector2:rot(
+                    --Угол поворота вектора на заданный угол (в радианах)
+                    angle: number->rad, 
+                    --Вращение вектора относительно осей ("x", "y", "z")
+                    axis: str, 
+                    --Если истина, то угол поворота певеодится автоматический из градусы в радианы
+                    convert2deg: bool
+                    ) -> vec2
+```
+Поворот вектора
+
+### Операции с векторами
+
+```lua
+    local vec2 = require("res:vector2")
+
+    local v1 = vec2(5, 10)
+    local v2 = vec2(10, 15)
+    
+    -- vec2 .. vec2
+    sum_vectors = v1 + v2 -- (15, 25)
+    sub_vectors = v1 - v2 -- (-5, -5)
+    mul_vectors = v1 * v2 -- (50, 150)
+    div_vectors = v1 / v2 -- (0.5, 0.66667.)
+    pow_vectors = v1 ^ v2 -- (9765625, 1e+15)
+
+    --vec2 .. scalar
+    sum_vec2_scalar = v1 + 10 -- (15, 25)
+    sub_vec2_scalar = v1 - 12 -- (-7, -2)
+    mul_vec2_scalar = v1 * 20 -- (100, 200)
+    div_vec2_scalar = v1 / 1 -- (5, 10)
+    pow_vec2_scalar= v1 ^ 2 -- (25, 100)
+```
+
+
+
+## Vector3
+### Операции над векторами
+
+```lua
+function vector3:round(decimals: number) -> round[vec3]
+```
+Округление компонентов вектора
+```lua
+function vector3:len() -> number
+```
+Длина вектора
+
+```lua
+function vector3:norm() -> number
+```
+Нормализация вектора
+
+```lua
+function vector3:abtw(vector: vec3) -> number
+```
+Угол между двумя векторами в радианах
+
+```lua
+function vector3:isParallel(vector: vec3) -> bool
+```
+Параллельность вектора к другому вектору
+
+
+```lua
+function vector3:proj(vector: vec3) -> vec3
+```
+Проекция вектора
+...
+
+```lua
+function vector3:dot(vector: vec3) -> number
+```
+Векторное (внутреннее) произведение
+
+```lua
+function vector3:lerp(
+                     --Целевой вектор
+                     b: vec3, 
+                     --Интерполяционный коэффициент (от 0 до 1)
+                     t: number
+                     ) -> vec3
+```
+Линейная интерполяция вектора
+
+```lua
+function vector3:dist(vector: vec3) -> number
+```
+Дистанция между двумя векторами
+
+```lua
+function vector3:dist2line(point1: vec3, point2: vec3) -> number
+```
+Дистанция до линии
+
+```lua
+function vector3:cross(vector: vec3) -> number
+```
+Векторное (внешнее) произведение
+
+```lua
+function vector3:rot(
+                    --Угол поворота вектора на заданный угол (в радианах)
+                    angle: number->rad, 
+                    --Вращение вектора относительно осей ("x", "y", "z")
+                    axis: str, 
+                    --Если истина, то угол поворота певеодится автоматический из градусы в радианы
+                    convert2deg: bool
+                    ) -> vec2
+```
+Поворот вектора
+
+### Операции с векторами
+
+```lua
+    
+local vec3 = require("res:vector3")
+
+local v1 = vec3(1, 2, 3)
+local v2 = vec3(4, 5, 6)
+
+-- vec3.. vec3
+local sum_vectors = v1 + v2 -- (5, 7, 9)
+local sub_vectors = v1 - v2 -- (-3, -3, -3)
+local mul_vectors = v1 * v2 -- (4, 10, 18)
+local div_vectors = v1 / v2 -- (0.25, 0.4, 0.5)
+local pow_vectors = v1 ^ v2 -- (1, 32, 216)
+
+-- vec3.. scalar
+local scalar_vector = v1 * 2 -- (2, 4, 6)
+local scalar_number = 2 * v1 -- (2, 4, 6)
+-- ..etc
+
+```
+
@@ -0,0 +1,91 @@
+## Конвертация значений в байты и обратно
+
+```lua
+function bit_converter.string_to_bytes(string: str) -> table
+```
+Конвертирует строку в байты
+
+```lua
+function bit_converter.bool_to_byte(boolean: bool) -> integer
+```
+Конвертирует логический булев в байт
+
+```lua
+function bit_converter.single_to_bytes(number: single) -> table
+```
+Конвертирует плавающее значение одинарной точности в байты
+
+```lua
+function bit_converter.double_to_bytes(number: double) -> table
+```
+Конвертирует плавающее значение двойной точности в байты
+
+```lua
+function bit_converter.uint16_to_bytes(integer: int) -> table
+```
+Конвертирует беззнаковое 2-х битное целое число в байты
+
+```lua
+function bit_converter.uint32_to_bytes(integer: int) -> table
+```
+Конвертирует беззнаковое 4-х битное целое число в байты
+
+```lua
+function bit_converter.int16_to_bytes(integer: int) -> table
+```
+Конвертирует знаковое 2-х битное целое число в байты
+
+```lua
+function bit_converter.int32_to_bytes(integer: int) -> table
+```
+Конвертирует знаковое 4-х битное целое число в байты
+
+```lua
+function bit_converter.int64_to_bytes(integer: int) -> table
+```
+Конвертирует знаковое 8-и битное целое число в байты
+
+```lua
+function bit_converter.bytes_to_string(table: bytes) -> string
+```
+Конвертирует массив байтов в строку
+
+```lua
+function bit_converter.byte_to_bool(integer: byte) -> boolean
+```
+Конвертирует байт в логическое булевое значение
+
+```lua
+function bit_converter.bytes_to_single(table: bytes) -> number№
+```
+Конвертирует массив байтов в плавающее число одинарной точности
+
+```lua
+function bit_converter.bytes_to_double(table: bytes) -> number
+```
+Конвертирует массив байтов в плавающее число двойной точности
+
+```lua
+function bit_converter.bytes_to_uint16(table: bytes) -> integer
+```
+Конвертирует массив байтов в 2-х битное беззнаковое число
+
+```lua
+function bit_converter.bytes_to_uint32(table: bytes) -> integer
+```
+Конвертирует массив байтов в 4-х битное беззнаковое число
+
+```lua
+function bit_converter.bytes_to_int16(table: bytes) -> integer
+```
+Конвертирует массив байтов в 2-х битное знаковое число
+
+```lua
+function bit_converter.bytes_to_int32(table: bytes) -> integer
+```
+Конвертирует массив байтов в 4-х битное знаковое число
+
+```lua
+function bit_converter.bytes_to_int64(table: bytes) -> integer
+```
+Конвертирует массив байтов в 8-х битное знаковое число
@@ -0,0 +1,153 @@
+## Буффер данных
+### Хранит в себе массив байтов и позволяет легко получать или добавлять разные значения
+
+```lua
+function data_buffer(bytes)
+```
+Создаёт новый экземпляр data_buffer (параметр bytes необязательный)
+
+```lua
+function data_buffer:put_byte(integer: byte)
+```
+Записывает байт в буффер
+
+```lua
+function data_buffer:put_bytes(table: bytes)
+```
+Записывает байты в буффер
+
+```lua
+function data_buffer:put_string(string: str)
+```
+Конвертирует строку в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_bool(boolean: bool)
+```
+Конвертирует булевое значение в байт и записывает его в буффер
+
+```lua
+function data_buffer:put_single(number: single)
+```
+Конвертирует плавающее число одинарной точности в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_double(number: double)
+```
+Конвертирует плавающее число двойной точности в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_uint16(integer: int)
+```
+Конвертирует беззнаковое 2-х битное число в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_uint32(integer: int)
+```
+Конвертирует беззнаковое 4-х битное число в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_int16(integer: int)
+```
+Конвертирует знаковое 2-х битное число в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_int32(integer: int)
+```
+Конвертирует знаковое 4-х битное число в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_int64(integer: int)
+```
+Конвертирует знаковое 8-и битное число в байты и записывает их в буффер
+
+```lua
+function data_buffer:put_number(number: num)
+```
+Конвертирует любое число в байты и записывает их в буффер;
+
+Первый байт это тип значения:
+```lua
+zero = 0
+uint16 = 1
+uint32 = 2
+int16 = 3
+int32 = 4
+int64 = 5
+double = 6
+```
+
+```lua
+function data_buffer:get_byte() -> integer
+```
+Возвращает следующий байт из буффера
+
+```lua
+function data_buffer:get_bytes(n) -> table
+```
+Возвращает n следующих байтов, если n равен nil или не указан, то возвращается массив всех байтов
+
+```lua
+function data_buffer:get_string() -> string
+```
+Читает следующую строку из буффера
+
+```lua
+function data_buffer:get_bool() -> boolean
+```
+Читает следующий логический булев из буффера
+
+```lua
+function data_buffer:get_single() -> number
+```
+Читает следующее плавающее число одинарной точности из буффера
+
+```lua
+function data_buffer:get_double() -> number
+```
+Читает следующее плавающее число двойной точности из буффера
+
+```lua
+function data_buffer:get_uint16() -> integer
+```
+Читает следующее 2-х битное беззнаковое целое число из буффера
+
+```lua
+function data_buffer:get_uint32() -> integer
+```
+Читает следующее 4-х битное беззнаковое целое число из буффера
+
+```lua
+function data_buffer:get_int16() -> integer
+```
+Читает следующее 2-х битное знаковое целое число из буффера
+
+```lua
+function data_buffer:get_int32() -> integer
+```
+Читает следующее 4-х битное знаковое целое число из буффера
+
+```lua
+function data_buffer:get_int64() -> integer
+```
+Читает следующее 8-х битное знаковое целое число из буффера
+
+```lua
+function data_buffer:get_number() -> number
+```
+Читает следующее число (см. data_buffer:put_number)
+
+```lua
+function data_buffer:size() -> integer
+```
+Возвращает размер буффера
+
+```lua
+function data_buffer:set_position(integer: pos)
+```
+Устанавливает текущую позицию в буффере
+
+```lua
+function data_buffer:set_bytes(table: bytes)
+```
+Устанавливает байты в буффер
@@ -0,0 +1,59 @@
+# Пользовательский ввод
+
+Обработка нажатий клавиш и кнопок мыши обрабатываются через привязки (bindings), которые назначаются в паке, в файле `config/bindings.toml` в формате:
+
+```toml
+packid.binding.name="inputtype:codename"
+```
+
+- packid - опционально, но желательно
+- inputtype - key или mouse
+- codename - имя клавиши или кнопки мыши (left/right/middle)
+
+## Имена клавиш
+
+- space, backspace, tab, enter, caps-lock, escape
+- left-ctrl, left-shift, left-alt, left-super
+- right-ctrl, right-shift, right-alt, right-super
+- delete, home, end, insert, page-up, page-down
+- left, right, down, up
+- a..z
+- 0..9
+- f1..f25
+
+## Библиотека input
+
+```python
+input.keycode(keyname: str) -> int
+```
+
+Возвращает код клавиши по имени, либо -1
+
+```python
+input.mousecode(mousename: str) -> int
+```
+
+Возвращает код кнопки мыши по имени, либо -1
+
+```python
+input.add_callback(bindname: str, callback: function)
+```
+
+Назначает функцию, которая будет вызываться при активации привязки. Пример:
+```lua
+input.add_callback("hud.inventory", function ()
+	print("Inventory open key pressed")
+end)
+```
+
+```python
+input.get_mouse_pos() -> {int, int}
+```
+
+Возвращает позицию курсора на экране.
+
+```python
+input.get_bindings() -> массив строк
+```
+
+Возвращает названия всех доступных привязок.