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

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 GitHub
parent 66d85b0ae6
commit 32feb78002
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
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.
| Character | C++ Equivalent | Lua Type | Size |
| --------- | -------------- | -------- | ------- |
| `b` | int8_t | number | 1 byte |
| `B` | uint8_t | number | 1 byte |
| `?` | bool | boolean | 1 byte |
| `h` | int16_t | number | 2 bytes |
| `H` | uint16_t | number | 2 bytes |
| `i` | int32_t | number | 4 bytes |
| `I` | uint32_t | number | 4 bytes |
| `l` | int64_t | number | 8 bytes |
| `L` | uint64_t | number | 8 bytes |
| Character | C++ Equivalent | Lua Type | Size |
| --------- | --------------- | -------- | ------- |
| `b` | int8_t | number | 1 byte |
| `B` | uint8_t | number | 1 byte |
| `?` | bool | boolean | 1 byte |
| `h` | int16_t | number | 2 bytes |
| `H` | uint16_t | number | 2 bytes |
| `i` | int32_t | number | 4 bytes |
| `I` | uint32_t | number | 4 bytes |
| `f` | float32_t | number | 4 bytes |
| `l` | int64_t | number | 8 bytes |
| `L` | uint64_t | number | 8 bytes |
| `d` | float64_t | number | 8 bytes |
> [!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.

44
doc/ru/audio.md
View file

@ -143,66 +143,66 @@ audio.play_sound_2d(
```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 если не существует)
audio.is_loop(speakerid: integer) -> bool
audio.is_loop(speakerid: int) -> bool
-- получить громкость спикера (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 если не существует)
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 если не существует)
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 если не существует)
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 если не существует)
-- (используется OpenAL для имитации эффекта Доплера)
audio.get_velocity(speakerid: integer) -> number, number, number
audio.get_velocity(speakerid: int) -> number, number, number
-- установить скорость движения источника звука в мире
-- (используется 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, если длительность неизвестна (пример: радио)
audio.get_duration(speakerid: integer) -> number
audio.get_duration(speakerid: int) -> number
```
### Другие функции
```lua
-- получить текущее число живых спикеров
audio.count_speakers() -> integer
audio.count_speakers() -> int
-- получить текущее число проигрываемых аудио-потоков
audio.count_streams() -> integer
audio.count_streams() -> int
```
### audio.PCMStream
@ -211,11 +211,11 @@ audio.count_streams() -> integer
-- создание источника PCM данных
local stream = audio.PCMStream(
-- частота дискретизации
sample_rate: integer,
sample_rate: int,
-- число каналов (1 - моно, 2 - стерео)
channels: integer,
channels: int,
-- число бит на сэмпл (8 или 16)
bits_per_sample: integer,
bits_per_sample: int,
)
-- подача PCM данных в поток
@ -249,7 +249,7 @@ audio.input.fetch(
-- токен, полученный через audio.input.request_open
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
console.set_cheat(name: String, cheat: Boolean) -> cheatIsChanged: Boolean
console.is_cheat(name: String) -> Boolean
console.set_cheat(name: string, cheat: Boolean) -> cheatIsChanged: Boolean
console.is_cheat(name: string) -> Boolean
```
Сеттер и геттер статуса "чит" команды
@ -127,10 +127,7 @@ console.is_cheat(name: String) -> Boolean
```lua
console.log(...) -- Выводит информацию во внутриигровую консоль
console.chat(...) -- Выводит информацию во внутриигровой чат
console.get_commands_list() -> Table<String> -- Возвращает таблицу со списком команд
console.get_command_info(name: String) -> Table -- Возвращает информацию о команде
console.execute(command: str) -- Выполняет команду
console.get_commands_list() -> Table<string> -- Возвращает таблицу со списком команд
console.get_command_info(name: string) -> Table -- Возвращает информацию о команде
console.execute(command: string) -- Выполняет команду
```

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

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

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

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

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

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

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

@ -1,78 +1,95 @@
# Библиотека *block*
## Содержание
- [Таблицы и прочие общие методы](#таблицы-и-прочие-общие-методы)
- [Работа с миром](#работа-с-миром)
- [Свойства блоков](#свойства-блоков)
- [Raycast](#raycast)
- [Вращение](#вращение)
- [Расширенные блоки](#расширенные-блоки)
- [Модель и физика](#модель-и-физика)
- [Данные блоков](#данные-блоков)
## Таблицы и прочие общие методы
```lua
-- Возвращает строковый id блока по его числовому id.
block.name(blockid: int) -> str
-- Возвращает числовой id блока, принимая в качестве агрумента строковый
block.index(name: str) -> int
-- Возвращает id материала блока.
block.material(blockid: int) -> str
-- Возвращает количество id доступных в загруженном контенте блоков
block.defs_count() -> int
-- Таблица материалов по их полным именам (пример: base:carpet)
block.materials: table<string, table>
-- Таблица пользовательских свойств блоков (см. ../../block-properties.md)
block.properties: table<int, table<string, object>>
block.properties: table<int, table<string, any>>
```
-- Возвращает название блока, отображаемое в интерфейсе.
block.caption(blockid: int) -> str
## Работа с миром
```lua
-- Возвращает числовой id блока на указанных координатах.
-- Если чанк на указанных координатах не загружен, возвращает -1.
block.get(x: int, y: int, z: int) -> int
-- Возвращает полное состояние (поворот + сегмент + доп. информация) в виде целого числа
block.get_states(x: int, y: int, z: int) -> int
-- Устанавливает блок с заданным числовым 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 - по-умолчанию) на заданных координатах
-- от лица игрока, вызывая событие on_placed.
-- 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.
-- playerid не является обязательным
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.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
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
-- Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа).
-- Если поворот отсутствует, возвращает 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)
-- Возвращает имя профиля вращения (none/pane/pipe)
block.get_rotation_profile(id: int) -> str
block.get_rotation_profile(id: int) -> string
```
## Расширенные блоки
Расширенные блоки - те, размер которых превышает 1x1x1
```lua
-- Проверяет, является ли блок расширенным.
block.is_extended(id: int) -> bool
block.is_extended(id: int) -> boolean
-- Возвращает размер блока.
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
```
## Пользовательские биты
Выделенная под использования в скриптах часть поля `voxel.states` хранящего доп-информацию о вокселе, такую как вращение блока. На данный момент выделенная часть составляет 8 бит.
## Модель и физика
```lua
-- Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа
block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
-- возвращает тип модели блока (block/aabb/custom/...)
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 чисел):
-- 1. Минимальная точка хитбокса
-- 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}
```
## Модель
Информация о модели блока.
## Данные блоков
```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
-- возвращает имя модели блока
block.model_name(id: int) -> str
-- Записывает указанное число бит значения value в user bits по выбранному смещению
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(
x: int, y: int, z: int,
name: str,
value: bool|int|number|string,
name: string,
value: string | number | boolean,
[опционально] index: int = 0
)
@ -202,7 +200,7 @@ block.set_field(
-- * бросает исключение при выходе за границы массива
block.get_field(
x: int, y: int, z: int,
name: str,
name: string,
[опционально] index: int = 0
) -> хранимое значение или nil
```
) -> any | nil
```

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

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

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

@ -5,7 +5,7 @@
## Основные функции
```lua
cameras.get(name: str) -> table
cameras.get(name: string) -> table
-- или
cameras.get(index: int) -> table
```
@ -22,7 +22,7 @@ local cam = cameras.get("пак:имя-камеры")
cam:get_index() -> int
-- возвращает имя камеры
cam:get_name() -> str
cam:get_name() -> string
-- возвращает позицию камеры
cam:get_pos() -> vec3
@ -45,14 +45,14 @@ cam:get_fov() -> number
cam:set_fov(fov: number)
-- возвращает true если ось Y отражена
cam:is_flipped() -> bool
cam:is_flipped() -> boolean
-- отражает ось 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
@ -68,4 +68,4 @@ cam:look_at(point: vec3)
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(
-- Массив байт
data: array of integers,
data: Bytearray | table<int>,
-- Алгоритм сжатия (поддерживается только gzip)
[опционально] algorithm="gzip",
-- Вернуть результат в table?
[опционально] usetable=false
) -> array of integers
) -> Bytearray | table<int>
-- Разжимает массив байт.
compression.decode(
-- Массив байт
data: array of integers,
data: Bytearray | table<int>,
-- Алгоритм разжатия (поддерживается только gzip)
[опционально] algorithm="gzip",
-- Вернуть результат в table?
[опционально] usetable=false
) -> array of integers
) -> Bytearray | table<int>
```

16
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
entities.get_def(uid: int) -> int
-- Возвращает имя определения сущности по индексу (строковый ID).
entities.def_name(id: int) -> str
entities.def_name(id: int) -> string
-- Возвращает значение свойства 'hitbox' сущности
entities.def_hitbox(id: int) -> vec3
-- Возвращает индекс определения сущности по имени (числовой ID).
entities.def_index(name: str) -> int
entities.def_index(name: string) -> int
-- Возвращает число доступных определений сущностей
entities.defs_count() -> int
@ -48,17 +48,17 @@ entities.defs_count() -> int
entities.get_all() -> table
-- Возвращает таблицу загруженных сущностей по переданному списку UID
entities.get_all(uids: array<int>) -> table
entities.get_all(uids: table<int>) -> table
-- Возвращает список UID сущностей, попадающих в прямоугольную область
-- pos - минимальный угол области
-- size - размер области
entities.get_all_in_box(pos: vec3, size: vec3) -> array<int>
entities.get_all_in_box(pos: vec3, size: vec3) -> table<int>
-- Возвращает список UID сущностей, попадающих в радиус
-- center - центр области
-- radius - радиус области
entities.get_all_in_radius(center: vec3, radius: number) -> array<int>
entities.get_all_in_radius(center: vec3, radius: number) -> table<int>
```
```lua
@ -68,4 +68,4 @@ entities.raycast(start: vec3, dir: vec3, max_distance: number,
Функция является расширенным вариантом [block.raycast](libblock.md#raycast). Возвращает таблицу с результатами если луч касается блока, либо сущности.
Соответственно это повлияет на наличие полей *entity* и *block*.
Соответственно это повлияет на наличие полей *entity* и *block*.

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]
> Функцию не нужно использовать в сочетании с другими функциями из библиотеки, так как они делают это автоматически
Возвращаемый путь не является каноническим и может быть как абсолютным, так и относительным.
```python
file.read(путь: str) -> str
```
Читает весь текстовый файл и возвращает в виде строки
```python
file.read_bytes(путь: str, [опционально] usetable) -> array of integers
```
Читает файл в массив байт. При значении usetable = false возвращает Bytearray вместо table.
> Функцию file.resolve не нужно использовать в сочетании с другими функциями из библиотеки, так как они делают это автоматически.
> Возвращаемый путь не является каноническим и может быть как абсолютным, так и относительным.
## Файлы
```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
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
file.unmount(точка_входа: str) --> str
-- Совмещает массивы из JSON файлов разных паков.
file.read_combined_list(путь: string) -> table
-- Совмещает объекты из JSON файлов разных паков.
file.read_combined_object(путь: string) -> table
```
Размонтирует точку входа.
## Zip-архивы
```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
file.create_memory_device() --> str
```
-- Открывает поток для записи/чтения в файл по пути.
-- * Аргумент `режим` это список отдельных режимов, в котором каждый режим обозначается одним символом
file.open(путь: 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`, за исключением `+`
-- Открывает поток для записи/чтения в Named Pipe по пути `путь`
-- * `/tmp/` или `\\\\.\\pipe\\` добавлять не нужно - движок делает это автоматически.
-- * Недоступен режим с `+`
file.open_named_pipe(имя: string, режим: string) -> io_stream
```

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

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

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

@ -15,14 +15,14 @@
```lua
-- Возвращает индекс слота эффектов по имени (пак:имя_слота).
-- При отсутствии указанного слота возвращает -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
gfx.posteffects.get_intensity(slot: int) --> number
gfx.posteffects.get_intensity(slot: int) -> number
-- Устанавливает интенсивность эффекта (от 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)
-- Возвращает true если слот не пуст и интенсивность эффекта ненулевая
gfx.posteffects.is_active(slot: int) --> bool
gfx.posteffects.is_active(slot: int) -> boolean
-- Устанавливает значения параметров (директивы 'param')
gfx.posteffects.set_params(slot: int, params: table)
@ -40,9 +40,9 @@ gfx.posteffects.set_array(
-- индекс слота эффектов
slot: int,
-- имя параметра (массива)
name: str
name: string
-- строка данных (используйте функцию Bytearray_as_string)
data: str
data: string
)
-- Пример заполнения массива `#param vec3 u_имяМассива[64]`:
@ -54,4 +54,4 @@ for i = 0, 63 do
Bytearray.append(buffer, byteutil.pack("fff", x, y, z))
end
gfx.posteffects.set_array(slot, "u_имяМассива", Bytearray_as_string(buffer))
```
```

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

