voxelcore/doc/ru/scripting.md

Скриптинг

В качестве языка сценариев используется LuaJIT

Подразделы:

• События движка
• Пользовательский ввод
• Файловая система и сериализация
• Свойства и методы UI элементов
• Сущности и компоненты
• Библиотеки
  • animation
  • app
  • assets
  • base64
  • bjson, json, toml, yaml
  • block
  • byteutil
  • cameras
  • ctypes
  • entities
  • file
  • gfx.blockwraps
  • gfx.particles
  • gfx.posteffects
  • gfx.skeletons
  • gfx.text3d
  • gfx.weather
  • gui
  • hud
  • input
  • inventory
  • item
  • mat4
  • network
  • pack
  • pathfinding
  • player
  • quat
  • random
  • rules
  • session
  • time
  • utf8
  • vec2, vec3, vec4
  • world
• Расширения стандартных библиотек
• Модуль core:bit_converter
• Модуль core:data_buffer
• Модули core:vector2, core:vector3
• Встроенные компоненты сущностей

Аннотации типов данных

В документации к Lua библиотекам используются аннотации типов, не являющиеся частью синтаксиса Lua.

• vector - массив из трех или четырех чисел
• vec2 - массив из двух чисел
• vec3 - массив из трех чисел
• vec4 - массив из четырех чисел
• quat - массив из четырех чисел - кватернион
• matrix - массив из 16 чисел - матрица

Пространства имён

В настоящее время, движок использует иерархию пространств имён, минимизирующую конфликты между отдельными модулями, скриптами, да и паками.

Актуальна следующая структура:

• Глобальное пространство (оно же - _G), являющееся корневым, запись в которое, вне модулей ядра движка, является крайне нежелательным для вашего же времени, что может уйти на лишние часы отладки.
  • Пространство пака - создаётся каждый раз при загрузке контента для каждого, включённого в конфигурацию, пака. Это пространство используют модули, а также скрипты предметов и блоков.
    • Пространство компонента.
    • Пространство UI-документа
• Изолированное пространство имён генератора мира.

Модули

Модуль - глобальный объект со сроком жизни, ограниченным сроком жизни контента, используемый как для взаимодействия разных паков, так и для вместо глобальных переменных в пределах самого пака.

Модуль должен находиться в контентпак/modules/** (допускаются вложенные папки, что нужно будет указывать)

local имя_модуля = require "контентпак:имя_модуля" -- импортирует модуль

-- если модуль находится в том же паке, в котором импортируется, можно использовать сокращённый вариант:
local имя_модуля = require "имя_модуля"

-- при использовании вложенных папок:
local имя_модуля = require "контентпак:путь/к/имя_модуля" -- путь не включает `modules`
local имя_модуля = require "путь/к/имя_модуля" -- если в том же паке

Модуль будет иметь пространство имён того пака, в котором находится, независимо от пространства имён, из которого был выполнен первый импорт.

При создании модуля следует придерживаться следующего подхода, которого и ожидает require:

local this = {
    имя_переменной = ... -- публичные переменные
}

-- приватные переменные модуля
local имя_переменной = ...

-- приватные функции модуля
local function имя_функции(...)
    ...
end

-- публичные функции модуля
function this.имя_функции(...)
    ...
end

return this -- результат, который и будет возвращать и кешировать require

При повторном импорте модуль не будет перезагружен - вместо этого require вернёт кешированный результат.