From 32feb78002d149f015f94008ed509cdf0208b94b Mon Sep 17 00:00:00 2001 From: Xertis <118364459+Xertis@users.noreply.github.com> Date: Thu, 18 Dec 2025 12:58:39 +0300 Subject: [PATCH] Improved docs (#708) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * начало переписи доков * 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 --- doc/en/scripting/builtins/libbyteutil.md | 24 +- doc/ru/audio.md | 44 +-- doc/ru/console.md | 13 +- doc/ru/scripting/builtins/libapp.md | 174 ++++----- doc/ru/scripting/builtins/libassets.md | 16 +- doc/ru/scripting/builtins/libbase64.md | 14 +- doc/ru/scripting/builtins/libblock.md | 164 ++++---- doc/ru/scripting/builtins/libbyteutil.md | 32 +- doc/ru/scripting/builtins/libcameras.md | 14 +- doc/ru/scripting/builtins/libcompression.md | 8 +- doc/ru/scripting/builtins/libentities.md | 16 +- doc/ru/scripting/builtins/libfile.md | 316 +++++++--------- .../scripting/builtins/libgfx-blockwraps.md | 6 +- .../scripting/builtins/libgfx-posteffects.md | 14 +- doc/ru/scripting/builtins/libgfx-skeletons.md | 18 +- doc/ru/scripting/builtins/libgfx-weather.md | 8 +- doc/ru/scripting/builtins/libgui.md | 144 ++++---- doc/ru/scripting/builtins/libhud.md | 24 +- doc/ru/scripting/builtins/libinput.md | 94 ++--- doc/ru/scripting/builtins/libinventory.md | 22 +- doc/ru/scripting/builtins/libitem.md | 20 +- doc/ru/scripting/builtins/libmat4.md | 2 +- doc/ru/scripting/builtins/libnetwork.md | 82 ++-- doc/ru/scripting/builtins/libpack.md | 56 +-- doc/ru/scripting/builtins/libpathfinding.md | 18 +- doc/ru/scripting/builtins/libplayer.md | 228 +++++------- doc/ru/scripting/builtins/libquat.md | 6 +- doc/ru/scripting/builtins/librandom.md | 14 +- doc/ru/scripting/builtins/librules.md | 16 +- doc/ru/scripting/builtins/libtime.md | 31 +- doc/ru/scripting/builtins/libutf8.md | 22 +- doc/ru/scripting/builtins/libvecn.md | 68 ++-- doc/ru/scripting/builtins/libworld.md | 22 +- doc/ru/scripting/bytearray.md | 62 ++++ doc/ru/scripting/core_components.md | 6 +- doc/ru/scripting/events.md | 28 +- doc/ru/scripting/extensions.md | 349 +++++++----------- doc/ru/scripting/filesystem.md | 4 +- doc/ru/scripting/io_stream.md | 158 ++++---- .../scripting/modules/core_bit_converter.md | 24 +- doc/ru/scripting/modules/core_data_buffer.md | 28 +- doc/ru/scripting/ui.md | 2 +- doc/ru/world-generator.md | 10 +- 43 files changed, 1107 insertions(+), 1314 deletions(-) create mode 100644 doc/ru/scripting/bytearray.md diff --git a/doc/en/scripting/builtins/libbyteutil.md b/doc/en/scripting/builtins/libbyteutil.md index c0cf72d07..0df21f026 100644 --- a/doc/en/scripting/builtins/libbyteutil.md +++ b/doc/en/scripting/builtins/libbyteutil.md @@ -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. diff --git a/doc/ru/audio.md b/doc/ru/audio.md index 8291e7bab..c07c55677 100644 --- a/doc/ru/audio.md +++ b/doc/ru/audio.md @@ -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 ) ``` diff --git a/doc/ru/console.md b/doc/ru/console.md index f87dd89f8..df62413fd 100644 --- a/doc/ru/console.md +++ b/doc/ru/console.md @@ -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 -- Возвращает таблицу со списком команд -console.get_command_info(name: String) -> Table -- Возвращает информацию о команде -console.execute(command: str) -- Выполняет команду +console.get_commands_list() -> Table -- Возвращает таблицу со списком команд +console.get_command_info(name: string) -> Table -- Возвращает информацию о команде +console.execute(command: string) -- Выполняет команду ``` - - - diff --git a/doc/ru/scripting/builtins/libapp.md b/doc/ru/scripting/builtins/libapp.md index d8a1e81ca..07e358ef4 100644 --- a/doc/ru/scripting/builtins/libapp.md +++ b/doc/ru/scripting/builtins/libapp.md @@ -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 -``` -Возвращает список источников контента (путей), в порядке убывания приоритета. - -```lua +-- Устанавливает список источников контента (путей). Указывается в порядке убывания приоритета. app.set_content_sources(sources: table) -``` -Устанавливает список источников контента (путей). Указывается в порядке убывания приоритета. - -```lua +-- Сбрасывает список источников контента. app.reset_content_sources() -``` - -Сбрасывает список источников контента. +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libassets.md b/doc/ru/scripting/builtins/libassets.md index ec069e1a0..f80b710ad 100644 --- a/doc/ru/scripting/builtins/libassets.md +++ b/doc/ru/scripting/builtins/libassets.md @@ -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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libbase64.md b/doc/ru/scripting/builtins/libbase64.md index 33bac975e..99e2e7344 100644 --- a/doc/ru/scripting/builtins/libbase64.md +++ b/doc/ru/scripting/builtins/libbase64.md @@ -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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libblock.md b/doc/ru/scripting/builtins/libblock.md index 1466d1c8b..1dabdb7e8 100644 --- a/doc/ru/scripting/builtins/libblock.md +++ b/doc/ru/scripting/builtins/libblock.md @@ -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 -- Таблица пользовательских свойств блоков (см. ../../block-properties.md) -block.properties: table> +block.properties: table> +``` --- Возвращает название блока, отображаемое в интерфейсе. -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 -## Физика - -Информация свойствах блока, используемых физическим движком. - -```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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libbyteutil.md b/doc/ru/scripting/builtins/libbyteutil.md index 2c675594e..54dc474ff 100644 --- a/doc/ru/scripting/builtins/libbyteutil.md +++ b/doc/ru/scripting/builtins/libbyteutil.md @@ -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 -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libcameras.md b/doc/ru/scripting/builtins/libcameras.md index b5a1bed1f..71b4c9ee1 100644 --- a/doc/ru/scripting/builtins/libcameras.md +++ b/doc/ru/scripting/builtins/libcameras.md @@ -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#камеры). \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libcompression.md b/doc/ru/scripting/builtins/libcompression.md index 276fbd29c..6c6b194b8 100644 --- a/doc/ru/scripting/builtins/libcompression.md +++ b/doc/ru/scripting/builtins/libcompression.md @@ -6,20 +6,20 @@ -- Сжимает массив байт. compression.encode( -- Массив байт - data: array of integers, + data: Bytearray | table, -- Алгоритм сжатия (поддерживается только gzip) [опционально] algorithm="gzip", -- Вернуть результат в table? [опционально] usetable=false -) -> array of integers +) -> Bytearray | table -- Разжимает массив байт. compression.decode( -- Массив байт - data: array of integers, + data: Bytearray | table, -- Алгоритм разжатия (поддерживается только gzip) [опционально] algorithm="gzip", -- Вернуть результат в table? [опционально] usetable=false -) -> array of integers +) -> Bytearray | table ``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libentities.md b/doc/ru/scripting/builtins/libentities.md index 000070f2e..a66bc83b8 100644 --- a/doc/ru/scripting/builtins/libentities.md +++ b/doc/ru/scripting/builtins/libentities.md @@ -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) -> table +entities.get_all(uids: table) -> table -- Возвращает список UID сущностей, попадающих в прямоугольную область -- pos - минимальный угол области -- size - размер области -entities.get_all_in_box(pos: vec3, size: vec3) -> array +entities.get_all_in_box(pos: vec3, size: vec3) -> table -- Возвращает список UID сущностей, попадающих в радиус -- center - центр области -- radius - радиус области -entities.get_all_in_radius(center: vec3, radius: number) -> array +entities.get_all_in_radius(center: vec3, radius: number) -> table ``` ```lua @@ -68,4 +68,4 @@ entities.raycast(start: vec3, dir: vec3, max_distance: number, Функция является расширенным вариантом [block.raycast](libblock.md#raycast). Возвращает таблицу с результатами если луч касается блока, либо сущности. -Соответственно это повлияет на наличие полей *entity* и *block*. +Соответственно это повлияет на наличие полей *entity* и *block*. \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libfile.md b/doc/ru/scripting/builtins/libfile.md index 67af51785..0d1b9d58c 100644 --- a/doc/ru/scripting/builtins/libfile.md +++ b/doc/ru/scripting/builtins/libfile.md @@ -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 + +-- Возвращает список файлов и директорий в указанной без указания конкретной точки входа. +file.list_all_res(путь: string) -> table + +-- Возвращает путь на уровень выше. Пример: `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 + +-- Читает файл в массив байт. При значении usetable = false возвращает Bytearray вместо table. +file.read_bytes(путь: string, [опционально] usetable: boolean=false) -> Bytearray | table + +-- Записывает текст в файл (с перезаписью) +file.write(путь: string, текст: string) -> nil + +-- Записывает массив байт в файл (с перезаписью) +file.write_bytes(путь: string, data: table) + +-- Удаляет файл. Возращает 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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libgfx-blockwraps.md b/doc/ru/scripting/builtins/libgfx-blockwraps.md index ea794d2b5..645df7ec9 100644 --- a/doc/ru/scripting/builtins/libgfx-blockwraps.md +++ b/doc/ru/scripting/builtins/libgfx-blockwraps.md @@ -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`. \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libgfx-posteffects.md b/doc/ru/scripting/builtins/libgfx-posteffects.md index 0664486b9..01c13d888 100644 --- a/doc/ru/scripting/builtins/libgfx-posteffects.md +++ b/doc/ru/scripting/builtins/libgfx-posteffects.md @@ -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)) -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libgfx-skeletons.md b/doc/ru/scripting/builtins/libgfx-skeletons.md index 0e80b8f9d..2a04d598c 100644 --- a/doc/ru/scripting/builtins/libgfx-skeletons.md +++ b/doc/ru/scripting/builtins/libgfx-skeletons.md @@ -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) -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libgfx-weather.md b/doc/ru/scripting/builtins/libgfx-weather.md index 9c923a5c5..add94550b 100644 --- a/doc/ru/scripting/builtins/libgfx-weather.md +++ b/doc/ru/scripting/builtins/libgfx-weather.md @@ -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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libgui.md b/doc/ru/scripting/builtins/libgui.md index a9bffe486..50203bb46 100644 --- a/doc/ru/scripting/builtins/libgui.md +++ b/doc/ru/scripting/builtins/libgui.md @@ -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, + -- таблица переменных (может быть использована в разметке) + -- * Пр: + -- * text в данном случае, это значение из params по ключу text + params: table, + -- таблица, доступная в событиях как глобальная переменная DATA + [опционально] data: table +) -> string ``` -Загружает UI документ с его скриптом, возвращает имя документа, если успешно загружен. +## Корневой документ ```lua +-- Корневой UI документ. gui.root: Document -``` - -Корневой UI документ +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libhud.md b/doc/ru/scripting/builtins/libhud.md index 6ed81e050..1e904cc56 100644 --- a/doc/ru/scripting/builtins/libhud.md +++ b/doc/ru/scripting/builtins/libhud.md @@ -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() -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libinput.md b/doc/ru/scripting/builtins/libinput.md index 6aadbdc13..7d04747a9 100644 --- a/doc/ru/scripting/builtins/libinput.md +++ b/doc/ru/scripting/builtins/libinput.md @@ -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 + +-- Возвращает текстовое представление кнопки по имени привязки. +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 -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libinventory.md b/doc/ru/scripting/builtins/libinventory.md index 97fa56ffc..50ed8dccb 100644 --- a/doc/ru/scripting/builtins/libinventory.md +++ b/doc/ru/scripting/builtins/libinventory.md @@ -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 ) -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libitem.md b/doc/ru/scripting/builtins/libitem.md index 2c312dc49..4f78ecffd 100644 --- a/doc/ru/scripting/builtins/libitem.md +++ b/doc/ru/scripting/builtins/libitem.md @@ -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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libmat4.md b/doc/ru/scripting/builtins/libmat4.md index e6f3a3b15..1531798a4 100644 --- a/doc/ru/scripting/builtins/libmat4.md +++ b/doc/ru/scripting/builtins/libmat4.md @@ -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) ``` diff --git a/doc/ru/scripting/builtins/libnetwork.md b/doc/ru/scripting/builtins/libnetwork.md index 8c574f361..31f59fb25 100644 --- a/doc/ru/scripting/builtins/libnetwork.md +++ b/doc/ru/scripting/builtins/libnetwork.md @@ -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 + [опционально] headers: table ) -- Пример: @@ -23,10 +23,10 @@ end) -- Вариант для двоичных файлов, с массивом байт вместо строки в ответе. network.get_binary( - url: str, - callback: function(ByteArray), + url: string, + callback: function(Bytearray), [опционально] onfailure: function(int, Bytearray), - [опционально] headers: table + [опционально] headers: table ) -- Выполняет 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 + [опционально] headers: table ) ``` @@ -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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libpack.md b/doc/ru/scripting/builtins/libpack.md index 91726d72e..0c4aac0c1 100644 --- a/doc/ru/scripting/builtins/libpack.md +++ b/doc/ru/scripting/builtins/libpack.md @@ -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 ``` Возращает id всех установленных в мире контент-паков. -```python -pack.get_available() -> массив строк +```lua +pack.get_available() -> table ``` Возвращает id всех доступных, но не установленных в мире контент-паков. -```python -pack.get_base_packs() -> массив строк +```lua +pack.get_base_packs() -> table ``` Возвращает 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 -- опциональный } ``` @@ -88,17 +88,17 @@ pack.get_info(packid: str) -> { производить сканирование для каждого пака: ```lua -pack.get_info(packids: table) -> {id={...}, id2={...}, ...} +pack.get_info(packids: table) -> table ``` ```lua -pack.assemble(packids: table) -> table +pack.assemble(packids: table) -> table ``` -Проверяет корректность конфигурации и добавляет зависимости, возвращая полную. +Проверяет корректность конфигурации и добавляет зависимости, возвращая полную конфигурацию. ```lua -pack.request_writeable(packid: str, callback: function(str)) +pack.request_writeable(packid: string, callback: function(string)) ``` -Запрашивает у пользователя право на модификацию пака. При подтвержении новая точка входа будет передана в callback. +Запрашивает у пользователя право на модификацию пака. При подтвержении новая точка входа будет передана в callback. \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libpathfinding.md b/doc/ru/scripting/builtins/libpathfinding.md index fe31c18e2..3d0a07e2e 100644 --- a/doc/ru/scripting/builtins/libpathfinding.md +++ b/doc/ru/scripting/builtins/libpathfinding.md @@ -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 или nil +local route = pf.get_route() -> table или nil --- ... ``` @@ -30,19 +30,19 @@ local route = pf.get_route() --> table или 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 +pathfinding.make_route(start: vec3, target: vec3) -> table --- Асинхронное создание маршрута на основе заданных точек. --- Функция позволяет выполнять поиск пути в фоновом режиме, не блокируя основной поток выполнения @@ -50,7 +50,7 @@ pathfinding.make_route_async(agent: int, start: vec3, target: vec3) --- Получение маршрута, который агент уже нашел. Используется для получения маршрута после асинхронного поиска. --- Если поиск ещё не завершён, возвращает nil. Если маршрут не найден, возвращает пустую таблицу. -pathfinding.pull_route(agent: int) --> table или nil +pathfinding.pull_route(agent: int) -> table или nil --- Установка максимального количества посещенных блоков для агента. Используется для ограничения объема работы алгоритма поиска пути. pathfinding.set_max_visited(agent: int, max_visited: int) @@ -63,4 +63,4 @@ pathfinding.avoid_tag( -- стоимость пересечения блока cost: int = 10 ) -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libplayer.md b/doc/ru/scripting/builtins/libplayer.md index b156d6d27..d4f77cac6 100644 --- a/doc/ru/scripting/builtins/libplayer.md +++ b/doc/ru/scripting/builtins/libplayer.md @@ -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 -``` -Возвращает массив id игроков в пределах сферы с центром `center` и радиусом `radius`. - -```lua +-- Возвращает массив id всех активных игроков. player.get_all() -> table -``` -Возвращает массив id всех активных игроков. - -```lua -player.get_nearest(position: vec3) -> int -``` - -Возвращает id ближайшего к указанной позиции игрока, либо nil если игроков нет. +-- Возвращает id ближайшего к указанной позиции игрока, либо nil если игроков нет. +player.get_nearest(position: vec3) -> int / nil +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libquat.md b/doc/ru/scripting/builtins/libquat.md index 5b61c36b3..5a6495658 100644 --- a/doc/ru/scripting/builtins/libquat.md +++ b/doc/ru/scripting/builtins/libquat.md @@ -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 ``` diff --git a/doc/ru/scripting/builtins/librandom.md b/doc/ru/scripting/builtins/librandom.md index 8aa58592a..252ffe8e6 100644 --- a/doc/ru/scripting/builtins/librandom.md +++ b/doc/ru/scripting/builtins/librandom.md @@ -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) diff --git a/doc/ru/scripting/builtins/librules.md b/doc/ru/scripting/builtins/librules.md index a0307c7c1..efd5c71aa 100644 --- a/doc/ru/scripting/builtins/librules.md +++ b/doc/ru/scripting/builtins/librules.md @@ -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 | \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libtime.md b/doc/ru/scripting/builtins/libtime.md index 5bf9ad018..c4be679be 100644 --- a/doc/ru/scripting/builtins/libtime.md +++ b/doc/ru/scripting/builtins/libtime.md @@ -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 в секундах \ No newline at end of file +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libutf8.md b/doc/ru/scripting/builtins/libutf8.md index e4d79f4ff..657b89192 100644 --- a/doc/ru/scripting/builtins/libutf8.md +++ b/doc/ru/scripting/builtins/libutf8.md @@ -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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/builtins/libvecn.md b/doc/ru/scripting/builtins/libvecn.md index b3791bad7..00ec0277a 100644 --- a/doc/ru/scripting/builtins/libvecn.md +++ b/doc/ru/scripting/builtins/libvecn.md @@ -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 diff --git a/doc/ru/scripting/builtins/libworld.md b/doc/ru/scripting/builtins/libworld.md index 5713a3287..215329df3 100644 --- a/doc/ru/scripting/builtins/libworld.md +++ b/doc/ru/scripting/builtins/libworld.md @@ -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 ) -``` +``` \ No newline at end of file diff --git a/doc/ru/scripting/bytearray.md b/doc/ru/scripting/bytearray.md new file mode 100644 index 000000000..c90b6d67e --- /dev/null +++ b/doc/ru/scripting/bytearray.md @@ -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) + +-- Вставляет данные по индексу. +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 +``` \ No newline at end of file diff --git a/doc/ru/scripting/core_components.md b/doc/ru/scripting/core_components.md index a90cf1d82..7113a62bb 100644 --- a/doc/ru/scripting/core_components.md +++ b/doc/ru/scripting/core_components.md @@ -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) diff --git a/doc/ru/scripting/events.md b/doc/ru/scripting/events.md index 7266a4356..72ff37244 100644 --- a/doc/ru/scripting/events.md +++ b/doc/ru/scripting/events.md @@ -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 diff --git a/doc/ru/scripting/extensions.md b/doc/ru/scripting/extensions.md index 9a89b2b53..868210056 100644 --- a/doc/ru/scripting/extensions.md +++ b/doc/ru/scripting/extensions.md @@ -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 + +-- Разбивает строку str на части по указанному разделителю delimiter и возвращает результат ввиде таблицы из строк. +string.split(str: string, delimiter: string) -> table + +-- Экранирует специальные символы в строке, такие как `()[]+-.$%^?*` в формате `%символ`. Символ `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 текущего инстанса движка +``` \ No newline at end of file diff --git a/doc/ru/scripting/filesystem.md b/doc/ru/scripting/filesystem.md index 10d82c602..0e060d94c 100644 --- a/doc/ru/scripting/filesystem.md +++ b/doc/ru/scripting/filesystem.md @@ -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 ``` ## Сохранение данных в мире diff --git a/doc/ru/scripting/io_stream.md b/doc/ru/scripting/io_stream.md index 16a978db0..283e0c48b 100644 --- a/doc/ru/scripting/io_stream.md +++ b/doc/ru/scripting/io_stream.md @@ -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`| `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 | string | table | ... + [опционально] arg: number | string, + [опционально] useTable | trimEmptyLines: boolean +) -> Bytearray | table | string | table | ... --[[ Записывает данные в поток - В двоичном режиме: + Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток -Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток - -Если arg - Bytearray | table, то записывает байты в поток + Если arg - Bytearray | table, то записывает байты в поток В текстовом режиме: + Если arg - string, то записывает строку в поток (вместе с окончанием LF) -Если arg - string, то записывает строку в поток (вместе с окончанием LF) - -Если arg - table, то записывает каждую строку из таблицы отдельно + Если arg - table, то записывает каждую строку из таблицы отдельно --]] io_stream:write( - arg: Bytearray | table | string | table, + arg: Bytearray | table | string | table, [опционально] ... ) -- Читает одну строку с окончанием CRLF/LF из потока вне зависимости от двоичного режима -io_stream:read_line() --> string +io_stream:read_line() -> string -- Записывает одну строку с окончанием LF в поток вне зависимости от двоичного режима io_stream:write_line(string) --[[ - В двоичном режиме: - -Читает все доступные байты из потока и возвращает ввиде Bytearray или table, если useTable = true + Читает все доступные байты из потока и возвращает ввиде Bytearray или table, если useTable = true В текстовом режиме: - -Читает все доступные строки из потока в table если useTable = true, или в одну строку вместе с окончаниями, если нет + Читает все доступные строки из потока в table если useTable = true, или в одну строку вместе с окончаниями, если нет --]] io_stream:read_fully( - [опционально] useTable: bool -) --> Bytearray | table | table | string + [опционально] useTable: boolean +) -> Bytearray | table | table | 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, diff --git a/doc/ru/scripting/modules/core_bit_converter.md b/doc/ru/scripting/modules/core_bit_converter.md index 44b915c7b..acf7fd9e6 100644 --- a/doc/ru/scripting/modules/core_bit_converter.md +++ b/doc/ru/scripting/modules/core_bit_converter.md @@ -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-х байтовое знаковое число diff --git a/doc/ru/scripting/modules/core_data_buffer.md b/doc/ru/scripting/modules/core_data_buffer.md index 09b682b9f..eb3b43c3c 100644 --- a/doc/ru/scripting/modules/core_data_buffer.md +++ b/doc/ru/scripting/modules/core_data_buffer.md @@ -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) ``` Устанавливает текущую позицию в буффере diff --git a/doc/ru/scripting/ui.md b/doc/ru/scripting/ui.md index 33c4958f4..4371c931e 100644 --- a/doc/ru/scripting/ui.md +++ b/doc/ru/scripting/ui.md @@ -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) | заменяет данные пикселей (ширина * высота * 4 чисел) | +| data:set_data(data: Bytearray | table) | заменяет данные пикселей (ширина * высота * 4 чисел) | | data:get_data() | создаёт объект Bytearray с пиксельными данными изображения | | data:create_texture(name: str) | создаёт и делится текстурой с рендерером | | data:unbind_texture() | отвязывает текстуру от холста | diff --git a/doc/ru/world-generator.md b/doc/ru/world-generator.md index 5e0c50c1b..3f262ab3f 100644 --- a/doc/ru/world-generator.md +++ b/doc/ru/world-generator.md @@ -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, -- высота чанка -) --> массив размещений структур / тоннелей +) -> массив размещений структур / тоннелей ``` ## Структурный воздух