127 lines
4.7 KiB
Markdown
127 lines
4.7 KiB
Markdown
# Content-packs
|
|
|
|
Every content pack must have an ID following requirements:
|
|
- name can consist of Capital letters A-Z, lowercase letters a-z digits 0-9, and underscore '\_' signs.
|
|
- the first character must not be a digit.
|
|
- name length must be in range \[2, 24\]
|
|
|
|
Content-pack folder having name same as ID may be created in *res/content*.
|
|
Content-pack folder must contain file **package.json** with following contents:
|
|
|
|
```json
|
|
{
|
|
"id": "pack_id",
|
|
"title": "pack name will be displayed in the content menu",
|
|
"version": "content-pack version - major.minor",
|
|
"creator": "content-pack creator",
|
|
"description": "short description",
|
|
"dependencies": [
|
|
"pack",
|
|
"dependencies"
|
|
]
|
|
}
|
|
```
|
|
|
|
Dependency levels are indicated by prefixes in the name:
|
|
- '!' - required dependency
|
|
- '?' - optional dependency
|
|
- '~' - weak dependency
|
|
If prefix is not specified, '!' level will be used.
|
|
|
|
Example: '~randutil' - weak dependency 'randutil'.
|
|
|
|
Dependency version is indicated after '@' symbol and have operators to restrict acceptable versions.
|
|
If version is not specified, '\*' (any) version will be used.
|
|
|
|
Example: 'randutil@>=1.0' - dependency 'randutil' which requires version 1.0 or newer.
|
|
|
|
Example:
|
|
```json
|
|
{
|
|
"id": "doors",
|
|
"title": "DOORS",
|
|
"creator": "MihailRis",
|
|
"version": "1.0",
|
|
"description": "doors test"
|
|
}
|
|
```
|
|
|
|
Content pack picture should be added as *icon.png* file. Recommended size: 128x128
|
|
|
|
# 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.
|