K
GitHub
Crates

Create Crates

Everything you need to know about defining, structuring, and configuring crates — from the editor to raw YAML.

What Is a Crate?

A crate is a config-backed entity that defines:

  • Its unique ID
  • Its display name and description
  • Whether it is RANDOM or SELECTABLE
  • Its reward pool
  • Its key mode (physical or virtual)
  • Optional pity, cooldown, and per-player limits

Crate configs live inside plugins/BloodlineCrates/crates/ as individual .yml files. Each file maps to exactly one crate.

Create via the In-Game Editor

The fastest and most reliable method for most server owners:

  1. 1
    Open the editor
    /bc editor
  2. 2
    Navigate to the crate manager
    Select from the editor main menu
  3. 3
    Pick an existing crate or duplicate example.yml on disk
  4. 4
    Configure display name, description, crate type, rewards, key display item, key mode, layout, cooldown, pity, and limits
  5. 5
    Save and reload
    /bc reloadcrates

Create via Config (Config-First)

For power users who prefer working directly with YAML, the config-first approach is clean and fast.

  1. 1Copy example.yml inside plugins/BloodlineCrates/crates/
  2. 2Change the id field to your new crate's unique ID
  3. 3Update the display name
  4. 4Replace the rewards section
  5. 5Run /bc reloadcrates to apply
example.yml (skeleton)
1id: "example"
2display-name: "&6Example Crate"
3type: RANDOM
4 
5key:
6  mode: PHYSICAL
7  display-name: "&6Example Key"
8 
9cooldown:
10  enabled: false
11  duration: 3600
12 
13pity:
14  enabled: false
15  threshold: 50
16  guarantee: "legendary_sword"
17 
18limits:
19  enabled: false
20  max-opens: 10
21 
22rewards:
23  - id: "diamond_sword"
24    chance: 5.0
25    display-name: "&bDiamond Sword"
26    broadcast: true
27    actions:
28      - "give {player} diamond_sword 1"
29  - id: "iron_ingot"
30    chance: 50.0
31    display-name: "&7Iron Ingot"
32    actions:
33      - "give {player} iron_ingot 5"

Crate Types

RANDOM

Use a random crate for classic RNG-based openings. Rewards are selected by weight. Good for traditional loot crates, vote crates, donation perks.

SELECTABLE

Use a selectable crate when you want players to choose their reward from a visual menu. Excellent for battle pass reward claims, premium item selectors, or any case where player agency matters.

Selectable setup tips
Keep reward pool sizes readable. Use visually distinct icons per reward. Clean reward names make the menu feel polished and premium.

Configuring Rewards

Rewards belong to a crate's reward pool. Supported reward types:

Item Rewards
Give inventory items to the player.
Command Rewards
Execute console commands on open.
Economy Rewards
Grant in-game currency via Vault.
Crate Rewards
Give keys or access to other crates.
Multi Rewards
Bundle multiple reward types together.
Broadcast-aware
Announce rare wins to the server.

Cooldowns, Pity & Limits

Cooldowns

Prevent players from opening a crate more than once within a defined period. Cooldowns are defined per-crate and enforced server-side.

Pity System

Set a threshold after which a guaranteed rare reward fires. The pity counter resets after a pity trigger. Pity state is tracked per-player, per-crate.

Limits

Cap the maximum number of times a player can open a specific crate. Useful for seasonal or event-tied crates.

Stats alignment
Player open counts are stored in the shared stats-backed player data section, keeping limits, broadcasts, pity, and stats all aligned in one system.
← Quick StartNext: Key Types →