EasyCrates

EasyCrates crates are blocks you place in the world. By default a player with a key right-clicks the crate, picks the reward they want from a menu and confirms, so they always know what they get. Set a crate to spin mode and it rolls a weighted random reward with an animation instead.

Keys can be items (physical keys) or a number stored per player (virtual keys). Crates can also be daily crates on a timer, show drop chances, open 10 or 100 keys at once, and guarantee a rare reward after a dry streak.

Permissions#

Opening crates needs no permission, only a key.

Commands#

Every /crates command needs easycrates.admin. Aliases: /easycrates, /crate, /donutcrates.

/crates givekey works from the console, so store and vote plugins can use it.

With keys-command.enabled: true, every player also gets /keys (alias /key), which lists how many keys they have per crate. It needs no permission.

Configuration#

A crate file#

icon:
  name: '&aᴄᴏᴍᴍᴏɴ ᴄʀᴀᴛᴇ'
  material: CHEST
inventory:
  name: '&8ᴄʜᴏᴏsᴇ 1 ɪᴛᴇᴍ'
  rows: 3
hologram:
  1:
    height: 1.5
    lines:
      - '&aᴄᴏᴍᴍᴏɴ ᴄʀᴀᴛᴇ'
      - '&a%easycrates_common-crate% &fKeys'
rewards:
  1:
    slot: 10
    give-icon: true
    icon:
      material: NETHERITE_HELMET
      name: '&aᴄᴏᴍᴍᴏɴ ʜᴇʟᴍᴇᴛ'
  2:
    slot: 11
    give-icon: false
    icon:
      material: COMMAND_BLOCK
      name: '&a$500'
    commands:
      - 'eco give %player% 500'

Optional crate sections#

Each of these is off until you add it to a crate file. crate-example.yml shows all of them.

A daily crate:

cooldown:
  enabled: true
  duration: 24h
  require-key: false
  bypass-permission: 'easycrates.cooldown.bypass'

The cooldown is saved per player, so relogging or switching servers doesn't reset it.

config.yml#

Every message is under messages, each with its own type and sound.

Install#

1. Put the EasyCrates jar in plugins/ and start the server once. It creates plugins/EasyCrates/ with the files above and 6 example crates.
2. Paste your license key into license-key in license.yml. Your key is under My Licenses on the BlazeZ portal; licenses linked to your Discord account show up there automatically. If yours is missing, open a License Key ticket in the BlazeZ Discord.
3. Restart the server.

Coming from DonutCrates#

Swap the DonutCrates jar for the EasyCrates jar and start the server. On first start, EasyCrates copies plugins/DonutCrates into plugins/EasyCrates, including crates, placed crates and every player's keys. The old folder stays as a backup. donutcrates.admin and the %donut_<crate>% placeholder keep working, and so does your license key.

Creating a crate#

1. Copy a file in crates/, for example common-crate.yml to vote-crate.yml. The file name is the crate's name.
2. Change the icon, inventory title and hologram lines.
3. Set the rewards in the file, or run /crates reload and add them in game (see below).
4. Run /crates get vote-crate and place the block where players should open it.
5. Give keys with /crates givekey <player> vote-crate 1, or key items with /crates givephysicalkey.

A player with a key right-clicks the block, picks a reward and confirms. One key is used per open.

Editing rewards in game#

/crates editor lists every crate. Click one, then Edit Rewards:

• Add Reward adds any item, with all its data, and lets you pick its slot.
• Click a reward to replace its item, add or remove commands, or delete it.

Changes are saved to the crate file.

To remove a placed crate, break its block.

Placeholders#

Every placeholder also works with donut in place of easycrates.

Developer API#

EasyCrates fires two Bukkit events from net.luxcube.minecraft.api.event.

@EventHandler
public void onOpen(CrateOpenEvent event) {
    if (event.getCrateName().equals("gold-crate") && !event.getPlayer().hasPermission("vip")) {
        event.setCancelled(true);
    }
}

Add softdepend: [EasyCrates] to your plugin.yml.

Troubleshooting#

• A crate is missing after /crates reload: the console names the file, line and key that couldn't be read. A broken reward shows as a barrier and the rest of the crate still loads.
• Players can't preview or multi-open with commands: those commands are admin-only. Players use the buttons in the crate menu.