@ -9,17 +9,17 @@
```lua
-- Возвращает объектную обёртку над скелетом
local skeleton = gfx.skeletons.get(name: str)
local skeleton = gfx.skeletons.get(name: string)
-- Возвращает индекс кости по имени или 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
@ -28,22 +28,22 @@ skeleton:get_matrix(index: int) -> 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:set_color(color: vec3)
```
```

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

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

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

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

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

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

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

@ -1,27 +1,52 @@
# Библиотека *input*
## Основные методы
```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
input.mousecode(mousename: str) --> int
-- Возвращает позицию курсора на экране.
input.get_mouse_pos() -> {number, number}
-- Возращает дельту позиции курсора.
input.get_mouse_delta() -> {number, number}
```
Возвращает код кнопки мыши по имени, либо -1
## Создание обработчиков
```lua
input.add_callback(
-- Имя привязки
bindname: str,
bindname: string,
-- Обработчик
callback: function
-- UI элемент-владелец обработчика (отвечает за срок жизни)
[опционально] owner: Element,
-- Игнорировать захват ввода UI элементами
[опционально] istoplevel: bool
[опционально] istoplevel: boolean
)
```
@ -49,55 +74,4 @@ input.add_callback("key:escape", function ()
print("NO")
return true -- предотвращает вызов назначенных ранее функций
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
```
```

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

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

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

@ -2,16 +2,16 @@
```lua
-- Возвращает строковый id предмета по его числовому id (как block.name)
item.name(itemid: int) -> str
item.name(itemid: int) -> string
-- Возвращает числовой 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
@ -20,22 +20,20 @@ item.stack_size(itemid: int) -> int
item.defs_count() -> int
-- Возвращает имя иконки предмета для использования в свойстве 'src' элемента image
item.icon(itemid: int) -> str
item.icon(itemid: int) -> string
-- Возвращает числовой id блока, назначенного как 'placing-block' или 0
item.placing_block(itemid: int) -> int
-- Возвращает значение свойства `model-name`
item.model_name(itemid: int) -> str
item.model_name(itemid: int) -> string
-- Возвращает emission параметр у предмета
item.emission(itemid: int) -> str
item.emission(itemid: int) -> string
-- Возвращает значение свойства `uses`
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)
-- возвращает строку представляющую содержимое матрицы, многострочную, если multiline = true
mat4.tostring(m: matrix, multiline: bool)
mat4.tostring(m: matrix, multiline: boolean)
```

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

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

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

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

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

@ -18,11 +18,11 @@ local 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
--- Создание нового агента. Возвращает идентификатор созданного агента
local agent = pathfinding.create_agent() --> int
local agent = pathfinding.create_agent() -> int
--- Удаление агента по идентификатору. Возвращает 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
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. Если маршрут не найден, возвращает пустую таблицу.
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)
@ -63,4 +63,4 @@ pathfinding.avoid_tag(
-- стоимость пересечения блока
cost: int = 10
)
```
```

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

@ -1,180 +1,128 @@
# Библиотека *player*
## Содержание
- [Управление игроками](#управление-игроками)
- [Позиция и движение](#позиция-и-движение)
- [Режимы и свойства](#режимы-и-свойства)
- [Инвентарь и взаимодействие](#инвентарь-и-взаимодействие)
- [Камеры](#камеры)
- [Поиск игроков](#поиск-игроков)
## Управление игроками
```lua
player.create(name: str) -> int
```
-- Создает игрока и возвращает его ID
player.create(name: string) -> int
Создаёт игрока и возвращает его id.
```lua
-- Удаляет игрока по ID
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
-- Сеттер и геттер позиции игрока
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.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.get_rot(playerid: int, interpolated: boolean) -> number, number, number
Устанавливает x, y вращения камеры (в градусах)
```lua
-- Возвращает вектор направления взгляда игрока
player.get_dir(playerid: int) -> vec3
```
Возвращает вектор направления взгляда игрока
## Режимы и свойства
```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
```
Возвращает 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)
```
Устанавливает индекс выбранного слота
```lua
-- Возвращает позицию выбранного блока
player.get_selected_block(playerid: int) -> x,y,z
```
Возвращает координаты выделенного блока, либо nil
```lua
-- Возвращает ID выбранной сущности
player.get_selected_entity(playerid: int) -> int
```
Возвращает уникальный идентификатор сущности, на которую нацелен игрок
## Камеры
```lua
player.get_entity(playerid: int) -> int
-- Возвращает индекс текущей камеры игрока
player.get_camera(playerid: int) -> int
-- Переключает камеры игрока
player.set_camera(playerid: int, camera_index: int)
```
Возвращает уникальный идентификатор сущности игрока
## Поиск игроков
```lua
-- Возвращает массив id игроков в пределах сферы с центром center и радиусом radius.
player.get_all_in_radius(center: vec3, radius: number) -> table<int>
```
Возвращает массив id игроков в пределах сферы с центром `center` и радиусом `radius`.
```lua
-- Возвращает массив id всех активных игроков.
player.get_all() -> table<int>
```
Возвращает массив id всех активных игроков.
```lua
player.get_nearest(position: vec3) -> int
```
Возвращает id ближайшего к указанной позиции игрока, либо nil если игроков нет.
-- Возвращает id ближайшего к указанной позиции игрока, либо nil если игроков нет.
player.get_nearest(position: vec3) -> int / nil
```

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

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

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

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

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

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

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

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

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

