DonutCrates - Complete Documentation

ShyamSai · Jun 16, 2025

DonutCrates Documentation
The Ultimate Premium Crates Plugin with In-Game Editor

---

Installation & Setup

Requirements

Software	Version	Required
Minecraft Server	1.20+	✓ Required
Java	17+	✓ Required
PlaceholderAPI	Latest	✓ Required
Hologram Plugin	Any supported	✓ Required

Supported Hologram Plugins

DecentHolograms - Recommended for best performance
FancyHolograms - Modern alternative with great features
HolographicDisplays - Classic and stable option

Installation Steps

Download and install PlaceholderAPI and your chosen hologram plugin
Place DonutCrates.jar in your /plugins/ folder
Start your server to generate configuration files
Get your license key from our Discord Server
Add your license key to config.yml
Restart your server
Use /crates editor to create your first crate!

Code:

# config.yml
License: "YOUR_LICENSE_KEY_HERE"

automatic-key-all:
  enabled: true
  time: 300
  keys:
    common-crate: 1

database:
  thread-pool-size: 2

---

Commands & Permissions

Player Commands

Command	Description	Permission
`/crates`	Show command help	`donutcrates.command`
`/crates version`	Show plugin version	`donutcrates.command`

Admin Commands

Command	Description	Permission
`/crates editor`	Open the in-game crate editor	`donutcrates.admin`
`/crates get <crate>`	Get a physical crate item	`donutcrates.admin`
`/crates givekey <player> <crate> [amount]`	Give keys to a specific player	`donutcrates.admin`
`/crates givekeyall <crate> [amount]`	Give keys to all online players	`donutcrates.admin`
`/crates reload`	Reload plugin configuration	`donutcrates.admin`

Permission Nodes

donutcrates.command - Access to basic commands (default: true)
donutcrates.admin - Access to all admin features (default: op)

---

PlaceholderAPI Integration

Available Placeholders

Placeholder	Description	Example Output
`%donut_<cratename>%`	Player's key amount for specific crate	`5`
`%donut_keyall_countdown%`	Time until next automatic key distribution	`4m 32s`
`%donutcrates_<cratename>_key%`	Alternative format for key amounts	`12`

Usage Examples

Code:

# In hologram configuration
lines:
  - "&aCommon Crate"
  - "&f%donut_common-crate% Keys Available"
  - "&7Click to open!"

# Scoreboard example
- "&eYour Keys:"
- "&f  Common: &a%donut_common-crate%"
- "&f  Gold: &6%donut_gold-crate%"
- "&f  Prime: &b%donut_prime-crate%"

---

Configuration Files

Main Configuration (config.yml)

Code:

# Get your license key from our discord server https://discord.gg/shyamstudio
License: ""

automatic-key-all:
  enabled: true
  time: 300  # Time in seconds between key distributions

  # Which crates to give keys for during KeyAll events
  keys:
    common-crate: 1
    gold-crate: 1
    prime-crate: 1

  # Title message settings
  title-message:
    show: true
    title: '&aKey All'
    subtitle: '&aYou have received a crate key!'
    fade-in: 10
    stay: 70
    fade-out: 20

  # Action bar message
  action-bar:
    show: true
    message: '&aCongratulations! You have been awarded a key!'

  # Chat messages
  chat:
    show: true
    messages:
      - '&aCongratulations! You have been awarded a key as part of our Key All event!'
      - '&6Thank you for participating!'

  # Sound configuration
  sound:
    enabled: true
    name: 'ENTITY_EXPERIENCE_ORB_PICKUP'
    volume: 0.5
    pitch: 2.0

# Database settings
database:
  thread-pool-size: 2

Messages Configuration (messages.yml)

Code:

# Plugin messages configuration
reloaded: "&aPlugin reloaded in %ms%ms."
no_permission: "&cYou don't have permission to use this command."
crate_not_found: "&cCrate with that name was not found."
player_not_found: "&cPlayer not found."
key_given: "&aSuccessfully gave x%amount% of %crate% keys to %player%."
key_all_given: "&aSuccessfully gave x%amount% of %crate% keys to all online players."
key_received: "&aYou have received x%amount% of %crate% keys!"
no_key: "&cYou don't have any keys for this crate!"
inventory_full: "&cYou do not have enough space in your inventory."

