Crates

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)

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

- 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).

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:

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:

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.

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). 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) 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:

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 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:

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::

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 · GUI Customization