diff --git a/doc/ru/main-page.md b/doc/ru/main-page.md index b826d9dfd..55cf9cd8e 100644 --- a/doc/ru/main-page.md +++ b/doc/ru/main-page.md @@ -10,6 +10,7 @@ - [Контент‐паки](content-packs.md) - [Модели блоков](block-models.md) - [Предзагрузка ассетов](assets-preload.md) +- [Проекты](projects.md) - [Рекомендации по использованию движка](engine-use-recommendations.md) - [Ресурсы (resources.json)](resources.md) - [Риггинг](rigging.md) diff --git a/doc/ru/projects.md b/doc/ru/projects.md new file mode 100644 index 000000000..2a614ea4d --- /dev/null +++ b/doc/ru/projects.md @@ -0,0 +1,210 @@ +# Проекты + +Проект описывает приложение, которое запускает движок: его имя и заголовок окна, контент-паки, на которых оно построено, выданные ему разрешения и управляющие им скрипты. + +Контент-паки добавляют контент (блоки, предметы, генераторы, скрипты, ассеты и т.д.). +Проект управляет приложением на верхнем уровне: что загружается по умолчанию, как выглядит главное меню, какие возможности движка доступны. + +## Расположение проекта + +Папка проекта выбирается при запуске: + +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).