voxelcore/doc/ru/projects.md
2026-10-18 18:24:15 +03:00

12 KiB
Raw Blame History

Проекты

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

Контент-паки добавляют контент (блоки, предметы, генераторы, скрипты, ассеты и т.д.). Проект управляет приложением на верхнем уровне: что загружается по умолчанию, как выглядит главное меню, какие возможности движка доступны.

Расположение проекта

Папка проекта выбирается при запуске:

  1. Путь, переданный через --project <путь>, если указан.
  2. Иначе project/ в папке пользовательских файлов (user:project), если существует.
  3. Иначе project/ в папке ресурсов (res/project/) - проект по умолчанию, поставляемый с движком.
  4. Иначе сама папка ресурсов.

Т.е. пользователь может заменить проект по умолчанию без аргументов командной строки, создав папку 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:content
  • user:content
  • project:content
  • res: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.