update doc/*/content-packs.md

2025-11-09 21:24:21 +03:00 · 2025-11-09 21:24:21 +03:00 · 65bba0088b
commit 65bba0088b
parent 60ed10c0a1
2 changed files with 151 additions and 3 deletions
--- 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.
--- 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`.
+
+Версия пака, при этом, на данный момент, не учитывается.