> ## Documentation Index
> Fetch the complete documentation index at: https://items.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource pack

> How LodeItems builds the pack and gets it to players: built-in hosting, your own URL, S3, merging and optional packs.

LodeItems builds one resource pack from everything in `items/` and writes it to `plugins/LodeItems/pack.zip`. It picks the right pack format for your Minecraft version by itself. Players are sent the pack when they join, and again after a `/lodeitems reload` that changed it. Their game only downloads it again when its contents changed.

## Asking players to accept it

```yaml config.yml theme={null}
pack:
  required: false
  prompt: "<gray>This server uses custom items - please accept the resource pack."
```

With `required: true`, players who decline the pack are disconnected.

When a player's download fails, the console says so. That almost always means the pack host can't be reached: check that the port is open, or set `public-address` (below).

`config.yml` is read at startup, so restart the server after changing these settings.

## Hosting

Choose one of three ways to host it.

**Built-in (default)**

LodeItems runs a small web server and players download the pack from it.

```yaml config.yml theme={null}
pack:
  host:
    enabled: true
    port: 8163
    public-address: ""
```

* The port has to be reachable from the internet, like your game port.
* Leave `public-address` empty to use the address the player typed to join. That works for most servers.
* Set it when the web port is reached another way, for example behind a proxy like Velocity or BungeeCord, or on another IP: `public-address: "203.0.113.5"` or `"packs.myserver.net"`.

**Your own URL**

Host the zip yourself, on a web server or CDN:

```yaml config.yml theme={null}
pack:
  host:
    enabled: false
  url: "https://cdn.myserver.net/pack.zip"
```

Upload `plugins/LodeItems/pack.zip` there again **after every change**.

**S3 and compatible**

LodeItems uploads every new pack to S3 or a compatible service (Cloudflare R2, Backblaze B2, MinIO...) by itself. Players download it from there. This takes priority over the other two when enabled.

```yaml config.yml theme={null}
pack:
  s3:
    enabled: true
    endpoint: "https://<account>.r2.cloudflarestorage.com"
    region: auto
    bucket: "my-packs"
    access-key: "..."
    secret-key: "..."
    path-style: true
    public-url: "https://packs.myserver.net"   # a public bucket URL, or a domain in front of it
    prefix: "lodeitems/"
```

Each pack is named after its hash, so it's uploaded once and cached well.

## Merging other packs

Your pack can include other resource packs, for example one from ModelEngine or a texture pack you made earlier.

* **Inside `items/`:** any folder in `items/` that has an `assets/` folder inside it is merged automatically.
* **Elsewhere:** list folders or `.zip` files, relative to `plugins/`:
  ```yaml config.yml theme={null}
  pack:
    merge:
      - "ModelEngine/resource pack"
      - "MyOtherPlugin/pack.zip"
  ```

When two packs have the same file, LodeItems' own file wins and the console says so. Files the game combines across packs anyway are combined: `sounds.json`, languages, fonts and atlases.

## Optional packs

Players can turn extra packs on and off with `/packs`, for example HD textures or a different art style. They are sent on top of the main pack.

```yaml config.yml theme={null}
pack:
  optional:
    hd:
      name: "<gold>HD textures"
      description: ["<gray>Sharper textures for our items."]
      default: false        # on for players who never chose
      required: false       # always on
      conflicts: [retro]    # can't be on together with these
    retro:
      name: "<green>Retro look"
```

Put each pack's files in `plugins/LodeItems/packs/<id>/` (an unzipped pack folder) or `packs/<id>.zip`. A folder without a `pack.mcmeta` gets one.

Players' choices are saved and applied when they close the `/packs` menu, since every change makes their game reload its resources.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.