Project wiki moved to doc folder + english translation (#182)

doc/ru/0.Главная.md

@@ -0,0 +1,13 @@
+# Разделы
+
+- [Рекомендации по использованию движка](1.Рекомендации-по-использованию-движка.md)
+- [Контент‐паки](2.Контент‐паки.md)
+- [Свойства блоков](3.Свойства-блоков.md)
+- [Свойства предметов](4.Свойства-предметов.md)
+- [XML разметка интерфейса](5.XML-разметка-интерфейса.md)
+- [Предзагрузка ассетов](6.Предзагрузка-ассетов.md)
+- [Аудио](7.Аудио.md)
+- [Скриптинг](8.Скриптинг.md)
+    - [Модуль core:bit_converter](8.1.Модуль-Lua-core_bit_converter.md)
+    - [Модуль core:data_buffer](8.2.Модуль-Lua-core_data_buffer.md)
+- [Модели блоков](9.Модели-блоков.md)

doc/ru/1.Рекомендации-по-использованию-движка.md

@@ -0,0 +1,30 @@
+# Рекомендации по использованию движка
+
+## Наименование контента
+
+### ID контент-паков
+
+Идентификатор контент-пака должен следовать следующим требованиям:
+- название может состоять только из букв латиницы, цифр и символа подчёркивания '\_'
+- название не может начинаться с цифры
+- длина названия должна находиться в пределах от 2 до 24 включительно
+
+### Блоки и предметы
+
+- id блоков и предметов следуют тем же требованиям, что и ID контент-пака.
+- окончание `.item` добавляется только для замены сгенерированного для блока предмета. Пример: `base:stone.item` - предмет сгенерированный для блока камня.
+- поле **caption**, предназначенное для отображения названия в инвентаре, не указывается с заглавной буквы, без необходимости. Движок автоматически повышает регистр при отображении в интерфейсе.
+
+## Хранение файлов
+
+### Данные контент-паков
+
+Настройки, состояние, которое нужно сохранять в мире, должны находиться в `world:data/id_пака/`. Путь следует получать через специальную функцию: 
+```lua
+local path = pack.data_file(PACK_ID, "имя_файла")
+file.write(path, данные)
+-- запишет данные в файл world:data/PACK_ID/имя_файла
+```
+Здесь PACK_ID является доступной константой, т.е не нужно вписывать имя пака самостоятельно.
+
+Папка `world:data/PACK_ID` будет создана при вызове `pack.data_file`.

doc/ru/2.Контент‐паки.md

@@ -0,0 +1,39 @@
+# Контент-паки
+
+Для создания контент-пака сначала нужно придумать ему название (id) соответствующее следующим требованиям:
+- название может состоять только из букв латиницы, цифр и символа подчёркивания '\_'
+- название не может начинаться с цифры
+- длина названия должна находиться в пределах от 2 до 24 включительно
+
+Далее в *res/content* создаётся папка с выбранным названием контент-пака.
+
+В созданной папке создаётся файл **package.json** с следующим содержимым:
+```json
+{
+    "id": "выбранное_имя_пака",
+    "title": "имя контент-пака для отображения в меню контента",
+    "version": "версия контент-пака в формате major.minor",
+    "creator": "создатель контент-пака",
+    "description": "краткое описание",
+    "dependencies": [
+        "зависимости",
+        "пакета"
+    ]
+}
+```
+
+Пример:
+```json
+{
+    "id": "doors",
+    "title": "DOORS",
+    "creator": "MihailRis",
+    "version": "1.0",
+    "description": "doors test"
+}
+```
+
+Изображение контент-пака добавляется в виде файла *icon.png* в папку пака (не в textures). Рекомендованный размер изображения: 128x128
+
+Новые блоки добавляются в под-папку **blocks**, предметы в **items**, текстуры в **textures**
+С примером файловой структуры лучше ознакомиться через базовый пакет (*res/content/base*)

doc/ru/3.Свойства-блоков.md

@@ -0,0 +1,131 @@
+# Вид
+
+## Текстура - `texture`
+
+Название текстуры блока (указывается только имя, без расширения или пути к файлу)
+
+Файл текстуры должен находиться в `res/textures/blocks/` и иметь формат **png**
+
+## Текстурирование сторон - `texture-faces`
+
+>[!IMPORTANT]
+> Не может использоваться одновременно с `texture`
+
+Массив из 6 названий текстур, позволяющих указать их для каждой из сторон отдельно.
+
+Пример: 
+```json
+"texture-faces": [
+    "grass_side",
+    "grass_side",
+    "dirt",
+    "grass_top",
+    "grass_side",
+    "grass_side"
+]
+```
+
+## Модель - `model`
+
+Модель блока из списка:
+- "block" - используется по-умолчанию для всех обычных блоков
+- "none" - невидимый блок (пример: воздух)
+- "X" - модель травы (крест из двух спрайтов)
+- "aabb" - модель, соответствующая хитбоксу блока (составной хитбокс будет объединен в один). Примеры: трубы, лампочки, панели.
+
+## Группа отрисовки - `draw-group`
+
+Целое число определяющее номер группы отрисовки данного блока. 
+Актуально для полупрозрачных блоков - решает проблемы невидимых сторон блоков за этим блоком.
+
+## Вращение - `rotation`
+
+Профиль вращения (набор положений, в которые можно установить блок) из списка:
+
+- "none" - вращение блока отключено (по-умолчанию)
+- "pipe" - профиль "труба". Примеры блоков: бревно, труба, лампочка
+- "pane" - профиль "панель". Примеры блоков: панель, дверь, табличка
+
+# Освещение
+
+## Излучение - `emission`
+
+Массив из трех целых чисел - R, G, B освещения от 0 до 15.
+
+Примеры:
+
+- `[15, 15, 15]` - самый яркий белый свет
+- `[7, 0, 0]` - слабый красный свет
+- `[0, 0, 0]` - блок не излучает свет (по-умолчанию)
+
+
+## Светопроводимость - `light-passing`
+
+При значении `true` блок проводит свет от излучающих блоков.
+
+## Солнечная светопроводимость - `sky-light-passing`
+
+При значении `true` блок не препятствует прохождению вертикального луча солнечного света.
+
+# Физика
+
+## Препятствие - `obstacle`:
+
+Значение false отключает хитбокс у блока (позволяет игроку проходить сквозь блок)
+
+## Хитбокс - `hitbox`:
+
+Массив из 6 чисел описывающих смещение и размер хитбокса блока.
+
+Числа указываются в диапазоне [0.0, 1.0] - т.е в пределах блока.
+
+Массив `[0.25, 0.0, 0.5,  0.75, 0.4, 0.3]` описывает хитбокс: 
+- шириной (с востока на запад) 0.75 м
+- высотой 0.4 м
+- длиной (с юга на север) 0.3 м
+- смещен на 0.25 м на запад
+- смещен на 0.0 м вверх
+- смещен на 0.5 м на север
+
+## Приземленность - `grounded`
+
+Блок может быть установлен только на полный блок.
+Разрушается при разрушении блока под ним.
+
+## Выделяемость - `selectable`
+
+При значении в `false` курсор будет игнорировать блок, выделяя тот, что находится за ним.
+
+## Заменяемость - `replaceable`
+
+При значении в `true` на месте блока можно установить любой другой блок. Пример: вода, трава, цветок.
+
+## Разрушаемость - `breakable`
+
+При значении в `false` блок нельзя сломать.
+
+# Инвентарь
+
+## Скрытый блок - `hidden`
+
+При значении в `true` блок не появляется в инвентаре и для него не генерируется предмет, поэтому c 0.17 требуется указать свойство `picking-item`
+
+## Подбираемый предмет - `picking-item`
+
+Предмет, который будет выбран при при нажатии средней кнопкой мыши на блок.
+
+Пример: блок `door:door_open` скрыт (hidden) поэтому указывается `picking-item: "door:door.item"`
+
+## Имя скрипта - `script-name`
+
+Позволяет указать название скрипта блока. Свойство обеспечивает возможность использования одного скрипта для нескольких блоков.
+Название указывается без `пак:scripts/` и расширения.
+
+## Имя макета UI - `ui-layout`
+
+Позволяет указать id XML-макета интерфейса блока. По-умолчанию используется строковый id блока.
+
+## Размер инвентаря - `inventory-size`
+
+Число слотов инвентаря блока. По-умолчанию - 0 (инвентарь отсутствует)
+

doc/ru/4.Свойства-предметов.md

@@ -0,0 +1,38 @@
+# Вид
+
+## Тип иконки - `icon-type` и сама иконка - `icon`
+
+В последней версии движка существуют следующие типы иконок предметов, определяющих то, как предмет будет отображаться в инвентаре:
+- `none` - невидимый тип, используется только для `core:empty` (пустой предмет). Не влияет на появление предмета на панель доступа к контенту. Тип может быть удалён в будущем
+- `sprite` - 2D изображение. Требуется указание свойства icon, состоящее из имени атласа и имени текстуры в этом атласе, разделённые `:`. Пример: `blocks:notfound`. На данный момент в движке существует два текстурных атласа:
+  - blocks (генерируется из png файлов в `res/textures/blocks/`)
+  - items (генерируется из png файлов в `res/textures/items/`)
+- `block` - отображает предпросмотр блока. В icon указывается строковый id блока который нужно отображать. Пример `base:wood`
+
+# Поведение
+
+## Устанавливаемый блок - `placing-block`
+
+При указании строкового id блока предмет устанавливает его при нажатии ПКМ. Именно это свойство используется у всех сгенерированных для блоков предметов.
+
+Пример: предмет ставит блоки базальта:
+
+```json
+"placing-block": "base:bazalt"
+```
+
+## Излучение - `emission`
+
+Влияет на свет излучаемый предметом, когда он находится в руке игрока.
+
+Массив из трех целых чисел - R, G, B освещения от 0 до 15.
+
+Примеры:
+
+- `[15, 15, 15]` - самый яркий белый свет
+- `[7, 0, 0]` - слабый красный свет
+- `[0, 0, 0]` - предмет не излучает свет (по-умолчанию)
+
+## Размер стопки (стека) - `stack-size`
+
+Определяет максимальное количество предмета в одном слоте. Значение по-умолчанию - 64.

doc/ru/5.XML-разметка-интерфейса.md

@@ -0,0 +1,113 @@
+# XML разметка интерфейса
+
+# Специфические типы
+
+**2D вектор** - пара чисел, разделенная запятой.
+Примеры: 
+- `"500,200"`
+- `"0.4,53.01"`
+- `"0,0"`
+
+**3D вектор** - три числа, разделенная запятой.
+Примеры: 
+- `"60,30,53"`
+- `"0.4,0.1,0.753"`
+
+**4D вектор** - четыре числа, разделенная запятой.
+Примеры: 
+- `"10,5,10,3"`
+- `"0.1,0.5,0.0,0.0"`
+
+**RGBA цвет** - на данный момент доступна только HEX запись.
+Примеры:
+- `"#FF8000"` - оранжевый непрозрачный
+- `"#FFFFFF80"` - белый полупрозрачный
+- `"#000000FF"` - черный непрозрачный
+
+# Общие атрибуты элементов
+
+- `id` - идентификатор элемента. Тип: строка.
+- `pos` - позиция элемента. Тип: 2D вектор.
+- `size` - размер элемента. Тип: 2D вектор.
+- `color` - цвет элемента. Тип: RGBA цвет.
+- `margin` - внешний отступ элемента. Тип: 4D вектор. 
+    Порядок: `"left,top,right,bottom"`
+- `visible` - видимость элемента. Тип: логический ("true"/"false").
+- `position-func` - поставщик позиции элемента (два числа), вызываемый при изменении размера контейнера, в котором находится элемент, либо при добавлении элемента в контейнер. Может быть вызван до вызова on_hud_open.
+
+# Общие атрибуты контейнеров
+
+В число контейнеров также входят панели и кнопки.
+- `padding` - внутренний отступ элемента. Тип: 4D вектор.
+    Порядок: `"left,top,right,bottom"`
+- `scrollable` - возможность скроллинга. Работает только у Panel. Тип: логический.
+
+# Общие атрибуты панелей
+
+В число панелей также входят кнопки.
+- `max-length` - максимальная длина, на которую растягивается панель до начала скроллинга (если scrollable = true). Тип: число
+
+# Основные элементы
+
+## Кнопка `button`
+
+Внутренний текст - текст кнопки.
+
+- `text-align` - выравнивание текста ("left", "center" или "right"). Тип: строка.
+- `onclick` - lua функция вызываемая при нажатии на кнопку.
+
+## Изображение `image`
+
+- `src` - имя изображения в папке textures без указания расширения. Тип: строка. Например `gui/error`
+
+## Изображение `image`
+
+- `src` - имя изображения в папке textures без указания расширения. Тип: строка. Например `gui/error`
+
+# Текстовое поле `textbox`
+
+Внутренний текст - изначально введенный текст
+
+- `placeholder` - текст подстановки (используется текстовое поле пусто)
+- `consumer` - lua функция-приемник введенного текста. Вызывается только при завершении ввода
+
+## Ползунок `trackbar`
+
+- `min` - минимальное значение. Тип: число. По-умолчанию: 0
+- `max` - максимальное значение. Тип: число. По-умолчанию: 1
+- `value` - изначальное значение. Тип: число. По-умолчанию: 0
+- `step` - размер деления ползунка. Тип: число. По-умолчанию: 1
+- `track-width` - ширина указателя (в делениях). Тип: число. По-умолчанию: 1
+- `consumer` - lua функция-приемник установленного значения
+- `supplier` - lua функция-поставщик значения
+
+# Элементы инвентаря
+
+## Инвентарь `inventory`
+
+Элемент является контейнером. На данный момент не имеет специфических атрибутов. 
+
+> [!WARNING]
+> Расположение инвентарей управляется движком и не может быть изменено свойствами pos, margin и т.д.
+
+## Одиночный слот `slot`
+
+Элемент должен находиться внутри `inventory` элемента, без посредников.
+- `index` - индекс слота инвентаря. (Нумерация с 0)
+- `item-source` - включает поведение подобное панели контента. Тип: логический
+- `sharefunc` - lua событие вызываемое при использовании ЛКМ + Shift. Передается id инвентаря и индекс слота
+- `updatefunc` - lua событие вызываемое при изменении содержимого слота
+- `onrightclick` - lua событие вызываемое при использовании ПКМ. Передается id инвентаря и индекс слота
+
+## Решетка слотов `slots-grid`
+
+Элемент должен находиться внутри `inventory` элемента, без посредников.
+- `start-index` - индекс первого слота
+- `rows` - число рядов (не указывается, если указано cols).
+- `cols` - число столбцов (не указывается, если указано rows).
+- `count` - общее число слотов (не указывается, если указаны rows и cols). 
+- `interval` - интервал между слотами. Тип: число.
+- `padding` - отступ вокруг решетки слотов. Тип: число.   (*атрибут будет удален*)
+- `sharefunc` - lua событие вызываемое при использовании ЛКМ + Shift. Передается id инвентаря и индекс слота
+- `updatefunc` - lua событие вызываемое при изменении содержимого слота
+- `onrightclick` - lua событие вызываемое при использовании ПКМ. Передается id инвентаря и индекс слота

doc/ru/6.Предзагрузка-ассетов.md

@@ -0,0 +1,54 @@
+# Предзагрузка ассетов (файл *preload.json*)
+
+Для загрузки ассетов, не загружаемых автоматически, такие как звуки, дополнительные текстуры, используется файл `preload.json`, создающийся в папке контент-пака.
+
+Ассеты в файле разделяются на категории:
+- fonts - шрифты
+- shaders - шейдеры
+- textures - текстуры
+- sounds - звуки
+
+> [!NOTE]
+> При загрузке звука подгружаются все его вариации, по шаблону:
+> (звук: sound_name) -> *sound_name.ogg, sound_name_1.ogg, sound_name_2.ogg, ...*
+> или *sound_name_0.ogg, sound_name_1.ogg, sound_name_2.ogg, ...*
+
+Добавление звука `пак:sounds/events/explosion.ogg` со всеми его вариантами:
+```json
+{
+    "sounds": [
+        "events/explosion"
+    ]
+}
+```
+Будет доступен под именем: "events/explosion"
+
+В случае, если нужно будет работать с PCM данными звука (сейчас не доступно из скриптинга), требуется указать параметр `keep-pcm`:
+```json
+{
+    "sounds": [
+        {
+            "name": "events/explosion",
+            "keep-pcm": true
+        }
+    ]
+}
+```
+
+
+Пример файла из пакета `core:` (`res/preload.json`):
+```json
+{
+    "shaders": [
+        "ui3d",
+        "screen",
+        "background",
+        "skybox_gen"
+    ],
+    "textures": [
+        "misc/moon",
+        "misc/sun",
+        "gui/crosshair"
+    ]
+}
+```

doc/ru/7.Аудио.md

@@ -0,0 +1,196 @@
+# Аудио
+
+## Основные понятия
+
+### Бекенд (Backend)
+
+Вариант внутренней реализации звуковой подсистемы, управляющий выводом звука.
+На данный момент в движке существует два:
+- NoAudio - заглушка, используемая при невозможности инициализации OpenAL, либо, при отключенной через файл настроек, аудиосистеме: `[audio] enabled=false`. Данный бекенд загружает PCM данные только по требованию, не создает спикеров при попытке воспроизведения аудио.
+- ALAudio - основной вариант. Вывод звука через OpenAL.
+
+### Канал (Channel)
+
+Определяет категорию источников аудио для регулирования громкости, наложения эффектов, паузы.
+На данный момент существует следующий набор каналов:
+- master - управляет громкостью остальных каналов. Не следует указывать как целевой канал при воспроизведении аудио.
+- ui - звуки интерфейса
+- regular - звуки игрового мира, ставятся на паузу вместе с игрой.
+- ambient - то же, что и regular, но предназначается для фоновых звуков: погода и иной эмбиент.
+- music - канал для воспроизведения музыки. Как правило, потокового аудио.
+
+Каналы управляются самим движком.
+### Спикер (Speaker)
+
+Одноразовый контроллер проигрываемого аудио: звука или потока. Спикер уничтожается после остановки через вызов метода **stop** или при окончании аудио (поток также не удерживает спикер от уничтожения).
+Контроллер продолжает жить при паузе. 
+
+> [!NOTE]
+Доступ к спикерам производится по целочисленным id, которые не повторяются за время работы движка, следует избегать хранения прямых указателей на объекты класса.
+
+Нумерация ID спикеров начинается с 1. ID 0 означает невозможность воспроизведения, по какой-либо причине.
+### Звук (Sound)
+
+Звуковые данные загруженные в память для возможности одновременного воспроизведения из нескольких источников. Может предоставлять доступ к PCM данным.
+
+### Источник PCM (PCMStream)
+
+Поток, используемый потоком как источник PCM-данных. Реализация зависит не от бекенда звуковой системы, а от формата файла. Реализация потокового аудио из сетевого соединения делается через реализацию данного интерфейса.
+
+### Поток (Stream)
+
+Потоковое аудио. Не загружается полностью в память, поэтому не требует предзагрузки через `preload.json`. Не может воспроизводиться через несколько спикеров одновременно.
+
+## Поддержка форматов
+
+На данный момент реализована поддержка двух форматов.
+- WAV: поддерживаются 8 и 16 bit (24 bit не поддерживается OpenAL)
+- OGG: реализовано через библиотеку libvorbis
+
+
+## Дополнительно
+
+> [!WARNING]
+> При воспроизведении через OpenAL стерео звуки не будут учитывать расположение источников относительно игрока. Звуки, которые должны учитывать расположение, должны быть в моно.
+
+## API аудио в скриптинге
+
+### Воспроизведение аудио
+
+Работа с аудио производится с библиотекой `audio`.
+
+```lua
+audio.play_stream(
+    -- путь к аудио-файлу
+    name: string, 
+    -- позиция источника аудио в мире
+    x: number, y: number, z: number,
+    -- громкость аудио (от 0.0 до 1.0)
+    volume: number
+    -- скорость воспроизведения (положительное число)
+    pitch: number,
+    -- [опционально] имя канала: regular/ambient/music/ui (по-умолчанию - regular)
+    channel: string,
+    -- [опционально] зацикливание потока (по-умолчанию - false)
+    loop: bool
+) -> int
+```
+
+Воспроизводит потоковое аудио из указанного файла, на указанной позиции в мире. Возвращает id спикера.
+
+```lua
+audio.play_stream_2d(
+    -- путь к аудио-файлу
+    name: string, 
+    -- громкость аудио (от 0.0 до 1.0)
+    volume: number
+    -- скорость воспроизведения (положительное число)
+    pitch: number,
+    -- [опционально] имя канала: regular/ambient/music/ui (по-умолчанию - regular)
+    channel: string,
+    -- [опционально] зацикливание потока (по-умолчанию - false)
+    loop: bool
+) -> int
+```
+
+Воспроизводит потоковое аудио из указанного файла. Возвращает id спикера.
+
+
+```lua
+audio.play_sound(
+    -- название загруженного звука без префикса пака, "sounds/", номера варианта и расширения 
+    -- пример "steps/stone" для проигрывания звука, загруженного из "sounds/steps/stone.ogg" или любого из его вариантов
+    -- вариант звука выбирается случайно
+    name: string, 
+    -- позиция источника аудио в мире
+    x: number, y: number, z: number,
+    -- громкость аудио (от 0.0 до 1.0)
+    volume: number
+    -- скорость воспроизведения (положительное число)
+    pitch: number,
+    -- [опционально] имя канала: regular/ambient/music/ui (по-умолчанию - regular)
+    channel: string,
+    -- [опционально] зацикливание потока (по-умолчанию - false)
+    loop: bool
+) -> int
+```
+
+Воспроизводит звук на указанной позиции в мире. Возвращает id спикера.
+
+```lua
+audio.play_sound_2d(
+    -- название загруженного звука без префикса пака, "sounds/", номера варианта и расширения 
+    -- пример "steps/stone" для проигрывания звука, загруженного из "sounds/steps/stone.ogg" или любого из его вариантов
+    -- вариант звука выбирается случайно
+    name: string, 
+    -- громкость аудио (от 0.0 до 1.0)
+    volume: number
+    -- скорость воспроизведения (положительное число)
+    pitch: number,
+    -- [опционально] имя канала: regular/ambient/music/ui (по-умолчанию - regular)
+    channel: string,
+    -- [опционально] зацикливание потока (по-умолчанию - false)
+    loop: bool
+) -> int
+```
+
+Воспроизводит звук. Возвращает id спикера.
+
+### Взаимодействие со спикером.
+
+При обращении к несуществующим спикером ничего происходить не будет.
+
+```lua
+-- остановить воспроизведение спикера
+audio.stop(speakerid: integer)
+
+-- поставить спикер на паузу
+audio.pause(speakerid: integer)
+
+-- снять спикер с паузы
+audio.resume(speakerid: integer)
+
+-- установить зацикливание аудио
+audio.set_loop(speakerid: integer, state: bool)
+
+-- проверить, зациклено ли аудио (false если не существует)
+audio.is_loop(speakerid: integer) -> bool
+
+-- получить громкость спикера (0.0 если не существует)
+audio.get_volume(speakerid: integer) -> number
+
+-- установить громкость спикера
+audio.set_volume(speakerid: integer, volume: number)
+
+-- получить скорость воспроизведения (1.0 если не существует)
+audio.get_pitch(speakerid: integer) -> number
+
+-- установить скорость воспроизведения
+audio.set_pitch(speakerid: integer, pitch: number)
+
+-- получить временную позицию аудио в секундах (0.0 если не существует)
+audio.get_time(speakerid: integer) -> number
+
+-- установить временную позицию аудио в секундах
+audio.set_time(speakerid: integer, time: number)
+
+-- получить позицию источника звука в мире (nil если не существует)
+audio.get_position(speakerid: integer) -> number, number, number
+
+-- установить позицию источника звука в мире
+audio.set_position(speakerid: integer, x: number, y: number, z: number)
+
+-- получить скорость движения источника звука в мире (nil если не существует)
+-- (используется OpenAL для имитации эффекта Доплера)
+audio.get_velocity(speakerid: integer) -> number, number, number
+
+-- установить скорость движения источника звука в мире
+-- (используется OpenAL для имитации эффекта Доплера)
+audio.set_velocity(speakerid: integer, x: number, y: number, z: number)
+
+-- получить длительность аудио в секуднах, проигрываемого источником
+-- возвращает 0, если не спикер не существует
+-- так же возвращает 0, если длительность неизвестна (пример: радио)
+audio.get_duration(speakerid: integer) -> number
+```
+

doc/ru/8.1.Модуль-Lua-core_bit_converter.md

@@ -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-х битное знаковое число

doc/ru/8.2.Модуль-Lua-core_data_buffer.md

@@ -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)
+```
+Устанавливает байты в буффер

doc/ru/8.Скриптинг.md

@@ -0,0 +1,513 @@
+# Скриптинг
+
+В качестве языка сценариев используется LuaJIT
+
+## Функции, доступные в скриптах
+
+```lua
+load_script("контентпак:scripts/имя_скрипта.lua") -- загружает скрипт, если ещё не загружен
+load_script("контентпак:scripts/имя_скрипта.lua", true) -- перезагружает скрипт
+require "контентпак:имя_модуля" -- загружает lua модуль из папки modules (расширение не указывается)
+```
+
+## Библиотека player
+```python
+player.get_pos(playerid: int) -> number, number, number
+```
+Возвращает x, y, z координаты игрока
+
+```python
+player.set_pos(playerid: int, x: number, y: number, z: number)
+```
+
+Устанавливает x, y, z координаты игрока
+
+```python
+player.get_rot(playerid: int) -> number, number
+```
+
+Возвращает x, y вращения камеры (в радианах)
+
+```python
+player.set_rot(playerid: int, x: number, y: number, z: number)
+```
+
+Устанавливает x, y вращения камеры (в радианах)
+
+```python
+player.get_inventory(playerid: int) -> int, int
+```
+
+Возвращает id инвентаря игрока и индекс выбранного слота (от 0 до 9)
+
+## Библиотека world
+
+```python
+world.get_day_time() -> number
+```
+
+Возвращает текущее игровое время от 0.0 до 1.0, где 0.0 и 1.0 - полночь, 0.5 - полдень.
+
+```python
+world.set_day_time(time: number)
+```
+
+Устанавливает указанное игровое время.
+
+```python
+world.get_total_time() -> number
+```
+
+Возвращает общее суммарное время, прошедшее в мире
+
+```python
+world.get_seed() -> int
+```
+
+Возвращает зерно мира.
+
+## Библиотека gui
+
+Библиотека содержит функции для доступа к свойствам UI элементов. Вместо gui следует использовать объектную обертку, предоставляющую доступ к свойствам через мета-методы __index, __newindex:
+```lua
+local inventory_doc = Document.new("id-макета")
+print(inventory_doc.some_button.text)
+indentory_doc.some_button.text = "new text"
+```
+
+В скрипте макета `layouts/файл_макета.xml` - `layouts/файл_макета.xml.lua` уже доступна переменная **document** содержащая объект класса Document
+
+## Библиотека inventory
+
+Библиотека функций для работы с инвентарем.
+
+```python
+inventory.get(invid: int, slot: int) -> int, int
+```
+
+Принимает id инвентаря и индекс слота. Возвращает id предмета и его количество. id = 0 (core:empty) обозначает, что слот пуст.
+
+```python
+inventory.set(invid: int, slot: int, itemid: int, count: int)
+```
+
+Устанавливает содержимое слота.
+
+```python
+inventory.size(invid: int) -> int
+```
+
+Возращает размер инвентаря (число слотов). Если указанного инвентаря не существует, бросает исключение.
+
+```python
+inventory.add(invid: int, itemid: int, count: int) -> int
+```
+
+Добавляет предмет в инвентарь. Если не удалось вместить все количество, возвращает остаток.
+
+```python
+inventory.get_block(x: int, y: int, z: int) -> int
+```
+
+Функция возвращает id инвентаря указанного блока. Если блок не может иметь инвентарь - возвращает 0.
+
+```python
+inventory.bind_block(invid: int, x: int, y: int, z: int)
+```
+
+Привязывает указанный инвентарь к блоку.
+
+```python
+inventory.unbind_block(x: int, y: int, z: int)
+```
+
+Отвязывает инвентарь от блока.
+
+> [!WARNING]
+> Инвентари, не привязанные ни к одному из блоков, удаляются при выходе из мира.
+
+```python
+inventory.clone(invid: int) -> int
+```
+
+Создает копию инвентаря и возвращает id копии. Если копируемого инвентаря не существует, возвращает 0. 
+
+## Библиотека block
+
+```python
+block.name(blockid: int) -> str
+```
+
+Возвращает строковый id блока по его числовому id
+
+```python
+block.index(name: str) -> int
+```
+
+Возвращает числовой id блока, принимая в качестве агрумента строковый
+
+```python
+block.get(x: int, y: int, z: int) -> int
+```
+
+Возвращает числовой id блока на указанных координатах. Если чанк на указанных координатах не загружен, возвращает -1.
+
+```python
+block.get_states(x: int, y: int, z: int) -> int
+```
+
+Возвращает состояние (поворот + доп. информация) в виде целого числа
+
+```python
+block.set(x: int, y: int, z: int, id: int, states: int)
+```
+
+Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах.
+
+> [!WARNING]
+> `block.set` не вызывает событие on_placed.
+
+```python
+block.is_solid_at(x: int, y: int, z: int) -> bool
+```
+
+Проверяет, является ли блок на указанных координатах полным
+
+```python
+block.is_replaceable_at(x: int, y: int, z: int) -> bool
+```
+Проверяет, можно ли на заданных координатах поставить блок (примеры: воздух, трава, цветы, вода)
+
+```python
+block.defs_count() -> int
+```
+
+Возвращает количество id доступных в движке блоков
+
+Следующие три функции используется для учёта вращения блока при обращении к соседним блокам или других целей, где направление блока имеет решающее значение.
+
+
+```python
+block.get_X(x: int, y: int, z: int) -> int, int, int
+```
+
+Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа).
+Если поворот отсутствует, возвращает 1, 0, 0
+
+```python
+block.get_Y(x: int, y: int, z: int) -> int, int, int
+```
+
+Возвращает целочисленный единичный вектор Y блока на указанных координатах с учётом его вращения (три целых числа).
+Если поворот отсутствует, возвращает 0, 1, 0
+
+```python
+block.get_Z(x: int, y: int, z: int) -> int, int, int
+```
+
+Возвращает целочисленный единичный вектор Z блока на указанных координатах с учётом его вращения (три целых числа).
+Если поворот отсутствует, возвращает 0, 0, 1
+
+### Пользовательские биты
+
+Выделенная под использования в скриптах часть поля `voxel.states` хранящего доп-информацию о вокселе, такую как вращение блока. На данный момент выделенная часть составляет 8 бит.
+
+```python
+block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
+``` 
+
+Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа
+
+```python
+block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
+```
+Записывает указанное число бит значения value в user bits по выбранному смещению
+
+## Библиотека item
+
+```python
+item.name(itemid: int) -> str
+```
+
+Возвращает строковый id предмета по его числовому id (как block.name)
+
+```python
+item.index(name: str) -> int
+```
+
+Возвращает числовой id предмета по строковому id (как block_index)
+
+```python
+item.stack_size(itemid: int) -> int
+```
+
+Возвращает максимальный размер стопки для предмета.
+
+```python
+item.defs_count() -> int
+```
+
+Возвращает общее число доступных предметов (включая сгенерированные)
+
+## Библиотека hud
+
+```python
+hud.open_inventory()
+```
+
+Открывает инвентарь
+
+```python
+hud.close_inventory()
+```
+
+Закрывает инвентарь
+
+```python
+hud.open_block(x: int, y: int, z: int) -> int, str
+```
+
+Открывает инвентарь и UI блока. Если блок не имеет макета UI - бросается исключение.
+
+Возвращает id инвентаря блока (при *"inventory-size"=0* создаётся виртуальный инвентарь, который удаляется после закрытия), и id макета UI. 
+
+> [!NOTE]
+> Одновременно может быть открыт только один блок
+
+```python
+hud.open_permanent(layoutid: str)
+```
+
+Добавляет постоянный элемент на экран. Элемент не удаляется при закрытии инвентаря. Чтобы не перекрывать затенение в режиме инвентаря нужно установить z-index элемента меньшим чем -1. В случае тега inventory, произойдет привязка слотов к инвентарю игрока.
+
+```python
+hud.close(layoutid: str)
+```
+
+Удаляет элемент с экрана
+## События блоков
+
+```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)
+```
+
+Вызывается при выходе из мира, перед его сохранением.
+
+## Библиотеки движка
+
+### 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 если были созданы директории.
+
+### time
+
+```python
+time.uptime() -> float
+```
+
+Возвращает время с момента запуска движка в секундах
+
+## Доступные модули
+
+### TOML сериализация/десериализация
+
+```lua
+local toml = require "core:toml"
+
+local t = {a=53, b=42, s="test", sub={x=1, y=6}}
+local s = toml.serialize(t)
+print(s)
+local t2 = toml.deserialize(s) 
+```
+вывод:
+```toml
+b = 42
+s = "test"
+a = 53
+[sub]
+y = 6
+x = 1
+```

doc/ru/9.Модели-блоков.md

@@ -0,0 +1,19 @@
+# Модели блоков
+
+Создание собственной модели блока может быть реализовано при указании у блока свойств:
+```js
+"model": "custom",
+"model-primitives": {
+  "aabbs": [
+     // список описаний AABB примитивов
+  ],
+  // ... другие примитивы
+}
+```
+
+**AABB** примитив - массив состоящий из значений: 
+```
+[x, y, z, width, height, depth, имёна текстур для каждой стороны]
+```
+
+**tetragon** примитив (по смыслу скорее parallelogram) - массив из трёх векторов, описывающих позицию примитива, вектор X\*ширина, Y\*высота.