# Crates

A complete crate system: weighted reward tables, keys, seasonal events, globally-limited unique rewards, server-wide broadcasts, and physical crate blocks placed in the world.

## Crate Types

| Type | `always-open` | Behavior |
|---|---|---|
| **Simple crate** | `true` | Always available. Usually opened by paying currency directly. |
| **Seasonal crate** | `false` | Closed by default. An admin opens it for a limited time (or permanently) for events. |

## Configuration (`crates.yml`)

```yaml
crates:
  celestial:
    display: "&#F0F43CCelestial Crate"
    icon: ENDER_CHEST
    price: 0                # 0 = key-only, no currency purchase option
    always-open: false       # seasonal — admin controls the open window
    rewards:
      - type: set
        id: rainbow
        weight: 1
        stock: 1              # only 1 copy will EVER be won on the server
        broadcast: true       # announce server-wide when someone wins it
      - type: set
        id: aurora
        weight: 2
        stock: 3
      - "set:metallic:2:5"     # shorthand: type:id:weight:stock
      - "tag:red_shake:8"      # shorthand without stock = unlimited
    announce:
      interval: 300            # seconds between chat reminders while open
      messages:
        - "&#F0F43C&l✦ &fThe {crate} &fis OPEN! &7({time} left) &fUse &e/cosmetics crates &#F0F43C&l✦"

  starter:
    display: "&7Starter Crate"
    icon: CHEST
    price: 250
    always-open: true
    rewards:
      - "chatcolor:fire:10"
      - "emoji:rainbow:15"
```

### Reward Entry Formats

Two equivalent formats:

- **Shorthand string:** `"type:id:weight"` or `"type:id:weight:stock"`
- **Full map:** supports every option including `broadcast`

```yaml
- type: set
  id: aurora
  weight: 2
  stock: 3
  broadcast: true
```

### Global Stock

`stock: N` makes a reward **globally limited across the entire server** — once N players have won it (tracked in SQLite, claimed atomically so simultaneous crate openings can never both win the last copy), it disappears from the pool and shows **SOLD OUT** in the preview. Omit `stock` (or set it to a shorthand string without a 4th value) for unlimited rewards.

`broadcast: true` announces server-wide the first time a reward is won (not on repeat wins, since cosmetics are stackable and repeats are normal — see [Vault & Trading](Vault-and-Trading.md)).

## Pity / Guaranteed Luck

A pity system prevents long unlucky streaks. Flag the "rare" rewards in a crate with `pity: true`, and give the crate a `pity-threshold`:

```yaml
crates:
  celestial:
    pity-threshold: 40          # unset = pity disabled for this crate
    rewards:
      - type: set
        id: rainbow
        weight: 1
        pity: true              # this reward counts toward the pity guarantee
```

If a player opens the crate `pity-threshold` times **in a row without landing any `pity: true` reward**, the next open is **guaranteed** to give one of them (chosen among the pity-flagged rewards, respecting their relative weights). The counter is tracked per player per crate and resets the moment a pity reward is won — by luck or by the guarantee.

```
/cosmetics crate pity <player> <crate>          Show a player's current counter / threshold
/cosmetics crate pity <player> <crate> reset    Reset it to zero
```

## Daily-Login Keys

Any crate can hand out keys automatically on login:

```yaml
crates:
  daily:
    display: "&aDaily Crate"
    icon: CHEST
    daily: true                 # enable the daily-login key
    daily-keys: 1               # how many keys to grant per claim
    daily-cooldown-hours: 24    # hours between claims (decimals allowed)
```

With `daily: true`, every player receives `daily-keys` keys for that crate the first time they log in after `daily-cooldown-hours` have passed since their last claim. Players check their remaining cooldown with `/cosmetics daily`. Full page: **[Daily Rewards](Daily-Rewards.md)**.

## Opening a Crate

- **With a key:** consumes 1 key item, always free.
- **By paying:** only available if `price > 0`; deducts currency, always with a confirmation prompt first.
- Either way: a **CS:GO-style roulette animation** plays — a reel of possible prizes spins and decelerates onto the winning item, with building sound cues. The reward is already granted before the animation starts, so closing the menu early never costs you the prize.

Every win — repeat or not — adds a real, stackable copy to the winner's vault (see [Vault & Trading](Vault-and-Trading.md)). There is no "you already own this" penalty and no currency substitute; duplicates are simply extra copies, ready to keep, trade, or sell.

