update doc/*/content-packs.md

2025-11-09 21:31:36 +03:00
parent 652f652e55
commit 50af44c9de
2 changed files with 151 additions and 3 deletions
@@ -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.