# Проекты
Проект описывает приложение, которое запускает движок: его имя и заголовок окна, контент-паки, на которых оно построено, выданные ему разрешения и управляющие им скрипты.
Контент-паки добавляют контент (блоки, предметы, генераторы, скрипты, ассеты и т.д.).
Проект управляет приложением на верхнем уровне: что загружается по умолчанию, как выглядит главное меню, какие возможности движка доступны.
## Расположение проекта
Папка проекта выбирается при запуске:
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).