## The Rewards Preview

Shift-click a crate (or left-click a [physical crate block](#physical-crate-blocks)) to open the rewards preview:

- Every possible reward with its live win chance (recalculated against only the currently-available pool, so sold-out items don't skew the percentages for what's left)
- Stock remaining for limited rewards
- Who has already won a limited reward (`Won by: Player1, Player2...`)
- A full set-preview line for Set rewards, composed live with the viewing player's own name
- **Open with Key** and **Buy & Open** buttons directly inside the preview (buy also goes through a confirmation menu)

## Keys

Keys are physical, tradeable items tied to a specific crate.

```
/cosmetics crate givekey <player> <crate> [amount]
```

Right-clicking a key in hand opens its crate directly.

## Seasonal Crate Admin Commands

```
/cosmetics crate enable <crate> <7d|12h30m|always>
/cosmetics crate disable <crate>
```

Duration format accepts any combination of `d`/`h`/`m`/`s` (e.g. `3d12h`, `90m`). The open/closed state and remaining time survive server restarts (stored in SQLite) and the periodic chat announcements (`announce:` in config) automatically resume.

## Physical Crate Blocks

Place any block in the world — a chest, ender chest, shulker box, or a custom ItemsAdder/Oraxen/Nexo block — and link it to a crate:

```
/cosmetics crate setblock <crate>            (then right-click the block)
/cosmetics crate setblock <crate> <world> <x> <y> <z>   (direct, works from console)
/cosmetics crate removeblock                 (then right-click the block)
/cosmetics crate blocks                      (list every linked block and its coordinates)
```

- **Right-click** the block → opens the crate (key or paid, same logic as the menu).
- **Left-click** the block → opens the rewards preview.
- Linked blocks are **protected from being broken** until explicitly unlinked with `removeblock`.

### Default block locations (config)

Instead of (or alongside) linking blocks by hand, a crate can declare its own default location(s) directly in `crates.yml`. They're auto-linked every time the server starts or you `/cosmetics reload` — no clicking required:

```yaml
crates:
  celestial:
    blocks:
      - { world: world, x: 100, y: 65, z: 200 }
      - "world;-50;70;12"        # shorthand string form also accepted
```

This is **additive only** — removing an entry from `blocks:` later does **not** un-link the physical block; use `/cosmetics crate removeblock` for that. Manually-linked blocks (via `/cosmetics crate setblock`) and config-declared ones coexist fine; a crate can have both.

### Hologram label (FancyHolograms)

If **[FancyHolograms](https://modrinth.com/plugin/fancyholograms)** is installed, every linked crate block — config-declared or manually set — gets a small floating label above it, created/updated automatically (no extra setup):

```
Celestial Crate
LIMITED Cosmetics Crate
```

Whether a crate shows as **Limited** or **Normal** is auto-detected from its rewards: any reward with a global `stock` cap makes the crate Limited. Override it explicitly, or turn the label off for one crate, with:

```yaml
crates:
  celestial:
    hologram:
      limited: true    # force Limited/Normal instead of auto-detecting
      enabled: false   # hide the label just for this crate
```

Global appearance (text templates, height above the block, on/off switch) lives in `config.yml` under `crate-holograms:`:

```yaml
crate-holograms:
  enabled: true
  height-offset: 1.6
  lines-normal:
    - '&f{crate}'
    - '&7Cosmetics Crate'
  lines-limited:
    - '&f{crate}'
    - '&c&lLIMITED &7Cosmetics Crate'
```

`{crate}` is replaced with the crate's `display` name. Without FancyHolograms installed, this section is simply ignored — the physical block still works normally, just without the floating label.

## Full Command Reference

```
/cosmetics crates                              Open the crates browse menu
/cosmetics crate open <crate>                  Open a crate (uses a key if you have one)
/cosmetics crate givekey <player> <crate> [n]  Give keys
/cosmetics crate enable <crate> <duration>     Open a seasonal crate
/cosmetics crate disable <crate>               Close a seasonal crate
/cosmetics crate setblock <crate> [coords]     Link a world block to a crate
/cosmetics crate removeblock [coords]          Unlink a world block
/cosmetics crate blocks                        List every linked block
/cosmetics crate pity <player> <crate> [reset] Check or reset a pity counter
/cosmetics daily                               Check your daily-crate cooldowns
```

---

Next: [Daily Rewards](Daily-Rewards.md) · [GUI Customization](GUI-Customization.md)