voxelcoreprojects/voxelcore
1
0
Fork 0
mirror of https://github.com/MihailRis/voxelcore.git synced 2026-10-07 12:01:50 +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 MihailRis
parent 8b31bdeb78
commit ac02bc0c8e
43 changed files with 1107 additions and 1314 deletions
Download patch file Download diff file Expand all files Collapse all files

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
)
```
```