voxelcoreprojects/voxelcore
1
0
Fork 0
mirror of https://github.com/MihailRis/voxelcore.git synced 2026-10-09 04:51:49 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Improved docs (#708)

Browse source 
* начало переписи доков

* extensions update

* libapp update

* libfile update

* io_stream update

* Update io_stream.md

* io_stream update x3

* io_stream update x4

* libtime update

* libgui update + make bytearray.md

* libinput update

* Update libapp.md

* Update libapp.md

* libgui update

* events.md ru fix

* да ну не надо так делать

--> не имеет смысла, ибо гитхаб -> показывает адекватно

* types refactoring

* fixes

* Update libblock.md

* Update libblock.md

* Update libbyteutil.md
This commit is contained in:
Xertis 2025-12-18 12:58:39 +03:00 • committed by MihailRis
parent 8b31bdeb78
commit ac02bc0c8e
43 changed files with 1107 additions and 1314 deletions
Download patch file Download diff file Expand all files Collapse all files

24
doc/en/scripting/builtins/libbyteutil.md
View file

@ -24,17 +24,19 @@ Special characters specify the byte order for the subsequent values:
Value characters describe the type and size. Value characters describe the type and size.
| Character | C++ Equivalent | Lua Type | Size | | Character | C++ Equivalent | Lua Type | Size |
| --------- | -------------- | -------- | ------- | | --------- | --------------- | -------- | ------- |
| `b` | int8_t | number | 1 byte | | `b` | int8_t | number | 1 byte |
| `B` | uint8_t | number | 1 byte | | `B` | uint8_t | number | 1 byte |
| `?` | bool | boolean | 1 byte | | `?` | bool | boolean | 1 byte |
| `h` | int16_t | number | 2 bytes | | `h` | int16_t | number | 2 bytes |
| `H` | uint16_t | number | 2 bytes | | `H` | uint16_t | number | 2 bytes |
| `i` | int32_t | number | 4 bytes | | `i` | int32_t | number | 4 bytes |
| `I` | uint32_t | number | 4 bytes | | `I` | uint32_t | number | 4 bytes |
| `l` | int64_t | number | 8 bytes | | `f` | float32_t | number | 4 bytes |
| `L` | uint64_t | number | 8 bytes | | `l` | int64_t | number | 8 bytes |
| `L` | uint64_t | number | 8 bytes |
| `d` | float64_t | number | 8 bytes |
> [!WARNING] > [!WARNING]
> Due to the absence of an integer type in Lua for values `l` and `L`, only an output size of 8 bytes is guaranteed; the value may differ from what is expected. > Due to the absence of an integer type in Lua for values `l` and `L`, only an output size of 8 bytes is guaranteed; the value may differ from what is expected.

44
doc/ru/audio.md
View file

@ -143,66 +143,66 @@ audio.play_sound_2d(
```lua ```lua
-- остановить воспроизведение спикера -- остановить воспроизведение спикера
audio.stop(speakerid: integer) audio.stop(speakerid: int)
-- поставить спикер на паузу -- поставить спикер на паузу
audio.pause(speakerid: integer) audio.pause(speakerid: int)
-- снять спикер с паузы -- снять спикер с паузы
audio.resume(speakerid: integer) audio.resume(speakerid: int)
-- установить зацикливание аудио -- установить зацикливание аудио
audio.set_loop(speakerid: integer, state: bool) audio.set_loop(speakerid: int, state: bool)
-- проверить, зациклено ли аудио (false если не существует) -- проверить, зациклено ли аудио (false если не существует)
audio.is_loop(speakerid: integer) -> bool audio.is_loop(speakerid: int) -> bool
-- получить громкость спикера (0.0 если не существует) -- получить громкость спикера (0.0 если не существует)
audio.get_volume(speakerid: integer) -> number audio.get_volume(speakerid: int) -> number
-- установить громкость спикера -- установить громкость спикера
audio.set_volume(speakerid: integer, volume: number) audio.set_volume(speakerid: int, volume: number)
-- получить скорость воспроизведения (1.0 если не существует) -- получить скорость воспроизведения (1.0 если не существует)
audio.get_pitch(speakerid: integer) -> number audio.get_pitch(speakerid: int) -> number
-- установить скорость воспроизведения -- установить скорость воспроизведения
audio.set_pitch(speakerid: integer, pitch: number) audio.set_pitch(speakerid: int, pitch: number)
-- получить временную позицию аудио в секундах (0.0 если не существует) -- получить временную позицию аудио в секундах (0.0 если не существует)
audio.get_time(speakerid: integer) -> number audio.get_time(speakerid: int) -> number
-- установить временную позицию аудио в секундах -- установить временную позицию аудио в секундах
audio.set_time(speakerid: integer, time: number) audio.set_time(speakerid: int, time: number)
-- получить позицию источника звука в мире (nil если не существует) -- получить позицию источника звука в мире (nil если не существует)
audio.get_position(speakerid: integer) -> number, number, number audio.get_position(speakerid: int) -> number, number, number
-- установить позицию источника звука в мире -- установить позицию источника звука в мире
audio.set_position(speakerid: integer, x: number, y: number, z: number) audio.set_position(speakerid: int, x: number, y: number, z: number)
-- получить скорость движения источника звука в мире (nil если не существует) -- получить скорость движения источника звука в мире (nil если не существует)
-- (используется OpenAL для имитации эффекта Доплера) -- (используется OpenAL для имитации эффекта Доплера)
audio.get_velocity(speakerid: integer) -> number, number, number audio.get_velocity(speakerid: int) -> number, number, number
-- установить скорость движения источника звука в мире -- установить скорость движения источника звука в мире
-- (используется OpenAL для имитации эффекта Доплера) -- (используется OpenAL для имитации эффекта Доплера)
audio.set_velocity(speakerid: integer, x: number, y: number, z: number) audio.set_velocity(speakerid: int, x: number, y: number, z: number)
-- получить длительность аудио в секуднах, проигрываемого источником -- получить длительность аудио в секуднах, проигрываемого источником
-- возвращает 0, если не спикер не существует -- возвращает 0, если не спикер не существует
-- так же возвращает 0, если длительность неизвестна (пример: радио) -- так же возвращает 0, если длительность неизвестна (пример: радио)
audio.get_duration(speakerid: integer) -> number audio.get_duration(speakerid: int) -> number
``` ```
### Другие функции ### Другие функции
```lua ```lua
-- получить текущее число живых спикеров -- получить текущее число живых спикеров
audio.count_speakers() -> integer audio.count_speakers() -> int
-- получить текущее число проигрываемых аудио-потоков -- получить текущее число проигрываемых аудио-потоков
audio.count_streams() -> integer audio.count_streams() -> int
``` ```
### audio.PCMStream ### audio.PCMStream
@ -211,11 +211,11 @@ audio.count_streams() -> integer
-- создание источника PCM данных -- создание источника PCM данных
local stream = audio.PCMStream( local stream = audio.PCMStream(
-- частота дискретизации -- частота дискретизации
sample_rate: integer, sample_rate: int,
-- число каналов (1 - моно, 2 - стерео) -- число каналов (1 - моно, 2 - стерео)
channels: integer, channels: int,
-- число бит на сэмпл (8 или 16) -- число бит на сэмпл (8 или 16)
bits_per_sample: integer, bits_per_sample: int,
) )
-- подача PCM данных в поток -- подача PCM данных в поток
@ -249,7 +249,7 @@ audio.input.fetch(
-- токен, полученный через audio.input.request_open -- токен, полученный через audio.input.request_open
access_token: string, access_token: string,
-- максимальное размер буфера в байтах -- максимальное размер буфера в байтах
[опционально] max_read_size: integer [опционально] max_read_size: int
) )
``` ```

13
doc/ru/console.md
View file

