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

210 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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