> For the complete documentation index, see [llms.txt](https://docs.mantic.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mantic.dev/manticcrates/configuration-files/crate-files.md).

# Crate files

Configure one crate per YAML file, including access, rewards, limits, items, and visuals.

Each `crates/<id>.yml` file defines one crate. The top-level `id:` value is used in commands and references. Keep the filename and this ID matching, for example `crates/basic.yml` with `id: basic`. There is no combined `crates.yml`; use the in-game Crate Editor or edit the individual file.

## Basic example

```yaml
id: starter
display-name: '&eStarter Crate'
key-name: '&eStarter Key'
crate-material: CHEST
key-material: TRIPWIRE_HOOK
virtual-keys: true
selector-enabled: true
rewards:
  - id: diamonds
    display-name: '&b8 Diamonds'
    rarity: Rare
    icon-material: DIAMOND
    weight: 10
    items:
      - material: DIAMOND
        amount: 8
```

This is a shortened example. The generated crate file contains comments and defaults for the other settings. Use a material name available on your server version.

## Access, keys, and costs

* `virtual-keys: true` stores keys as a player balance. `false` uses physical key items.
* `permission` and `access-permissions` restrict access; a player needs any one configured node.
* `key-requirements` can require multiple crate-key types and amounts. If omitted, one key for this crate is required.
* `free-open: true` removes the key requirement. `open-cost` can add a Vault economy cost.
* `cooldown-seconds: 0` has no cooldown; a positive number sets seconds; `-1` makes it one-time per player until reset.
* `allowed-worlds` lists worlds where the crate can open; an empty list allows all worlds.
* `available-from`, `available-until`, `monthly-claim-limit`, and `monthly-timezone` configure calendar-based availability and claims. Dates are inclusive in the configured timezone. A limit of `0` disables the monthly allowance.

The supplied example files use virtual keys for most crates and physical keys for `rare`. Change the setting independently on any crate.

## Selector, preview, and animation

* `selector-enabled` controls whether the crate appears in `/crates`.
* Optional `selector-slot` pins it to the same zero-based slot on each selector page. For example, `selector-slot: 13` is row 2, column 5. Use `-1` or omit it for automatic placement. The slot must be a dot entry in `menus/player/selector.yml`; control slots cannot be used. A conflict falls back to automatic placement.
* `preview-enabled` and `preview-on-left-click` control previews.
* `hide-unavailable-preview-rewards: true` hides rewards the viewer cannot currently win.
* `spin-type` accepts `horizontal`, `vertical`, `simple`, `border`, `snake`, `spiral`, or `bounce`.
* `animation-duration-ticks: -1` inherits the global duration, `0` skips the roll, and `1`–`1200` sets the crate duration.
* `cinematic-pack` selects a reveal in `cinematics/<id>.yml` instead of the ordinary GUI roll.
* `physical-animation-enabled: true` allows a spin above a linked crate when global physical openings are enabled and the player is not using the GUI roll.

## Holograms and idle effects

Use `hologram-enabled`, `hologram-height`, and `hologram-lines` in each crate file:

```yaml
hologram-enabled: true
hologram-height: 1.4
hologram-lines:
  - '&b{crate}'
  - '&7You have &e{keys} &7{keys-word}'
  - '&eRight-click to open'
```

The key-count line above is intended for a virtual-key crate. For a physical-key crate, use instructions such as `'&7Requires a physical key'` instead.

Supported tokens include `{crate}`, `{id}`, `{player}`, `{keys}`, `{key-count}`, `{keys-word}`, `{openings}`, `{cooldown}`, `{cooldown-time}`, `{monthly-remaining}`, `{monthly-reset}`, `{latest-opener}`, `{latest-reward}`, `{next-milestone-openings}`, and `{next-milestone-reward}`. Use `{cooldown-time}` for a readable countdown.

Long text wraps using `config.yml`'s `hologram-line-width`; `hologram-line-spacing` controls the distance between lines. Viewer range is controlled by `hologram-view-distance`.

Idle visuals use `particle`, `particle-model`, `particle-count`, `particle-radius`, and `particle-height`. Models are `circle`, `helix`, `spiral`, `orbit`, `pulse`, `burst`, and `none`.

### Inventory spin examples

![An inventory reward animation](https://2746822811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCVqlaAAAoPORtPYtxCWn%2Fuploads%2F44WutFLOPSLI1Zs7tMuU%2Fmanticcrates-animation.gif?alt=media)

*An inventory reward animation.*

![The Serpent crate uses a snake-shaped reward track](https://2746822811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCVqlaAAAoPORtPYtxCWn%2Fuploads%2FAJh6KK6tIi6VEzFZRRAp%2Fmanticcrates-serpent.webp?alt=media)

*The Serpent crate uses a snake-shaped reward track.*

### Reward preview

Players can preview the configured reward pool before opening.

![The Haunted Vault reward preview](https://2746822811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCVqlaAAAoPORtPYtxCWn%2Fuploads%2FvZfnLC4SvJISu1Xg1EDD%2Fmanticcrates-preview.png?alt=media)

*The Haunted Vault reward preview.*

## Weighted rewards and rarities

Each reward needs a unique `id`. Other settings such as pity, milestones, choices, and crate chains refer to that ID. `weight` is a relative chance value, not a percentage; higher eligible weights are more likely. Use `weight: 0` to disable a reward.

Optional `rarities:` entries assign a display/effect group and rarity weight. Rarity entries can configure `sound`, `particle`, `particle-model`, `particle-count`, `particle-duration-ticks`, `post-reward-effect`, `firework`, and `announce`. Supported particle models are `circle`, `helix`, `spiral`, `orbit`, `pulse`, `burst`, and `none`. Post-reward effects are `none`, `snowfall`, `blossom`, `haunted`, and `celebration`.

## Reward options

A reward can include any combination of:

* `items`: one or more item stacks with a required `material`. Optional fields include `amount`, `name`, `lore`, `item-data`, `reroll-token`, and generated `nbt-data`.
* `commands`: server-console commands. `{player}`, `{crate}`, and `{reward}` are replaced when the reward pays.
* `money`: Vault money payout.
* `key-crate-id` and `key-amount`: keys for another crate.
* `rerolls`: add banked reroll credits. If an item in the reward has `reroll-token: true`, the credits are redeemed only when the player right-clicks that item.
* `choose-from`: a list of 2–5 other reward IDs in this crate. The choice pays the selected reward instead of the trigger reward; closing the choice menu selects one option so the opening still pays.
* `open-crate-id`: open another crate for free after the current reward. Chains stop after three links.

The Crate Editor can capture a held custom item with its serialized data, including plugin NBT. Leave the generated `nbt-data` value intact; recapture the item in the editor to replace it.

## Limits and progression

* `player-limit`: maximum wins for one player; `0` means unlimited.
* `global-limit`: total wins across the server; `0` means unlimited.
* `global-player-limit`: maximum distinct players who can win; `0` means unlimited. Existing winners may win again if their personal limit permits.
* `pity-after` and `pity-reward`: grant a configured reward after a number of unsuccessful openings.
* `milestones:`: give rewards after configured opening counts; milestones may repeat.
* `rerolls` at the crate root: `-1` inherits `default-rerolls`, `0` disables free per-opening rerolls, and `1`–`10` sets a per-opening count. Banked player credits are separate.

Set limits in `/crates editor` → crate → **Rewards** → reward → **Reward limits**, or edit the reward's fields:

```yaml
player-limit: 2
global-limit: 100
global-player-limit: 25
```

Reset counters with:

```
/crates limits reset player <player> <crate> <reward>
/crates limits reset global <crate> <reward>
/crates limits reset all <crate> <reward>
/crates monthly reset <player> <crate>
```

Optional settings may be omitted when they match their defaults. The comments on visible fields include the exact location and copyable examples for adding them back. Root crate settings belong beside `id:`; reward settings belong under the matching entry in `rewards:`.

### Keep or reroll

The reward offer appears after the reveal while the player has an available reroll. Choosing to reroll consumes a reroll rather than another key.

![The keep-or-reroll reward menu](https://2746822811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCVqlaAAAoPORtPYtxCWn%2Fuploads%2FVC0KE311x3wv5HlVfVHi%2Fmanticcrates-reroll.png?alt=media)

*The keep-or-reroll reward menu.*

## Portable multi-prize items

Set `consumable-crate: true` to make `/crates give` issue a one-use crate item. Set `bundle-min-rewards`, `bundle-max-rewards`, `bundle-unique-rewards`, and optional `guaranteed-rewards` at the crate root. Guaranteed reward IDs are paid once and excluded from the random pool. They must be eligible or the item remains unconsumed. These items replace the usual key and money cost; monthly limits, world restrictions, and cooldowns still apply. They do not use single-roll pity or rerolls.

By contrast, `/crates givechest` always gives a permanent placement block. See Pouch files for multi-prize items that use a crate's pool without charging a key.