@ -5,32 +5,32 @@
```lua
-- Конвертирует UTF-8 строку в Bytearray или массив чисел если
-- второй аргумент - true
utf8.tobytes(text: str, [опционально] usetable=false) -> Bytearray|table
utf8.tobytes(text: string, [опционально] usetable: boolean=false) -> Bytearray|table
-- Конвертирует 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
utf8.encode(codepoint: int) -> str
utf8.encode(codepoint: int) -> string
-- Возвращает подстроку от позиции 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
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 - массив из двух чисел
- vec3 - массив из трех чисел
- vec4 - массив из четырех чисел
@ -27,76 +27,79 @@
```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
vecn.add(a: vector, b: vector, dst: vector)
vecn.add(a: vecn, b: vecn, dst: vecn)
```
#### Вычитание - *vecn.sub(...)*
```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
vecn.sub(a: vector, b: vector, dst: vector)
vecn.sub(a: vecn, b: vecn, dst: vecn)
```
#### Умножение - *vecn.mul(...)*
```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(...)*
```lua
-- возвращает результат инверсии (противоположный) вектора
vecn.inverse(a: vector)
vecn.inverse(a: vecn) -> vecn
-- записывает инвертированный вектор в dst
vecn.inverse(v: vector, dst: vector)
vecn.inverse(v: vecn, dst: vecn)
```
#### Деление - *vecn.div(...)*
```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
vecn.div(a: vector, b: vector, dst: vector)
vecn.div(a: vecn, b: vecn, dst: vecn)
```
#### Нормализация - *vecn.norm(...)*
```lua
-- возвращает нормализованный вектор
vecn.normalize(a: vector)
vecn.normalize(a: vecn) -> vecn
-- записывает нормализованный вектор в dst
vecn.normalize(v: vector, dst: vector)
vecn.normalize(v: vecn, dst: vecn)
```
#### Длина вектора - *vecn.len(...)*
```lua
-- возвращает длину вектора
vecn.length(a: vector)
vecn.length(a: vecn) -> number
```
@ -104,53 +107,56 @@ vecn.length(a: vector)
```lua
-- возвращает расстояние между двумя векторами
vecn.distance(a: vector, b: vector)
vecn.distance(a: vecn, b: vecn) -> number
```
#### Абсолютное значение - *vecn.abs(...)*
```lua
-- возвращает вектор с абсолютными значениями
vecn.abs(a: vector)
vecn.abs(a: vecn) -> vecn
-- записывает абсолютное значение вектора в dst
vecn.abs(v: vector, dst: vector)
vecn.abs(v: vecn, dst: vecn)
```
#### Округление - *vecn.round(...)*
```lua
-- возвращает вектор с округленными значениями
vecn.round(a: vector)
vecn.round(a: vecn) -> vecn
-- записывает округленный вектор в dst
vecn.round(v: vector, dst: vector)
vecn.round(v: vecn, dst: vecn)
```
#### Степень - *vecn.pow(...)*
```lua
-- возвращает вектор с элементами, возведенными в степень
vecn.pow(a: vector, b: number)
vecn.pow(a: vecn, b: number) -> vecn
-- возвращает вектор с элементами, возведенными в значения другого вектора
vecn.pow(a: vecn, b: vecn) -> vecn
-- записывает вектор, возведенный в степень, в dst
vecn.pow(v: vector, exponent: number, dst: vector)
vecn.pow(v: vecn, exponent: number, dst: vecn)
```
#### Скалярное произведение - *vecn.dot(...)*
```lua
-- возвращает скалярное произведение векторов
vecn.dot(a: vector, b: vector)
vecn.dot(a: vecn, b: vecn) -> number
```
#### Смешивание - *vecn.mix(...)*
```lua
-- возвращает вектор 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
vecn.mix(a: vector, b: vector, t: number, dst: vector)
vecn.mix(a: vecn, b: vecn, t: number, dst: vecn)
```
#### Перевод в строку - *vecn.tostring(...)*
@ -158,7 +164,7 @@ vecn.mix(a: vector, b: vector, t: number, dst: vector)
> Возвращает только тогда, когда содержимым является вектор
```lua
-- возвращает строку представляющую содержимое вектора
vecn.tostring(a: vector)
vecn.tostring(a: vecn) -> string
```
## Специфические функции
@ -167,16 +173,16 @@ vecn.tostring(a: vector)
```lua
-- возвращает случайный вектор, координаты которого равномерно распределены на сфере заданного радиуса
vec3.spherical_rand(radius: number)
vec3.spherical_rand(radius: number) -> vec3
-- записывает случайный вектор, координаты которого равномерно распределены на сфере заданного радиуса в dst
vec3.spherical_rand(radius: number, dst: vec3)
-- возвращает угол направления вектора v в градусах [0, 360]
vec2.angle(v: vec2)
vec2.angle(v: vec2) -> number
-- возвращает угол направления вектора {x, y} в градусах [0, 360]
vec2.angle(x: number, y: number)
vec2.angle(x: number, y: number) -> number
-- возвращает повернутый вектор на угол в градусах против часовой стрелки
vec2.rotate(v: vec2, angle: number) -> vec2

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

@ -2,17 +2,17 @@
```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}
}
}>
-- Возвращает текущее игровое время от 0.0 до 1.0, где 0.0 и 1.0 - полночь, 0.5 - полдень.
world.get_day_time() -> number
@ -33,16 +33,16 @@ world.get_total_time() -> number
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 вечера).
world.is_day() -> bool
world.is_day() -> boolean
-- Проверяет является ли текущее время ночью. От 0.833(8 вечера) до 0.333(8 утра).
world.is_night() -> bool
world.is_night() -> boolean
-- Возвращает общее количество загруженных в память чанков
world.count_chunks() -> int
@ -60,7 +60,7 @@ world.set_chunk_data(
x: int, z: int,
-- сжатые данные чанка
data: Bytearray
) -> bool
) -> boolean
-- Сохраняет данные чанка в регион.
-- Изменения будет записаны в файл только после сохранения мира.
@ -69,4 +69,4 @@ world.save_chunk_data(
-- сжатые данные чанка
data: Bytearray
)
```
```

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.get_target() --> vec3
pathfinding.get_target() -> vec3
-- Устанавливает высоту преодолимого прыжком препятствия
pathfinding.set_jump_height(height: number)
@ -24,7 +24,7 @@ pathfinding.reset_route()
-- Возвращает следующую точку маршрута, по текущим координатам.
-- (следует использовать компонент core:mob - функция mob.follow_waypoints)
pathfinding.next_waypoint() --> vec3 или nil
pathfinding.next_waypoint() -> vec3 или nil
-- Устанавливает интервал перестройки маршрута в тактах обновления.
pathfinding.set_refresh_interval(interval: number)
@ -82,7 +82,7 @@ mob.follow_waypoints(
mob.set_dir(dir: vec3)
-- Проверяет, включён ли режим полёта
mob.is_flight() --> bool
mob.is_flight() -> 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]
> Mass events such as on_block_tick, on_block_present, and on_block_removed,
> if used carelessly or excessively, can lead to performance issues.
> Массовые события, такие как on_block_tick, on_block_present и on_block_removed,
> при небрежном или чрезмерном использовании, могут привести к проблемам с производительностью.
```lua
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`
```lua
function on_player_tick(playerid: int, tps: int)
```
Вызывается tps (20) раз в секунду. Используйте 1/tps вместо `time.delta()`.
### События чанков (world.lua)
```lua
@ -221,6 +230,9 @@ function on_hud_close(playerid: int)
Вызывается при выходе из мира, перед его сохранением.
## События ECS
События **ECS** описаны [тут](ecs.md#события-компонента)
## Библиотека *events*
```lua

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

