Merge branch 'main' into dev

This commit is contained in:
MihailRis 2026-10-20 20:32:20 +03:00
commit 3f73f81866
5 changed files with 431 additions and 2 deletions

View file

@ -16,11 +16,12 @@
- [Entity properties](entity-properties.md)
- [Item properties](item-properties.md)
- [Particles](particles.md)
- [Projects](projects.md)
- [Resources (resources.json)](resources.md)
- [Rigging](rigging.md)
- [Scripting](scripting.md)
- [Text styles](text-styles.md)
- [VCM models format](vcm.md)
- [VCM animation format](vca.md)
- [VCM models format](vcm.md)
- [World generator engine](world-generator.md)
- [XML UI building](xml-ui-layouts.md)

210
doc/en/projects.md Normal file
View file

@ -0,0 +1,210 @@
# Projects
A project describes the application the engine runs: its name and window title, the content packs it is built on, the permissions granted to it, and the scripts that drive it.
Content packs add content (blocks, items, generators, scripts, assets, etc.).
A project controls the application at the top level: what is loaded by default, what the main menu looks like, which engine capabilities are available.
## Project location
The project folder is selected at startup:
1. The path passed via `--project <path>`, if specified.
2. Otherwise `project/` in the user files folder (`user:project`), if it exists.
3. Otherwise `project/` in the resources folder (`res/project/`) - the default project shipped with the engine.
4. Otherwise the resources folder itself.
That is, a user can replace the default project without command line arguments by creating a `project/` folder in the user files folder (the one set via `--dir`).
```sh
VoxelCore --project path/to/project_name
```
The selected folder is mounted as the `project` entry point and is read-only for scripts:
```lua
print(file.read("project:project.toml"))
```
## Project structure
- `project_name/`
- `project.toml` - project description
- `start.lua` - application script (optional)
- `project_client.lua` - client script (optional)
- `content/` - project content packs (optional)
## Project configuration - project.toml
```toml
name = "project_name"
title = "Project Name"
base_packs = ["base"]
permissions = [
"network",
"record-audio",
]
```
| Field | Type | Description |
| ------------- | --------------- | ------------------------------------------------------------------------------ |
| `name` | string | Project identifier. Used in logs. |
| `title` | string | Shown in the window title as `<title> - VoxelCore v<version>`. Optional. |
| `base_packs` | list\[string\] | Packs that are always loaded and cannot be removed in the content menu. |
| `permissions` | list\[string\] | Engine capabilities available to the project. See [Permissions](#permissions). |
Base packs are loaded together with the core content on every content reset (e.g., in the main menu), so their resources (textures, layouts, scripts) are available outside of worlds as well.
The default project (`res/project/project.toml`):
```toml
name = "default"
base_packs = ["base"]
permissions = [
"network",
"record-audio",
"sub-instances",
]
```
### Permissions
Capabilities not listed in `permissions` are disabled for the project.
| Permission | Grants access to |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network` | The network subsystem and the [network](scripting/builtins/libnetwork.md) library. Without it, the library functions throw an error. |
| `record-audio` | Audio input devices (microphone). |
| `write-to-user` | Writing to the `user` entry point via the [file](scripting/builtins/libfile.md) library. By default only `world`, `config` and `export` are writable. |
| `sub-instances` | `app.start_background_instance` - starting background (headless) engine instances. |
| `debugging` | `app.start_debug_instance` - starting engine instances with a debug server. |
> [!NOTE]
> The `--dbg-server` command line argument works even without the `network` permission.
## start.lua
`start.lua` is the **project's controlling script**. It is started after engine initialization as a coroutine
running in parallel with the main loop, and has access to the [app](scripting/builtins/libapp.md) library.
```lua
-- wait for the main menu to be ready
app.tick()
app.config_packs({"base", "my_pack"})
app.load_content()
app.new_world("demo", "42", "core:default")
```
Rules:
- The script runs in its own coroutine. `app.tick()`, `app.sleep(...)` and `app.sleep_until(...)` yield control to the engine for one or more frames.
- Content reload functions (`app.load_content`, `app.reset_content`, `app.reconfig_packs`, `app.config_packs`) must be called from this coroutine.
- The script has its own global environment: all global functions and tables are available, as well as the `app` library.
- If the engine is started with `--script <file>` or `--test <file>`, that script replaces `start.lua`: only one application script runs at a time.
- In headless mode (`--headless`) only the script passed via `--script`/`--test` runs. Without it the engine has nothing to do and exits immediately.
- In test mode (`--test`) the engine stops when the script finishes. Otherwise the engine keeps running after `start.lua` finishes.
## project_client.lua
`project_client.lua` is loaded once at startup and only in client mode (it is not loaded with `--headless`).
It controls the client-side presentation of the project - primarily screens.
The script has its own environment with access to global functions, libraries and `app`. The engine calls the following functions if they are defined:
```lua
-- Called after the screen is opened.
function on_<screen>_setup() end
-- Called before the screen is closed (when switching to another one).
function on_<screen>_clear() end
```
Screen names:
| Screen | Description |
| ------- | ----------------------------- |
| `menu` | Main menu screen. |
| `level` | In-world screen (world open). |
When switching screens, `on_<old>_clear` is called first, then the new screen is opened, then `on_<new>_setup` is called. Errors in these functions are logged and do not stop the engine.
The engine resets the menu when the menu screen is opened; opening a page is the project's job. The default project's client script sets the menu background and opens the `main` page (simplified):
```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]
> A project does not have to use the standard `menu`.
Pages are looked up as `layouts/pages/<name>.xml` in the core and loaded packs, so a project can ship its own main menu page in one of its base packs:
```lua
-- opens layouts/pages/title.xml from a base pack
function on_menu_setup()
menu.page = "title"
menu.visible = true
end
```
## project:content
The project's `content/` folder is a [content source](content-packs.md#content-sources). Packs placed in it are available to the project the same way as packs in `res/content/`:
- `my_project/`
- `content/`
- `pack_name/`
- `package.json`
Content sources in descending order of priority:
- `world:content`
- `user:content`
- `project:content`
- `res:content`
## Project arguments
Arguments after a standalone `--` are passed to the project rather than the engine:
```sh
VoxelCore --project my_project -- --mode server --port 6000 --verbose
```
Each argument must have the form `--name`, optionally followed by a value. An argument without a value gets an empty string.
Project arguments are available to all scripts:
```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
```
## Child instances
Engine instances started from scripts use projects too:
- `app.start_background_instance(script, output_file, project_args)` starts a headless instance with the **current project** and passes `project_args` as project arguments. Requires the `sub-instances` permission.
- `app.start_debug_instance(port, project_path, output_file)` starts an instance with a debug server. If `project_path` is specified, the instance runs that project; otherwise the project is selected the usual way. Requires the `debugging` permission.
Child instances use the same resources and user files folders as the parent. Nesting depth is limited to two levels.
See the [app library](scripting/builtins/libapp.md).

View file

@ -14,6 +14,7 @@
- [Контент‐паки](content-packs.md)
- [Модели блоков](block-models.md)
- [Предзагрузка ассетов](assets-preload.md)
- [Проекты](projects.md)
- [Рекомендации по использованию движка](engine-use-recommendations.md)
- [Ресурсы (resources.json)](resources.md)
- [Риггинг](rigging.md)

210
doc/ru/projects.md Normal file
View file

@ -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` | строка | Отображается в заголовке окна как `<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).

View file

@ -16,5 +16,12 @@
"curl",
"freetype",
"openssl"
],
"builtin-baseline": "802d61d714db2714e3fefcfc59447431166b8367",
"overrides": [
{
"name": "entt",
"version": "3.16.0"
}
]
}
}