@ -118,8 +118,8 @@ console.add_command(
## Остальные методы ## Остальные методы
```lua ```lua
console.set_cheat(name: String, cheat: Boolean) -> cheatIsChanged: Boolean console.set_cheat(name: string, cheat: Boolean) -> cheatIsChanged: Boolean
console.is_cheat(name: String) -> Boolean console.is_cheat(name: string) -> Boolean
``` ```
Сеттер и геттер статуса "чит" команды Сеттер и геттер статуса "чит" команды
@ -127,10 +127,7 @@ console.is_cheat(name: String) -> Boolean
```lua ```lua
console.log(...) -- Выводит информацию во внутриигровую консоль console.log(...) -- Выводит информацию во внутриигровую консоль
console.chat(...) -- Выводит информацию во внутриигровой чат console.chat(...) -- Выводит информацию во внутриигровой чат
console.get_commands_list() -> Table<String> -- Возвращает таблицу со списком команд console.get_commands_list() -> Table<string> -- Возвращает таблицу со списком команд
console.get_command_info(name: String) -> Table -- Возвращает информацию о команде console.get_command_info(name: string) -> Table -- Возвращает информацию о команде
console.execute(command: str) -- Выполняет команду console.execute(command: string) -- Выполняет команду
``` ```

172
doc/ru/scripting/builtins/libapp.md
View file

@ -9,185 +9,137 @@ local filename = "script:"..app.script..".lua"
Так как управляющий сценарий может не принадлежать ни одному из паков, он не относиться к своему паку и имеет собственное пространство имён, в котором доступны все глобальные функции и таблицы, а также библиотека `app`. Так как управляющий сценарий может не принадлежать ни одному из паков, он не относиться к своему паку и имеет собственное пространство имён, в котором доступны все глобальные функции и таблицы, а также библиотека `app`.
## Функции ## Содержание:
Методы для работы с:
- [основными процессами движка](#основные-процессы-движка)
- [контент-паками](#контент-паки)
- [мирами](#миры)
- [свойствами и настройками](#свойства-и-настройки-движка)
- [точками входа и путями](#точки-входа-и-пути)
## Основные процессы движка
```lua ```lua
-- Выполняет один такт основного цикла движка.
app.tick() app.tick()
```
Выполняет один такт основного цикла движка. -- Ожидает указанное время в секундах, выполняя основной цикл движка.
```lua
app.sleep(time: number) app.sleep(time: number)
```
Ожидает указанное время в секундах, выполняя основной цикл движка. -- Завершает выполнение движка, выводя стек вызовов для ослеживания места вызова функции.
app.quit()
```lua -- Ожидает истинности утверждения (условия), проверяемого функцией, выполняя основной цикл движка.
app.sleep_until( app.sleep_until(
-- функция, проверяющее условия завершения ожидания -- функция, проверяющее условия завершения ожидания
predicate: function() -> bool, predicate: function() -> boolean,
-- максимальное количество тактов цикла движка, после истечения которых -- максимальное количество тактов цикла движка, после истечения которых
-- будет брошено исключение "max ticks exceed" -- будет брошено исключение "max ticks exceed"
[опционально] max_ticks = 1e9, [опционально] max_ticks: int = 1e9,
-- максимальное длительность ожидания в секундах. -- максимальное длительность ожидания в секундах.
-- (работает с системным временем, включая test-режим) -- (работает с системным временем, включая test-режим)
[опционально] timeout = 1e9 [опционально] timeout: number = 1e9
) )
``` ```
Ожидает истинности утверждения (условия), проверяемого функцией, выполнячя основной цикл движка. ## Контент-паки
```lua ```lua
app.quit() -- Проверяет, загружен ли контент.
``` app.is_content_loaded() -> boolean
Завершает выполнение движка, выводя стек вызовов для ослеживания места вызова функции. -- Загружает контент из конфига, нельзя использовать, если контент уже загружен
app.load_content()
```lua -- Выгружает весь контент, сбрасывая до единственного пака ядра (`core`).
app.reset_content(
-- Паки, для которых не будут сброшены модули, ивенты и окружение
[опционально] non_reset_packs: table
)
-- Обновляет конфигурацию паков, проверяя её корректность (зависимости и доступность паков).
-- Автоматически добавляет зависимости.
-- Для удаления ВСЕХ паков из конфигурации можно использовать `pack.get_installed()`
app.reconfig_packs( app.reconfig_packs(
-- добавляемые паки -- добавляемые паки
add_packs: table, add_packs: table,
-- удаляемые паки -- удаляемые паки
remove_packs: table remove_packs: table
) )
```
Обновляет конфигурацию паков, проверяя её корректность (зависимости и доступность паков). -- Обновляет конфигурацию паков, автоматически удаляя лишние, добавляя отсутствующие в прошлой конфигурации.
Автоматически добавляет зависимости. -- Использует app.reconfig_packs.
Для удаления всех паков из конфигурации можно использовать `pack.get_installed()`:
```lua
app.reconfig_packs({}, pack.get_installed())
```
В этом случае из конфигурации будет удалён и `base`.
```lua
app.config_packs( app.config_packs(
-- ожидаемый набор паков (без учёта зависимостей) -- ожидаемый набор паков (без учёта зависимостей)
packs: table packs: table
) )
``` ```
Обновляет конфигурацию паков, автоматически удаляя лишние, добавляя отсутствующие в прошлой конфигурации. ## Миры
Использует app.reconfig_packs.
```lua
app.is_content_loaded() -> bool
```
Проверяет, загружен ли контент.
```lua ```lua
-- Создаёт новый мир и открывает его.
app.new_world( app.new_world(
-- название мира, пустая строка приведёт к созданию безымянного мира -- название мира, пустая строка приведёт к созданию безымянного мира
name: str, name: string,
-- зерно генерации -- зерно генерации
seed: str, seed: string,
-- название генератора -- название генератора
generator: str generator: string
-- id локального игрока -- id локального игрока
[опционально] local_player: int=0 [опционально] local_player: int = 0
) )
```
Создаёт новый мир и открывает его. -- Удаляет мир по названию.
app.delete_world(name: string)
```lua -- Открывает мир по названию.
app.open_world(name: str) app.open_world(name: string)
```
Открывает мир по названию. -- Переоткрывает мир.
```lua
app.reopen_world() app.reopen_world()
```
Переоткрывает мир. -- Сохраняет мир.
```lua
app.save_world() app.save_world()
```
Сохраняет мир. -- Закрывает мир.
```lua
app.close_world( app.close_world(
-- сохранить мир перед закрытием -- сохранить мир перед закрытием
[опционально] save_world: bool=false [опционально] save_world: boolean = false
) )
``` ```
Закрывает мир.
```lua
app.delete_world(name: str)
```
Удаляет мир по названию.
## Свойства и настройки движка
```lua ```lua
-- Возвращает мажорную и минорную версии движка.
app.get_version() -> int, int app.get_version() -> int, int
```
Возвращает мажорную и минорную версии движка. -- Возвращает значение настройки. Бросает исключение, если настройки не существует.
app.get_setting(name: string) -> any
```lua -- Устанавливает значение настройки. Бросает исключение, если настройки не существует.
app.get_setting(name: str) -> value app.set_setting(name: string, value: any)
```
Возвращает значение настройки. Бросает исключение, если настройки не существует. -- Возвращает таблицу с информацией о настройке. Бросает исключение, если настройки не существует.
app.get_setting_info(name: string) -> table
```lua -- Переводит окно на передний план и устанавливает фокус ввода.
app.set_setting(name: str, value: value)
```
Устанавливает значение настройки. Бросает исключение, если настройки не существует.
```lua
app.get_setting_info(name: str) -> {
-- значение по-умолчанию
def: value
-- минимальное значение
[только числовые настройки] min: number,
-- максимальное значение
[только числовые настройки] max: number
}
```
Возвращает таблицу с информацией о настройке. Бросает исключение, если настройки не существует.
```lua
app.focus() app.focus()
``` ```
Переводит окно на передний план и устанавливает фокус ввода. ## Точки входа и пути
```lua
-- Создаёт файловую систему в памяти.
app.create_memory_device( app.create_memory_device(
-- имя точки входа -- имя точки входа
name: str name: string
) )
```
Создаёт файловую систему в памяти. -- Возвращает список источников контента (путей), в порядке убывания приоритета.
```lua
app.get_content_sources() -> table<string> app.get_content_sources() -> table<string>
```
Возвращает список источников контента (путей), в порядке убывания приоритета. -- Устанавливает список источников контента (путей). Указывается в порядке убывания приоритета.
```lua
app.set_content_sources(sources: table<string>) app.set_content_sources(sources: table<string>)
```
Устанавливает список источников контента (путей). Указывается в порядке убывания приоритета. -- Сбрасывает список источников контента.
```lua
app.reset_content_sources() app.reset_content_sources()
``` ```
Сбрасывает список источников контента.

14
doc/ru/scripting/builtins/libassets.md
View file

@ -10,20 +10,20 @@ assets.load_texture(
-- Массив байт файла изображения -- Массив байт файла изображения
data: table | Bytearray, data: table | Bytearray,
-- Имя текстуры после загрузки -- Имя текстуры после загрузки
name: str, name: string,
-- Формат файла изображения (поддерживается только png) -- Формат файла изображения (поддерживается только png)
[опционально] [опционально]
format: str = "png" format: string = "png"
) )
-- Парсит и загружает 3D модель -- Парсит и загружает 3D модель
assets.parse_model( assets.parse_model(
-- Формат файла модели (xml / vcm) -- Формат файла модели (xml / vcm)
format: str, format: string,
-- Содержимое файла модели -- Содержимое файла модели
content: str, content: string,
-- Имя модели после загрузки -- Имя модели после загрузки
name: str name: string
) )
-- Создаёт холст (Canvas) из загруженной текстуры -- Создаёт холст (Canvas) из загруженной текстуры
@ -31,6 +31,6 @@ assets.to_canvas(
-- Имя загруженной текстуры. -- Имя загруженной текстуры.
-- Поддерживается как отдельные ("имя_текстуры"), -- Поддерживается как отдельные ("имя_текстуры"),
-- так и находящиеся в атласе ("атлас:имя_текстуры"). -- так и находящиеся в атласе ("атлас:имя_текстуры").
name: str name: string
) --> Canvas ) -> Canvas
``` ```

12
doc/ru/scripting/builtins/libbase64.md
View file

@ -4,14 +4,14 @@
```lua ```lua
-- Кодирует массив байт в base64 строку -- Кодирует массив байт в base64 строку
base64.encode(bytes: table|ByteArray) -> str base64.encode(bytes: table|Bytearray) -> string
-- Декодирует base64 строку в ByteArray или таблицу чисел, если второй аргумент установлен на true -- Декодирует base64 строку в Bytearray или таблицу чисел, если второй аргумент установлен на true
base64.decode(base64string: str, [опционально]usetable: bool=false) -> table|ByteArray base64.decode(base64string: string, [опционально]usetable: boolean=false) -> table|Bytearray
-- Кодирует массив байт в urlsafe-base64 строку ('-', '_' вместо '+', '/') -- Кодирует массив байт в urlsafe-base64 строку ('-', '_' вместо '+', '/')
base64.encode_urlsafe(bytes: table|ByteArray) -> str base64.encode_urlsafe(bytes: table|Bytearray) -> string
-- Декодирует urlsafe-base64 строку в ByteArray или таблицу чисел, если второй аргумент установлен на true -- Декодирует urlsafe-base64 строку в Bytearray или таблицу чисел, если второй аргумент установлен на true
base64.decode_urlsafe(base64string: str, [опционально]usetable: bool=false) -> table|ByteArray base64.decode_urlsafe(base64string: string, [опционально]usetable: boolean=false) -> table|Bytearray
``` ```

162
doc/ru/scripting/builtins/libblock.md
View file

@ -1,78 +1,95 @@
# Библиотека *block* # Библиотека *block*
## Содержание
- [Таблицы и прочие общие методы](#таблицы-и-прочие-общие-методы)
- [Работа с миром](#работа-с-миром)
- [Свойства блоков](#свойства-блоков)
- [Raycast](#raycast)
- [Вращение](#вращение)
- [Расширенные блоки](#расширенные-блоки)
- [Модель и физика](#модель-и-физика)
- [Данные блоков](#данные-блоков)
## Таблицы и прочие общие методы
```lua ```lua
-- Возвращает строковый id блока по его числовому id. -- Возвращает количество id доступных в загруженном контенте блоков
block.name(blockid: int) -> str block.defs_count() -> int
-- Возвращает числовой id блока, принимая в качестве агрумента строковый
block.index(name: str) -> int
-- Возвращает id материала блока.
block.material(blockid: int) -> str
-- Таблица материалов по их полным именам (пример: base:carpet) -- Таблица материалов по их полным именам (пример: base:carpet)
block.materials: table<string, table> block.materials: table<string, table>
-- Таблица пользовательских свойств блоков (см. ../../block-properties.md) -- Таблица пользовательских свойств блоков (см. ../../block-properties.md)
block.properties: table<int, table<string, object>> block.properties: table<int, table<string, any>>
```
-- Возвращает название блока, отображаемое в интерфейсе.
block.caption(blockid: int) -> str
## Работа с миром
```lua
-- Возвращает числовой id блока на указанных координатах. -- Возвращает числовой id блока на указанных координатах.
-- Если чанк на указанных координатах не загружен, возвращает -1. -- Если чанк на указанных координатах не загружен, возвращает -1.
block.get(x: int, y: int, z: int) -> int block.get(x: int, y: int, z: int) -> int
-- Возвращает полное состояние (поворот + сегмент + доп. информация) в виде целого числа
block.get_states(x: int, y: int, z: int) -> int
-- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах. -- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах.
block.set(x: int, y: int, z: int, id: int, states: int) -- Если передан noupdate=true, то вызов ивента `on_update` для соседних блоков не произойдёт.
block.set(x: int, y: int, z: int, id: int, states: int, noupdate: boolean=false)
-- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах -- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах
-- от лица игрока, вызывая событие on_placed. -- от лица игрока, вызывая событие on_placed.
-- playerid не является обязательным -- playerid не является обязательным
block.place(x: int, y: int, z: int, id: int, states: int, [optional] playerid: int) block.place(x: int, y: int, z: int, id: int, states: int, [опционально] playerid: int)
-- Ломает блок на заданных координатах от лица игрока, вызывая событие on_broken. -- Ломает блок на заданных координатах от лица игрока, вызывая событие on_broken.
-- playerid не является обязательным -- playerid не является обязательным
block.destruct(x: int, y: int, z: int, playerid: int) block.destruct(x: int, y: int, z: int, playerid: int)
-- Собирает полное состояние в виде целого числа
block.compose_state(state: {rotation: int, segment: int, userbits: int}) -> int
-- Разбирает полное состояние на: вращение, сегмент, пользовательские биты
block.decompose_state(state: int) -> {int, int, int}
```
> [!WARNING]
> `block.set` не вызывает событие on_placed.
```lua
-- Проверяет, является ли блок на указанных координатах полным
block.is_solid_at(x: int, y: int, z: int) -> bool
-- Проверяет, можно ли на заданных координатах поставить блок
-- (примеры: воздух, трава, цветы, вода)
block.is_replaceable_at(x: int, y: int, z: int) -> bool
-- Возвращает количество id доступных в загруженном контенте блоков
block.defs_count() -> int
-- Возвращает числовой id предмета, указанного в свойстве *picking-item*.
block.get_picking_item(id: int) -> int
-- Возвращает индекс варианта блока -- Возвращает индекс варианта блока
block.get_variant(x: int, y: int, z: int) -> int block.get_variant(x: int, y: int, z: int) -> int
-- Устанавливает вариант блока по индексу -- Устанавливает вариант блока по индексу
block.set_variant(x: int, y: int, z: int, index: int) -> int block.set_variant(x: int, y: int, z: int, index: int) -> int
-- Проверяет наличие тега у блока
block.has_tag(id: int, tag: str) -> bool
``` ```
### Raycast > [!WARNING]
> `block.set` не вызывает событие on_placed.
## Свойства блоков
```lua
-- Проверяет, является ли блок на указанных координатах полным
block.is_solid_at(x: int, y: int, z: int) -> boolean
-- Проверяет, можно ли на заданных координатах поставить блок
-- (примеры: воздух, трава, цветы, вода)
block.is_replaceable_at(x: int, y: int, z: int) -> boolean
-- Возвращает полное состояние (поворот + сегмент + доп. информация) в виде целого числа
block.get_states(x: int, y: int, z: int) -> int
-- Возвращает название блока, отображаемое в интерфейсе.
block.caption(blockid: int) -> string
-- Возвращает строковый id блока по его числовому id.
block.name(blockid: int) -> string
-- Возвращает числовой id блока, принимая в качестве агрумента строковый
block.index(name: string) -> int
-- Собирает полное состояние в виде целого числа
block.compose_state(state: {rotation: int, segment: int, userbits: int}) -> int
-- Разбирает полное состояние на: вращение, сегмент, пользовательские биты
block.decompose_state(state: int) -> {int, int, int}
-- Проверяет наличие тега у блока
block.has_tag(id: int, tag: string) -> boolean
-- Возвращает числовой id предмета, указанного в свойстве *picking-item*.
block.get_picking_item(id: int) -> int
-- Возвращает id материала блока.
block.material(blockid: int) -> string
```
## Raycast
```lua ```lua
block.raycast(start: vec3, dir: vec3, max_distance: number, [опционально] dest: table, [опционально] filter: table) -> { block.raycast(start: vec3, dir: vec3, max_distance: number, [опционально] dest: table, [опционально] filter: table) -> {
@ -95,9 +112,6 @@ block.raycast(start: vec3, dir: vec3, max_distance: number, [опциональ
## Вращение ## Вращение
Следующие функции используется для учёта вращения блока при обращении к соседним блокам или других целей, где направление блока имеет решающее значение.
```lua ```lua
-- Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа). -- Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа).
-- Если поворот отсутствует, возвращает 1, 0, 0 -- Если поворот отсутствует, возвращает 1, 0, 0
@ -119,46 +133,38 @@ block.get_rotation(x: int, y: int, z: int) -> int
block.set_rotation(x: int, y: int, z: int, rotation: int) block.set_rotation(x: int, y: int, z: int, rotation: int)
-- Возвращает имя профиля вращения (none/pane/pipe) -- Возвращает имя профиля вращения (none/pane/pipe)
block.get_rotation_profile(id: int) -> str block.get_rotation_profile(id: int) -> string
``` ```
## Расширенные блоки ## Расширенные блоки
Расширенные блоки - те, размер которых превышает 1x1x1
```lua ```lua
-- Проверяет, является ли блок расширенным. -- Проверяет, является ли блок расширенным.
block.is_extended(id: int) -> bool block.is_extended(id: int) -> boolean
-- Возвращает размер блока. -- Возвращает размер блока.
block.get_size(id: int) -> int, int, int block.get_size(id: int) -> int, int, int
-- Проверяет является ли блок сегментом расширенного блока, не являющимся главным. -- Проверяет является ли блок сегментом расширенного блока, не являющимся главным.
block.is_segment(x: int, y: int, z: int) -> bool block.is_segment(x: int, y: int, z: int) -> boolean
-- Возвращает позицию главного сегмента расширенного блока или исходную позицию, -- Возвращает позицию главного сегмента расширенного блока или исходную позицию,
-- если блок не является расширенным. -- если блок не является расширенным.
block.seek_origin(x: int, y: int, z: int) -> int, int, int block.seek_origin(x: int, y: int, z: int) -> int, int, int
``` ```
## Пользовательские биты ## Модель и физика
Выделенная под использования в скриптах часть поля `voxel.states` хранящего доп-информацию о вокселе, такую как вращение блока. На данный момент выделенная часть составляет 8 бит.
```lua ```lua
-- Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа -- возвращает тип модели блока (block/aabb/custom/...)
block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int block.get_model(id: int) -> string
-- Записывает указанное число бит значения value в user bits по выбранному смещению -- возвращает имя модели блока
block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int block.model_name(id: int) -> string
```
-- возвращает массив из 6 текстур, назначенных на стороны блока
block.get_textures(id: int) -> table<string>
## Физика
Информация свойствах блока, используемых физическим движком.
```lua
-- Возвращает массив из двух векторов (массивов из 3 чисел): -- Возвращает массив из двух векторов (массивов из 3 чисел):
-- 1. Минимальная точка хитбокса -- 1. Минимальная точка хитбокса
-- 2. Размер хитбокса -- 2. Размер хитбокса
@ -166,32 +172,24 @@ block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int)
block.get_hitbox(id: int, rotation_index: int) -> {vec3, vec3} block.get_hitbox(id: int, rotation_index: int) -> {vec3, vec3}
``` ```
## Модель ## Данные блоков
Информация о модели блока.
```lua ```lua
-- возвращает тип модели блока (block/aabb/custom/...) -- Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа
block.get_model(id: int) -> str block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
-- возвращает имя модели блока -- Записывает указанное число бит значения value в user bits по выбранному смещению
block.model_name(id: int) -> str block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
-- возвращает массив из 6 текстур, назначенных на стороны блока
block.get_textures(id: int) -> таблица строк
```
## Поля данных
```lua
-- записывает значение в указанное поле блока -- записывает значение в указанное поле блока
-- * бросает исключение при несовместимости типов -- * бросает исключение при несовместимости типов
-- * бросает исключение при выходе за границы массива -- * бросает исключение при выходе за границы массива
-- * ничего не делает при отсутствии поля у блока -- * ничего не делает при отсутствии поля у блока
block.set_field( block.set_field(
x: int, y: int, z: int, x: int, y: int, z: int,
name: str, name: string,
value: bool|int|number|string, value: string | number | boolean,
[опционально] index: int = 0 [опционально] index: int = 0
) )
@ -202,7 +200,7 @@ block.set_field(
-- * бросает исключение при выходе за границы массива -- * бросает исключение при выходе за границы массива
block.get_field( block.get_field(
x: int, y: int, z: int, x: int, y: int, z: int,
name: str, name: string,
[опционально] index: int = 0 [опционально] index: int = 0
) -> хранимое значение или nil ) -> any | nil
``` ```

30
doc/ru/scripting/builtins/libbyteutil.md
View file

@ -3,8 +3,8 @@
Библиотека предоставляет функции для работы с массивами байт, представленными в виде таблиц или Bytearray. Библиотека предоставляет функции для работы с массивами байт, представленными в виде таблиц или Bytearray.
```lua ```lua
byteutil.pack(format: str, ...) -> Bytearray byteutil.pack(format: string, ...) -> Bytearray
byteutil.tpack(format: str, ...) -> table byteutil.tpack(format: string, ...) -> table
``` ```
Возвращает массив байт, содержащий переданные значения, упакованные в соответствии со строкой формата. Аргументы должны точно соответствовать значениям, требуемым форматом. Возвращает массив байт, содержащий переданные значения, упакованные в соответствии со строкой формата. Аргументы должны точно соответствовать значениям, требуемым форматом.
@ -24,24 +24,26 @@ byteutil.tpack(format: str, ...) -> table
Символы значений описывают тип и размер. Символы значений описывают тип и размер.
| Символ | Аналог в С++ | Тип Lua | Размер | | Символ | Аналог в С++ | Тип Lua | Размер |
| ------ | ------------ | -------- | ------- | | --------- | --------------- | -------- | ------- |
| `b` | int8_t | number | 1 байт | | `b` | int8_t | number | 1 байт |
| `B` | uint8_t | number | 1 байт | | `B` | uint8_t | number | 1 байт |
| `?` | bool | boolean | 1 байт | | `?` | bool | boolean | 1 байт |
| `h` | int16_t | number | 2 байта | | `h` | int16_t | number | 2 байта |
| `H` | uint16_t | number | 2 байта | | `H` | uint16_t | number | 2 байта |
| `i` | int32_t | number | 4 байта | | `i` | int32_t | number | 4 байта |
| `I` | uint32_t | number | 4 байта | | `I` | uint32_t | number | 4 байта |
| `l` | int64_t | number | 8 байта | | `f` | float32_t | number | 4 байта |
| `L` | uint64_t | number | 8 байта | | `l` | int64_t | number | 8 байтов |
| `L` | uint64_t | number | 8 байтов |
| `d` | float64_t | number | 8 байтов |
> [!WARNING] > [!WARNING]
> Из-за отсутствия в Lua целочисленного типа для значений `l` и `L` гарантируется > Из-за отсутствия в Lua целочисленного типа для значений `l` и `L` гарантируется
> только выходной размер в 8 байт, значение может отличаться от ожидаемого. > только выходной размер в 8 байт, значение может отличаться от ожидаемого.
```lua ```lua
byteutil.unpack(format: str, bytes: table|Bytearray) -> ... byteutil.unpack(format: string, bytes: table|Bytearray) -> ...
``` ```
Извлекает значения из массива байт, ориентируясь на строку формата. Извлекает значения из массива байт, ориентируясь на строку формата.

14
doc/ru/scripting/builtins/libcameras.md
View file

@ -5,7 +5,7 @@
## Основные функции ## Основные функции
```lua ```lua
cameras.get(name: str) -> table cameras.get(name: string) -> table
-- или -- или
cameras.get(index: int) -> table cameras.get(index: int) -> table
``` ```
@ -22,7 +22,7 @@ local cam = cameras.get("пак:имя-камеры")
cam:get_index() -> int cam:get_index() -> int
-- возвращает имя камеры -- возвращает имя камеры
cam:get_name() -> str cam:get_name() -> string
-- возвращает позицию камеры -- возвращает позицию камеры
cam:get_pos() -> vec3 cam:get_pos() -> vec3
@ -45,14 +45,14 @@ cam:get_fov() -> number
cam:set_fov(fov: number) cam:set_fov(fov: number)
-- возвращает true если ось Y отражена -- возвращает true если ось Y отражена
cam:is_flipped() -> bool cam:is_flipped() -> boolean
-- отражает ось Y при значении true -- отражает ось Y при значении true
cam:set_flipped(flipped: bool) cam:set_flipped(flipped: boolean)
-- проверяет, включен ли режим перспективы -- проверяет, включен ли режим перспективы
cam:is_perspective() -> bool cam:is_perspective() -> boolean
-- включает/выключает режим перспективы -- включает/выключает режим перспективы
cam:set_perspective(perspective: bool) cam:set_perspective(perspective: boolean)
-- возвращает вектор направления камеры -- возвращает вектор направления камеры
cam:get_front() -> vec3 cam:get_front() -> vec3
@ -68,4 +68,4 @@ cam:look_at(point: vec3)
cam:look_at(point: vec3, t: number) cam:look_at(point: vec3, t: number)
``` ```
Переключение камеры возможно через функцию player.set_camera. Переключение камеры возможно через функцию [player.set_camera](libplayer.md#камеры).

8
doc/ru/scripting/builtins/libcompression.md
View file

@ -6,20 +6,20 @@
-- Сжимает массив байт. -- Сжимает массив байт.
compression.encode( compression.encode(
-- Массив байт -- Массив байт
data: array of integers, data: Bytearray | table<int>,
-- Алгоритм сжатия (поддерживается только gzip) -- Алгоритм сжатия (поддерживается только gzip)
[опционально] algorithm="gzip", [опционально] algorithm="gzip",
-- Вернуть результат в table? -- Вернуть результат в table?
[опционально] usetable=false [опционально] usetable=false
) -> array of integers ) -> Bytearray | table<int>
-- Разжимает массив байт. -- Разжимает массив байт.
compression.decode( compression.decode(
-- Массив байт -- Массив байт
data: array of integers, data: Bytearray | table<int>,
-- Алгоритм разжатия (поддерживается только gzip) -- Алгоритм разжатия (поддерживается только gzip)
[опционально] algorithm="gzip", [опционально] algorithm="gzip",
-- Вернуть результат в table? -- Вернуть результат в table?
[опционально] usetable=false [опционально] usetable=false
) -> array of integers ) -> Bytearray | table<int>
``` ```

14
doc/ru/scripting/builtins/libentities.md
View file

@ -16,22 +16,22 @@ entities.get(uid: int) -> table
-- имя - название компонента -- имя - название компонента
-- префикс и имя компонента разделяются двумя подчеркиваниями -- префикс и имя компонента разделяются двумя подчеркиваниями
-- Возвращает обьект сущности -- Возвращает обьект сущности
entities.spawn(name: str, pos: vec3, [optional] args: table) -> table entities.spawn(name: string, pos: vec3, [optional] args: table) -> table
-- Проверяет наличие сущности по уникальному идентификатору. -- Проверяет наличие сущности по уникальному идентификатору.
entities.exists(uid: int) -> bool entities.exists(uid: int) -> boolean
-- Возвращает индекс определения сущности по UID -- Возвращает индекс определения сущности по UID
entities.get_def(uid: int) -> int entities.get_def(uid: int) -> int
-- Возвращает имя определения сущности по индексу (строковый ID). -- Возвращает имя определения сущности по индексу (строковый ID).
entities.def_name(id: int) -> str entities.def_name(id: int) -> string
-- Возвращает значение свойства 'hitbox' сущности -- Возвращает значение свойства 'hitbox' сущности
entities.def_hitbox(id: int) -> vec3 entities.def_hitbox(id: int) -> vec3
-- Возвращает индекс определения сущности по имени (числовой ID). -- Возвращает индекс определения сущности по имени (числовой ID).
entities.def_index(name: str) -> int entities.def_index(name: string) -> int
-- Возвращает число доступных определений сущностей -- Возвращает число доступных определений сущностей
entities.defs_count() -> int entities.defs_count() -> int
@ -48,17 +48,17 @@ entities.defs_count() -> int
entities.get_all() -> table entities.get_all() -> table
-- Возвращает таблицу загруженных сущностей по переданному списку UID -- Возвращает таблицу загруженных сущностей по переданному списку UID
entities.get_all(uids: array<int>) -> table entities.get_all(uids: table<int>) -> table
-- Возвращает список UID сущностей, попадающих в прямоугольную область -- Возвращает список UID сущностей, попадающих в прямоугольную область
-- pos - минимальный угол области -- pos - минимальный угол области
-- size - размер области -- size - размер области
entities.get_all_in_box(pos: vec3, size: vec3) -> array<int> entities.get_all_in_box(pos: vec3, size: vec3) -> table<int>
-- Возвращает список UID сущностей, попадающих в радиус -- Возвращает список UID сущностей, попадающих в радиус
-- center - центр области -- center - центр области
-- radius - радиус области -- radius - радиус области
entities.get_all_in_radius(center: vec3, radius: number) -> array<int> entities.get_all_in_radius(center: vec3, radius: number) -> table<int>
``` ```
```lua ```lua

316
doc/ru/scripting/builtins/libfile.md
View file

@ -2,213 +2,147 @@
Библиотека функций для работы с файлами Библиотека функций для работы с файлами
```python ## Содержание
file.resolve(путь: str) -> str - [Основные методы](#основные-методы)
``` - [Файлы](#файлы)
- [Директории](#директории)
- [Контент-паки](#контент-паки)
- [Zip-архивы](#zip-архивы)
- [IO-Stream](#io-stream)
Функция приводит запись `точка_входа:путь` (например `user:worlds/house1`) к обычному пути. (например `C://Users/user/.voxeng/worlds/house1`) ## Основные методы
```lua
-- Возвращает размер файла в байтах, либо -1, если файл не найден
file.length(путь: string) -> number
-- Проверяет, существует ли по данному пути файл или директория
file.exists(путь: string) -> boolean
-- Возвращает список файлов и директорий в указанной.
file.list(путь: string) -> table<string>
-- Возвращает список файлов и директорий в указанной без указания конкретной точки входа.
file.list_all_res(путь: string) -> table<string>
-- Возвращает путь на уровень выше. Пример: `world:data/base/config.toml` -> `world:data/base`
file.parent(путь: string) -> string
-- Соединяет путь. Пример: `file.join("world:data", "base/config.toml")` -> `world:data/base/config.toml`
file.join(директория: string, путь: string) -> string
-- Ищет файл или директорию от последнего пака до res. Путь указывается без префикса. Возвращает путь с нужным префиксом. Если файл не найден, возвращает nil.
file.find(путь: string) -> string
-- Создаёт файловую систему в памяти, возвращает имя точки входа. Удаляется при выгрузке контента.
-- * Следует использовать данную функцию вместо конкатенации с `/`, так как `префикс:/путь` не является валидным.
file.create_memory_device() -> string
-- Функция приводит запись `точка_входа:путь` (например `user:worlds/house1`) к обычному пути. (например `C://Users/user/.voxeng/worlds/house1`)
file.resolve(путь: string) -> string
```
> [!NOTE] > [!NOTE]
> Функцию не нужно использовать в сочетании с другими функциями из библиотеки, так как они делают это автоматически > Функцию file.resolve не нужно использовать в сочетании с другими функциями из библиотеки, так как они делают это автоматически.
> Возвращаемый путь не является каноническим и может быть как абсолютным, так и относительным.
Возвращаемый путь не является каноническим и может быть как абсолютным, так и относительным.
```python
file.read(путь: str) -> str
```
Читает весь текстовый файл и возвращает в виде строки
```python
file.read_bytes(путь: str, [опционально] usetable) -> array of integers
```
Читает файл в массив байт. При значении usetable = false возвращает Bytearray вместо table.
## Файлы
```lua ```lua
file.is_writeable(путь: str) -> bool -- Читает весь текстовый файл и возвращает в виде строки
file.read(путь: string) -> string
-- Читает весь текстовый файл и делит его на строки по символу \n
-- Возвращает массив строк файла
file.readlines(путь: string) -> table<string>
-- Читает файл в массив байт. При значении usetable = false возвращает Bytearray вместо table.
file.read_bytes(путь: string, [опционально] usetable: boolean=false) -> Bytearray | table<number>
-- Записывает текст в файл (с перезаписью)
file.write(путь: string, текст: string) -> nil
-- Записывает массив байт в файл (с перезаписью)
file.write_bytes(путь: string, data: table<number>)
-- Удаляет файл. Возращает true если файл существовал. Бросает исключение при нарушении доступа.
file.remove(путь: string) -> boolean
-- Проверяет, существует ли по данному пути файл
file.isfile(путь: string) -> boolean
-- Извлекает имя файла из пути. Пример: `world:data/base/config.toml` -> `config.toml`.
file.name(путь: string) -> string
-- Извлекает имя файла из пути, удаляя расширение. Пример: `world:data/base/config.toml` -> `config`.
file.stem(путь: string) -> string
-- Извлекает расширение из пути. Пример: `world:data/base/config.toml` -> `toml`.
file.ext(путь: string) -> string
``` ```
Проверяет, доступно ли право записи по указанному пути. ## Директории
```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.list(путь: str) -> массив строк
```
Возвращает список файлов и директорий в указанной.
```python
file.list_all_res(путь: str) -> массив строк
```
Возвращает список файлов и директорий в указанной без указания конкретной точки входа.
```python
file.find(путь: str) -> str
```
Ищет файл от последнего пака до res. Путь указывается без префикса. Возвращает путь с нужным префиксом. Если файл не найден, возвращает nil.
```python
file.remove(путь: str) -> bool
```
Удаляет файл. Возращает **true** если файл существовал. Бросает исключение при нарушении доступа.
```python
file.remove_tree(путь: str) -> int
```
Рекурсивно удаляет файлы. Возвращает число удаленных файлов.
```python
file.read_combined_list(путь: str) -> массив
```
Совмещает массивы из JSON файлов разных паков.
```python
file.read_combined_object(путь: str) -> массив
```
Совмещает объекты из JSON файлов разных паков.
```lua ```lua
file.mount(путь: str) --> str -- Создает директорию. Возвращает true если была создана новая директория
file.mkdir(путь: string) -> boolean
-- Создает всю цепочку директорий. Возвращает true если были созданы директории.
file.mkdirs(путь: string) -> boolean
-- Рекурсивно удаляет файлы. Возвращает число удаленных файлов.
file.remove_tree(путь: string) -> number
-- Проверяет, доступно ли право записи по указанному пути.
file.is_writeable(путь: string) -> boolean
-- Проверяет, существует ли по данному пути директория
file.isdir(путь: string) -> boolean
-- Извлекает точку входа (префикс) из пути. Пример: `world:data/base/config.toml` -> `world`.
file.prefix(путь: string) -> string
-- Убирает точку входа (префикс) из пути. Пример: `world:data/base/config.toml` -> `data/base/config.toml`
file.path(путь: string) -> string
``` ```
Монтирует ZIP-архив как файловой системе. Возвращает имя точки входа. ## Контент-паки
```lua ```lua
file.unmount(точка_входа: str) --> str -- Совмещает массивы из JSON файлов разных паков.
file.read_combined_list(путь: string) -> table
-- Совмещает объекты из JSON файлов разных паков.
file.read_combined_object(путь: string) -> table
``` ```
Размонтирует точку входа. ## Zip-архивы
```lua ```lua
file.create_zip(директория: str, выходной_файл: str) --> str -- Монтирует ZIP-архив как файловой системе. Возвращает имя точки входа.
file.mount(путь: string) -> string
-- Размонтирует точку входа.
file.unmount(точка_входа: string) -> string
-- Создаёт ZIP-архив из содержимого указанной директории.
file.create_zip(директория: string, выходной_файл: string) -> string
``` ```
Создаёт ZIP-архив из содержимого указанной директории. ## IO-Stream
### Режимы
- `r` - Чтение из файла
- `w` - Запись в файл
- `b` - Открыть поток в двоичном режиме (см. [io_stream.md](../io_stream.md))
- `+` - Работает совместно с `w`. Добавляет к существующим данным новые (`append-mode`)
Режимы также можно комбинировать
### Методы
```lua ```lua
file.create_memory_device() --> str -- Открывает поток для записи/чтения в файл по пути.
-- * Аргумент `режим` это список отдельных режимов, в котором каждый режим обозначается одним символом
file.open(путь: string, режим: string) -> io_stream
-- Открывает поток для записи/чтения в Named Pipe по пути `путь`
-- * `/tmp/` или `\\\\.\\pipe\\` добавлять не нужно - движок делает это автоматически.
-- * Недоступен режим с `+`
file.open_named_pipe(имя: string, режим: string) -> io_stream
``` ```
Создаёт файловую систему в памяти, возвращает имя точки входа. Удаляется при выгрузке контента.
```lua
file.name(путь: str) --> str
```
Извлекает имя файла из пути. Пример: `world:data/base/config.toml` -> `config.toml`.
```lua
file.stem(путь: str) --> str
```
Извлекает имя файла из пути, удаляя расширение. Пример: `world:data/base/config.toml` -> `config`.
```lua
file.ext(путь: str) --> str
```
Извлекает расширение из пути. Пример: `world:data/base/config.toml` -> `toml`.
```lua
file.prefix(путь: str) --> str
```
Извлекает точку входа (префикс) из пути. Пример: `world:data/base/config.toml` -> `world`.
```lua
file.parent(путь: str) --> str
```
Возвращает путь на уровень выше. Пример: `world:data/base/config.toml` -> `world:data/base`
```lua
file.path(путь: str) --> str
```
Убирает точку входа (префикс) из пути. Пример: `world:data/base/config.toml` -> `data/base/config.toml`
```lua
file.join(директория: str, путь: str) --> str
```
Соединяет путь. Пример: `file.join("world:data", "base/config.toml)` -> `world:data/base/config.toml`.
Следует использовать данную функцию вместо конкатенации с `/`, так как `префикс:/путь` не является валидным.
```lua
file.open(путь: str, режим: str) --> io_stream
```
Открывает поток для записи/чтения в файл по пути `путь`.
Аргумент `режим` это список отдельных режимов, в котором каждый обозначается одним символом
`r` - Чтение из файла
`w` - Запись в файл
`b` - Открыть поток в двоичном режиме (см. `../io_stream.md`)
`+` - Работает совместно с `w`. Добавляет к существующим данным новые (`append-mode`)
```lua
file.open_named_pipe(имя: str, режим: str) -> io_stream
```
Открывает поток для записи/чтения в Named Pipe по пути `путь`
`/tmp/` или `\\\\.\\pipe\\` добавлять не нужно - движок делает это автоматически.
Доступные режимы такие же, как и в `file.open`, за исключением `+`

4
doc/ru/scripting/builtins/libgfx-blockwraps.md
View file

@ -8,7 +8,7 @@
```lua ```lua
-- Создаёт обертку на указанной позиции, с указанной текстурой. -- Создаёт обертку на указанной позиции, с указанной текстурой.
-- Возвращает id обёртки. -- Возвращает id обёртки.
gfx.blockwraps.wrap(position: vec3, texture: str) --> int gfx.blockwraps.wrap(position: vec3, texture: string) -> int
-- Удаляет обертку, если она существует. -- Удаляет обертку, если она существует.
gfx.blockwraps.unwrap(id: int) gfx.blockwraps.unwrap(id: int)
@ -17,7 +17,7 @@ gfx.blockwraps.unwrap(id: int)
gfx.blockwraps.set_pos(id: int, position: vec3) gfx.blockwraps.set_pos(id: int, position: vec3)
-- Меняет текстуру обёртки, если она существует. -- Меняет текстуру обёртки, если она существует.
gfx.blockwraps.set_texture(id: int, texture: str) gfx.blockwraps.set_texture(id: int, texture: string)
``` ```
Обертки не удаляются автоматически без вызова `unwrap`. Обертки не удаляются автоматически без вызова `unwrap`.

12
doc/ru/scripting/builtins/libgfx-posteffects.md
View file

@ -15,14 +15,14 @@
```lua ```lua
-- Возвращает индекс слота эффектов по имени (пак:имя_слота). -- Возвращает индекс слота эффектов по имени (пак:имя_слота).
-- При отсутствии указанного слота возвращает -1 -- При отсутствии указанного слота возвращает -1
gfx.posteffects.index(name: str) --> int gfx.posteffects.index(name: string) -> int
-- Назначает эффект на слот -- Назначает эффект на слот
gfx.posteffects.set_effect(slot: int, effect: str) gfx.posteffects.set_effect(slot: int, effect: string)
-- Возвращает интенсивность эффекта (от 0.0 до 1.0) -- Возвращает интенсивность эффекта (от 0.0 до 1.0)
-- Если слот пуст, возвращает 0.0 -- Если слот пуст, возвращает 0.0
gfx.posteffects.get_intensity(slot: int) --> number gfx.posteffects.get_intensity(slot: int) -> number
-- Устанавливает интенсивность эффекта (от 0.0 до 1.0) -- Устанавливает интенсивность эффекта (от 0.0 до 1.0)
-- (Корректность обработки параметра между значениями 0.0 и 1.0 зависит -- (Корректность обработки параметра между значениями 0.0 и 1.0 зависит
@ -30,7 +30,7 @@ gfx.posteffects.get_intensity(slot: int) --> number
gfx.posteffects.set_intensity(slot: int, intensity: number) gfx.posteffects.set_intensity(slot: int, intensity: number)
-- Возвращает true если слот не пуст и интенсивность эффекта ненулевая -- Возвращает true если слот не пуст и интенсивность эффекта ненулевая
gfx.posteffects.is_active(slot: int) --> bool gfx.posteffects.is_active(slot: int) -> boolean
-- Устанавливает значения параметров (директивы 'param') -- Устанавливает значения параметров (директивы 'param')
gfx.posteffects.set_params(slot: int, params: table) gfx.posteffects.set_params(slot: int, params: table)
@ -40,9 +40,9 @@ gfx.posteffects.set_array(
-- индекс слота эффектов -- индекс слота эффектов
slot: int, slot: int,
-- имя параметра (массива) -- имя параметра (массива)
name: str name: string
-- строка данных (используйте функцию Bytearray_as_string) -- строка данных (используйте функцию Bytearray_as_string)
data: str data: string
) )
-- Пример заполнения массива `#param vec3 u_имяМассива[64]`: -- Пример заполнения массива `#param vec3 u_имяМассива[64]`:

16
doc/ru/scripting/builtins/libgfx-skeletons.md
View file

@ -9,17 +9,17 @@
```lua ```lua
-- Возвращает объектную обёртку над скелетом -- Возвращает объектную обёртку над скелетом
local skeleton = gfx.skeletons.get(name: str) local skeleton = gfx.skeletons.get(name: string)
-- Возвращает индекс кости по имени или nil -- Возвращает индекс кости по имени или nil
skeleton:index(name: str) -> int skeleton:index(name: string) -> int
-- Возвращает имя модели, назначенной на кость с указанным индексом -- Возвращает имя модели, назначенной на кость с указанным индексом
skeleton:get_model(index: int) -> str skeleton:get_model(index: int) -> string
-- Переназначает модель кости с указанным индексом -- Переназначает модель кости с указанным индексом
-- Сбрасывает до изначальной, если не указывать имя -- Сбрасывает до изначальной, если не указывать имя
skeleton:set_model(index: int, name: str) skeleton:set_model(index: int, name: string)
-- Возвращает матрицу трансформации кости с указанным индексом -- Возвращает матрицу трансформации кости с указанным индексом
skeleton:get_matrix(index: int) -> mat4 skeleton:get_matrix(index: int) -> mat4
@ -28,18 +28,18 @@ skeleton:get_matrix(index: int) -> mat4
skeleton:set_matrix(index: int, matrix: mat4) skeleton:set_matrix(index: int, matrix: mat4)
-- Возвращает текстуру по ключу (динамически назначаемые текстуры - '$имя') -- Возвращает текстуру по ключу (динамически назначаемые текстуры - '$имя')
skeleton:get_texture(key: str) -> str skeleton:get_texture(key: string) -> string
-- Назначает текстуру по ключу -- Назначает текстуру по ключу
skeleton:set_texture(key: str, value: str) skeleton:set_texture(key: string, value: string)
-- Проверяет статус видимости кости по индесу -- Проверяет статус видимости кости по индесу
-- или всего скелета, если индекс не указан -- или всего скелета, если индекс не указан
skeleton:is_visible([опционально] index: int) -> bool skeleton:is_visible([опционально] index: int) -> boolean
-- Устанавливает статус видимости кости по индексу -- Устанавливает статус видимости кости по индексу
-- или всего скелета, если индекс не указан -- или всего скелета, если индекс не указан
skeleton:set_visible([опционально] index: int, status: bool) skeleton:set_visible([опционально] index: int, status: boolean)
-- Возвращает цвет сущности -- Возвращает цвет сущности
skeleton:get_color() -> vec3 skeleton:get_color() -> vec3

6
doc/ru/scripting/builtins/libgfx-weather.md
View file

@ -36,11 +36,11 @@ gfx.weather.change(
-- длительность изменения погоды в секундах -- длительность изменения погоды в секундах
time: number, time: number,
-- название пресета погоды -- название пресета погоды
[опционально] name: str [опционально] name: string
) )
-- Возвращает имя пресета погоды -- Возвращает имя пресета погоды
gfx.weather.get_current() -> str gfx.weather.get_current() -> string
-- Возвращает копию таблицы настроек погоды -- Возвращает копию таблицы настроек погоды
gfx.weather.get_current_data() -> table gfx.weather.get_current_data() -> table
@ -49,5 +49,5 @@ gfx.weather.get_current_data() -> table
gfx.weather.get_fall_intensity() -> number gfx.weather.get_fall_intensity() -> number
-- Проверяет, происходит ли в данный момент переключение погоды -- Проверяет, происходит ли в данный момент переключение погоды
gfx.weather.is_transition() -> bool gfx.weather.is_transition() -> boolean
``` ```

142
doc/ru/scripting/builtins/libgui.md
View file

@ -1,108 +1,112 @@
# Библиотека *gui* ## Содержание
Библиотека содержит функции для доступа к свойствам UI элементов. Вместо gui следует использовать объектную обертку, предоставляющую доступ к свойствам через мета-методы __index, __newindex: * [Основное](#основное)
* [Локализация](#локализация)
* [Окно и окружение](#окно-и-окружение)
* [Разметка](#разметка)
* [Диалоговые окна](#диалоговые-окна)
* [Документы и шаблоны](#документы-и-шаблоны)
* [Корневой документ](#корневой-документ)
## Основное
- Библиотека содержит функции для доступа к свойствам UI элементов.
- В макетных скриптах доступна переменная document (класс Document).
- Вместо gui следует использовать объектную обертку:
```lua ```lua
print(document.some_button.text) -- где 'some_button' - id элемета print(document.some_button.text)
document.some_button.text = "новый текст" document.some_button.text = "новый текст"
``` ```
В скрипте макета `layouts/файл_макета.xml` - `layouts/файл_макета.xml.lua` уже доступна переменная **document** содержащая объект класса Document ## Локализация
```python
gui.str(text: str, context: str) -> str
```
Возращает переведенный текст.
```python
gui.get_viewport() -> {int, int}
```
Возвращает размер главного контейнера (окна).
```python
gui.get_env(document: str) -> table
```
Возвращает окружение (таблица глобальных переменных) указанного документа.
```python
gui.get_locales_info() -> таблица таблиц где
ключ - id локали в формате isolangcode_ISOCOUNTRYCODE
значение - таблица {
name: str # название локали на её языке
}
```
Возвращает информацию о всех загруженных локалях (res/texts/\*).
```lua ```lua
-- Возвращает переведённый текст.
gui.str(text: string, context: string) -> string
```
## Окно и окружение
```lua
-- Возвращает размер главного контейнера (окна).
gui.get_viewport() -> {number, number}
-- Возвращает окружение (глобальные переменные) указанного документа.
gui.get_env(document: string) -> table
-- Возвращает информацию о всех загруженных локалях.
-- Ключ - id локали в формате isolangcode_ISOCOUNTRYCODE
-- Значение - таблица { name: string }
gui.get_locales_info() -> table
```
## Разметка
```lua
-- Удаляет разметку из текста.
gui.clear_markup( gui.clear_markup(
-- язык разметки ("md" - Markdown) language: string, -- язык разметки ("md" - Markdown)
language: str, text: string -- текст с разметкой
-- текст с разметкой ) -> string
text: str
) -> str
```
Удаляет разметку из текста. -- Экранирует разметку в тексте.
```lua
gui.escape_markup( gui.escape_markup(
-- язык разметки ("md" - Markdown) language: string, -- язык разметки ("md" - Markdown)
language: str, text: string -- текст с разметкой
-- текст с разметкой ) -> string
text: str
) -> str
``` ```
Экранирует разметку в тексте. ## Диалоговые окна
```lua ```lua
-- Выводит окно с сообщением. Не останавливает выполнение кода.
gui.alert( gui.alert(
-- сообщение (не переводится автоматически, используйте gui.str(...)) message: string, -- сообщение (не переводится автоматически, используйте gui.str(...))
message: str, on_ok: function() -> nil -- вызывается при закрытии
-- функция, вызываемая при закрытии
on_ok: function() -> nil
) )
```
Выводит окно с сообщением. **Не** останавливает выполнение кода. -- Запрашивает подтверждение действия. Не останавливает выполнение кода.
```lua
gui.confirm( gui.confirm(
-- сообщение (не переводится автоматически, используйте gui.str(...)) -- сообщение (не переводится автоматически, используйте gui.str(...))
message: str, message: string,
-- функция, вызываемая при подтвержении -- функция, вызываемая при подтвержении
on_confirm: function() -> nil, on_confirm: function() -> nil,
-- функция, вызываемая при отказе/отмене -- функция, вызываемая при отказе/отмене
[опционально] on_deny: function() -> nil, [опционально] on_deny: function() -> nil,
-- текст кнопки подтвержения (по-умолчанию: "Да") -- текст кнопки подтвержения (по-умолчанию: "Да")
-- используйте пустую строку для значения по-умолчанию, если нужно указать no_text. -- используйте пустую строку для значения по-умолчанию, если нужно указать no_text.
[опционально] yes_text: str, [опционально] yes_text: string
-- текст кнопки отказа (по-умолчанию: "Нет") -- текст кнопки отказа (по-умолчанию: "Нет")
[опционально] no_text: str, [опционально] no_text: string
) )
``` ```
Запрашивает у пользователя подтверждение действия. **Не** останавливает выполнение кода. ## Документы и шаблоны
```lua ```lua
-- Загружает UI документ и его скрипт. Возвращает имя документа.
gui.load_document( gui.load_document(
-- Путь к xml файлу страницы. Пример: `core:layouts/pages/main.xml` path: string, -- путь к xml файлу, например: core:layouts/pages/main.xml
path: str, name: string, -- id документа, например: core:pages/main
-- Имя (id) документа. Пример: `core:pages/main` args: table -- параметры для события on_open
name: str ) -> string
-- Таблица параметров, передаваемых в событие on_open
args: table -- Загружает шаблон в лояут
) --> str gui.template(
-- имя шаблона в layouts/templates без пути и расширения
name: string,
-- таблица переменных (может быть использована в разметке)
-- * Пр: <label>%{text}</label>
-- * text в данном случае, это значение из params по ключу text
params: table,
-- таблица, доступная в событиях как глобальная переменная DATA
[опционально] data: table
) -> string
``` ```
Загружает UI документ с его скриптом, возвращает имя документа, если успешно загружен. ## Корневой документ
```lua ```lua
-- Корневой UI документ.
gui.root: Document gui.root: Document
``` ```
Корневой UI документ

22
doc/ru/scripting/builtins/libhud.md
View file

@ -13,24 +13,24 @@ hud.close_inventory()
-- Возвращает invid или id виртуального инвентаря. -- Возвращает invid или id виртуального инвентаря.
hud.open( hud.open(
-- Макет UI -- Макет UI
layoutid: str, layoutid: string,
-- Не открывать инвентарь игрока -- Не открывать инвентарь игрока
[опционально] disablePlayerInventory: bool, [опционально] disablePlayerInventory: boolean,
-- Инвентарь, к которому будет привязан UI макет -- Инвентарь, к которому будет привязан UI макет
[опционально] invid: int [опционально] invid: int
) -> int ) -> int
-- Возвращает true если указаный макет UI открыт. -- Возвращает true если указаный макет UI открыт.
hud.is_open( hud.is_open(
layoutid: str layoutid: string
) -> bool ) -> boolean
-- Открывает инвентарь и UI блока. -- Открывает инвентарь и UI блока.
-- Если блок не имеет макета UI - бросается исключение. -- Если блок не имеет макета UI - бросается исключение.
-- Возвращает id инвентаря блока -- Возвращает id инвентаря блока
-- (при *"inventory-size"=0* создаётся виртуальный инвентарь, -- (при *"inventory-size"=0* создаётся виртуальный инвентарь,
-- который удаляется после закрытия), и id макета UI. -- который удаляется после закрытия), и id макета UI.
hud.open_block(x: int, y: int, z: int) -> int, str hud.open_block(x: int, y: int, z: int) -> int, string
``` ```
> [!NOTE] > [!NOTE]
@ -41,16 +41,16 @@ hud.open_block(x: int, y: int, z: int) -> int, str
-- Также показывает инвентарь игрока, если playerinv - **true**. -- Также показывает инвентарь игрока, если playerinv - **true**.
-- Через args можно указать массив значений параметров, что будут переданы -- Через args можно указать массив значений параметров, что будут переданы
-- в on_open показываемого оверлея. -- в on_open показываемого оверлея.
hud.show_overlay(layoutid: str, playerinv: bool, [опционально] args: table) hud.show_overlay(layoutid: string, playerinv: boolean, [опционально] args: table)
-- Добавляет постоянный элемент на экран. Элемент не удаляется при -- Добавляет постоянный элемент на экран. Элемент не удаляется при
-- закрытии инвентаря. Чтобы не перекрывать затенение в режиме -- закрытии инвентаря. Чтобы не перекрывать затенение в режиме
-- инвентаря нужно установить z-index элемента меньшим чем -1. -- инвентаря нужно установить z-index элемента меньшим чем -1.
-- В случае тега inventory, произойдет привязка слотов к инвентарю игрока. -- В случае тега inventory, произойдет привязка слотов к инвентарю игрока.
hud.open_permanent(layoutid: str) hud.open_permanent(layoutid: string)
-- Удаляет элемент с экрана. -- Удаляет элемент с экрана.
hud.close(layoutid: str) hud.close(layoutid: string)
-- Дает ID инвентаря открытого блока или 0. -- Дает ID инвентаря открытого блока или 0.
hud.get_block_inventory() -> int hud.get_block_inventory() -> int
@ -65,13 +65,13 @@ hud.pause()
hud.resume() hud.resume()
-- Возвращает true если открыто меню паузы. -- Возвращает true если открыто меню паузы.
hud.is_paused() -> bool hud.is_paused() -> boolean
-- Возвращает true если открыт инвентарь или оверлей. -- Возвращает true если открыт инвентарь или оверлей.
hud.is_inventory_open() -> bool hud.is_inventory_open() -> boolean
-- Устанавливает разрешение на паузу. При значении false меню паузы не приостанавливает игру. -- Устанавливает разрешение на паузу. При значении false меню паузы не приостанавливает игру.
hud.set_allow_pause(flag: bool) hud.set_allow_pause(flag: boolean)
-- Функция, управляющая именованным скелетом 'hand' (см. gfx.skeletons) -- Функция, управляющая именованным скелетом 'hand' (см. gfx.skeletons)
hud.hand_controller: function() hud.hand_controller: function()

92
doc/ru/scripting/builtins/libinput.md
View file

@ -1,27 +1,52 @@
# Библиотека *input* # Библиотека *input*
## Основные методы
```lua ```lua
input.keycode(keyname: str) --> int -- Возвращает код клавиши по имени, либо -1
input.keycode(keyname: string) -> number
-- Возвращает код кнопки мыши по имени, либо -1
input.mousecode(mousename: string) -> number
-- Проверяет активность ввода по коду, состоящему из:
-- * типа ввода: key (клавиша) или mouse (кнопка мыши)
-- * код ввода: [имя клавиши](#имена-клавиш) или имя кнопки мыши (left, middle, right)
input.is_pressed(code: string) -> boolean
-- Возвращает названия всех доступных привязок.
input.get_bindings() -> table<string>
-- Возвращает текстовое представление кнопки по имени привязки.
input.get_binding_text(bindname: string) -> string
-- Проверяет активность привязки.
input.is_active(bindname: string) -> string
-- Включает/выключает привязку до выхода из мира.
input.set_enabled(bindname: string, flag: boolean)
``` ```
Возвращает код клавиши по имени, либо -1 ## Курсор мыши
```lua ```lua
input.mousecode(mousename: str) --> int -- Возвращает позицию курсора на экране.
input.get_mouse_pos() -> {number, number}
-- Возращает дельту позиции курсора.
input.get_mouse_delta() -> {number, number}
``` ```
Возвращает код кнопки мыши по имени, либо -1 ## Создание обработчиков
```lua ```lua
input.add_callback( input.add_callback(
-- Имя привязки -- Имя привязки
bindname: str, bindname: string,
-- Обработчик -- Обработчик
callback: function callback: function
-- UI элемент-владелец обработчика (отвечает за срок жизни) -- UI элемент-владелец обработчика (отвечает за срок жизни)
[опционально] owner: Element, [опционально] owner: Element,
-- Игнорировать захват ввода UI элементами -- Игнорировать захват ввода UI элементами
[опционально] istoplevel: bool [опционально] istoplevel: boolean
) )
``` ```
@ -50,54 +75,3 @@ input.add_callback("key:escape", function ()
return true -- предотвращает вызов назначенных ранее функций return true -- предотвращает вызов назначенных ранее функций
end, document.root) end, document.root)
``` ```
```lua
input.get_mouse_pos() --> {int, int}
```
Возвращает позицию курсора на экране.
```lua
input.get_mouse_delta() --> {int, int}
```
Возращает дельту позиции курсора.
```lua
input.get_bindings() --> массив строк
```
Возвращает названия всех доступных привязок.
```lua
input.get_binding_text(bindname: str) --> str
```
Возвращает текстовое представление кнопки по имени привязки.
```lua
input.is_active(bindname: str) --> bool
```
Проверяет активность привязки.
```lua
input.set_enabled(bindname: str, flag: bool)
```
Включает/выключает привязку до выхода из мира.
```lua
input.is_pressed(code: str) --> bool
```
Проверяет активность ввода по коду, состоящему из:
- типа ввода: key (клавиша) или mouse (кнопка мыши)
- код ввода: [имя клавиши](#имена-клавиш) или имя кнопки мыши (left, middle, right)
Пример:
```lua
if input.is_pressed("key:enter") then
...
end
```

20
doc/ru/scripting/builtins/libinventory.md
View file

@ -80,11 +80,11 @@ inventory.remove(invid: int)
> [!WARNING] > [!WARNING]
> Инвентари, не привязанные ни к одному из блоков, удаляются при выходе из мира. > Инвентари, не привязанные ни к одному из блоков, удаляются при выходе из мира.
> [!NOTE]
Локальные свойства предмета - данные прикреплённые к последнему предмету в стеке. > Локальные свойства предмета - данные прикреплённые к последнему предмету в стеке.
При разделении стека (ПКМ) данные не копируются а перемемещаются в новый стек. > При разделении стека (ПКМ) данные не копируются а перемещаются в новый стек.
Свойства могут иметь любой сериализуемый тип, включая таблицы. > Свойства могут иметь любой сериализуемый тип, включая таблицы.
В отличие от полей блоков имена свойств не требуется регистрировать в определении предмета. > В отличие от полей блоков имена свойств не требуется регистрировать в определении предмета.
Сочетание Сочетание
```lua ```lua
@ -93,7 +93,7 @@ inventory.get_all_data(...)
inventory.set(...) inventory.set(...)
inventory.set_all_data(...) inventory.set_all_data(...)
``` ```
для перемещения вляется неэффективным, используйте inventory.move или inventory.move_range. для перемещения является неэффективным, используйте inventory.move или inventory.move_range.
```lua ```lua
-- Получает имя предмета в слоте -- Получает имя предмета в слоте
inventory.get_caption( inventory.get_caption(
@ -138,8 +138,8 @@ inventory.has_data(
-- индекс слота -- индекс слота
slot: int, slot: int,
-- имя свойства -- имя свойства
name: str name: string
) -> bool ) -> boolean
-- Возвращает копию значения локального свойства предмета по имени или nil. -- Возвращает копию значения локального свойства предмета по имени или nil.
inventory.get_data( inventory.get_data(
@ -148,7 +148,7 @@ inventory.get_data(
-- индекс слота -- индекс слота
slot: int, slot: int,
-- имя свойства -- имя свойства
name: str name: string
) -> any ) -> any
-- Устанавливает значение локального свойства предмета по имени. -- Устанавливает значение локального свойства предмета по имени.
@ -159,7 +159,7 @@ inventory.set_data(
-- индекс слота -- индекс слота
slot: int, slot: int,
-- имя свойства -- имя свойства
name: str name: string
-- значение -- значение
value: any value: any
) )

18
doc/ru/scripting/builtins/libitem.md
View file

@ -2,16 +2,16 @@
```lua ```lua
-- Возвращает строковый id предмета по его числовому id (как block.name) -- Возвращает строковый id предмета по его числовому id (как block.name)
item.name(itemid: int) -> str item.name(itemid: int) -> string
-- Возвращает числовой id предмета по строковому id (как block_index) -- Возвращает числовой id предмета по строковому id (как block_index)
item.index(name: str) -> int item.index(name: string) -> int
-- Возвращает название предмета, отображаемое в интерфейсе. -- Возвращает название предмета, отображаемое в интерфейсе.
item.caption(itemid: int) -> str item.caption(itemid: int) -> string
-- Возвращает описание предмета, отображаемое в интерфейсе. -- Возвращает описание предмета, отображаемое в интерфейсе.
item.description(itemid: int) -> str item.description(itemid: int) -> string
-- Возвращает максимальный размер стопки для предмета. -- Возвращает максимальный размер стопки для предмета.
item.stack_size(itemid: int) -> int item.stack_size(itemid: int) -> int
@ -20,22 +20,20 @@ item.stack_size(itemid: int) -> int
item.defs_count() -> int item.defs_count() -> int
-- Возвращает имя иконки предмета для использования в свойстве 'src' элемента image -- Возвращает имя иконки предмета для использования в свойстве 'src' элемента image
item.icon(itemid: int) -> str item.icon(itemid: int) -> string
-- Возвращает числовой id блока, назначенного как 'placing-block' или 0 -- Возвращает числовой id блока, назначенного как 'placing-block' или 0
item.placing_block(itemid: int) -> int item.placing_block(itemid: int) -> int
-- Возвращает значение свойства `model-name` -- Возвращает значение свойства `model-name`
item.model_name(itemid: int) -> str item.model_name(itemid: int) -> string
-- Возвращает emission параметр у предмета -- Возвращает emission параметр у предмета
item.emission(itemid: int) -> str item.emission(itemid: int) -> string
-- Возвращает значение свойства `uses` -- Возвращает значение свойства `uses`
item.uses(itemid: int) -> int item.uses(itemid: int) -> int
-- Проверяет наличие тега у предмета -- Проверяет наличие тега у предмета
item.has_tag(itemid: int, tag: str) -> bool item.has_tag(itemid: int, tag: string) -> boolean
``` ```

2
doc/ru/scripting/builtins/libmat4.md
View file

@ -129,5 +129,5 @@ mat4.look_at(eye: vec3, center: vec3, up: vec3, dst: matrix)
-- возвращает строку представляющую содержимое матрицы -- возвращает строку представляющую содержимое матрицы
mat4.tostring(m: matrix) mat4.tostring(m: matrix)
-- возвращает строку представляющую содержимое матрицы, многострочную, если multiline = true -- возвращает строку представляющую содержимое матрицы, многострочную, если multiline = true
mat4.tostring(m: matrix, multiline: bool) mat4.tostring(m: matrix, multiline: boolean)
``` ```

80
doc/ru/scripting/builtins/libnetwork.md
View file

@ -7,13 +7,13 @@
```lua ```lua
-- Выполняет GET запрос к указанному URL. -- Выполняет GET запрос к указанному URL.
network.get( network.get(
url: str, url: string,
-- Функция, вызываемая при получении ответа -- Функция, вызываемая при получении ответа
callback: function(str), callback: function(string),
-- Обработчик ошибок -- Обработчик ошибок
[опционально] onfailure: function(int, str), [опционально] onfailure: function(int, string),
-- Список дополнительных заголовков запроса -- Список дополнительных заголовков запроса
[опционально] headers: table<str> [опционально] headers: table<string>
) )
-- Пример: -- Пример:
@ -23,10 +23,10 @@ end)
-- Вариант для двоичных файлов, с массивом байт вместо строки в ответе. -- Вариант для двоичных файлов, с массивом байт вместо строки в ответе.
network.get_binary( network.get_binary(
url: str, url: string,
callback: function(ByteArray), callback: function(Bytearray),
[опционально] onfailure: function(int, Bytearray), [опционально] onfailure: function(int, Bytearray),
[опционально] headers: table<str> [опционально] headers: table<string>
) )
-- Выполняет POST запрос к указанному URL. -- Выполняет POST запрос к указанному URL.
@ -34,15 +34,15 @@ network.get_binary(
-- После получения ответа, передаёт текст в функцию callback. -- После получения ответа, передаёт текст в функцию callback.
-- В случае ошибки в onfailure будет передан HTTP-код ответа. -- В случае ошибки в onfailure будет передан HTTP-код ответа.
network.post( network.post(
url: str, url: string,
-- Тело запроса в виде таблицы, конвертируемой в JSON или строки -- Тело запроса в виде таблицы, конвертируемой в JSON или строки
body: table|str, body: table|string,
-- Функция, вызываемая при получении ответа -- Функция, вызываемая при получении ответа
callback: function(str), callback: function(string),
-- Обработчик ошибок -- Обработчик ошибок
[опционально] onfailure: function(int, str), [опционально] onfailure: function(int, string),
-- Список дополнительных заголовков запроса -- Список дополнительных заголовков запроса
[опционально] headers: table<str> [опционально] headers: table<string>
) )
``` ```
@ -51,7 +51,7 @@ network.post(
```lua ```lua
network.tcp_connect( network.tcp_connect(
-- Адрес -- Адрес
address: str, address: string,
-- Порт -- Порт
port: int, port: int,
-- Функция, вызываемая при успешном подключении -- Функция, вызываемая при успешном подключении
@ -60,8 +60,8 @@ network.tcp_connect(
callback: function(Socket) callback: function(Socket)
-- Функция, вызываемая при ошибке подключения -- Функция, вызываемая при ошибке подключения
-- Как аргументы передаются сокет и текст ошибки -- Как аргументы передаются сокет и текст ошибки
[опционально] error_callback: function(Socket, str) [опционально] error_callback: function(Socket, string)
) --> Socket ) -> Socket
``` ```
Инициирует TCP подключение. Инициирует TCP подключение.
@ -70,14 +70,14 @@ network.tcp_connect(
```lua ```lua
-- Отправляет массив байт -- Отправляет массив байт
socket:send(table|ByteArray|str) socket:send(table|Bytearray|string)
-- Читает полученные данные -- Читает полученные данные
socket:recv( socket:recv(
-- Максимальный размер читаемого массива байт -- Максимальный размер читаемого массива байт
length: int, length: int,
-- Использовать таблицу вместо Bytearray -- Использовать таблицу вместо Bytearray
[опционально] usetable: bool=false [опционально] usetable: boolean=false
) -> nil|table|Bytearray ) -> nil|table|Bytearray
-- В случае ошибки возвращает nil (сокет закрыт или несуществует). -- В случае ошибки возвращает nil (сокет закрыт или несуществует).
-- Если данных пока нет, возвращает пустой массив байт. -- Если данных пока нет, возвращает пустой массив байт.
@ -89,29 +89,29 @@ socket:recv_async(
-- Размер читаемого массива байт -- Размер читаемого массива байт
length: int, length: int,
-- Использовать таблицу вместо Bytearray -- Использовать таблицу вместо Bytearray
[опционально] usetable: bool=false [опционально] usetable: boolean=false
) -> nil|table|Bytearray ) -> nil|table|Bytearray
-- Закрывает соединение -- Закрывает соединение
socket:close() socket:close()
-- Возвращает количество доступных для чтения байт данных -- Возвращает количество доступных для чтения байт данных
socket:available() --> int socket:available() -> int
-- Проверяет, что сокет существует и не закрыт. -- Проверяет, что сокет существует и не закрыт.
socket:is_alive() --> bool socket:is_alive() -> boolean
-- Проверяет наличие соединения (доступно использование socket:send(...)). -- Проверяет наличие соединения (доступно использование socket:send(...)).
socket:is_connected() --> bool socket:is_connected() -> boolean
-- Возвращает адрес и порт соединения. -- Возвращает адрес и порт соединения.
socket:get_address() --> str, int socket:get_address() -> string, int
-- Возвращает состояние NoDelay -- Возвращает состояние NoDelay
socket:is_nodelay() --> bool socket:is_nodelay() -> boolean
-- Устанавливает состояние NoDelay -- Устанавливает состояние NoDelay
socket:set_nodelay(state: bool) socket:set_nodelay(state: boolean)
``` ```
```lua ```lua
@ -122,7 +122,7 @@ network.tcp_open(
-- Функция, вызываемая при поключениях -- Функция, вызываемая при поключениях
-- Как единственный аргумент передаётся сокет подключенного клиента -- Как единственный аргумент передаётся сокет подключенного клиента
callback: function(Socket) callback: function(Socket)
) --> ServerSocket ) -> ServerSocket
``` ```
Класс SocketServer имеет следующие методы: Класс SocketServer имеет следующие методы:
@ -132,24 +132,24 @@ network.tcp_open(
server:close() server:close()
-- Проверяет, существует и открыт ли TCP сервер. -- Проверяет, существует и открыт ли TCP сервер.
server:is_open() --> bool server:is_open() -> boolean
-- Возвращает порт сервера. -- Возвращает порт сервера.
server:get_port() --> int server:get_port() -> int
``` ```
## UDP-Датаграммы ## UDP-Датаграммы
```lua ```lua
network.udp_connect( network.udp_connect(
address: str, address: string,
port: int, port: int,
-- Функция, вызываемая при получении датаграммы с указанного при открытии сокета адреса и порта -- Функция, вызываемая при получении датаграммы с указанного при открытии сокета адреса и порта
datagramHandler: function(Bytearray), datagramHandler: function(Bytearray),
-- Функция, вызываемая после открытия сокета -- Функция, вызываемая после открытия сокета
-- Опциональна, так как в UDP нет handshake -- Опциональна, так как в UDP нет handshake
[опционально] openCallback: function(WriteableSocket), [опционально] openCallback: function(WriteableSocket),
) --> WriteableSocket ) -> WriteableSocket
``` ```
Открывает UDP-сокет с привязкой к удалённому адресу и порту Открывает UDP-сокет с привязкой к удалённому адресу и порту
@ -158,16 +158,16 @@ network.udp_connect(
```lua ```lua
-- Отправляет датаграмму на адрес и порт, заданные при открытии сокета -- Отправляет датаграмму на адрес и порт, заданные при открытии сокета
socket:send(table|Bytearray|str) socket:send(table|Bytearray|string)
-- Закрывает сокет -- Закрывает сокет
socket:close() socket:close()
-- Проверяет открыт ли сокет -- Проверяет открыт ли сокет
socket:is_open() --> bool socket:is_open() -> boolean
-- Возвращает адрес и порт, на которые привязан сокет -- Возвращает адрес и порт, на которые привязан сокет
socket:get_address() --> str, int socket:get_address() -> string, int
``` ```
```lua ```lua
@ -175,8 +175,8 @@ network.udp_open(
port: int, port: int,
-- Функция, вызываемая при получении датаграмы -- Функция, вызываемая при получении датаграмы
-- В параметры передаётся адрес и порт отправителя, а также сами данные -- В параметры передаётся адрес и порт отправителя, а также сами данные
datagramHandler: function(address: str, port: int, data: Bytearray, server: DatagramServerSocket) datagramHandler: function(address: string, port: int, data: Bytearray, server: DatagramServerSocket)
) --> DatagramServerSocket ) -> DatagramServerSocket
``` ```
Открывает UDP-сервер на указанном порту Открывает UDP-сервер на указанном порту
@ -185,16 +185,16 @@ network.udp_open(
```lua ```lua
-- Отправляет датаграмму на переданный адрес и порт -- Отправляет датаграмму на переданный адрес и порт
server:send(address: str, port: int, data: table|Bytearray|str) server:send(address: string, port: int, data: table|Bytearray|string)
-- Завершает принятие датаграмм -- Завершает принятие датаграмм
server:stop() server:stop()
-- Проверяет возможность принятия датаграмм -- Проверяет возможность принятия датаграмм
server:is_open() --> bool server:is_open() -> boolean
-- Возвращает порт, который слушает сервер -- Возвращает порт, который слушает сервер
server:get_port() --> int server:get_port() -> int
``` ```
## Аналитика ## Аналитика
@ -202,15 +202,15 @@ server:get_port() --> int
```lua ```lua
-- Возвращает приблизительный объем отправленных данных (включая соединения с localhost) -- Возвращает приблизительный объем отправленных данных (включая соединения с localhost)
-- в байтах. -- в байтах.
network.get_total_upload() --> int network.get_total_upload() -> int
-- Возвращает приблизительный объем полученных данных (включая соединения с localhost) -- Возвращает приблизительный объем полученных данных (включая соединения с localhost)
-- в байтах. -- в байтах.
network.get_total_download() --> int network.get_total_download() -> int
``` ```
## Другое ## Другое
```lua ```lua
-- Ищет свободный для использования порт. -- Ищет свободный для использования порт.
network.find_free_port() --> int или nil network.find_free_port() -> int | nil
``` ```

54
doc/ru/scripting/builtins/libpack.md
View file

@ -1,15 +1,15 @@
# Библиотека *pack* # Библиотека *pack*
```python ```lua
pack.is_installed(packid: str) -> bool pack.is_installed(packid: string) -> boolean
``` ```
Проверяет наличие установленного пака в мире Проверяет наличие установленного пака в мире
```lua ```lua
pack.data_file(packid: str, filename: str) -> str pack.data_file(packid: string, filename: string) -> string
-- и -- и
pack.shared_file(packid: str, filename: str) -> str pack.shared_file(packid: string, filename: string) -> string
``` ```
Возвращает путь к файлу данных Возвращает путь к файлу данных
@ -33,46 +33,46 @@ file.write(pack.shared_file(PACK_ID, "example.txt"), text)
Используйте для хранения данных общих для всех миров. Используйте для хранения данных общих для всех миров.
```python ```lua
pack.get_folder(packid: str) -> str pack.get_folder(packid: string) -> string
``` ```
Возвращает путь к папке установленного контент-пака. Возвращает путь к папке установленного контент-пака.
```python ```lua
pack.is_installed(packid: str) -> bool pack.is_installed(packid: string) -> boolean
``` ```
Проверяет наличие контент-пака в мире Проверяет наличие контент-пака в мире
```python ```lua
pack.get_installed() -> массив строк pack.get_installed() -> table<string>
``` ```
Возращает id всех установленных в мире контент-паков. Возращает id всех установленных в мире контент-паков.
```python ```lua
pack.get_available() -> массив строк pack.get_available() -> table<string>
``` ```
Возвращает id всех доступных, но не установленных в мире контент-паков. Возвращает id всех доступных, но не установленных в мире контент-паков.
```python ```lua
pack.get_base_packs() -> массив строк pack.get_base_packs() -> table<string>
``` ```
Возвращает id всех базовых паков (неудаляемых) Возвращает id всех базовых паков (неудаляемых)
```lua ```lua
pack.get_info(packid: str) -> { pack.get_info(packid: string) -> {
id: str, id: string,
title: str, title: string,
creator: str, creator: string,
description: str, description: string,
version: str, version: string,
path: str, path: string,
icon: str, -- отсутствует в headless режиме icon: string, -- отсутствует в headless режиме
dependencies: опциональный массив строк dependencies: table<string> -- опциональный
} }
``` ```
@ -88,17 +88,17 @@ pack.get_info(packid: str) -> {
производить сканирование для каждого пака: производить сканирование для каждого пака:
```lua ```lua
pack.get_info(packids: table) -> {id={...}, id2={...}, ...} pack.get_info(packids: table<string>) -> table<string, table>
``` ```
```lua ```lua
pack.assemble(packids: table) -> table pack.assemble(packids: table<string>) -> table<string>
``` ```
Проверяет корректность конфигурации и добавляет зависимости, возвращая полную. Проверяет корректность конфигурации и добавляет зависимости, возвращая полную конфигурацию.
```lua ```lua
pack.request_writeable(packid: str, callback: function(str)) pack.request_writeable(packid: string, callback: function(string))
``` ```
Запрашивает у пользователя право на модификацию пака. При подтвержении новая точка входа будет передана в callback. Запрашивает у пользователя право на модификацию пака. При подтвержении новая точка входа будет передана в callback.

16
doc/ru/scripting/builtins/libpathfinding.md
View file

@ -18,11 +18,11 @@ local z = ...
pf.set_target({x, y, z}) pf.set_target({x, y, z})
--- Получение текущей цели агента --- Получение текущей цели агента
local target = pf.get_target() --> vec3 или nil local target = pf.get_target() -> vec3 или nil
--- ... --- ...
--- Получение текущего маршрута агента --- Получение текущего маршрута агента
local route = pf.get_route() --> table<vec3> или nil local route = pf.get_route() -> table<vec3> или nil
--- ... --- ...
``` ```
@ -30,19 +30,19 @@ local route = pf.get_route() --> table<vec3> или nil
```lua ```lua
--- Создание нового агента. Возвращает идентификатор созданного агента --- Создание нового агента. Возвращает идентификатор созданного агента
local agent = pathfinding.create_agent() --> int local agent = pathfinding.create_agent() -> int
--- Удаление агента по идентификатору. Возвращает true, если агент существовал, иначе false --- Удаление агента по идентификатору. Возвращает true, если агент существовал, иначе false
pathfinding.remove_agent(agent: int) --> bool pathfinding.remove_agent(agent: int) -> boolean
--- Установка состояния агента (включен/выключен) --- Установка состояния агента (включен/выключен)
pathfinding.set_enabled(agent: int, enabled: bool) pathfinding.set_enabled(agent: int, enabled: boolean)
--- Проверка состояния агента. Возвращает true, если агент включен, иначе false --- Проверка состояния агента. Возвращает true, если агент включен, иначе false
pathfinding.is_enabled(agent: int) --> bool pathfinding.is_enabled(agent: int) -> boolean
--- Создание маршрута на основе заданных точек. Возвращает массив точек маршрута --- Создание маршрута на основе заданных точек. Возвращает массив точек маршрута
pathfinding.make_route(start: vec3, target: vec3) --> table<vec3> pathfinding.make_route(start: vec3, target: vec3) -> table<vec3>
--- Асинхронное создание маршрута на основе заданных точек. --- Асинхронное создание маршрута на основе заданных точек.
--- Функция позволяет выполнять поиск пути в фоновом режиме, не блокируя основной поток выполнения --- Функция позволяет выполнять поиск пути в фоновом режиме, не блокируя основной поток выполнения
@ -50,7 +50,7 @@ pathfinding.make_route_async(agent: int, start: vec3, target: vec3)
--- Получение маршрута, который агент уже нашел. Используется для получения маршрута после асинхронного поиска. --- Получение маршрута, который агент уже нашел. Используется для получения маршрута после асинхронного поиска.
--- Если поиск ещё не завершён, возвращает nil. Если маршрут не найден, возвращает пустую таблицу. --- Если поиск ещё не завершён, возвращает nil. Если маршрут не найден, возвращает пустую таблицу.
pathfinding.pull_route(agent: int) --> table<vec3> или nil pathfinding.pull_route(agent: int) -> table<vec3> или nil
--- Установка максимального количества посещенных блоков для агента. Используется для ограничения объема работы алгоритма поиска пути. --- Установка максимального количества посещенных блоков для агента. Используется для ограничения объема работы алгоритма поиска пути.
pathfinding.set_max_visited(agent: int, max_visited: int) pathfinding.set_max_visited(agent: int, max_visited: int)

228
doc/ru/scripting/builtins/libplayer.md
View file

@ -1,180 +1,128 @@
# Библиотека *player* ## Содержание
- [Управление игроками](#управление-игроками)
- [Позиция и движение](#позиция-и-движение)
- [Режимы и свойства](#режимы-и-свойства)
- [Инвентарь и взаимодействие](#инвентарь-и-взаимодействие)
- [Камеры](#камеры)
- [Поиск игроков](#поиск-игроков)
## Управление игроками
```lua ```lua
player.create(name: str) -> int -- Создает игрока и возвращает его ID
``` player.create(name: string) -> int
Создаёт игрока и возвращает его id. -- Удаляет игрока по ID
```lua
player.delete(id: int) player.delete(id: int)
-- Возвращает ID сущности игрока
player.get_entity(playerid: int) -> int
-- Сеттер и геттер точки спавна игрока
player.set_spawnpoint(playerid: int, x: number, y: number, z: number)
player.get_spawnpoint(playerid: int) -> number, number, number
-- Сеттер и геттер имени игрока
player.set_name(playerid: int, name: string)
player.get_name(playerid: int) -> string
-- Сеттер и геттер статуса "заморозки" игрока.
player.set_suspended(pid: int, suspended: boolean)
player.is_suspended(pid: int) -> boolean
``` ```
Удаляет игрока по id. ## Позиция и движение
```lua
player.get_pos(playerid: int) -> number, number, number
```
Возвращает x, y, z координаты игрока
```lua ```lua
-- Сеттер и геттер позиции игрока
player.set_pos(playerid: int, x: number, y: number, z: number) player.set_pos(playerid: int, x: number, y: number, z: number)
``` player.get_pos(playerid: int) -> number, number, number
Устанавливает x, y, z координаты игрока
```lua -- Сеттер и геттер линейной скорости игрока
player.get_vel(playerid: int) -> number, number, number
```
Возвращает x, y, z линейной скорости игрока
```lua
player.set_vel(playerid: int, x: number, y: number, z: number) player.set_vel(playerid: int, x: number, y: number, z: number)
``` player.get_vel(playerid: int) -> number, number, number
Устанавливает x, y, z линейной скорости игрока -- Сеттер и геттер вращения камеры игрока
```lua
player.get_rot(playerid: int, interpolated: bool=false) -> number, number, number
```
Возвращает x, y, z вращения камеры (в градусах). Интерполяция актуальна в случаях, когда частота обновления вращения ниже частоты кадров.
```lua
player.set_rot(playerid: int, x: number, y: number, z: number) player.set_rot(playerid: int, x: number, y: number, z: number)
``` player.get_rot(playerid: int, interpolated: boolean) -> number, number, number
Устанавливает x, y вращения камеры (в градусах)
```lua -- Возвращает вектор направления взгляда игрока
player.get_dir(playerid: int) -> vec3 player.get_dir(playerid: int) -> vec3
``` ```
Возвращает вектор направления взгляда игрока ## Режимы и свойства
```lua ```lua
-- Сеттер и геттер режима полета
player.set_flight(playerid: int, boolean)
player.is_flight(playerid: int) -> boolean
-- Сеттер и геттер режима noclip
player.set_noclip(playerid: int, boolean)
player.is_noclip(playerid: int) -> boolean
-- Сеттер и геттер бесконечных предметов (не удаляются из инвентаря при использовании)
player.set_infinite_items(playerid: int, boolean)
player.is_infinite_items(playerid: int) -> boolean
-- Сеттер и геттер мнгновенного разрушения блоков при активации привязки player.destroy.
player.set_instant_destruction(playerid: int, boolean)
player.is_instant_destruction(playerid: int) -> boolean
-- Сеттер и геттер свойства, определяющего, прогружает ли игрок чанки вокруг себя.
player.set_loading_chunks(playerid: int, boolean)
player.is_loading_chunks(playerid: int) -> boolean
-- Сеттер и геттер свойства, определяющего максимальную дистанцию взаимодействия.
player.set_interaction_distance(playerid: int, distance: number)
player.get_interaction_distance(playerid: int) -> number
```
## Инвентарь и взаимодействие
```lua
-- Возвращает ID инвентаря и индекс выбранного слота
player.get_inventory(playerid: int) -> int, int player.get_inventory(playerid: int) -> int, int
```
Возвращает id инвентаря игрока и индекс выбранного слота (от 0 до 9) -- Устанавливает выбранный слот
```lua
player.is_flight(playerid: int) -> bool
player.set_flight(playerid: int, bool)
```
Геттер и сеттер режима полета
```lua
player.is_noclip(playerid: int) -> bool
player.set_noclip(playerid: int, bool)
```
Геттер и сеттер noclip режима (выключенная коллизия игрока)
```lua
player.is_infinite_items(playerid: int) -> bool
player.set_infinite_items(playerid: int, bool)
```
Геттер и сеттер бесконечных предметов (не удаляются из инвентаря при использовании)
```lua
player.is_instant_destruction(playerid: int) -> bool
player.set_instant_destruction(playerid: int, bool)
```
Геттер и сеттер мнгновенного разрушения блоков при активации привязки `player.destroy`.
```lua
player.is_loading_chunks(playerid: int) -> bool
player.set_loading_chunks(playerid: int, bool)
```
Геттер и сеттер свойства, определяющего, прогружает ли игрок чанки вокруг.
```lua
player.get_interaction_distance(playerid: int) -> float
player.set_interaction_distance(playerid: int, distance: float)
```
Геттер и сеттер свойства, определяющего максимальную дистанцию взаимодействия.
```lua
player.set_spawnpoint(playerid: int, x: number, y: number, z: number)
player.get_spawnpoint(playerid: int) -> number, number, number
```
Сеттер и геттер точки спавна игрока
```lua
player.is_suspended(pid: int) -> bool
player.set_suspended(pid: int, suspended: bool)
```
Сеттер и геттер статуса "заморозки" игрока.
При "заморозке" удаляется сущность, а игрок выключается из симуляции мира.
```lua
player.set_name(playerid: int, name: str)
player.get_name(playerid: int) -> str
```
Сеттер и геттер имени игрока
```lua
player.get_camera(playerid: int) -> int
```
Возвращает индекс текущей камеры игрока
```lua
player.set_camera(playerid: int, camera_index: int)
```
Переключает камеру игрока. См. [камеры](libcameras.md).
```lua
player.set_selected_slot(playerid: int, slotid: int) player.set_selected_slot(playerid: int, slotid: int)
```
Устанавливает индекс выбранного слота -- Возвращает позицию выбранного блока
```lua
player.get_selected_block(playerid: int) -> x,y,z player.get_selected_block(playerid: int) -> x,y,z
```
Возвращает координаты выделенного блока, либо nil -- Возвращает ID выбранной сущности
```lua
player.get_selected_entity(playerid: int) -> int player.get_selected_entity(playerid: int) -> int
``` ```
Возвращает уникальный идентификатор сущности, на которую нацелен игрок ## Камеры
```lua ```lua
player.get_entity(playerid: int) -> int -- Возвращает индекс текущей камеры игрока
player.get_camera(playerid: int) -> int
-- Переключает камеры игрока
player.set_camera(playerid: int, camera_index: int)
``` ```
Возвращает уникальный идентификатор сущности игрока ## Поиск игроков
```lua ```lua
-- Возвращает массив id игроков в пределах сферы с центром center и радиусом radius.
player.get_all_in_radius(center: vec3, radius: number) -> table<int> player.get_all_in_radius(center: vec3, radius: number) -> table<int>
```
Возвращает массив id игроков в пределах сферы с центром `center` и радиусом `radius`. -- Возвращает массив id всех активных игроков.
```lua
player.get_all() -> table<int> player.get_all() -> table<int>
-- Возвращает id ближайшего к указанной позиции игрока, либо nil если игроков нет.
player.get_nearest(position: vec3) -> int / nil
``` ```
Возвращает массив id всех активных игроков.
```lua
player.get_nearest(position: vec3) -> int
```
Возвращает id ближайшего к указанной позиции игрока, либо nil если игроков нет.

6
doc/ru/scripting/builtins/libquat.md
View file

@ -6,7 +6,7 @@
```lua ```lua
-- создает кватернион на основе матрицы вращения -- создает кватернион на основе матрицы вращения
quat.from_mat4(m: matrix) quat.from_mat4(m: matrix) -> quat
-- записывает кватернион по матрице вращения в dst -- записывает кватернион по матрице вращения в dst
quat.from_mat4(m: matrix, dst: quat) quat.from_mat4(m: matrix, dst: quat)
@ -19,7 +19,7 @@ quat.from_mat4(m: matrix, dst: quat)
```lua ```lua
-- создает кватернион как интерполяцию между a и b, -- создает кватернион как интерполяцию между a и b,
-- где t - фактор интерполяции -- где t - фактор интерполяции
quat.slerp(a: quat, b: quat, t: number) quat.slerp(a: quat, b: quat, t: number) -> quat
-- записывает кватернион как интерполяцию между a и b в dst, -- записывает кватернион как интерполяцию между a и b в dst,
-- где t - фактор интерполяции -- где t - фактор интерполяции
@ -30,5 +30,5 @@ quat.slerp(a: quat, b: quat, t: number, dst: quat)
```lua ```lua
-- возвращает строку представляющую содержимое кватерниона -- возвращает строку представляющую содержимое кватерниона
quat.tostring(q: quat) quat.tostring(q: quat) -> string
``` ```

14
doc/ru/scripting/builtins/librandom.md
View file

@ -6,19 +6,19 @@
```lua ```lua
-- Генерирует случайное число в диапазоне [0..1) -- Генерирует случайное число в диапазоне [0..1)
random.random() --> number random.random() -> number
-- Генерирует случайное целое число в диапазоне [0..n] -- Генерирует случайное целое число в диапазоне [0..n]
random.random(n) --> number random.random(n) -> number
-- Генерирует случайное целое число в диапазоне [a..b] -- Генерирует случайное целое число в диапазоне [a..b]
random.random(a, b) --> number random.random(a, b) -> number
-- Генерирует случайный массив байт длиной n -- Генерирует случайный массив байт длиной n
random.bytes(n: number) -> Bytearray random.bytes(n: number) -> Bytearray
-- Генерирует UUID версии 4 -- Генерирует UUID версии 4
random.uuid() -> str random.uuid() -> string
``` ```
## Псевдослучайные числа ## Псевдослучайные числа
@ -29,9 +29,9 @@ random.uuid() -> str
local rng = random.Random() local rng = random.Random()
-- Используется аналогично math.random -- Используется аналогично math.random
local a = rng:random() --> [0..1) local a = rng:random() --> [0; 1)
local b = rng:random(10) --> [0..10] local b = rng:random(10) --> [0; 10]
local c = rng:random(5, 20) --> [5..20] local c = rng:random(5, 20) --> [5; 20]
-- Устанавливает состояние генератора для генерации воспроизводимой последовательности случайных чисел -- Устанавливает состояние генератора для генерации воспроизводимой последовательности случайных чисел
rng:seed(42) rng:seed(42)

14
doc/ru/scripting/builtins/librules.md
View file

@ -3,9 +3,9 @@
```lua ```lua
rules.create( rules.create(
-- имя правила -- имя правила
name: str, name: string,
-- значение по-умолчанию -- значение по-умолчанию
default: bool, default: boolean,
-- функция-обработчик изменения значения -- функция-обработчик изменения значения
[опционально] handler: function [опционально] handler: function
) -> int ) -> int
@ -21,7 +21,7 @@ rules.create(
```lua ```lua
rules.listen( rules.listen(
-- имя правила -- имя правила
name: str, name: string,
-- функция-обработчик изменения значения -- функция-обработчик изменения значения
handler: function handler: function
) -> int ) -> int
@ -32,26 +32,26 @@ rules.listen(
Также позволяет подписаться на правило до его создания. Также позволяет подписаться на правило до его создания.
```lua ```lua
rules.unlisten(name: str, id: int) rules.unlisten(name: string, id: int)
``` ```
Удаляет обработчик правила по id, если он существует. Удаляет обработчик правила по id, если он существует.
```lua ```lua
rules.get(name: str) -> bool | nil rules.get(name: string) -> boolean | nil
``` ```
Возвращает значение правила или nil, если оно ещё не было создано. Возвращает значение правила или nil, если оно ещё не было создано.
```lua ```lua
rules.set(name: str, value: bool) rules.set(name: string, value: boolean)
``` ```
Устанавливает значение правила, вызывая обработчики. Может использоваться и Устанавливает значение правила, вызывая обработчики. Может использоваться и
до создания правила. до создания правила.
```lua ```lua
rules.reset(name: str) rules.reset(name: string)
``` ```
Сбрасывает значение правила к значению по-умолчанию. Сбрасывает значение правила к значению по-умолчанию.

29
doc/ru/scripting/builtins/libtime.md
View file

@ -1,31 +1,18 @@
# Библиотека time # Библиотека time
```python ```lua
time.uptime() -> float -- Возвращает время с момента запуска движка в секундах и милисекундах.
``` time.uptime() -> number
Возвращает время с момента запуска движка в секундах. -- Возвращает дельту времени в секундах и милисекундах (время прошедшее с предыдущего кадра)
time.delta() -> number
```python -- Возвращает время UTC в секундах
time.delta() -> float
```
Возвращает дельту времени (время прошедшее с предыдущего кадра)
```python
time.utc_time() -> int time.utc_time() -> int
```
Возвращает время UTC в секундах -- Возвращает локальное (системное) время в секундах
```python
time.local_time() -> int time.local_time() -> int
```
Возвращает локальное (системное) время в секундах -- Возвращает смещение локального времени от UTC в секундах
```python
time.utc_offset() -> int time.utc_offset() -> int
``` ```
Возвращает смещение локального времени от UTC в секундах

20
doc/ru/scripting/builtins/libutf8.md
View file

@ -5,32 +5,32 @@
```lua ```lua
-- Конвертирует UTF-8 строку в Bytearray или массив чисел если -- Конвертирует UTF-8 строку в Bytearray или массив чисел если
-- второй аргумент - true -- второй аргумент - true
utf8.tobytes(text: str, [опционально] usetable=false) -> Bytearray|table utf8.tobytes(text: string, [опционально] usetable: boolean=false) -> Bytearray|table
-- Конвертирует Bytearray или массив чисел в UTF-8 строку -- Конвертирует Bytearray или массив чисел в UTF-8 строку
utf8.tostring(bytes: Bytearray|table) -> str utf8.tostring(bytes: Bytearray|table) -> string
-- Возвращает длину юникод-строки -- Возвращает длину юникод-строки
utf8.length(text: str) -> int utf8.length(text: string) -> int
-- Возвращает код первого символа строки -- Возвращает код первого символа строки
utf8.codepoint(chars: str) -> int utf8.codepoint(chars: string) -> int
-- Кодирует код в в UTF-8 -- Кодирует код в в UTF-8
utf8.encode(codepoint: int) -> str utf8.encode(codepoint: int) -> string
-- Возвращает подстроку от позиции startchar до endchar включительно -- Возвращает подстроку от позиции startchar до endchar включительно
utf8.sub(text: str, startchar: int, [опционально] endchar: int) -> str utf8.sub(text: string, startchar: int, [опционально] endchar: int) -> string
-- Переводит строку в вверхний регистр -- Переводит строку в вверхний регистр
utf8.upper(text: str) -> str utf8.upper(text: string) -> string
-- Переводит строку в нижний регистр -- Переводит строку в нижний регистр
utf8.lower(text: str) -> str utf8.lower(text: string) -> string
-- Экранирует строку -- Экранирует строку
utf8.escape(text: str) -> str utf8.escape(text: string) -> string
-- Экранирует спец-символы XML -- Экранирует спец-символы XML
utf8.escape_xml(text: str) -> str utf8.escape_xml(text: string) -> string
``` ```

68
doc/ru/scripting/builtins/libvecn.md
View file

@ -11,7 +11,7 @@
## Типы данных ## Типы данных
На данной странице будут использоваться условные обозначения типов. На данной странице будут использоваться условные обозначения типов.
- vector - массив из двух, трех или четырех чисел - vecn - массив из двух, трех или четырех чисел
- vec2 - массив из двух чисел - vec2 - массив из двух чисел
- vec3 - массив из трех чисел - vec3 - массив из трех чисел
- vec4 - массив из четырех чисел - vec4 - массив из четырех чисел
@ -27,76 +27,79 @@
```lua ```lua
-- возвращает результат сложения векторов -- возвращает результат сложения векторов
vecn.add(a: vector, b: vector) vecn.add(a: vecn, b: vecn) -> vecn
-- возвращает результат сложения вектора и скаляра -- возвращает результат сложения вектора и скаляра
vecn.add(a: vector, b: number) vecn.add(a: vecn, b: number) -> vecn
-- записывает результат сложения двух векторов в dst -- записывает результат сложения двух векторов в dst
vecn.add(a: vector, b: vector, dst: vector) vecn.add(a: vecn, b: vecn, dst: vecn)
``` ```
#### Вычитание - *vecn.sub(...)* #### Вычитание - *vecn.sub(...)*
```lua ```lua
-- возвращает результат вычитания векторов -- возвращает результат вычитания векторов
vecn.sub(a: vector, b: vector) vecn.sub(a: vecn, b: vecn) -> vecn
-- возвращает результат вычитания скаляра из вектора -- возвращает результат вычитания скаляра из вектора
vecn.sub(a: vector, b: number) vecn.sub(a: vecn, b: number) -> vecn
-- записывает результат вычитания двух векторов в dst -- записывает результат вычитания двух векторов в dst
vecn.sub(a: vector, b: vector, dst: vector) vecn.sub(a: vecn, b: vecn, dst: vecn)
``` ```
#### Умножение - *vecn.mul(...)* #### Умножение - *vecn.mul(...)*
```lua ```lua
-- возвращает результат умножения векторов -- возвращает результат умножения векторов
vecn.mul(a: vector, b: vector) vecn.mul(a: vecn, b: vecn) -> vecn
-- возвращает результат умножения вектора на скаляр -- возвращает результат умножения вектора на скаляр
vecn.mul(a: vector, b: number) vecn.mul(a: vecn, b: number) -> vecn
-- записывает результат умножения двух векторов в dst
vecn.mul(a: vecn, b: vecn, dst: vecn)
``` ```
#### Инверсия - *vecn.inv(...)* #### Инверсия - *vecn.inv(...)*
```lua ```lua
-- возвращает результат инверсии (противоположный) вектора -- возвращает результат инверсии (противоположный) вектора
vecn.inverse(a: vector) vecn.inverse(a: vecn) -> vecn
-- записывает инвертированный вектор в dst -- записывает инвертированный вектор в dst
vecn.inverse(v: vector, dst: vector) vecn.inverse(v: vecn, dst: vecn)
``` ```
#### Деление - *vecn.div(...)* #### Деление - *vecn.div(...)*
```lua ```lua
-- возвращает результат деления векторов -- возвращает результат деления векторов
vecn.div(a: vector, b: vector) vecn.div(a: vecn, b: vecn) -> vecn
-- возвращает результат деления вектора на скаляр -- возвращает результат деления вектора на скаляр
vecn.div(a: vector, b: number) vecn.div(a: vecn, b: number) -> vecn
-- записывает результат деления двух векторов в dst -- записывает результат деления двух векторов в dst
vecn.div(a: vector, b: vector, dst: vector) vecn.div(a: vecn, b: vecn, dst: vecn)
``` ```
#### Нормализация - *vecn.norm(...)* #### Нормализация - *vecn.norm(...)*
```lua ```lua
-- возвращает нормализованный вектор -- возвращает нормализованный вектор
vecn.normalize(a: vector) vecn.normalize(a: vecn) -> vecn
-- записывает нормализованный вектор в dst -- записывает нормализованный вектор в dst
vecn.normalize(v: vector, dst: vector) vecn.normalize(v: vecn, dst: vecn)
``` ```
#### Длина вектора - *vecn.len(...)* #### Длина вектора - *vecn.len(...)*
```lua ```lua
-- возвращает длину вектора -- возвращает длину вектора
vecn.length(a: vector) vecn.length(a: vecn) -> number
``` ```
@ -104,53 +107,56 @@ vecn.length(a: vector)
```lua ```lua
-- возвращает расстояние между двумя векторами -- возвращает расстояние между двумя векторами
vecn.distance(a: vector, b: vector) vecn.distance(a: vecn, b: vecn) -> number
``` ```
#### Абсолютное значение - *vecn.abs(...)* #### Абсолютное значение - *vecn.abs(...)*
```lua ```lua
-- возвращает вектор с абсолютными значениями -- возвращает вектор с абсолютными значениями
vecn.abs(a: vector) vecn.abs(a: vecn) -> vecn
-- записывает абсолютное значение вектора в dst -- записывает абсолютное значение вектора в dst
vecn.abs(v: vector, dst: vector) vecn.abs(v: vecn, dst: vecn)
``` ```
#### Округление - *vecn.round(...)* #### Округление - *vecn.round(...)*
```lua ```lua
-- возвращает вектор с округленными значениями -- возвращает вектор с округленными значениями
vecn.round(a: vector) vecn.round(a: vecn) -> vecn
-- записывает округленный вектор в dst -- записывает округленный вектор в dst
vecn.round(v: vector, dst: vector) vecn.round(v: vecn, dst: vecn)
``` ```
#### Степень - *vecn.pow(...)* #### Степень - *vecn.pow(...)*
```lua ```lua
-- возвращает вектор с элементами, возведенными в степень -- возвращает вектор с элементами, возведенными в степень
vecn.pow(a: vector, b: number) vecn.pow(a: vecn, b: number) -> vecn
-- возвращает вектор с элементами, возведенными в значения другого вектора
vecn.pow(a: vecn, b: vecn) -> vecn
-- записывает вектор, возведенный в степень, в dst -- записывает вектор, возведенный в степень, в dst
vecn.pow(v: vector, exponent: number, dst: vector) vecn.pow(v: vecn, exponent: number, dst: vecn)
``` ```
#### Скалярное произведение - *vecn.dot(...)* #### Скалярное произведение - *vecn.dot(...)*
```lua ```lua
-- возвращает скалярное произведение векторов -- возвращает скалярное произведение векторов
vecn.dot(a: vector, b: vector) vecn.dot(a: vecn, b: vecn) -> number
``` ```
#### Смешивание - *vecn.mix(...)* #### Смешивание - *vecn.mix(...)*
```lua ```lua
-- возвращает вектор a * (1.0 - t) + b * t -- возвращает вектор a * (1.0 - t) + b * t
vecn.mix(a: vector, b: vector, t: number) vecn.mix(a: vecn, b: vecn, t: number) -> vecn
-- записывает в dst вектор a * (1.0 - t) + b * t -- записывает в dst вектор a * (1.0 - t) + b * t
vecn.mix(a: vector, b: vector, t: number, dst: vector) vecn.mix(a: vecn, b: vecn, t: number, dst: vecn)
``` ```
#### Перевод в строку - *vecn.tostring(...)* #### Перевод в строку - *vecn.tostring(...)*
@ -158,7 +164,7 @@ vecn.mix(a: vector, b: vector, t: number, dst: vector)
> Возвращает только тогда, когда содержимым является вектор > Возвращает только тогда, когда содержимым является вектор
```lua ```lua
-- возвращает строку представляющую содержимое вектора -- возвращает строку представляющую содержимое вектора
vecn.tostring(a: vector) vecn.tostring(a: vecn) -> string
``` ```
## Специфические функции ## Специфические функции
@ -167,16 +173,16 @@ vecn.tostring(a: vector)
```lua ```lua
-- возвращает случайный вектор, координаты которого равномерно распределены на сфере заданного радиуса -- возвращает случайный вектор, координаты которого равномерно распределены на сфере заданного радиуса
vec3.spherical_rand(radius: number) vec3.spherical_rand(radius: number) -> vec3
-- записывает случайный вектор, координаты которого равномерно распределены на сфере заданного радиуса в dst -- записывает случайный вектор, координаты которого равномерно распределены на сфере заданного радиуса в dst
vec3.spherical_rand(radius: number, dst: vec3) vec3.spherical_rand(radius: number, dst: vec3)
-- возвращает угол направления вектора v в градусах [0, 360] -- возвращает угол направления вектора v в градусах [0, 360]
vec2.angle(v: vec2) vec2.angle(v: vec2) -> number
-- возвращает угол направления вектора {x, y} в градусах [0, 360] -- возвращает угол направления вектора {x, y} в градусах [0, 360]
vec2.angle(x: number, y: number) vec2.angle(x: number, y: number) -> number
-- возвращает повернутый вектор на угол в градусах против часовой стрелки -- возвращает повернутый вектор на угол в градусах против часовой стрелки
vec2.rotate(v: vec2, angle: number) -> vec2 vec2.rotate(v: vec2, angle: number) -> vec2

20
doc/ru/scripting/builtins/libworld.md
View file

@ -2,17 +2,17 @@
```lua ```lua
-- Проверяет, открыт ли мир -- Проверяет, открыт ли мир
world.is_open() -> bool world.is_open() -> boolean
-- Возвращает информацию о мирах. -- Возвращает информацию о мирах.
world.get_list() -> массив таблиц { world.get_list() -> table<{
-- название мира -- название мира
name: str, name: string,
-- предпросмотр (автоматически загружаемая текстура) -- предпросмотр (автоматически загружаемая текстура)
icon: str, icon: string,
-- версия движка, на которой был сохранен мир -- версия движка, на которой был сохранен мир
version: {int, int} version: {int, int}
} }>
-- Возвращает текущее игровое время от 0.0 до 1.0, где 0.0 и 1.0 - полночь, 0.5 - полдень. -- Возвращает текущее игровое время от 0.0 до 1.0, где 0.0 и 1.0 - полночь, 0.5 - полдень.
world.get_day_time() -> number world.get_day_time() -> number
@ -33,16 +33,16 @@ world.get_total_time() -> number
world.get_seed() -> int world.get_seed() -> int
-- Возвращает имя генератора. -- Возвращает имя генератора.
world.get_generator() -> str world.get_generator() -> string
-- Проверяет существование мира по имени. -- Проверяет существование мира по имени.
world.exists(name: str) -> bool world.exists(name: string) -> boolean
-- Проверяет является ли текущее время днём. От 0.333(8 утра) до 0.833(8 вечера). -- Проверяет является ли текущее время днём. От 0.333(8 утра) до 0.833(8 вечера).
world.is_day() -> bool world.is_day() -> boolean
-- Проверяет является ли текущее время ночью. От 0.833(8 вечера) до 0.333(8 утра). -- Проверяет является ли текущее время ночью. От 0.833(8 вечера) до 0.333(8 утра).
world.is_night() -> bool world.is_night() -> boolean
-- Возвращает общее количество загруженных в память чанков -- Возвращает общее количество загруженных в память чанков
world.count_chunks() -> int world.count_chunks() -> int
@ -60,7 +60,7 @@ world.set_chunk_data(
x: int, z: int, x: int, z: int,
-- сжатые данные чанка -- сжатые данные чанка
data: Bytearray data: Bytearray
) -> bool ) -> boolean
-- Сохраняет данные чанка в регион. -- Сохраняет данные чанка в регион.
-- Изменения будет записаны в файл только после сохранения мира. -- Изменения будет записаны в файл только после сохранения мира.

62
doc/ru/scripting/bytearray.md Normal file
View file

@ -0,0 +1,62 @@
# Класс *Bytearray*
*Bytearray* - динамический байтовый массив, реализованный через LuaJIT FFI. По нему можно итерироваться стандартными функциями **pairs** и **ipairs**
## Основное
### Создание массива
```lua
local bytes = Bytearray() -- пустой
local bytes = Bytearray("hello") -- из строки
local bytes = Bytearray({1,2,3}) -- из таблицы чисел
```
### Методы
```lua
-- Добавляет элемент(ы) в конец массива.
bytes:append(value: int)
bytes:append(values: Bytearray | table<int>)
-- Вставляет данные по индексу.
bytes:insert(index: int, value: int)
-- Удаляет элемент(ы), если передан `count`, удалит `count` кол-во элементов с выбранного индекса.
bytes:remove(index: int, [опционально] count: int)
-- Очищает массив
bytes:clear()
-- Создаёт новый Bytearray, содержащий копию части данных с offset до offset+length
bytes:slice(offset: int, length: int) -> Bytearray
```
## View
Это "вьюшки" поверх Bytearray, которые интерпретируют его байты как массив чисел другого размера - **без копирования данных**.
Не имеет своих методов, является просто объектной ссылкой на оригинальный Bytearray.
| Класс | Тип элементов | Размер |
| ------------ | ------------------ | ------- |
| `I16view` | `int16_t` | 2 байта |
| `U16view` | `uint16_t` | 2 байта |
| `I32view` | `int32_t` | 4 байта |
| `U32view` | `uint32_t` | 4 байта |
---
### Пример использования
```lua
local bytes = Bytearray({1, 0, 2, 0, 250, 255})
local u16 = U16view(bytes)
local i16 = I16view(bytes)
print(u16[1]) -- 1
print(u16[2]) -- 2
print(i16[3]) -- -6 (signed вьюшка)
for _, num in ipairs(i16) do
print(num)
end -- 1; 2; -6
```

6
doc/ru/scripting/core_components.md
View file

@ -11,7 +11,7 @@ local pathfinding = entity:require_component("core:pathfinding")
pathfinding.set_target(target: vec3) pathfinding.set_target(target: vec3)
-- Возвращает текущую цель движения -- Возвращает текущую цель движения
pathfinding.get_target() --> vec3 pathfinding.get_target() -> vec3
-- Устанавливает высоту преодолимого прыжком препятствия -- Устанавливает высоту преодолимого прыжком препятствия
pathfinding.set_jump_height(height: number) pathfinding.set_jump_height(height: number)
@ -24,7 +24,7 @@ pathfinding.reset_route()
-- Возвращает следующую точку маршрута, по текущим координатам. -- Возвращает следующую точку маршрута, по текущим координатам.
-- (следует использовать компонент core:mob - функция mob.follow_waypoints) -- (следует использовать компонент core:mob - функция mob.follow_waypoints)
pathfinding.next_waypoint() --> vec3 или nil pathfinding.next_waypoint() -> vec3 или nil
-- Устанавливает интервал перестройки маршрута в тактах обновления. -- Устанавливает интервал перестройки маршрута в тактах обновления.
pathfinding.set_refresh_interval(interval: number) pathfinding.set_refresh_interval(interval: number)
@ -82,7 +82,7 @@ mob.follow_waypoints(
mob.set_dir(dir: vec3) mob.set_dir(dir: vec3)
-- Проверяет, включён ли режим полёта -- Проверяет, включён ли режим полёта
mob.is_flight() --> bool mob.is_flight() -> bool
-- Включает/выключает режим полёта -- Включает/выключает режим полёта
mob.set_flight(flag: bool) mob.set_flight(flag: bool)

28
doc/ru/scripting/events.md
View file

@ -1,12 +1,21 @@
# События движка # События движка
## Содержание
- [События блоков](#события-блоков)
- [События предметов](#события-предметов)
- [События мира](#события-мира)
- [События макета](#события-макета)
- [События HUD](#события-hud)
- [События ECS](ecs.md#события-компонента)
- [Библиотека *Events*](#библиотека-events)
## События блоков ## События блоков
Функции для обработки событий, прописываемые в скрипте блока. Функции для обработки событий, прописываемые в скрипте блока.
> [!WARNING] > [!WARNING]
> Mass events such as on_block_tick, on_block_present, and on_block_removed, > Массовые события, такие как on_block_tick, on_block_present и on_block_removed,
> if used carelessly or excessively, can lead to performance issues. > при небрежном или чрезмерном использовании, могут привести к проблемам с производительностью.
```lua ```lua
function on_placed(x, y, z, playerid) function on_placed(x, y, z, playerid)
@ -72,12 +81,6 @@ function on_block_removed(x, y, z)
Вызывается при выгрузке чанка, в котором находится блок. Вызывается при выгрузке чанка, в котором находится блок.
```lua
function on_player_tick(playerid: int, tps: int)
```
Вызывается tps (20) раз в секунду. Используйте 1/tps вместо `time.delta()`.
## События предметов ## События предметов
Функции для обработки событий, прописываемые в скрипте предмета. Функции для обработки событий, прописываемые в скрипте предмета.
@ -152,6 +155,12 @@ function on_block_interact(blockid, x, y, z, playerid) -> bool
Вызывается при нажатии на блок ПКМ. Предотвращает установку блоков, если возвращает `true` Вызывается при нажатии на блок ПКМ. Предотвращает установку блоков, если возвращает `true`
```lua
function on_player_tick(playerid: int, tps: int)
```
Вызывается tps (20) раз в секунду. Используйте 1/tps вместо `time.delta()`.
### События чанков (world.lua) ### События чанков (world.lua)
```lua ```lua
@ -221,6 +230,9 @@ function on_hud_close(playerid: int)
Вызывается при выходе из мира, перед его сохранением. Вызывается при выходе из мира, перед его сохранением.
## События ECS
События **ECS** описаны [тут](ecs.md#события-компонента)
## Библиотека *events* ## Библиотека *events*
```lua ```lua

347
doc/ru/scripting/extensions.md
View file

@ -2,174 +2,73 @@
В скрипте ядра **stdmin.lua** определены функции, расширяющие и дополняющие некоторые из стандартных библиотек **Lua** В скрипте ядра **stdmin.lua** определены функции, расширяющие и дополняющие некоторые из стандартных библиотек **Lua**
## Содержание:
- [расширения для table](#расширения-для-table)
- [расширения для string](#расширения-для-string)
- [расширения для math](#расширения-для-math)
- [расширения для bit](#расширения-для-bit)
- [Дополнительные глобальные функции](#дополнительные-глобальные-функции)
## Расширения для table ## Расширения для table
```lua ```lua
-- Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.
table.copy(t: table) -> table table.copy(t: table) -> table
```
Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной. -- Функция глубокого копирования создает полную копию исходной таблицы, включая все её вложенные таблицы.
```lua
table.deep_copy(t: table) -> table table.deep_copy(t: table) -> table
```
Функция глубокого копирования создает полную копию исходной таблицы, включая все её вложенные таблицы. -- Возвращает количество пар в переданной таблице.
table.count_pairs(t: table) -> int
```lua -- Возвращает один элемент из переданной таблицы на случайной позиции.
table.count_pairs(t: table) -> integer table.random(t: table) -> any
```
Возвращает количество пар в переданной таблице. -- Возвращает true, если x содержится в t.
table.has(t: table, x: any) -> boolean
```lua -- Возвращает индекс объекта x в t. Если переданный объект не содержится в таблице, то функция вернёт значение -1.
table.random(t: table) -> object table.index(t: table, x: any) -> int
```
Возвращает один элемент из переданной таблицы на случайной позиции. -- Удаляет элемент x из t.
table.remove_value(t: table, x: any)
```lua -- Перемешивает значения в таблице.
table.has(t: table, x: object) -> bool
```
Возвращает **true**, если **x** содержится в **t**.
```lua
table.index(t: table, x: object) -> integer
```
Возвращает индекс обьекта **x** в **t**. Если переданный обьект не содержится в таблице, то функция вернёт значение **-1**.
```lua
table.remove_value(t: table, x: object)
```
Удаляет элемент **x** из **t**.
```lua
table.shuffle(t: table) -> table table.shuffle(t: table) -> table
```
Перемешивает значения в таблице. -- Добавляет в таблицу t1 значения из таблицы t2. Если в таблице t2 присутствует ключ из t1, то значение ключа не будет изменено.
```lua
table.merge(t1: table, t2: table) -> table table.merge(t1: table, t2: table) -> table
```
Добавляет в таблицу **t1** значения из таблицы **t2**. Если в таблице **t2** присутствует ключ из **t1**, то значение ключа не будет изменено. -- Проходится по таблице и применяет ко всем её элементам func, которая возвращает новое значение элемента.
table.map(t: table, func: function(indx, value)) -> table
```lua -- Проходится по таблице с помощью func, которая возвращает true если элемент надо сохранить и false, если его надо удалить.
table.map(t: table, func: function(indx, value) ) -> table table.filter(t: table, func: function(indx, value)) -> table
```
Проходится по таблице и применяет ко всем её элементам **func**, которая возвращает новое значение элемента. -- Позволяет безопасно получать значение по указанному ключу. Если ключ существует в таблице, метод вернет его значение.
-- Если ключ отсутствует, метод установит его со значением default и вернет его.
table.set_default(t: table, key: int | string, default: any) -> any
```lua -- Возвращает "плоскую" версию исходной таблицы.
table.filter(t: table, func: function(indx, value) ) -> table
```
Проходится по таблице с помощью **func**, которая возвращает **true** если элемент надо сохранить и **false**, если его надо удалить.
```lua
table.set_default(t: table, key: number | string, default: any) -> any | default
```
Позволяет безопасно получать значение по указанному ключу. Если ключ существует в таблице, метод вернет его значение. Если ключ отсутствует, метод установит его со значением **default** и вернет его.
```lua
table.flat(t: table) -> table table.flat(t: table) -> table
```
Возвращает "плоскую" версию исходной таблицы. -- Возвращает глубокую "плоскую" версию исходной таблицы.
```lua
table.deep_flat(t: table) -> table table.deep_flat(t: table) -> table
```
Возвращает глубокую "плоскую" версию исходной таблицы. -- Возвращает обрезанную версию таблицы с индекса start до индекса stop включительно, при этом пары ключ-значение
-- не сохраняются в новой таблице. При значениях nil начинает с 1 и заканчивает #arr соответственно.
```lua
table.sub(arr: table, start: number | nil, stop: number | nil) -> table table.sub(arr: table, start: number | nil, stop: number | nil) -> table
```
Возвращает обрезанную версию таблицы с индекса **start** до индекса **stop** включительно, при этом пары ключ-значение не сохраняются в новой таблице. При значениях **nil** начинает с **1** и заканчивает **#arr** соответственно. -- Добавляет значение в таблицу, только если его там изначально не было.
```lua
table.insert_unique(t: table, val: any) table.insert_unique(t: table, val: any)
table.insert_unique(t: table, pos: number, val: any) table.insert_unique(t: table, pos: int, val: any)
```
Добавляет значение в таблицу, только если его там не было. -- Конвертирует переданную таблицу в строку.
```lua
table.tostring(t: table) -> string table.tostring(t: table) -> string
``` ```
Конвертирует переданную таблицу в строку.
## Расширения для string ## Расширения для string
```lua Важно подметить, что все ниже перечисленные функции, расширяющие **string** можно использовать как мета-методы на экземплярах строк, т.е.:
string.explode(separator: string, str: string, withpattern: bool) -> table[string]
```
Разбивает строку **str** на части по указанному разделителю/выражению **separator** и возвращает результат ввиде таблицы из строк. Если **withpattern** равен **true**, то параметр **separator** будет определяться как регулярное выражение.
```lua
string.split(str: string, delimiter: string) -> table[string]
```
Разбивает строку **str** на части по указанному разделителю **delimiter** и возвращает результат ввиде таблицы из строк.
```lua
string.pattern_safe(str: string)
```
Экранирует специальные символы в строке, такие как `()[]+-.$%^?*` в формате `%символ`. Символ `NUL` (`\0`) будет преобразован в `%z`.
```lua
string.formatted_time(seconds: number, format: string) -> string | table
```
Разбивает секунды на часы, минуты и миллисекунды и форматирует в **format** с следующим порядком параметров: `минуты, секунды, миллисекунды` и после возвращает результат. Если **format** не указан, то возвращает таблицу, где: **h** - hours, **m** - minutes, **s** - seconds, **ms** - milliseconds.
```lua
string.replace(str: string, tofind: string, toreplace: string) -> string
```
Заменяет все подстроки в **str**, равные **tofind** на **toreplace** и возвращает строку со всеми измененными подстроками.
```lua
string.trim(str: string, char: string) -> string
```
Удаляет все символы, равные **char** из строки **str** с левого и правого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.
```lua
string.trim_left(str: string, char: string) -> string
```
Удаляет все символы, равные **char** из строки **str** с левого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.
```lua
string.trim_right(str: string, char: string) -> string
```
Удаляет все символы, равные **char** из строки **str** с правого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.
```lua
string.starts_with(str: string, start: string) -> bool
```
Возвращает **true**, если строка **str** начинается на подстроку **start**
```lua
string.ends_with(str: string, endStr: string) -> bool
```
Возвращает **true**, если строка **str** заканчивается на подстроку **endStr**
Также важно подметить, что все выше перечисленные функции, расширяющие **string** можно использовать как мета-методы на экземплярах строк, т.е.:
```lua ```lua
local str = "ABA str BAB" local str = "ABA str BAB"
@ -179,108 +78,126 @@ if str:starts_with("ABA") and str:ends_with("BAB") then
end end
``` ```
Также функции `string.lower` и `string.upper` переопределены на `utf8.lower` и `utf8.upper`
```lua ```lua
-- Разбивает строку str на части по указанному разделителю/выражению separator и возвращает результат ввиде таблицы из строк. Если withpattern равен true, то параметр separator будет определяться как регулярное выражение.
string.explode(separator: string, str: string, withpattern: boolean) -> table<string>
-- Разбивает строку str на части по указанному разделителю delimiter и возвращает результат ввиде таблицы из строк.
string.split(str: string, delimiter: string) -> table<string>
-- Экранирует специальные символы в строке, такие как `()[]+-.$%^?*` в формате `%символ`. Символ `NUL` (`\0`) будет преобразован в `%z`.
string.pattern_safe(str: string) -> string
-- Разбивает секунды на часы, минуты и миллисекунды и форматирует в format с следующим порядком параметров: `минуты, секунды, миллисекунды` и после возвращает результат. Если format не указан, то возвращает таблицу, где:
-- h - hours,
-- m - minutes,
-- s - seconds,
-- ms - milliseconds.
string.formatted_time(seconds: number, format: string) -> string | table
-- Заменяет все подстроки в str, равные tofind на toreplace и возвращает строку со всеми измененными подстроками.
string.replace(str: string, tofind: string, toreplace: string) -> string
-- Удаляет все символы, равные char из строки str с левого и правого конца и возвращает результат.
-- Если параметр char не определен, то будут выбраны все пустые символы.
string.trim(str: string, char: string) -> string
-- Удаляет все символы, равные char из строки str с левого конца и возвращает результат.
-- Если параметр char не определен, то будут выбраны все пустые символы.
string.trim_left(str: string, char: string) -> string
-- Удаляет все символы, равные char из строки str с правого конца и возвращает результат.
-- Если параметр char не определен, то будут выбраны все пустые символы.
string.trim_right(str: string, char: string) -> string
-- Возвращает true, если строка str начинается на подстроку start.
string.starts_with(str: string, start: string) -> boolean
-- Возвращает true, если строка str заканчивается на подстроку endStr.
string.ends_with(str: string, endStr: string) -> boolean
-- Также функции string.lower и string.upper переопределены на utf8.lower и utf8.upper.
-- Экранирует строку. Является псевдонимом utf8.escape.
string.escape(str: string) -> string string.escape(str: string) -> string
-- Экранирует спец-символы XML. Является псевдонимом utf8.escape_xml.
string.escape_xml(text: string) -> string
-- Добавляет char слева и справа от строки, пока её размер не будет равен size.
-- По стандарту char равен символу пробела.
string.pad(str: string, size: int, char: string) -> string
-- Добавляет char слева от строки, пока её размер не будет равен size.
-- По стандарту char равен символу пробела.
string.left_pad(str: string, size: int, char: string) -> string
-- Добавляет char справа от строки, пока её размер не будет равен size.
-- По стандарту char равен символу пробела.
string.right_pad(str: string, size: int, char: string) -> string
``` ```
Экранирует строку. Является псевдонимом `utf8.escape`.
```lua
string.escape_xml(text: str) -> str
```
Экранирует спец-символы XML. Является псевдонимом `utf8.escape_xml`.
```lua
string.pad(str: string, size: number, [опционально] char: string) -> string
```
Добавляет **char** слева и справа от строки, пока её размер не будет равен **size**. По стандарту **char** равен символу пробела
```lua
string.left_pad(str: string, size: number, [опционально] char: string) -> string
```
Добавляет **char** слева от строки, пока её размер не будет равен **size**. По стандарту **char** равен символу пробела
```lua
string.right_pad(str: string, size: number, [опционально] char: string) -> string
```
Добавляет **char** справа от строки, пока её размер не будет равен **size**. По стандарту **char** равен символу пробела
## Расширения для math ## Расширения для math
```lua ```lua
math.clamp(_in, low, high) -- Возвращает _in, если оно находится в диапозоне low <= _in <= high
``` -- Иначе возвращает границу, к которой ближе всего находится значение _in.
math.clamp(_in: number, low: number, high: number) -> number
Ограничивает число **_in** по лимитам **low** и **high**. Т.е.: Если **_in** больше чем **high** - вернётся **high**, если **_in** меньше чем **low** - вернётся **low**. В противном случае вернётся само число. -- Возвращает случайное дробное число в диапазоне от low до high.
math.rand(low: number, high: number) -> number
```lua -- Возвращает нормализованное значение num относительно conf.
math.rand(low, high) math.normalize(num: number, [опционально] conf: number) -> number
```
Возвращает случайное дробное число в диапазоне от **low** до **high**. -- Возвращает округлённое значение num до указанного количества знаков после запятой places.
math.round(num: number, [опционально] places: number) -> number
```lua -- Возвращает сумму всех принимаемых аргументов. Если в качестве аргумента была передана таблица, метод вернёт сумму всех её элементов.
math.normalize(num: number, [опционально] conf: num) -> number
```
Возвращает нормализованное значение num относительно conf.
```lua
math.round(num: number, [опционально] places: num) -> number
```
Возвращает округлённое значение num до указанного количества знаков после запятой places.
```lua
math.sum(x: number, ... | t: table) -> number math.sum(x: number, ... | t: table) -> number
``` ```
Возвращает сумму всех принимаемых аргументов. Если в качестве аргумента была передана таблица, метод вернёт сумму всех её элементов. ## Расширения для bit
```lua
-- Общие аргументы:
-- * expr: Строка с побитовым выражением, соответствует формату побитовых операций в Lua 5.3
-- * args: Список имён аргументов выражения. Если nil, список автоматически формируется на основе обнаруженных идентификаторов.
-- Компилирует функцию для выполнения побитовых операций
-- * asFunction: при значении true возвращает функцию, иначе строку кода функции
bit.compile(expr: string, args: table | nil, asFunction: boolean=true) -> function | string
-- Компилирует функцию для выполнения побитовых операций и на месте выполняет её
-- * ...: Значения, которые будут переданы в скомпилированную функцию.
bit.execute(expr: string, args: table | nil, ...) -> number
```
## Дополнительные глобальные функции ## Дополнительные глобальные функции
В этом же скрипте также определены и другие глобальные функции которые доступны для использования. Ниже их список В этом же скрипте также определены и другие глобальные функции которые доступны для использования. Ниже их список
```lua ```lua
is_array(x: table) -> bool -- Возвращает true, если переданная таблица является массивом, то есть если каждый ключ — это целое число больше или равное единице
``` -- и если каждый ключ следует за прошлым.
is_array(x: table) -> boolean
Возвращает **true**, если переданная таблица является массивом, тоесть если каждый ключ это целое число больше или равное единице и если каждый ключ следует за прошлым. -- Разбивает путь на две части и возвращает их: входную точку и путь к файлу.
parse_path(path: string) -> string, string
```lua -- Вызывает функцию func iters раз, передавая ей аргументы ..., а после выводит в консоль время в микросекундах,
function parse_path(path: string) -> string, string -- которое прошло с момента вызова timeit.
``` timeit(iters: int, func: function, ...)
Разбивает путь на две части и возвращает их: входную точку и путь к файлу. -- Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в timesec.
-- Функция может быть использована только внутри корутины.
sleep(timesec: number)
```lua -- Ожидает завершение переданной корутины, возвращая поток управления. Функция может быть использована только внутри корутины.
function timeit(iters: integer, func: func, ...) -- Возвращает значения аналогичные возвращаемым значениям pcall.
``` await(co: coroutine) -> result, error
Вызывает функцию **func** **iters** раз, передавая ей аргументы `...`, а после выводит в консоль время в микросекундах, которое прошло с момента вызова **timeit**. -- Константа, в которой хранится PID текущего инстанса движка.
```lua
function sleep(timesec: number)
```
Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в **timesec**. Функция может быть использована только внутри корутины.
```lua
function await(co: coroutine) -> result, error
```
Ожидает завершение переданной корутины, возвращая поток управления. Функция может быть использована только внутри корутины.
Возвращает значения аналогичные возвращаемым значениям *pcall*.
```lua
os.pid -> number os.pid -> number
``` ```
Константа, в которой хранится PID текущего инстанса движка

4
doc/ru/scripting/filesystem.md
View file

@ -63,10 +63,10 @@ bjson.tobytes(
value: table, value: table,
-- сжатие -- сжатие
[опционально] compression: bool=true [опционально] compression: bool=true
) --> Bytearray ) -> Bytearray
-- Декодирует массив байт в таблицу -- Декодирует массив байт в таблицу
bjson.frombytes(bytes: table | Bytearray) --> table bjson.frombytes(bytes: table | Bytearray) -> table
``` ```
## Сохранение данных в мире ## Сохранение данных в мире

158
doc/ru/scripting/io_stream.md
View file

@ -2,182 +2,182 @@
Класс, предназначенный для работы с потоками Класс, предназначенный для работы с потоками
## Содержание
- [Режимы](#режимы)
- [general](#general)
- [flush](#flush)
- [binary](#binary)
- Методы
- [режимы и их состояния](#методы-режимов-и-их-состояний)
- [I/O](#io-методы)
- [Buffered-методы](#методы-buffered-режима)
- [Методы потока](#методы-контроля-состояния-потока)
## Режимы ## Режимы
Поток имеет три различных вида режима: Поток имеет три различных вида режима:
- Режим общего поведения (`general` / `mode`)
**general** - Общий режим работы I/O - Режим сброса (`flush` / `flushMode`)
**binary** - Формат записи и чтения I/O
**flush** - Режим работы flush - Двоичный режим (`binary`)
### general ### general
Имеет три режима: Определяет, как поток обрабатывает чтение и запись,
имеет три подрежима:
**default** - Дефолтный режим работы потока. При read может вернуть только часть от требуемых данных, при write сразу записывает данные в поток. | Режим | Описание |
|---------------|--------|
**yield** - Почти тоже самое, что и **default**, но всегда будет возвращать все требуемые данные. Пока они не будут прочитаны, будет вызывать `coroutine.yield()`. Предназначен для работы в корутинах. | `"default"` | Прямой режим. `read` может вернуть меньше байт, чем запрошено. `write` сразу отправляет данные в низкоуровневый дескриптор. Нет буферизации. |
| `"yield"` | Как `default`, но при нехватке данных в `read(n)` поток будет вызывать `coroutine.yield()`, пока не соберёт ровно `n` байт. Удобно для корутин. |
**buffered** - Буферизирует записываемые и читаемые данные. | `"buffered"` | Включает внутренние буферы чтения и записи. `read` берёт данные из буфера, `write` — складывает в буфер. При превышении `maxBufferSize` — ошибка `buffer overflow`. |
При вызове `available`/`read` обновляет буфер чтения.
После обновления в `read`, если буфер чтения переполнен, то бросает ошибку `buffer overflow`.
Если требуемого кол-ва байт недостаточно в буфере для чтения, то бросает ошибку `buffer-underflow`.
При вызове `write` записывает итоговые байты в буфер для записи. Если он переполнен, то бросает ошибку `buffer overflow`.
При вызове `flush` проталкивает данные из буфера для записи в напрямую в поток
### flush ### flush
**all** - Сначала проталкивает данные из буфера напрямую в поток (если используется **buffered** режим), а после вызывает `flush` напрямую из библиотеки Работает только в режиме `"buffered"`,
имеет два подрежима:
**buffer** - Только проталкивает данные из буфера в поток (если используется **buffered** режим) | Режим | Что делает `flush()` |
|------------------|----------------------|
| `"all"` (по умолчанию) | Сначала сбрасывает буфер записи → низкоуровневый `write`, затем вызывает `ioLib.flush(descriptor)` |
| `"buffer"` | Сбрасывает только буфер записи, без вызова системного `flush` |
## Методы
Методы, позволяющие изменить или получить различные режимы поведения потока ### binary
**Независимый флаг** (включается через `set_binary_mode(true)` или при создании потока).
Определяет, в каком виде методы `read` и `write` принимают и возвращают данные:
| binary = true | binary = false (по умолчанию) |
|-----------------------------------------|----------------------------------------|
| Данные — это **байты** (`Bytearray`, таблица чисел 0..255) | Данные — это **текстовые строки** |
| `read(n)` → `Bytearray` или `table<number>`| `read()` → одна строка |
| `read("i4 f")` → распаковка через `byteutil.unpack` | `read(n)` → n строк в таблице |
| `write(Bytearray)` → запись байтов | `write("hello")` → строка + `\n` |
| `write("i4", 42)` → `byteutil.pack` | `write({"a","b"})` → две строки с `\n`|
`read_line` / `write_line` — работают как в текстовом режиме
> [!WARNING]
> Важно: даже в `binary = true` методы `read_line()` и `write_line()` остаются текстовыми — они всегда работают со строками.
## Методы режимов и их состояний
```lua ```lua
-- Возвращает true, если поток используется в двоичном режиме -- Возвращает true, если поток используется в двоичном режиме
io_stream:is_binary_mode() --> bool io_stream:is_binary_mode() -> boolean
-- Включает или выключает двоичный режим -- Включает или выключает двоичный режим
io_stream:set_binary_mode(bool) io_stream:set_binary_mode(boolean)
-- Возвращает режим работы потока -- Возвращает режим работы потока
io_stream:get_mode() --> string io_stream:get_mode() -> string
-- Задаёт режим работы потока. Выбрасывает ошибку, если передан неизвестный режим -- Задаёт режим работы потока. Выбрасывает ошибку, если передан неизвестный режим
io_stream:set_mode(string) io_stream:set_mode(string)
-- Возвращает режим работы flush -- Возвращает режим работы flush
io_stream:get_flush_mode() --> string io_stream:get_flush_mode() -> string
-- Задаёт режим работы flush -- Задаёт режим работы flush
io_stream:set_flush_mode(string) io_stream:set_flush_mode(string)
``` ```
I/O методы ## I/O методы
```lua ```lua
--[[ --[[
Читает данные из потока Читает данные из потока
В двоичном режиме: В двоичном режиме:
Если arg - number, то читает из потока arg байт и возвращает ввиде Bytearray или таблицы, если useTable = true
Если arg - int, то читает из потока arg байт и возвращает ввиде Bytearray или таблицы, если useTable = true Если arg - string, то функция интерпретирует arg как шаблон для byteutil. Прочитает кол-во байт, которое определено шаблоном, передаст их в byteutil.unpack и вернёт результат
Если arg - string, то функция интерпретирует arg как шаблон для byteutil. Прочитает кол-во байт, которое определено шаблоном, передаст их в byteutil.unpack и вернёт результат
В текстовом режиме: В текстовом режиме:
Если arg - number, то читает нужное кол-во строк с окончанием CRLF/LF из arg и возвращает ввиде таблицы. Также, если trimEmptyLines = true, то удаляет пустые строки с начала и конца из итоговой таблицы
Если arg - int, то читает нужное кол-во строк с окончанием CRLF/LF из arg и возвращает ввиде таблицы. Также, если trimEmptyLines = true, то удаляет пустые строки с начала и конца из итоговой таблицы Если arg не определён, то читает одну строку с окончанием CRLF/LF и возвращает её.
Если arg не определён, то читает одну строку с окончанием CRLF/LF и возвращает её.
--]] --]]
io_stream:read( io_stream:read(
[опционально] arg: int | string, [опционально] arg: number | string,
[опционально] useTable | trimEmptyLines: bool [опционально] useTable | trimEmptyLines: boolean
) --> Bytearray | table<int> | string | table<string> | ... ) -> Bytearray | table<number> | string | table<string> | ...
--[[ --[[
Записывает данные в поток Записывает данные в поток
В двоичном режиме: В двоичном режиме:
Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток
Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток Если arg - Bytearray | table<number>, то записывает байты в поток
Если arg - Bytearray | table<int>, то записывает байты в поток
В текстовом режиме: В текстовом режиме:
Если arg - string, то записывает строку в поток (вместе с окончанием LF)
Если arg - string, то записывает строку в поток (вместе с окончанием LF) Если arg - table<string>, то записывает каждую строку из таблицы отдельно
Если arg - table<string>, то записывает каждую строку из таблицы отдельно
--]] --]]
io_stream:write( io_stream:write(
arg: Bytearray | table<int> | string | table<string>, arg: Bytearray | table<number> | string | table<string>,
[опционально] ... [опционально] ...
) )
-- Читает одну строку с окончанием CRLF/LF из потока вне зависимости от двоичного режима -- Читает одну строку с окончанием CRLF/LF из потока вне зависимости от двоичного режима
io_stream:read_line() --> string io_stream:read_line() -> string
-- Записывает одну строку с окончанием LF в поток вне зависимости от двоичного режима -- Записывает одну строку с окончанием LF в поток вне зависимости от двоичного режима
io_stream:write_line(string) io_stream:write_line(string)
--[[ --[[
В двоичном режиме: В двоичном режиме:
Читает все доступные байты из потока и возвращает ввиде Bytearray или table<number>, если useTable = true
Читает все доступные байты из потока и возвращает ввиде Bytearray или table<int>, если useTable = true
В текстовом режиме: В текстовом режиме:
Читает все доступные строки из потока в table<string> если useTable = true, или в одну строку вместе с окончаниями, если нет
Читает все доступные строки из потока в table<string> если useTable = true, или в одну строку вместе с окончаниями, если нет
--]] --]]
io_stream:read_fully( io_stream:read_fully(
[опционально] useTable: bool [опционально] useTable: boolean
) --> Bytearray | table<int> | table<string> | string ) -> Bytearray | table<number> | table<string> | string
``` ```
Методы, имеющие смысл в использовании только в buffered режиме ## Методы Buffered-режима
```lua ```lua
--[[ --[[
Если length определён, то возвращает true, если length байт доступно к чтению. Иначе возвращает false Если length определён, то возвращает true, если length байт доступно к чтению. Иначе возвращает false
Если не определён, то возвращает количество байт, которое можно прочитать Если не определён, то возвращает количество байт, которое можно прочитать
--]] --]]
io_stream:available( io_stream:available(
[опционально] length: int [опционально] length: number
) --> int | bool ) -> number | boolean
-- Возвращает максимальный размер буферов -- Возвращает максимальный размер буферов
io_stream:get_max_buffer_size() --> int io_stream:get_max_buffer_size() -> number
-- Задаёт новый максимальный размер буферов -- Задаёт новый максимальный размер буферов
io_stream:set_max_buffer_size(max_size: int) io_stream:set_max_buffer_size(max_size: number)
``` ```
Методы, контролирующие состояние потока ## Методы контроля состояния потока
```lua ```lua
-- Возвращает true, если поток открыт на данный момент -- Возвращает true, если поток открыт на данный момент
io_stream:is_alive() --> bool io_stream:is_alive() -> bool
-- Возвращает true, если поток закрыт на данный момент -- Возвращает true, если поток закрыт на данный момент
io_stream:is_closed() --> bool io_stream:is_closed() -> bool
-- Закрывает поток -- Закрывает поток
io_stream:close() io_stream:close()
--[[ -- Записывает все данные из write-буфера в поток в buffer/all flush-режимах
-- Вызывает ioLib.flush() в all flush-режиме
Записывает все данные из write-буфера в поток в buffer/all flush-режимах
Вызывает ioLib.flush() в all flush-режиме
--]]
io_stream:flush() io_stream:flush()
```
Создание нового потока
```lua -- Создаёт новый поток с переданным дескриптором и использующим переданную I/O библиотеку. (Более подробно в core:io_stream.lua)
--[[
Создаёт новый поток с переданным дескриптором и использующим переданную I/O библиотеку. (Более подробно в core:io_stream.lua)
--]]
io_stream.new( io_stream.new(
descriptor: int, descriptor: int,
binaryMode: bool, binaryMode: bool,

24
doc/ru/scripting/modules/core_bit_converter.md
View file

@ -13,7 +13,7 @@ function bit_converter.string_to_bytes(str: string) -> table
Конвертирует строку в байты Конвертирует строку в байты
```lua ```lua
function bit_converter.bool_to_byte(bool: boolean) -> integer function bit_converter.bool_to_byte(bool: boolean) -> int
``` ```
Конвертирует логический булев в байт Конвертирует логический булев в байт
@ -28,27 +28,27 @@ function bit_converter.float64_to_bytes(float: number, [опционально]
Конвертирует плавающее значение двойной точности в байты Конвертирует плавающее значение двойной точности в байты
```lua ```lua
function bit_converter.uint16_to_bytes(int: integer, [опционально] order: string) -> table function bit_converter.uint16_to_bytes(int: int, [опционально] order: string) -> table
``` ```
Конвертирует беззнаковое 2-х байтовое целое число в байты Конвертирует беззнаковое 2-х байтовое целое число в байты
```lua ```lua
function bit_converter.uint32_to_bytes(int: integer, [опционально] order: string) -> table function bit_converter.uint32_to_bytes(int: int, [опционально] order: string) -> table
``` ```
Конвертирует беззнаковое 4-х байтовое целое число в байты Конвертирует беззнаковое 4-х байтовое целое число в байты
```lua ```lua
function bit_converter.sint16_to_bytes(int: integer, [опционально] order: string) -> table function bit_converter.sint16_to_bytes(int: int, [опционально] order: string) -> table
``` ```
Конвертирует знаковое 2-х байтовое целое число в байты Конвертирует знаковое 2-х байтовое целое число в байты
```lua ```lua
function bit_converter.sint32_to_bytes(int: integer, [опционально] order: string) -> table function bit_converter.sint32_to_bytes(int: int, [опционально] order: string) -> table
``` ```
Конвертирует знаковое 4-х байтовое целое число в байты Конвертирует знаковое 4-х байтовое целое число в байты
```lua ```lua
function bit_converter.int64_to_bytes(int: integer, [опционально] order: string) -> table function bit_converter.int64_to_bytes(int: int, [опционально] order: string) -> table
``` ```
Конвертирует знаковое 8-и байтовое целое число в байты Конвертирует знаковое 8-и байтовое целое число в байты
@ -58,7 +58,7 @@ function bit_converter.bytes_to_string(bytes: table) -> string
Конвертирует массив байтов в строку Конвертирует массив байтов в строку
```lua ```lua
function bit_converter.byte_to_bool(byte: integer) -> boolean function bit_converter.byte_to_bool(byte: int) -> boolean
``` ```
Конвертирует байт в логическое булевое значение Конвертирует байт в логическое булевое значение
@ -73,26 +73,26 @@ function bit_converter.bytes_to_float64(bytes: table|Bytearray, [опциона
Конвертирует массив байтов в плавающее число двойной точности Конвертирует массив байтов в плавающее число двойной точности
```lua ```lua
function bit_converter.bytes_to_uint16(bytes: table|Bytearray, [опционально] order: string) -> integer function bit_converter.bytes_to_uint16(bytes: table|Bytearray, [опционально] order: string) -> int
``` ```
Конвертирует массив байтов в 2-х байтовое беззнаковое число Конвертирует массив байтов в 2-х байтовое беззнаковое число
```lua ```lua
function bit_converter.bytes_to_uint32(bytes: table|Bytearray, [опционально] order: string) -> integer function bit_converter.bytes_to_uint32(bytes: table|Bytearray, [опционально] order: string) -> int
``` ```
Конвертирует массив байтов в 4-х байтовое беззнаковое число Конвертирует массив байтов в 4-х байтовое беззнаковое число
```lua ```lua
function bit_converter.bytes_to_sint16(bytes: table|Bytearray, [опционально] order: string) -> integer function bit_converter.bytes_to_sint16(bytes: table|Bytearray, [опционально] order: string) -> int
``` ```
Конвертирует массив байтов в 2-х байтовое знаковое число Конвертирует массив байтов в 2-х байтовое знаковое число
```lua ```lua
function bit_converter.bytes_to_sint32(bytes: table|Bytearray, [опционально] order: string) -> integer function bit_converter.bytes_to_sint32(bytes: table|Bytearray, [опционально] order: string) -> int
``` ```
Конвертирует массив байтов в 4-х байтовое знаковое число Конвертирует массив байтов в 4-х байтовое знаковое число
```lua ```lua
function bit_converter.bytes_to_int64(bytes: table|Bytearray, [опционально] order: string) -> integer function bit_converter.bytes_to_int64(bytes: table|Bytearray, [опционально] order: string) -> int
``` ```
Конвертирует массив байтов в 8-х байтовое знаковое число Конвертирует массив байтов в 8-х байтовое знаковое число

28
doc/ru/scripting/modules/core_data_buffer.md
View file

@ -20,7 +20,7 @@ function data_buffer:set_order(order: string)
Должен равняться одному из перечисленных в [**bit_converter**](core_bit_converter.md) Должен равняться одному из перечисленных в [**bit_converter**](core_bit_converter.md)
```lua ```lua
function data_buffer:put_byte(byte: integer) function data_buffer:put_byte(byte: int)
``` ```
Записывает байт в буффер Записывает байт в буффер
@ -50,27 +50,27 @@ function data_buffer:put_float64(float: number)
Конвертирует плавающее число двойной точности в байты и записывает их в буффер Конвертирует плавающее число двойной точности в байты и записывает их в буффер
```lua ```lua
function data_buffer:put_uint16(int: integer) function data_buffer:put_uint16(int: int)
``` ```
Конвертирует беззнаковое 2-х байтовое число в байты и записывает их в буффер Конвертирует беззнаковое 2-х байтовое число в байты и записывает их в буффер
```lua ```lua
function data_buffer:put_uint32(int: integer) function data_buffer:put_uint32(int: int)
``` ```
Конвертирует беззнаковое 4-х байтовое число в байты и записывает их в буффер Конвертирует беззнаковое 4-х байтовое число в байты и записывает их в буффер
```lua ```lua
function data_buffer:put_sint16(int: integer) function data_buffer:put_sint16(int: int)
``` ```
Конвертирует знаковое 2-х байтовое число в байты и записывает их в буффер Конвертирует знаковое 2-х байтовое число в байты и записывает их в буффер
```lua ```lua
function data_buffer:put_sint32(int: integer) function data_buffer:put_sint32(int: int)
``` ```
Конвертирует знаковое 4-х байтовое число в байты и записывает их в буффер Конвертирует знаковое 4-х байтовое число в байты и записывает их в буффер
```lua ```lua
function data_buffer:put_int64(int: integer) function data_buffer:put_int64(int: int)
``` ```
Конвертирует знаковое 8-и байтовое число в байты и записывает их в буффер Конвертирует знаковое 8-и байтовое число в байты и записывает их в буффер
@ -91,7 +91,7 @@ sint32 = 8
``` ```
```lua ```lua
function data_buffer:get_byte() -> integer function data_buffer:get_byte() -> int
``` ```
Возвращает следующий байт из буффера Возвращает следующий байт из буффера
@ -121,27 +121,27 @@ function data_buffer:get_float64() -> number
Читает следующее плавающее число двойной точности из буффера Читает следующее плавающее число двойной точности из буффера
```lua ```lua
function data_buffer:get_uint16() -> integer function data_buffer:get_uint16() -> int
``` ```
Читает следующее 2-х байтовое беззнаковое целое число из буффера Читает следующее 2-х байтовое беззнаковое целое число из буффера
```lua ```lua
function data_buffer:get_uint32() -> integer function data_buffer:get_uint32() -> int
``` ```
Читает следующее 4-х байтовое беззнаковое целое число из буффера Читает следующее 4-х байтовое беззнаковое целое число из буффера
```lua ```lua
function data_buffer:get_sint16() -> integer function data_buffer:get_sint16() -> int
``` ```
Читает следующее 2-х байтовое знаковое целое число из буффера Читает следующее 2-х байтовое знаковое целое число из буффера
```lua ```lua
function data_buffer:get_sint32() -> integer function data_buffer:get_sint32() -> int
``` ```
Читает следующее 4-х байтовое знаковое целое число из буффера Читает следующее 4-х байтовое знаковое целое число из буффера
```lua ```lua
function data_buffer:get_int64() -> integer function data_buffer:get_int64() -> int
``` ```
Читает следующее 8-х байтовое знаковое целое число из буффера Читает следующее 8-х байтовое знаковое целое число из буффера
@ -151,12 +151,12 @@ function data_buffer:get_number() -> number
Читает следующее число (см. data_buffer:put_number) Читает следующее число (см. data_buffer:put_number)
```lua ```lua
function data_buffer:size() -> integer function data_buffer:size() -> int
``` ```
Возвращает размер буффера Возвращает размер буффера
```lua ```lua
function data_buffer:set_position(integer: pos) function data_buffer:set_position(int: pos)
``` ```
Устанавливает текущую позицию в буффере Устанавливает текущую позицию в буффере

2
doc/ru/scripting/ui.md
View file

@ -196,7 +196,7 @@ document["worlds-panel"]:clear()
| data:clear(*цвет*) | заполняет холст указанным RGBA цветом | | data:clear(*цвет*) | заполняет холст указанным RGBA цветом |
| data:rect(x: int, y: int, w: int, h: int, *цвет*) | заполняет прямоугольник указанным RGBA цветом | | data:rect(x: int, y: int, w: int, h: int, *цвет*) | заполняет прямоугольник указанным RGBA цветом |
| data:update() | применяет изменения и загружает холст в видеопамять | | data:update() | применяет изменения и загружает холст в видеопамять |
| data:set_data(data: bytearray | table<int>) | заменяет данные пикселей (ширина * высота * 4 чисел) | | data:set_data(data: Bytearray | table<int>) | заменяет данные пикселей (ширина * высота * 4 чисел) |
| data:get_data() | создаёт объект Bytearray с пиксельными данными изображения | | data:get_data() | создаёт объект Bytearray с пиксельными данными изображения |
| data:create_texture(name: str) | создаёт и делится текстурой с рендерером | | data:create_texture(name: str) | создаёт и делится текстурой с рендерером |
| data:unbind_texture() | отвязывает текстуру от холста | | data:unbind_texture() | отвязывает текстуру от холста |

10
doc/ru/world-generator.md
View file

@ -275,7 +275,7 @@ map:noise(
-- коэфициент масштабирования координат -- коэфициент масштабирования координат
scale: number, scale: number,
-- число октав шума (по-умолчанию: 1) -- число октав шума (по-умолчанию: 1)
[опционально] octaves: integer, [опционально] octaves: int,
-- множитель амплитуды шума (по-умолчанию: 1.0) -- множитель амплитуды шума (по-умолчанию: 1.0)
[опционально] multiplier: number, [опционально] multiplier: number,
-- карта смещений координаты X при генерации шума -- карта смещений координаты X при генерации шума
@ -321,7 +321,7 @@ map:crop(x, y, ширина, высота)
### heightmap:at(x, y) ### heightmap:at(x, y)
```lua ```lua
map:at(x, y) --> number map:at(x, y) -> number
``` ```
Возвращает значение высота на заданной позиции. Возвращает значение высота на заданной позиции.
@ -382,7 +382,7 @@ function generate_heightmap(
bpd, -- число блоков на точку карты (blocks per dot) - масштаб bpd, -- число блоков на точку карты (blocks per dot) - масштаб
[опционально] inputs -- массив входных карт параметров биомов [опционально] inputs -- массив входных карт параметров биомов
-- (см. свойство heightmap-inputs генератора) -- (см. свойство heightmap-inputs генератора)
) --> Heightmap ) -> Heightmap
``` ```
Пример генерации карты высот из простого симплекс-шума с приведением Пример генерации карты высот из простого симплекс-шума с приведением
@ -455,7 +455,7 @@ function place_structures(
w, d, -- размер области в блоках w, d, -- размер области в блоках
heights, -- карта высот чанка heights, -- карта высот чанка
chunk_height, -- высота чанка chunk_height, -- высота чанка
) --> массив размещений структур ) -> массив размещений структур
``` ```
Структуры могут размещаться за пределами чанка, но не дальше, чем на один чанк. Структуры могут размещаться за пределами чанка, но не дальше, чем на один чанк.
@ -487,7 +487,7 @@ function place_structures_wide(
x, z, -- позиция начала области в блоках x, z, -- позиция начала области в блоках
w, d, -- размер области в блоках w, d, -- размер области в блоках
chunk_height, -- высота чанка chunk_height, -- высота чанка
) --> массив размещений структур / тоннелей ) -> массив размещений структур / тоннелей
``` ```
## Структурный воздух ## Структурный воздух