Sound Configuration (sounds.yml)

Code:

# Sound effects configuration
crate_open:
  sound: BLOCK_CHEST_OPEN
  volume: 1.0
  pitch: 1.0

confirm_open:
  sound: ENTITY_EXPERIENCE_ORB_PICKUP
  volume: 1.0
  pitch: 0.5

reward_claim:
  sound: ENTITY_PLAYER_LEVELUP
  volume: 1.0
  pitch: 1.0

key_received:
  sound: ENTITY_EXPERIENCE_ORB_PICKUP
  volume: 1.0
  pitch: 2.0

no_key:
  sound: ENTITY_VILLAGER_NO
  volume: 1.0
  pitch: 1.0

---

In-Game Editor Guide

The DonutCrates in-game editor is a powerful tool that allows you to create and modify crates without touching configuration files.

Accessing the Editor

Ensure you have the donutcrates.admin permission
Run the command /crates editor
The main editor menu will open

Editor Menu Structure

Main Editor Menu

Crate List - View and edit existing crates
Create New Crate - Start creating a new crate from scratch

Crate Edit Menu

Edit Icon - Modify the crate's appearance and display name
Edit Inventory - Configure GUI settings (title, size, background)
Edit Rewards - Manage all crate rewards and commands
Edit Holograms - Configure floating text displays

Creating Your First Crate

Open the editor with /crates editor
Click "Create New Crate"
Set a unique name for your crate (e.g., "mystical-crate")
Choose an icon item by placing it in your first hotbar slot and typing "confirm"
Select the inventory size (1-6 rows)
Click "Create Crate" to finalize
Your crate is now created with default holograms!

Managing Rewards

Setting	Description	Example
Icon	The item displayed in the GUI	Diamond Sword with custom name
Slot	Position in the crate GUI (0-53)	Slot 13 (center of 3-row GUI)
Give Icon	Whether the icon item is given to player	True for items, False for commands
Amount	Quantity of the reward	1 for single items, 64 for stacks
Commands	Commands executed when reward is claimed	`give %player% diamond 10`

---

Crate Configuration Files

While the editor handles most tasks, understanding the file structure is helpful for advanced users.

Crate File Structure

Code:

# crates/example-crate.yml
icon:
  name: '&aExample Crate'
  material: CHEST
  lore:
    - '&7(Place this crate)'

inventory:
  name: '&8Choose 1 Item'
  rows: 3
  background-icon:
    material: BLACK_STAINED_GLASS_PANE
    name: '&aExample Crate'

hologram:
  enable: true
  1:
    height: 1.2
    lines:
      - '&aExample Crate'
      - '&f/store'
  2:
    height: -0.5
    lines:
      - '&a%donut_example-crate% &fKeys'

rewards:
  1:
    slot: 13
    give-icon: true
    amount: 1
    icon:
      material: DIAMOND_SWORD
      name: '&bMagical Sword'
      enchantments:
        sharpness: 5
        unbreaking: 3
    commands:
      - 'broadcast %player% received a magical sword!'

Advanced Item Configuration

Code:

# Armor with trims
icon:
  material: NETHERITE_HELMET
  name: '&cWarrior Helmet'
  trim:
    material: diamond
    pattern: host
  enchantments:
    protection: 4
    unbreaking: 3
    mending: 1
  lore:
    - '&7A legendary piece of armor'
    - '&7worn by ancient warriors.'

# Custom model data item
icon:
  material: STICK
  name: '&6Magic Wand'
  custom-model-data: 12345
  enchantments:
    unbreaking: 1
  item-flags:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES

---

Developer API

DonutCrates provides a comprehensive API for developers to integrate with the plugin.

Getting Started

XML:

<!-- Add to your pom.xml -->
<repositories>
    <repository>
        <id>jitpack</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.github.raviraidev</groupId>
        <artifactId>DonutCrates</artifactId>
        <version>1.0.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

