From 61e7af4df08f553de93abd47487aa7dfc625a5ed Mon Sep 17 00:00:00 2001 From: MihailRis Date: Fri, 15 Mar 2024 12:39:59 +0300 Subject: [PATCH] =?UTF-8?q?Destroyed=20=D0=A1=D0=BA=D1=80=D0=B8=D0=BF?= =?UTF-8?q?=D1=82=D0=B8=D0=BD=D0=B3=20(markdown)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Скриптинг.md | 487 --------------------------------------------------- 1 file changed, 487 deletions(-) delete mode 100644 Скриптинг.md diff --git a/Скриптинг.md b/Скриптинг.md deleted file mode 100644 index c2abba1..0000000 --- a/Скриптинг.md +++ /dev/null @@ -1,487 +0,0 @@ -В качестве языка сценариев используется LuaJIT - -На данном этапе, скриптинг реализован в тестовом режиме и будет активно развиваться, с изменением (иногда и радикальным) API движка. - -## Функции, доступные в скриптах - -```lua -load_script("контентпак:scripts/имя_скрипта.lua") -- загружает скрипт, если ещё не загружен -load_script("контентпак:scripts/имя_скрипта.lua", true) -- перезагружает скрипт -require "контентпак:имя_модуля" -- загружает lua модуль из папки modules (расширение не указывается) -``` - -## Библиотека player -```python -player.get_pos(id: int) -> number, number, number -``` -Возвращает x, y, z координаты игрока - -```python -player.set_pos(id: int, x: number, y: number, z: number) -``` - -Устанавливает x, y, z координаты игрока - -```python -player.get_rot(id: int) -> number, number -``` - -Возвращает x, y вращения камеры (в радианах), где значение X не ограничено - -```python -player.set_rot(id: int, x: number, y: number, z: number) -``` - -Устанавливает x, y вращения камеры (в радианах) - -```python -player.get_inventory(playerid: int) -> int, int -``` - -Возвращает id инвентаря игрока и индекс выбранного слота (от 0 до 9) - -## Библиотека world - -```python -world.get_day_time() -> number -``` - -Возвращает текущее игровое время от 0.0 до 1.0, где 0.0 и 1.0 - полночь, 0.5 - полдень. - -```python -world.set_day_time(time: number) -``` - -Устанавливает указанное игровое время. - -```python -world.get_total_time() -> number -``` - -Возвращает общее суммарное время, прошедшее в мире - -```python -world.get_seed() -> int -``` - -Возвращает зерно мира. - -## Библиотека gui - -Библиотека содержит функции для доступа к свойствам UI элементов. Вместо gui следует использовать объектную обертку, предоставляющую доступ к свойствам через мета-методы __index, __newindex: -```lua -local inventory_doc = Document.new("id-макета") -print(inventory_doc.some_button.text) -indentory_doc.some_button.text = "new text" -``` - -В скрипте макета `layouts/файл_макета.xml` - `layouts/файл_макета.xml.lua` уже доступна переменная **document** содержащая объект класса Document - -## Библиотека inventory - -Библиотека функций для работы с инвентарем. - -```python -inventory.get(invid: int, slot: int) -> int, int -``` - -Принимает id инвентаря и индекс слота. Возвращает id предмета и его количество. id = 0 (core:empty) обозначает, что слот пуст. - -```python -inventory.set(invid: int, slot: int, itemid: int, count: int) -``` - -Устанавливает содержимое слота. - -```python -inventory.size(invid: int) -> int -``` - -Возращает размер инвентаря (число слотов). Если указанного инвентаря не существует, бросает исключение. - -```python -inventory.add(invid: int, itemid: int, count: int) -> int -``` - -Добавляет предмет в инвентарь. Если не удалось вместить все количество, возвращает остаток. - -```python -inventory.get_block(x: int, y: int, z: int) -> int -``` - -Функция возвращает id инвентаря указанного блока. Если блок не может иметь инвентарь - возвращает 0. - -```python -inventory.bind_block(invid: int, x: int, y: int, z: int) -``` - -Привязывает указанный инвентарь к блоку. - -```python -inventory.unbind_block(x: int, y: integer, z: int) -``` - -Отвязывает инвентарь от блока. - -> [!WARNING] -> Инвентари, не привязанные ни к одному из блоков, удаляются при выходе из мира. - -```python -inventory.clone(invid: int) -> int -``` - -Создает копию инвентаря и возвращает id копии. Если копируемого инвентаря не существует, возвращает 0. - -## Библиотека block - -```python -block.name(blockid: int) -> str -``` - -Возвращает строковый id блока по его числовому id - -```python -block.index(name: str) -> int -``` - -Возвращает числовой id блока, принимая в качестве агрумента строковый - -```python -block.get(x: int, y: int, z: int) -> int -``` - -Возвращает числовой id блока на указанных координатах. Если чанк на указанных координатах не загружен, возвращает -1. - -```python -block.get_states(x: int, y: int, z: int) -> int -``` - -Возвращает состояние (поворот + доп. информация) в виде целого числа - -```python -block.set(x: int, y: int, z: int, id: int, states: int) -``` - -Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах. -> [!WARNING] -> `block.set` не вызывает событие on_placed. - -```python -block.is_solid_at(x: int, y: int, z: int) -> bool -``` - -Проверяет, является ли блок на указанных координатах полным - -```python -block.is_replaceable_at(x: int, y: int, z: int) -> bool -``` -Проверяет, можно ли на заданных координатах поставить блок (примеры: воздух, трава, цветы, вода) - -```python -block.defs_count() -> int -``` - -Возвращает количество id доступных в движке блоков - -Следующие три функции используется для учёта вращения блока при обращении к соседним блокам или других целей, где направление блока имеет решающее значение. - - -```python -block.get_X(x: int, y: int, z: int) -> int, int, int -``` - -Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа). -Если поворот отсутствует, возвращает 1, 0, 0 - -```python -block.get_Y(x: int, y: int, z: int) -> int, int, int -``` - -Возвращает целочисленный единичный вектор Y блока на указанных координатах с учётом его вращения (три целых числа). -Если поворот отсутствует, возвращает 0, 1, 0 - -```python -block.get_Z(x: int, y: int, z: int) -> int, int, int -``` - -Возвращает целочисленный единичный вектор Z блока на указанных координатах с учётом его вращения (три целых числа). -Если поворот отсутствует, возвращает 0, 0, 1 - -### Пользовательские биты - -Выделенная под использования в скриптах часть поля `voxel.states` хранящего доп-информацию о вокселе, такую как вращение блока. На данный момент выделенная часть составляет 8 бит. - -```python -block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int -``` - -Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа - -```python -block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int -``` -Записывает указанное число бит значения value в user bits по выбранному смещению - -## Библиотека item - -```python -item.name(itemid: int) -> str -``` - -Возвращает строковый id предмета по его числовому id (как block.name) - -```python -item.index(name: str) -> int -``` - -Возвращает числовой id предмета по строковому id (как block_index) - -```python -item.stack_size(itemid: int) -> int -``` - -Возвращает максимальный размер стопки для предмета. - -```python -item.defs_count() -> int -``` - -Возвращает общее число доступных предметов (включая сгенерированные) - -## Библиотека hud - -```python -hud.open_inventory() -``` - -Возвращает id инвентаря блока (при inventory-size=0 создаётся виртуальный инвентарь, который удаляется после закрытия), и id макета UI. - -Открывает инвентарь - -```python -hud.close_inventory() -``` - -Закрывает инвентарь - -```python -hud.open_block(x: int, y: int, z: int) -> int, str -``` - -> [!NOTE] -> Одновременно может быть открыт только один блок - -Открывает инвентарь и UI блока. Если блок не имеет макета UI - бросается исключение. - -```python -hud.open_permanent(layoutid: str) -``` - -Добавляет постоянный элемент на экран. Элемент не удаляется при закрытии инвентаря. Чтобы не перекрывать затенение в режиме инвентаря нужно установить z-index элемента меньшим чем -1. В случае тега inventory, произойдет привязка слотов к инвентарю игрока. - -```python -hud.close(layoutid: str) -``` - -Удаляет элемент с экрана -## События блоков - -```lua -function on_placed(x, y, z, playerid) -``` - -Вызывается после установки блока игроком - -```lua -function on_broken(x, y, z, playerid) -``` - -Вызывается после разрушения блока игроком - -```lua -function on_interact(x, y, z, playerid) -``` - -Вызывается при нажатии на блок ПКМ. Предотвращает установку блоков, если возвращает `true` - -```lua -function on_update(x, y, z) -``` - -Вызывается при обновлении блока (если изменился соседний блок) - -```lua -function on_random_update(x, y, z) -``` - -Вызывается в случайные моменты времени (рост травы на блоках земли) - -```lua -function on_blocks_tick(tps: int) -``` - -Вызывается tps (20) раз в секунду - -## События предметов - -(v0.20+) -```lua -function on_use(playerid: int) -``` - -Вызывается при нажатии ПКМ не на блок. - -```lua -function on_use_on_block(x: int, y: int, z: int, playerid: int) -``` - -Вызывается при нажатии ПКМ на блок. Предотвращает установку блока, прописанного в `placing-block` если возвращает `true` - -```lua -function on_block_break_by(x: int, y: int, z: int, playerid: int) -``` - -Вызывается при нажатии ЛКМ на блок (в т.ч неразрушимый). Предотвращает разрушение блока, если возвращает `true` - -## События мира - -События мира для контент-пака прописываются в `scripts/world.lua` - -```lua -function on_world_open() -``` - -Вызывается при загрузке мира - -```lua -function on_world_save() -``` - -Вызывается перед сохранением мира - -```lua -function on_world_quit() -``` - -Вызывается при выходе из мира (после сохранения) - -## События макета - -События прописываются в файле `layouts/имя_макета.xml.lua`. - -```lua -function on_open(invid: int, x: int, y: int, z: int) -``` - -Вызывается при добавлении элемента на экран. -При отсутствии привязки к инвентарю invid будет равен 0. -При отсутствии привязки к блоку x, y, z так же будут равны 0. - -```lua -function on_close(invid: int) -``` - -Вызывается при удалении элемента с экрана. - -## События HUD - -События связанные с игровым интерфейсом прописываются в файле `scripts/hud.lua` - -```lua -function on_hud_open(playerid: int) -``` - -Вызывается после входа в мир, когда становится доступна библиотека hud. Здесь на экран добавляются постоянные элементы. - -```lua -function on_hud_close(playerid: int) -``` - -Вызывается при выходе из мира, перед его сохранением. - -## Библиотеки движка - -### file - -Библиотека функций для работы с файлами - -```python -file.resolve(путь: str) -> str -``` - -Функция приводит запись `точка_входа:путь` (например `user:worlds/house1`) к обычному пути. (например `C://Users/user/.voxeng/worlds/house1`) -> [!NOTE] -> Функцию не нужно использовать в сочетании с другими функциями из библиотеки, так как они делают это автоматически - -Возвращаемый путь не является каноническим и может быть как абсолютным, так и относительным. - -```python -file.read(путь: str) -> str -``` - -Читает весь текстовый файл и возвращает в виде строки - -```python -file.write(путь: str, текст: str) -> nil -``` - -Записывает текст в файл (с перезаписью) - -```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 если была создана новая директория - -### time - -```python -time.uptime() -> float -``` - -Возвращает время с момента запуска движка в секундах - -## Доступные модули - -### TOML сериализация/десериализация -```lua -local toml = require "core:toml" - -local t = {a=53, b=42, s="test", sub={x=1, y=6}} -local s = toml.serialize(t) -print(s) -local t2 = toml.deserialize(s) -``` -вывод: -```toml -b = 42 -s = "test" -a = 53 -[sub] -y = 6 -x = 1 -``` \ No newline at end of file