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

# Crates & Rewards

The crate file, one per crate under crates/.

Every file in `crates/` is a crate. The file name is the crate id (`rusty.yml` is `rusty`). The crate's icon in a menu is a GUI item (`custom-item: {type: crate, crate: rusty}` in any file under `guis/`, see [GUIs](/p/edcrates/features/guis.md)); the crate file holds everything else. `test.yml` demonstrates every option.

```yaml
display-name: '&6&lRusty &r&e&lKey'
tier: '&7[Tier #1]'
type: crate                 # crate (virtual keys + placeable) | lootbox (a physical item only)
animation: 'roulette'       # preset from animations.yml, or none
animate-bulk: true          # play the animation once for bulk opens (shows the top rewards)
cooldown: 0                 # seconds between opens per player
permission: ''              # optional permission to open

preview:                    # optional overrides of the preview GUI file's pagination settings
  gui: 'crate-preview'      # which guis/ file shows the rewards (config.yml gui.preview by default)
  show-chance: false
  chance-format: '&7Chance: &f{chance}%'
  footer: [ ' ', '&a&lREWARD ENABLED' ]

placeable: ...              # see Physical Crates

pools:
  main:
    rolls: 1                # draws from this pool per key
    rewards:
      tokens-1:
        slot: 0             # optional: pin to a preview slot; omit and rewards fill the preview in order
        weight: 1800        # relative weight, not a percentage
        rarity: common
        announce: false     # broadcast when won
        hidden: false       # can be won but is not shown
        permission: ''      # only players with it can roll it
        toggleable: true    # players may switch it off for themselves in the preview
        sound: ''           # played to the opener when it comes up
        actions:
          - 'currency:tokens 3500000'
        display:
          material: MAGMA_CREAM
          name: '&f&l3,500,000 &r&4┃ &r&c&lTokens'
          lore: [ ... ]
```

## Lootboxes

`type: lootbox` makes the crate a physical item and nothing else: no key balance, no placeable, no hologram. `/edcrates givelootbox <player> <id> [amount]` hands out the `item:` block; right-clicking one (air or block) consumes it and opens it on the spot with the crate's animation, one at a time. With `item.open-at-block: true` the animation plays on the clicked block. GUIs only ever preview a lootbox (a `crate` custom item pointing at one behaves as `preview`), and the key commands refuse it.

## Pools and multi-reward crates

A crate can have several pools, each drawn `rolls` times per key. The Treasure Lootbox draws one jackpot reward and four exclusive rewards on every open. `rollsPerOpen` (shown as `{rewards_per_open}`) is the sum.

## Weights

A reward's chance is `weight / total weight of its pool`. The shipped crates use common 1800 / rare 500 / legendary 120 / mythical 20 / final 5. `/edcrates simulate <crate> 100000` prints the real distribution next to the expected one.

## Items

Any item block accepts: `material`, `texture` (base64 head value, or `self`), `name`, `lore`, `amount`, `glow`, `custom-model-data`, `color` (leather/potion), `hide-flags`.