Resource packs

Basalt offers every pack in the resource_packs/ folder to players as they join. The client downloads the packs it does not already have and applies them before the player enters the world.

Add a pack

1. Put the pack in resource_packs/, beside basalt.toml. The folder is created on first start.
2. Run /reload, or restart Basalt.

A pack can be any of:

• a .mcpack file,
• a .zip file,
• an unpacked pack folder.

Each loaded pack is logged at startup:

Loaded resource pack My Textures 1.0.0 from resource_packs/my-textures.mcpack

A file or folder that is not a valid pack is skipped with a warning that names it and says why.

Note

Players already online keep the packs they were sent when they joined. After adding or changing a pack, only players who join afterwards get the new set.

What makes a valid pack

Basalt reads the pack’s manifest.json, which must be at the top level of the pack or one folder down. It needs:

• header.name,
• header.uuid, a UUID in the usual 8-4-4-4-12 form,
• header.version, as [1, 0, 0] or "1.0.0",
• at least one entry in modules. A module of type resources makes it a resource pack; a module of type data or script makes it a behaviour pack.

{
  "format_version": 2,
  "header": {
    "name": "My Textures",
    "description": "Custom textures",
    "uuid": "3c7a4e0e-52d1-4b8f-9d53-6f1c2a8b9e10",
    "version": [1, 0, 0],
    "min_engine_version": [1, 21, 0]
  },
  "modules": [
    { "type": "resources", "uuid": "a81e3d5c-07b2-4f66-8c1a-2d9e4b7f6a35", "version": [1, 0, 0] }
  ]
}

Packs are offered in file name order. If two packs share a UUID, the first one is kept and the other is skipped with a warning.

Require packs

By default a player may decline the packs and still join. To make them mandatory:

texturepack_required = true

A player who refuses is disconnected.

Behaviour packs

Behaviour packs in resource_packs/ are offered to clients as well, because clients need them for some addons. Turn that off with:

send_behaviour_packs = false

Resource packs are always offered.

Note

Putting a behaviour pack in resource_packs/ only sends it to clients. It does not make Basalt run it. Custom items, entities and plugins are loaded from plugins/; see Addons.

Packs that belong to a plugin

A plugin or addon folder can carry its own resource pack in a resource_pack/ subfolder:

plugins/
  my-addon/
    items/
    resource_pack/
      manifest.json
      textures/

Basalt offers it to players alongside the packs in resource_packs/. If a pack in resource_packs/ has the same UUID, that one wins.

Encrypted packs

For an encrypted pack, put its content key in a text file next to it. Basalt looks for the pack’s full file name plus .key, then for the name with its extension replaced by .key:

resource_packs/
  my-textures.zip
  my-textures.zip.key

Hosting packs on a CDN

Large packs download faster from a web server than through the game connection. List them in resource_packs/cdn.json:

[
  {
    "uuid": "3c7a4e0e-52d1-4b8f-9d53-6f1c2a8b9e10",
    "url": "https://cdn.example.org/packs/my-textures.zip"
  }
]

If a pack with that UUID is also in resource_packs/, clients are told to download it from the URL instead of from Basalt. If you give a version, it must match the pack’s.

A pack that exists only on the CDN can be listed too. Basalt cannot inspect it, so the entry must say more:

[
  {
    "uuid": "9b1d6f2a-4e3c-4a7b-b5d8-0c2e7f1a6d43",
    "url": "https://cdn.example.org/packs/music.zip",
    "version": "1.2.0",
    "size": 48211234,
    "name": "Music Pack"
  }
]

Field	Required	Meaning
uuid	Yes	The pack’s UUID.
url	Yes	An https URL. http is accepted with a warning, since clients may refuse it.
version	For CDN-only packs	The pack’s version, as "1.2.0".
size	For CDN-only packs	The size of the pack file in bytes.
name	No	The pack’s name. Defaults to the UUID.
content_key	No	The key of an encrypted pack.
sub_pack	No	The sub-pack to select.
behaviour	No	true if it is a behaviour pack.
scripts, addon, ray_tracing	No	true if the pack has scripts, is an addon, or uses ray tracing.

An unknown field in an entry makes Basalt skip the whole file with a warning.

Tuning the transfer

Packs are sent in pieces. resource_pack_chunk_size in basalt.toml sets the size of each piece in bytes; the default is 262144 (256 KiB). There is rarely a reason to change it.