VoxelEngine/doc/en/content-packs.md

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:

{
	"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:

{
    "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:

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 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 (not to be confused with assets)
  • resource-aliases.json - Files declaring aliases for resources

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.