12 KiB
Проекты
Проект описывает приложение, которое запускает движок: его имя и заголовок окна, контент-паки, на которых оно построено, выданные ему разрешения и управляющие им скрипты.
Контент-паки добавляют контент (блоки, предметы, генераторы, скрипты, ассеты и т.д.). Проект управляет приложением на верхнем уровне: что загружается по умолчанию, как выглядит главное меню, какие возможности движка доступны.
Расположение проекта
Папка проекта выбирается при запуске:
- Путь, переданный через
--project <путь>, если указан. - Иначе
project/в папке пользовательских файлов (user:project), если существует. - Иначе
project/в папке ресурсов (res/project/) - проект по умолчанию, поставляемый с движком. - Иначе сама папка ресурсов.
Т.е. пользователь может заменить проект по умолчанию без аргументов командной строки, создав папку project/ в папке пользовательских файлов (та, что задаётся через --dir).
VoxelCore --project путь/к/имя_проекта
Выбранная папка монтируется как точка входа project и доступна скриптам только для чтения:
print(file.read("project:project.toml"))
Структура проекта
имя_проекта/project.toml- описание проектаstart.lua- сценарий приложения (опционально)project_client.lua- клиентский скрипт (опционально)content/- контент-паки проекта (опционально)
Конфигурация проекта - project.toml
name = "имя_проекта"
title = "Имя проекта"
base_packs = ["base"]
permissions = [
"network",
"record-audio",
]
| Поле | Тип | Описание |
|---|---|---|
name |
строка | Идентификатор проекта. Используется в логах. |
title |
строка | Отображается в заголовке окна как <title> - VoxelCore v<версия>. Опционально. |
base_packs |
список[строк] | Паки, которые загружаются всегда и не могут быть убраны в меню контента. |
permissions |
список[строк] | Возможности движка, доступные проекту. См. Разрешения. |
Базовые паки загружаются вместе с контентом ядра при каждом сбросе контента (например, в главном меню), поэтому их ресурсы (текстуры, разметки, скрипты) доступны и вне миров.
Проект по умолчанию (res/project/project.toml):
name = "default"
base_packs = ["base"]
permissions = [
"network",
"record-audio",
"sub-instances",
]
Разрешения
Возможности, не указанные в permissions, для проекта отключены.
| Разрешение | Даёт доступ к |
|---|---|
network |
Сетевой подсистеме и библиотеке network. Без него функции библиотеки выбрасывают ошибку. |
record-audio |
Устройствам ввода звука (микрофону). |
write-to-user |
Записи в точку входа user через библиотеку file. По умолчанию доступны для записи только world, config и export. |
sub-instances |
app.start_background_instance - запуску фоновых (headless) экземпляров движка. |
debugging |
app.start_debug_instance - запуску экземпляров движка с отладочным сервером. |
Note
Аргумент командной строки
--dbg-serverработает и при отсутствии разрешенияnetwork.
start.lua
start.lua - управляющий сценарий проекта. Он запускается после инициализации движка как корутина,
выполняемая параллельно с основным циклом, и имеет доступ к библиотеке app.
-- дождаться готовности главного меню
app.tick()
app.config_packs({"base", "my_pack"})
app.load_content()
app.new_world("demo", "42", "core:default")
Правила:
- Сценарий выполняется в собственной корутине.
app.tick(),app.sleep(...)иapp.sleep_until(...)передают управление движку на один или несколько кадров. - Функции перезагрузки контента (
app.load_content,app.reset_content,app.reconfig_packs,app.config_packs) должны вызываться из этой корутины. - Сценарий имеет собственное глобальное окружение: доступны все глобальные функции и таблицы, а также библиотека
app. - Если движок запущен с
--script <файл>или--test <файл>, этот сценарий заменяетstart.lua: одновременно выполняется только один сценарий приложения. - В headless-режиме (
--headless) выполняется только сценарий, переданный через--script/--test. Без него движку нечего делать, и он сразу завершается. - В режиме теста (
--test) движок останавливается по завершении сценария. В остальных случаях движок продолжает работу после завершенияstart.lua.
project_client.lua
project_client.lua загружается один раз при запуске и только в клиентском режиме (с --headless не загружается).
Он управляет клиентским представлением проекта - прежде всего экранами.
Скрипт имеет собственное окружение с доступом к глобальным функциям, библиотекам и app. Движок вызывает следующие функции, если они определены:
-- Вызывается после открытия экрана.
function on_<экран>_setup() end
-- Вызывается перед закрытием экрана (при переключении на другой).
function on_<экран>_clear() end
Имена экранов:
| Экран | Описание |
|---|---|
menu |
Экран главного меню. |
level |
Экран в мире (открыт мир). |
При переключении экранов сначала вызывается on_<старый>_clear, затем открывается новый экран, затем вызывается on_<новый>_setup. Ошибки в этих функциях записываются в лог и не останавливают движок.
Движок сбрасывает меню при открытии экрана меню; открытие страницы - задача проекта. Клиентский скрипт проекта по умолчанию устанавливает фон меню и открывает страницу main (упрощённо):
function on_menu_setup()
setup_background()
menu.page = "main"
menu.visible = true
end
function on_menu_clear()
if menubg then
menubg:destruct()
menubg = nil
end
end
Note
Стандартное меню
menuможет не использоваться в проекте.
Страницы ищутся как layouts/pages/<имя>.xml в ядре и загруженных паках, поэтому проект может поставлять собственную страницу главного меню в одном из базовых паков:
-- открывает layouts/pages/title.xml из базового пака
function on_menu_setup()
menu.page = "title"
menu.visible = true
end
project:content
Папка content/ проекта является источником контента. Паки, размещённые в ней, доступны проекту так же, как паки в res/content/:
my_project/content/имя_пака/package.json
Источники контента в порядке убывания приоритета:
world:contentuser:contentproject:contentres:content
Аргументы проекта
Аргументы после отдельного -- передаются проекту, а не движку:
VoxelCore --project my_project -- --mode server --port 6000 --verbose
Каждый аргумент должен иметь вид --имя, за ним может следовать значение. Аргумент без значения получает пустую строку.
Аргументы проекта доступны всем скриптам:
vc.get_project_arg(name: str) -> str | nil
local port = tonumber(vc.get_project_arg("port") or "6000")
local verbose = vc.get_project_arg("verbose") ~= nil
Дочерние экземпляры
Экземпляры движка, запускаемые из скриптов, тоже используют проекты:
app.start_background_instance(script, output_file, project_args)запускает headless-экземпляр с текущим проектом и передаётproject_argsкак аргументы проекта. Требует разрешенияsub-instances.app.start_debug_instance(port, project_path, output_file)запускает экземпляр с отладочным сервером. Если указанproject_path, экземпляр запускает этот проект, иначе проект выбирается обычным образом. Требует разрешенияdebugging.
Дочерние экземпляры используют те же папки ресурсов и пользовательских файлов, что и родительский. Глубина вложенности ограничена двумя уровнями.
См. библиотеку app.