From 50af44c9de57b3f1c9489eaa78c08ad15c7dcb53 Mon Sep 17 00:00:00 2001 From: MihailRis Date: Sun, 9 Nov 2025 21:24:21 +0300 Subject: [PATCH 1/3] update doc/*/content-packs.md --- doc/en/content-packs.md | 75 +++++++++++++++++++++++++++++++++++++- doc/ru/content-packs.md | 79 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 151 insertions(+), 3 deletions(-) diff --git a/doc/en/content-packs.md b/doc/en/content-packs.md index a41f95f9..c193fb18 100644 --- a/doc/en/content-packs.md +++ b/doc/en/content-packs.md @@ -48,6 +48,79 @@ Example: Content pack picture should be added as *icon.png* file. Recommended size: 128x128 -See *res/content/base* as an example of content pack structure. +# File System +Every loaded pack is mounted to the internal file system as a new mount point, whose name matches the pack's id. +This means that accessing pack files does not require the use of additional functions: + +```lua +print(file.read("your_pack_id:package.json")) -- will output the contents of the pack's package.json +``` + +This is also one of the reasons why some ids are reserved and cannot be used. + +Mount points are mounted as read-only. To gain write access, use the `pack.request_writeable` function. + +Read more about the [file](scripting/builtins/libfile.md) library. + +# Content Pack Structure + +Don't be intimidated by the following text, as a minimal pack only requires `package.json`. + +- Content: + - `block_materials/` - Block material definitions + - `blocks/` - Block definitions + - `items/` - Item definitions + - `generators/` - World generators + - `entities/` - Entity definitions + - `skeletons/` - Entity skeleton definitions + - `presets/` - Presets (can also be used by packs for their own purposes) + - `text3d/` - 3D Text + - `weather/` - Weather +- Code: + - `modules/` - Script modules + - `scripts/` - Content scripts, world scripts + - `components/` - Entity components +- Assets (Client-side resources): + - `fonts/` - Fonts + - `models/` - 3D Models + - `textures/` - Textures + - `shaders/` - Shaders + - `effects/` - Post-processing effects + - `sounds/` - Sounds and Music + - `texts/` - Localization files +- GUI: + - `layouts/` - UI Layouts + - `pages/` - Menu page layouts (for the pagebox element) +- Configuration: + - `config/` - Configuration files + - `defaults.toml` - Overrides for standard content bindings, such as the player entity, default generator, etc. + - `bindings.toml` - Keyboard/Mouse bindings + - `user-props.toml` - User properties for content definitions + - `devtools/` - Auxiliary files for internal debugging tools + - `content.json` - Automatically generated content lists, used for validating world indices and for conversion when mismatched + - `icon.png` - Pack icon + - `package.json` - Pack definition file + - `preload.json` - Asset preload lists for assets that are not loaded automatically; avoid listing assets unnecessarily + - `resources.json` - Definition lists for [resources](resources.md) (not to be confused with assets) + - `resource-aliases.json` - Files declaring aliases for [resources](resources.md) + +> [!WARNING] +> Manually editing `content.json` is strongly discouraged and will most likely lead to irreversible world corruption. + +# Content Sources + +Content packs are searched for within **content sources**, which are paths in the engine's file system. + +Source priority determines the scan order: if the same pack is found in multiple sources, the one belonging to the source with the highest priority will be selected. + +Content sources in descending order of priority: +- `world:content` - Content in the world folder (`world/content/`) +- `user:content` - Content in the user folder (`$HOME/.voxeng/content/`) +- `project:content` - Content in the project folder (`project/content/`) +- `res:content` - Built-in content shipped with the engine core (`res/content/`) + +I.e., if the same pack exists in both `world:content` and `user:content`, the version from `world:content` will be selected. + +The pack version, however, is currently not taken into account. diff --git a/doc/ru/content-packs.md b/doc/ru/content-packs.md index 4245555f..32f9be59 100644 --- a/doc/ru/content-packs.md +++ b/doc/ru/content-packs.md @@ -50,5 +50,80 @@ Изображение контент-пака добавляется в виде файла *icon.png* в папку пака (не в textures). Рекомендованный размер изображения: 128x128 -Новые блоки добавляются в под-папку **blocks**, предметы в **items**, текстуры в **textures** -С примером файловой структуры лучше ознакомиться через базовый пакет (*res/content/base*) +# Файловая система + +Каждый загруженный пак монтируется к внутренней файловой системе как новая точка входа, имя которой совпадает с id пака. + +Это значит, что для доступа к файлам пака не требуется использование дополнительных функций: + +```lua +print(file.read("пак:package.json")) -- выведет содержимое package.json пака +``` + +Также это является одной из причин того, что некоторые id зарезервированы от использования. + +Точки входа монтируются как read-only. Для получения доступа к записи существует функция pack.request_writeable. + +Подробнее про библиотеку [file](scripting/builtins/libfile.md). + +# Структура контент-пака + +Пусть вас не пугает следующий текст, ведь минимальный пак содержит только package.json. + +- Контент: + - `block_materials/` - определения материалов блоков + - `blocks/` - определения блоков + - `items/` - определения предметов + - `generators/` - генераторы мира + - `entities/` - определения сущностей + - `skeletons/` - определения скелетов сущностей + - `presets/` - пресеты (может использоваться и паками в своих целях) + - `text3d/` - 3D текст + - `weather/` - погода +- Код: + - `modules/` - скриптовые модули + - `scripts/` - скрипты контента, мира + - `components/` - компоненты сущностей +- Ассеты (ресурсы клиентской стороны): + - `fonts/` - шрифты + - `models/` - 3D модели + - `textures/` - текстуры + - `shaders/` - шейдеры + - `effects/` - эффекты пост-обработки + - `sounds/` - звуки и музыка + - `texts/` - файлы локализации +- GUI: + - `layouts/` - макеты UI + - `pages/` - макеты страниц меню (элемент pagebox) +- Конфигурация: + - `config/` - файлы конфигурации + - `defaults.toml` - переопределения стандартных привязок к контенту, такие как сущность игрока, генератор по-умолчанию и т.д. + - `bindings.toml` - привязки к клавишам / мыши + - `user-props.toml` - пользовательские свойства определений контента + - `devtools/` - вспомогательные файлы внутренних инструментов отладки + - `content.json` - генерируемые автоматически списки контента, используемое для проверки корректности индексов в мире и конвертации при несовпадении + - `icon.png` - иконка пака + - `package.json` - файл опеределения пака + - `preload.json` - списки предзагрузки ассетов, которые не загружаются автоматически, не следует указывать ассеты без надобности + - `resources.json` - списки определений [ресурсов](resources.md) (не путать с ассетами) + - `resource-aliases.json` - файлы объявления псевдонимов для [ресурсов](resources.md) + +> [!WARNING] +> Ручное редактирование `content.json` противопоказано и скорее всего приведёт к необратимой поломке миров. + +# Источники контента + +Поиск контент-паков производится среди **источников контента**, являющихся путями в файловой системе движка. + +Приоритет источника определяет порядок сканирования: если один и тот же пак найден в нескольких источниках, +будет выбран тот, что принадлежит источнику с наивысшим приоритетом. + +Источники контента в порядке убывания приоритета: +- `world:content` - контент папке с миром (`мир/content/`) +- `user:content` - контент в папке пользователя (`$HOME/.voxeng/content/`) +- `project:content` - контент в папке с проектом (`проект/content/`) +- `res:content` - встроенный контент, поставляемый вместе с ядром движка (`res/content/`) + +Т.е. если в `world:content` и в `user:content` есть один и тот же пак, будет выбрана версия из `world:content`. + +Версия пака, при этом, на данный момент, не учитывается. From 72a71758463d2347e62583b841f1a451a3f68f6c Mon Sep 17 00:00:00 2001 From: MihailRis Date: Wed, 12 Nov 2025 20:09:31 +0300 Subject: [PATCH 2/3] update doc/*/main-page.md --- doc/en/main-page.md | 5 +++-- doc/ru/main-page.md | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/en/main-page.md b/doc/en/main-page.md index 5eb767f9..30cb106c 100644 --- a/doc/en/main-page.md +++ b/doc/en/main-page.md @@ -1,8 +1,9 @@ # Documentation -Documentation for 0.30 (in development). +Documentation for 0.30. -[Documentation for 0.29.](https://github.com/MihailRis/voxelcore/blob/release-0.29/doc/ru/main-page.md) +> [!WARNING] +> Version is in development. Proceed to [Documentation for 0.29.](https://github.com/MihailRis/voxelcore/blob/release-0.29/doc/ru/main-page.md) ## Sections diff --git a/doc/ru/main-page.md b/doc/ru/main-page.md index 60d0794d..e74c2915 100644 --- a/doc/ru/main-page.md +++ b/doc/ru/main-page.md @@ -1,8 +1,9 @@ # Документация -Документация версии 0.30 (в разработке). +Документация версии 0.30. -[Документация 0.29.](https://github.com/MihailRis/voxelcore/blob/release-0.29/doc/ru/main-page.md) +> [!WARNING] +> Версия находится в разработке. Перейдите к [документации для 0.28](https://github.com/MihailRis/voxelcore/blob/release-0.29/doc/ru/main-page.md) ## Разделы From dec1ea7b155a749a0ebc4b5d5fc25f52aef635bd Mon Sep 17 00:00:00 2001 From: MihailRis Date: Wed, 12 Nov 2025 20:11:51 +0300 Subject: [PATCH 3/3] fix documentation links in README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 30925fef..8503dd65 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ ## Latest release - [Download](https://github.com/MihailRis/VoxelCore/releases/latest) | [Скачать](https://github.com/MihailRis/VoxelCore/releases/latest) -- [Documentation](https://github.com/MihailRis/VoxelCore/blob/release-0.28/doc/en/main-page.md) | [Документация](https://github.com/MihailRis/VoxelCore/blob/release-0.28/doc/ru/main-page.md) +- [Documentation](https://github.com/MihailRis/VoxelCore/blob/release-0.29/doc/en/main-page.md) | [Документация](https://github.com/MihailRis/VoxelCore/blob/release-0.29/doc/ru/main-page.md) ---