CrateAPI Usage

Java:

// Get the API instance
DonutCrates plugin = DonutCrates.getInstance();
CrateAPI crateAPI = plugin.getCrateAPI();

// Get a crate by name
Crate crate = crateAPI.getCrate("common-crate");

// Get crate rewards
List<Reward> rewards = crateAPI.getCrateRewards("common-crate");

// Open crate menu for player
crateAPI.openCrateMenu(player, "common-crate");

// Give keys to player
crateAPI.giveCrateKey(player, "common-crate", 5);

// Give keys to all online players
crateAPI.giveCrateKeyAll("common-crate", 1);

// Check player's key amount
int keyAmount = crateAPI.getPlayerKeyAmount(player.getUniqueId(), "common-crate");

PlayerDataAPI Usage

Java:

// Get the API instance
PlayerDataAPI playerAPI = plugin.getPlayerDataAPI();

// Get player's key amount
int keys = playerAPI.getKeyAmount(player.getUniqueId(), "common-crate");

// Add keys to player
playerAPI.addKeys(player.getUniqueId(), "common-crate", 3);

// Remove keys from player
playerAPI.removeKeys(player.getUniqueId(), "common-crate", 1);

// Load player data asynchronously
CompletableFuture<PlayerData> future = playerAPI.loadPlayerData(player.getUniqueId());
future.thenAccept(playerData -> {
    // Handle loaded data
});

Custom Events

Java:

@EventHandler
public void onCrateOpen(CrateOpenEvent event) {
    Player player = event.getPlayer();
    Crate crate = event.getCrate();
    
    // Custom logic when player opens crate
}

@EventHandler
public void onRewardClaim(RewardClaimEvent event) {
    Player player = event.getPlayer();
    Reward reward = event.getReward();
    
    // Custom logic when player claims reward
}

---

Troubleshooting

Common Issues

Problem: Plugin doesn't start, shows license error
Solution:

Join our Discord Server to get your license key
Add the license key to config.yml under License: "YOUR_KEY"
Restart your server

Problem: Holograms don't show up above crates
Solution:

Ensure you have one of the supported hologram plugins installed
Check that the hologram plugin is loaded before DonutCrates
Verify holograms are enabled in your crate configuration
Try reloading with /crates reload

Problem: Placeholders show as raw text (e.g., %donut_common-crate%)
Solution:

Install PlaceholderAPI if not already installed
Register the expansion with /papi register donut
Check available placeholders with /papi list
Ensure DonutCrates loads after PlaceholderAPI

Problem: Can't access the in-game editor
Solution:

Verify you have donutcrates.admin permission
Check for console errors when using /crates editor
Ensure your client supports the required inventory features
Try restarting the server if editor seems unresponsive

Debug Information

When reporting issues, please provide:

DonutCrates version (/crates version)
Server software and version
Hologram plugin name and version
PlaceholderAPI version
Console errors (if any)
Steps to reproduce the issue

---

Configuration Examples

Economy Integration Example

Code:

# Economy-based crate rewards
rewards:
  1:
    slot: 10
    give-icon: false
    icon:
      material: GOLD_INGOT
      name: '&6$1000'
      lore:
        - '&7Cash reward'
    commands:
      - 'eco give %player% 1000'
      
  2:
    slot: 11
    give-icon: false
    icon:
      material: EMERALD
      name: '&a$5000'
      lore:
        - '&7Big cash reward'
    commands:
      - 'eco give %player% 5000'
      - 'broadcast %player% won $5000 from a crate!'

Rank Progression Example

Code:

# Rank upgrade crate
rewards:
  1:
    slot: 13
    give-icon: false
    icon:
      material: NETHER_STAR
      name: '&bVIP Rank'
      lore:
        - '&7Upgrade to VIP rank'
        - '&aIncludes perks and benefits'
    commands:
      - 'lp user %player% parent set vip'
      - 'tellraw %player% {"text":"Welcome to VIP rank!","color":"gold"}'
      
  2:
    slot: 14
    give-icon: false
    icon:
      material: BEACON
      name: '&6MVP Rank'
      lore:
        - '&7Upgrade to MVP rank'
        - '&aIncludes all VIP perks plus more'
    commands:
      - 'lp user %player% parent set mvp'
      - 'broadcast %player% is now MVP rank!'

