# Проекты Проект описывает приложение, которое запускает движок: его имя и заголовок окна, контент-паки, на которых оно построено, выданные ему разрешения и управляющие им скрипты. Контент-паки добавляют контент (блоки, предметы, генераторы, скрипты, ассеты и т.д.). Проект управляет приложением на верхнем уровне: что загружается по умолчанию, как выглядит главное меню, какие возможности движка доступны. ## Расположение проекта Папка проекта выбирается при запуске: 1. Путь, переданный через `--project <путь>`, если указан. 2. Иначе `project/` в папке пользовательских файлов (`user:project`), если существует. 3. Иначе `project/` в папке ресурсов (`res/project/`) - проект по умолчанию, поставляемый с движком. 4. Иначе сама папка ресурсов. Т.е. пользователь может заменить проект по умолчанию без аргументов командной строки, создав папку `project/` в папке пользовательских файлов (та, что задаётся через `--dir`). ```sh VoxelCore --project путь/к/имя_проекта ``` Выбранная папка монтируется как точка входа `project` и доступна скриптам только для чтения: ```lua print(file.read("project:project.toml")) ``` ## Структура проекта - `имя_проекта/` - `project.toml` - описание проекта - `start.lua` - сценарий приложения (опционально) - `project_client.lua` - клиентский скрипт (опционально) - `content/` - контент-паки проекта (опционально) ## Конфигурация проекта - project.toml ```toml name = "имя_проекта" title = "Имя проекта" base_packs = ["base"] permissions = [ "network", "record-audio", ] ``` | Поле | Тип | Описание | | ------------- | --------------- | --------------------------------------------------------------------------------- | | `name` | строка | Идентификатор проекта. Используется в логах. | | `title` | строка | Отображается в заголовке окна как ` - VoxelCore v<версия>`. Опционально. | | `base_packs` | список\[строк\] | Паки, которые загружаются всегда и не могут быть убраны в меню контента. | | `permissions` | список\[строк\] | Возможности движка, доступные проекту. См. [Разрешения](#разрешения). | Базовые паки загружаются вместе с контентом ядра при каждом сбросе контента (например, в главном меню), поэтому их ресурсы (текстуры, разметки, скрипты) доступны и вне миров. Проект по умолчанию (`res/project/project.toml`): ```toml name = "default" base_packs = ["base"] permissions = [ "network", "record-audio", "sub-instances", ] ``` ### Разрешения Возможности, не указанные в `permissions`, для проекта отключены. | Разрешение | Даёт доступ к | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `network` | Сетевой подсистеме и библиотеке [network](scripting/builtins/libnetwork.md). Без него функции библиотеки выбрасывают ошибку. | | `record-audio` | Устройствам ввода звука (микрофону). | | `write-to-user` | Записи в точку входа `user` через библиотеку [file](scripting/builtins/libfile.md). По умолчанию доступны для записи только `world`, `config` и `export`. | | `sub-instances` | `app.start_background_instance` - запуску фоновых (headless) экземпляров движка. | | `debugging` | `app.start_debug_instance` - запуску экземпляров движка с отладочным сервером. | > [!NOTE] > Аргумент командной строки `--dbg-server` работает и при отсутствии разрешения `network`. ## start.lua `start.lua` - **управляющий сценарий проекта**. Он запускается после инициализации движка как корутина, выполняемая параллельно с основным циклом, и имеет доступ к библиотеке [app](scripting/builtins/libapp.md). ```lua -- дождаться готовности главного меню 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`. Движок вызывает следующие функции, если они определены: ```lua -- Вызывается после открытия экрана. function on_<экран>_setup() end -- Вызывается перед закрытием экрана (при переключении на другой). function on_<экран>_clear() end ``` Имена экранов: | Экран | Описание | | ------- | -------------------------- | | `menu` | Экран главного меню. | | `level` | Экран в мире (открыт мир). | При переключении экранов сначала вызывается `on_<старый>_clear`, затем открывается новый экран, затем вызывается `on_<новый>_setup`. Ошибки в этих функциях записываются в лог и не останавливают движок. Движок сбрасывает меню при открытии экрана меню; открытие страницы - задача проекта. Клиентский скрипт проекта по умолчанию устанавливает фон меню и открывает страницу `main` (упрощённо): ```lua 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` в ядре и загруженных паках, поэтому проект может поставлять собственную страницу главного меню в одном из базовых паков: ```lua -- открывает layouts/pages/title.xml из базового пака function on_menu_setup() menu.page = "title" menu.visible = true end ``` ## project:content Папка `content/` проекта является [источником контента](content-packs.md#источники-контента). Паки, размещённые в ней, доступны проекту так же, как паки в `res/content/`: - `my_project/` - `content/` - `имя_пака/` - `package.json` Источники контента в порядке убывания приоритета: - `world:content` - `user:content` - `project:content` - `res:content` ## Аргументы проекта Аргументы после отдельного `--` передаются проекту, а не движку: ```sh VoxelCore --project my_project -- --mode server --port 6000 --verbose ``` Каждый аргумент должен иметь вид `--имя`, за ним может следовать значение. Аргумент без значения получает пустую строку. Аргументы проекта доступны всем скриптам: ```lua vc.get_project_arg(name: str) -> str | nil ``` ```lua 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](scripting/builtins/libapp.md).