> For the complete documentation index, see [llms.txt](https://esmp-fun.gitbook.io/plugins/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://esmp-fun.gitbook.io/plugins/vault-crates/loot-templates-yml.md).

# Loot templates

`loot-templates.yml` ships pre-populated with a handful of common rewards (XP bottles, keys, an elytra, an economy payout, a LuckPerms rank grant, etc.). It's surfaced in the admin GUI's **`+ Add custom`** flow: pick **From template** in the entry-type Dialog, then choose a template from the second-stage Dialog's option list. Click **Add** to append it to the current loot pool.

You can extend the file to ship your own house "loot patterns" for later reuse. After editing, run `/vc reload`.

## File location

```
plugins/VaultCrates/loot-templates.yml
```

## Top-level shape

```yaml
templates:
  <template-id>:
    label: "Human-readable label"
    description: "What this template does, shown in chat."
    entry: { ... a single LootEntry, same schema as crates.yml ... }
```

Each `template-id` is the stable identifier the GUI lists in the template-picker Dialog. Use lowercase letters, digits, `_`, and `-` only.

The `entry:` block is a literal loot entry — same schema as the `entries:` list under a crate's loot pool in `crates.yml`. Any entry type is allowed (`vanilla`, `command`, `key-reward`, `wild-spawner`).

## Built-in templates

| id                        | What it adds                                         |
| ------------------------- | ---------------------------------------------------- |
| `xp_bottle_4`             | 4 XP bottles per roll, weight 15                     |
| `give_xp_100`             | `/xp add {player} 100`, weight 10                    |
| `nether_star`             | One nether star, weight 2                            |
| `legendary_key`           | A Legendary crate key (requires a `legendary` crate) |
| `command_pay_1000`        | `eco give {player} 1000`, weight 10                  |
| `command_lp_user_donator` | 7d Donator+ via LuckPerms, weight 1, announced       |
| `diamond_block_stack`     | 64 diamond blocks, weight 1, announced               |
| `totem_of_undying`        | One totem, weight 3                                  |
| `elytra`                  | One elytra, weight 1, announced                      |

## Adding your own

Append to the `templates:` map. Example — a "Mythical Sword" template that grants a custom-named diamond sword with lore:

```yaml
templates:

  mythical_sword:
    label: "Mythical Sword"
    description: "Custom-named diamond sword with lore."
    entry:
      type: vanilla
      material: DIAMOND_SWORD
      amount: 1
      weight: 2
      display-name: "<gradient:gold:red><b>Mythical Sword</b></gradient>"
      lore:
        - "<gray>Forged in the heart of a dragon.</gray>"
      announce: true
```

## Validation

Templates that reference other content (a `crate-id` for `key-reward`, a `preset-id` for `wild-spawner`) are validated **at insert time**, not at load. If the referenced crate or preset is missing when an admin picks the template, they get a clear error in chat and the loot pool reopens with no change. This means it's safe to ship templates that reference optional content — they'll just refuse to apply until the content exists.

Templates with structurally invalid entries (bad material, missing required field) are logged with a warning at startup and skipped.

***

Next: [**Configuring crates.yml →**](/plugins/vault-crates/crates-yml.md) · [**The admin GUI →**](/plugins/vault-crates/admin-gui.md)