voxelcore/doc/en/assets-preload.md
2026-10-26 12:38:30 +03:00

2.1 KiB

Assets preloading (preload.json file)

preload.json in content-pack folder is used for specifying additional assets that should be loaded, like sounds.

The file contains following categories available:

  • animation
  • fonts
  • models
  • shaders
  • skeletons
  • sounds
  • textures

Note

Sound loading with all variations following template: (sound: sound_name) -> sound_name.ogg, sound_name_1.ogg, sound_name_2.ogg, ... or sound_name_0.ogg, sound_name_1.ogg, sound_name_2.ogg, ...

Adding sound packid:sounds/events/explosion.ogg with all variants example:

{
	"sounds": [
		"events/explosion"
	]
}

Sound will be available as "events/explosion"

Additional load settings example:

{
    "sounds": [
        {
            "name": "events/explosion",
            "keep-pcm": true
        }
    ]
}

Patterns

An asset name may contain * to include multiple assets at once. The * matches any sequence of characters within a single path segment.

Pattern matching is performed within the pack containing preload.json, specifically within the folder corresponding to the asset type (e.g., textures/, sounds/, etc.). The resulting asset names are the same as if each discovered asset had been specified explicitly.

{
    "textures": [
        "gui/*",
        "mobs/*/skin-*"
    ],
    "sounds": [
        "steps/*"
    ]
}

Note

Sound variations (such as grass_0.ogg, grass_1.ogg, etc.) are added as a single sound entry (e.g., steps/grass).

A pattern ending in / matches directories rather than individual files. This is used for atlases:

{
    "atlases": [
        "smth/*/other-*/*/"
    ]
}

Entry parameters apply to all matched assets. The path parameter cannot be used in conjunction with a pattern:

{
    "sounds": [
        {
            "name": "ambient/*",
            "keep-pcm": true
        }
    ]
}

preload.json example from core: package (res/preload.json):

{
    "shaders": [
        "ui3d",
        "screen",
        "background",
        "skybox_gen"
    ],
    "textures": [
        "misc/moon",
        "misc/sun",
        "gui/crosshair"
    ]
}