Custom Items Example

Code:

# Custom items with special properties
rewards:
  1:
    slot: 12
    give-icon: true
    icon:
      material: DIAMOND_SWORD
      name: '&cFlame Sword'
      enchantments:
        sharpness: 10
        fire_aspect: 3
        unbreaking: 5
      lore:
        - '&7A legendary sword forged'
        - '&7in the depths of the nether.'
        - ''
        - '&cDeal massive fire damage!'
    commands:
      - 'tellraw %player% {"text":"You obtained the Flame Sword!","color":"red"}'
      
  2:
    slot: 14
    give-icon: true
    icon:
      material: ELYTRA
      name: '&bWings of Freedom'
      enchantments:
        unbreaking: 10
        mending: 1
      lore:
        - '&7Mystical wings that never break'
        - '&7and repair themselves over time.'
    commands:
      - 'effect give %player% slow_falling 30 0'
      - 'tellraw %player% {"text":"Feel the power of flight!","color":"aqua"}'

---

Multi-Language Support Example

Code:

# Spanish messages (messages.yml)
reloaded: "&aPlugin recargado en %ms%ms."
no_permission: "&cNo tienes permisos para usar este comando."
crate_not_found: "&cCaja con ese nombre no encontrada."
player_not_found: "&cJugador no encontrado."
key_given: "&aLlaves x%amount% de %crate% dadas exitosamente a %player%."
key_all_given: "&aLlaves x%amount% de %crate% dadas a todos los jugadores en línea."
key_received: "&a¡Has recibido x%amount% llaves de %crate%!"
no_key: "&c¡No tienes llaves para esta caja!"
inventory_full: "&cNo tienes suficiente espacio en tu inventario."

---

Congratulations!
You're now ready to create amazing crate experiences with DonutCrates!

Need help? Join our Discord Community for support and updates.

Happy crating!

Welcome!

DonutCrates - Complete Documentation

ShyamSai

𝐀𝐝𝐦𝐢𝐧𝐢𝐬𝐭𝐫𝐚𝐭𝐨𝐫𝐬

Table of Contents​

Installation & Setup​

Requirements​

Supported Hologram Plugins​

Installation Steps​

Commands & Permissions​

Player Commands​

Admin Commands​

Permission Nodes​

PlaceholderAPI Integration​

Available Placeholders​

Usage Examples​

Configuration Files​

Main Configuration (config.yml)​

Messages Configuration (messages.yml)​

Sound Configuration (sounds.yml)​

In-Game Editor Guide​

Accessing the Editor​

Editor Menu Structure​

Creating Your First Crate​

Managing Rewards​

Crate Configuration Files​

Crate File Structure​

Advanced Item Configuration​

Developer API​

Getting Started​

CrateAPI Usage​

PlayerDataAPI Usage​

Custom Events​

Troubleshooting​

Common Issues​

Debug Information​

Configuration Examples​

Economy Integration Example​

Rank Progression Example​

Custom Items Example​

Multi-Language Support Example​

Table of Contents

Installation & Setup

Requirements

Supported Hologram Plugins

Installation Steps

Commands & Permissions

Player Commands

Admin Commands

Permission Nodes

PlaceholderAPI Integration

Available Placeholders

Usage Examples

Configuration Files

Main Configuration (config.yml)

Messages Configuration (messages.yml)

Sound Configuration (sounds.yml)

In-Game Editor Guide

Accessing the Editor

Editor Menu Structure

Creating Your First Crate

Managing Rewards

Crate Configuration Files

Crate File Structure

Advanced Item Configuration

Developer API

Getting Started

CrateAPI Usage

PlayerDataAPI Usage

Custom Events

Troubleshooting

Common Issues

Debug Information

Configuration Examples

Economy Integration Example

Rank Progression Example

Custom Items Example

Multi-Language Support Example