mirror of
https://github.com/MihailRis/voxelcore.git
synced 2026-11-20 17:39:46 +00:00
210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# Проекты
|
||
|
||
Проект описывает приложение, которое запускает движок: его имя и заголовок окна, контент-паки, на которых оно построено, выданные ему разрешения и управляющие им скрипты.
|
||
|
||
Контент-паки добавляют контент (блоки, предметы, генераторы, скрипты, ассеты и т.д.).
|
||
Проект управляет приложением на верхнем уровне: что загружается по умолчанию, как выглядит главное меню, какие возможности движка доступны.
|
||
|
||
## Расположение проекта
|
||
|
||
Папка проекта выбирается при запуске:
|
||
|
||
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` | строка | Отображается в заголовке окна как `<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).
|