@ -2,174 +2,73 @@
В скрипте ядра **stdmin.lua** определены функции, расширяющие и дополняющие некоторые из стандартных библиотек **Lua**
## Содержание:
- [расширения для table](#расширения-для-table)
- [расширения для string](#расширения-для-string)
- [расширения для math](#расширения-для-math)
- [расширения для bit](#расширения-для-bit)
- [Дополнительные глобальные функции](#дополнительные-глобальные-функции)
## Расширения для table
```lua
-- Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.
table.copy(t: table) -> table
```
Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.
```lua
-- Функция глубокого копирования создает полную копию исходной таблицы, включая все её вложенные таблицы.
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
table.random(t: table) -> object
```
-- Возвращает индекс объекта x в t. Если переданный объект не содержится в таблице, то функция вернёт значение -1.
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
```
Перемешивает значения в таблице.
```lua
-- Добавляет в таблицу t1 значения из таблицы t2. Если в таблице t2 присутствует ключ из t1, то значение ключа не будет изменено.
table.merge(t1: table, t2: table) -> table
```
Добавляет в таблицу **t1** значения из таблицы **t2**. Если в таблице **t2** присутствует ключ из **t1**, то значение ключа не будет изменено.
-- Проходится по таблице и применяет ко всем её элементам func, которая возвращает новое значение элемента.
table.map(t: table, func: function(indx, value)) -> table
```lua
table.map(t: table, func: function(indx, value) ) -> table
```
-- Проходится по таблице с помощью func, которая возвращает true если элемент надо сохранить и false, если его надо удалить.
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
```
Возвращает "плоскую" версию исходной таблицы.
```lua
-- Возвращает глубокую "плоскую" версию исходной таблицы.
table.deep_flat(t: table) -> table
```
Возвращает глубокую "плоскую" версию исходной таблицы.
```lua
-- Возвращает обрезанную версию таблицы с индекса start до индекса stop включительно, при этом пары ключ-значение
-- не сохраняются в новой таблице. При значениях nil начинает с 1 и заканчивает #arr соответственно.
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, pos: number, val: any)
```
table.insert_unique(t: table, pos: int, val: any)
Добавляет значение в таблицу, только если его там не было.
```lua
-- Конвертирует переданную таблицу в строку.
table.tostring(t: table) -> string
```
Конвертирует переданную таблицу в строку.
## Расширения для string
```lua
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** можно использовать как мета-методы на экземплярах строк, т.е.:
Важно подметить, что все ниже перечисленные функции, расширяющие **string** можно использовать как мета-методы на экземплярах строк, т.е.:
```lua
local str = "ABA str BAB"
@ -179,108 +78,126 @@ if str:starts_with("ABA") and str:ends_with("BAB") then
end
```
Также функции `string.lower` и `string.upper` переопределены на `utf8.lower` и `utf8.upper`
```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
-- Экранирует спец-символы 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
```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
math.rand(low, high)
```
-- Возвращает нормализованное значение num относительно conf.
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
```
Возвращает сумму всех принимаемых аргументов. Если в качестве аргумента была передана таблица, метод вернёт сумму всех её элементов.
## Расширения для 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
is_array(x: table) -> bool
```
-- Возвращает true, если переданная таблица является массивом, то есть если каждый ключ — это целое число больше или равное единице
-- и если каждый ключ следует за прошлым.
is_array(x: table) -> boolean
Возвращает **true**, если переданная таблица является массивом, тоесть если каждый ключ это целое число больше или равное единице и если каждый ключ следует за прошлым.
-- Разбивает путь на две части и возвращает их: входную точку и путь к файлу.
parse_path(path: string) -> string, string
```lua
function parse_path(path: string) -> string, string
```
-- Вызывает функцию func iters раз, передавая ей аргументы ..., а после выводит в консоль время в микросекундах,
-- которое прошло с момента вызова 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**.
```lua
function sleep(timesec: number)
```
Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в **timesec**. Функция может быть использована только внутри корутины.
```lua
function await(co: coroutine) -> result, error
```
Ожидает завершение переданной корутины, возвращая поток управления. Функция может быть использована только внутри корутины.
Возвращает значения аналогичные возвращаемым значениям *pcall*.
```lua
-- Константа, в которой хранится PID текущего инстанса движка.
os.pid -> number
```
Константа, в которой хранится PID текущего инстанса движка
```

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

@ -63,10 +63,10 @@ bjson.tobytes(
value: table,
-- сжатие
[опционально] 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
**binary** - Формат записи и чтения I/O
**flush** - Режим работы flush
- Режим сброса (`flush` / `flushMode`)
- Двоичный режим (`binary`)
### general
Имеет три режима:
Определяет, как поток обрабатывает чтение и запись,
имеет три подрежима:
**default** - Дефолтный режим работы потока. При read может вернуть только часть от требуемых данных, при write сразу записывает данные в поток.
**yield** - Почти тоже самое, что и **default**, но всегда будет возвращать все требуемые данные. Пока они не будут прочитаны, будет вызывать `coroutine.yield()`. Предназначен для работы в корутинах.
**buffered** - Буферизирует записываемые и читаемые данные.
При вызове `available`/`read` обновляет буфер чтения.
После обновления в `read`, если буфер чтения переполнен, то бросает ошибку `buffer overflow`.
Если требуемого кол-ва байт недостаточно в буфере для чтения, то бросает ошибку `buffer-underflow`.
При вызове `write` записывает итоговые байты в буфер для записи. Если он переполнен, то бросает ошибку `buffer overflow`.
При вызове `flush` проталкивает данные из буфера для записи в напрямую в поток
| Режим | Описание |
|---------------|--------|
| `"default"` | Прямой режим. `read` может вернуть меньше байт, чем запрошено. `write` сразу отправляет данные в низкоуровневый дескриптор. Нет буферизации. |
| `"yield"` | Как `default`, но при нехватке данных в `read(n)` поток будет вызывать `coroutine.yield()`, пока не соберёт ровно `n` байт. Удобно для корутин. |
| `"buffered"` | Включает внутренние буферы чтения и записи. `read` берёт данные из буфера, `write` — складывает в буфер. При превышении `maxBufferSize` — ошибка `buffer overflow`. |
### 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
-- Возвращает 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)
-- Возвращает режим работы flush
io_stream:get_flush_mode() --> string
io_stream:get_flush_mode() -> string
-- Задаёт режим работы flush
io_stream:set_flush_mode(string)
```
I/O методы
## I/O методы
```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(
[опционально] arg: int | string,
[опционально] useTable | trimEmptyLines: bool
) --> Bytearray | table<int> | string | table<string> | ...
[опционально] arg: number | string,
[опционально] useTable | trimEmptyLines: boolean
) -> Bytearray | table<number> | string | table<string> | ...
--[[
Записывает данные в поток
В двоичном режиме:
Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток
Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток
Если arg - Bytearray | table<int>, то записывает байты в поток
Если arg - Bytearray | table<number>, то записывает байты в поток
В текстовом режиме:
Если arg - string, то записывает строку в поток (вместе с окончанием LF)
Если arg - string, то записывает строку в поток (вместе с окончанием LF)
Если arg - table<string>, то записывает каждую строку из таблицы отдельно
Если arg - table<string>, то записывает каждую строку из таблицы отдельно
--]]
io_stream:write(
arg: Bytearray | table<int> | string | table<string>,
arg: Bytearray | table<number> | string | table<string>,
[опционально] ...
)
-- Читает одну строку с окончанием CRLF/LF из потока вне зависимости от двоичного режима
io_stream:read_line() --> string
io_stream:read_line() -> string
-- Записывает одну строку с окончанием LF в поток вне зависимости от двоичного режима
io_stream:write_line(string)
--[[
В двоичном режиме:
Читает все доступные байты из потока и возвращает ввиде Bytearray или table<int>, если useTable = true
Читает все доступные байты из потока и возвращает ввиде Bytearray или table<number>, если useTable = true
В текстовом режиме:
Читает все доступные строки из потока в table<string> если useTable = true, или в одну строку вместе с окончаниями, если нет
Читает все доступные строки из потока в table<string> если useTable = true, или в одну строку вместе с окончаниями, если нет
--]]
io_stream:read_fully(
[опционально] useTable: bool
) --> Bytearray | table<int> | table<string> | string
[опционально] useTable: boolean
) -> Bytearray | table<number> | table<string> | string
```
Методы, имеющие смысл в использовании только в buffered режиме
## Методы Buffered-режима
```lua
--[[
Если length определён, то возвращает true, если length байт доступно к чтению. Иначе возвращает false
Если не определён, то возвращает количество байт, которое можно прочитать
--]]
io_stream:available(
[опционально] length: int
) --> int | bool
[опционально] length: number
) -> 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
-- Возвращает true, если поток открыт на данный момент
io_stream:is_alive() --> bool
io_stream:is_alive() -> bool
-- Возвращает true, если поток закрыт на данный момент
io_stream:is_closed() --> bool
io_stream:is_closed() -> bool
-- Закрывает поток
io_stream:close()
--[[
Записывает все данные из write-буфера в поток в buffer/all flush-режимах
Вызывает ioLib.flush() в all flush-режиме
--]]
-- Записывает все данные из write-буфера в поток в buffer/all flush-режимах
-- Вызывает ioLib.flush() в all flush-режиме
io_stream:flush()
```
Создание нового потока
```lua
--[[
Создаёт новый поток с переданным дескриптором и использующим переданную I/O библиотеку. (Более подробно в core:io_stream.lua)
--]]
-- Создаёт новый поток с переданным дескриптором и использующим переданную I/O библиотеку. (Более подробно в core:io_stream.lua)
io_stream.new(
descriptor: int,
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
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
function bit_converter.uint16_to_bytes(int: integer, [опционально] order: string) -> table
function bit_converter.uint16_to_bytes(int: int, [опционально] order: string) -> table
```
Конвертирует беззнаковое 2-х байтовое целое число в байты
```lua
function bit_converter.uint32_to_bytes(int: integer, [опционально] order: string) -> table
function bit_converter.uint32_to_bytes(int: int, [опционально] order: string) -> table
```
Конвертирует беззнаковое 4-х байтовое целое число в байты
```lua
function bit_converter.sint16_to_bytes(int: integer, [опционально] order: string) -> table
function bit_converter.sint16_to_bytes(int: int, [опционально] order: string) -> table
```
Конвертирует знаковое 2-х байтовое целое число в байты
```lua
function bit_converter.sint32_to_bytes(int: integer, [опционально] order: string) -> table
function bit_converter.sint32_to_bytes(int: int, [опционально] order: string) -> table
```
Конвертирует знаковое 4-х байтовое целое число в байты
```lua
function bit_converter.int64_to_bytes(int: integer, [опционально] order: string) -> table
function bit_converter.int64_to_bytes(int: int, [опционально] order: string) -> table
```
Конвертирует знаковое 8-и байтовое целое число в байты
@ -58,7 +58,7 @@ function bit_converter.bytes_to_string(bytes: table) -> string
Конвертирует массив байтов в строку
```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
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-х байтовое беззнаковое число
```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-х байтовое беззнаковое число
```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-х байтовое знаковое число
```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-х байтовое знаковое число
```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-х байтовое знаковое число

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)
```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
function data_buffer:put_uint16(int: integer)
function data_buffer:put_uint16(int: int)
```
Конвертирует беззнаковое 2-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_uint32(int: integer)
function data_buffer:put_uint32(int: int)
```
Конвертирует беззнаковое 4-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_sint16(int: integer)
function data_buffer:put_sint16(int: int)
```
Конвертирует знаковое 2-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_sint32(int: integer)
function data_buffer:put_sint32(int: int)
```
Конвертирует знаковое 4-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_int64(int: integer)
function data_buffer:put_int64(int: int)
```
Конвертирует знаковое 8-и байтовое число в байты и записывает их в буффер
@ -91,7 +91,7 @@ sint32 = 8
```
```lua
function data_buffer:get_byte() -> integer
function data_buffer:get_byte() -> int
```
Возвращает следующий байт из буффера
@ -121,27 +121,27 @@ function data_buffer:get_float64() -> number
Читает следующее плавающее число двойной точности из буффера
```lua
function data_buffer:get_uint16() -> integer
function data_buffer:get_uint16() -> int
```
Читает следующее 2-х байтовое беззнаковое целое число из буффера
```lua
function data_buffer:get_uint32() -> integer
function data_buffer:get_uint32() -> int
```
Читает следующее 4-х байтовое беззнаковое целое число из буффера
```lua
function data_buffer:get_sint16() -> integer
function data_buffer:get_sint16() -> int
```
Читает следующее 2-х байтовое знаковое целое число из буффера
```lua
function data_buffer:get_sint32() -> integer
function data_buffer:get_sint32() -> int
```
Читает следующее 4-х байтовое знаковое целое число из буффера
```lua
function data_buffer:get_int64() -> integer
function data_buffer:get_int64() -> int
```
Читает следующее 8-х байтовое знаковое целое число из буффера
@ -151,12 +151,12 @@ function data_buffer:get_number() -> number
Читает следующее число (см. data_buffer:put_number)
```lua
function data_buffer:size() -> integer
function data_buffer:size() -> int
```
Возвращает размер буффера
```lua
function data_buffer:set_position(integer: pos)
function data_buffer:set_position(int: pos)
```
Устанавливает текущую позицию в буффере

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

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

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

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