Place the JAR file in your server's plugins folder
Restart your server
The plugin will generate default configuration files
Edit the configuration files to customize crates and rewards
Use the commands below to create and place your first crate
Requirements:
Paper 1.21.1 or higher
Java 21 or higher
2. Commands
Command
Description
Permission
/crate
Main command for DreamCrates
dreamcrates.command
/crate help
Shows help information
dreamcrates.command
/crate create <name>
Creates a new crate
dreamcrates.admin.create
/crate delete <name>
Deletes a crate
dreamcrates.admin.delete
/crate givekey <player> <crate> [amount] [type]
Gives keys to a player
dreamcrates.admin.givekey
/crate reload
Reloads the plugin configuration
dreamcrates.admin.reload
/crate setlocation <crate>
Sets the location of a crate
dreamcrates.admin.setlocation
/crate preview <crate>
Previews crate rewards
dreamcrates.preview
Command Examples:
Code (Text):
/crate create common
/crate setlocation common
/crate givekey Steve common 5 PHYSICAL
/crate givekey Alex rare 1 VIRTUAL
/crate preview legendary
3. Permissions
Permission
Description
Default
dreamcrates.command
Allows use of the /crate command
true
dreamcrates.preview
Allows previewing crate rewards
true
dreamcrates.admin.create
Allows creating crates
op
dreamcrates.admin.delete
Allows deleting crates
op
dreamcrates.admin.givekey
Allows giving keys to players
op
dreamcrates.admin.reload
Allows reloading the plugin
op
dreamcrates.admin.setlocation
Allows setting crate locations
op
dreamcrates.admin
Grants all admin permissions
op
Permission Groups Example (LuckPerms):
Code (Text):
/lp group admin permission set dreamcrates.admin true
/lp group moderator permission set dreamcrates.admin.givekey true
/lp group default permission set dreamcrates.preview true
4. Configuration
DreamCrates uses three main configuration files:
config.yml Contains general settings for the plugin:
Code (Text):
# DreamCrates - Main Configuration
# This file contains general settings for the plugin
# Message Settings
messages:
prefix: "&8[&bDreamCrates&8] "
no-permission: "&cYou don't have permission to do that!"
crate-created: "&aCrate '%name%' created successfully!"
crate-deleted: "&aCrate '%name%' deleted successfully!"
crate-not-found: "&cCrate '%name%' not found!"
key-given: "&aGave %amount% key(s) for '%name%' to %player%!"
key-received: "&aYou received %amount% key(s) for '%name%'!"
no-key: "&cYou don't have a key for this crate!"
inventory-full: "&cYour inventory is full! Some items were dropped on the ground."
reward-received: "&aYou received: %reward%"
legendary-broadcast: "&6&l%player% &eunboxed a &6&lLEGENDARY &eitem from a %crate%&e!"
commands-executed: "&aBonus rewards have been added to your account!"
# Command-only reward example
coins_50:
material: SUNFLOWER
amount: 1 # Must be at least 1
command-only: true # This makes it a command-only reward
display-name: "&e50 Coins"
lore:
- "&7Adds 50 coins to your account."
- "&7From Common Crate"
rarity: COMMON
weight: 10.0
commands:
- "eco give {player} 50"
- "tell {player} You received 50 coins!"
locations.yml Stores the physical locations of placed crates (automatically generated):
DreamCrates allows you to create unlimited crate types. Each crate type can have its own:
Display Name - The name shown in GUIs and holograms
GUI Size - The size of the inventory (must be a multiple of 9)
Animation - The opening animation type
Key Type - PHYSICAL or VIRTUAL
Key Material - The material for physical keys
Hologram Color - The color of the hologram text
Sounds - Sounds played when opening the crate
Particles - Particles shown around the crate
Rewards - The items that can be won from the crate
Default Crate Types:
Common - Basic rewards with high chance
Rare - Better rewards with medium chance
Epic - Valuable rewards with low chance
Legendary - Best rewards with very low chance
Daily - Given to players once per day
Vote - Given to players when they vote
6. Key System
DreamCrates supports two types of keys:
Physical Keys Physical keys are actual items in the player's inventory:
Configured with key-type: "PHYSICAL" in crates.yml
The material is set with key-material
Can have custom name and lore
Can have a glow effect (enabled by default)
Are consumed when used
Virtual Keys Virtual keys are stored in the plugin's data and not in the player's inventory:
Configured with key-type: "VIRTUAL" in crates.yml
Don't take up inventory space
Are consumed when used
Players can see how many they have when they right-click a crate
Giving Keys: Use the command:
/crate givekey <player> <crate> [amount] [type]
player - The player's name
crate - The name of the crate
amount - How many keys to give (default: 1)
type - PHYSICAL or VIRTUAL (default: the crate's configured key type)
7. Reward System
Reward Properties:
material - The Minecraft item material
amount - How many of the item to give
display-name - Custom name for the item
lore - Custom lore for the item
rarity - COMMON, UNCOMMON, RARE, EPIC, LEGENDARY, or VOTE
weight - The chance of getting this reward (higher = more likely)
enchantments - Custom enchantments for the item
commands - Commands to execute when the reward is given
command-only - Set to true if the reward should only run commands (no item)
Reward Weights and Rarities: The chance of getting a reward is calculated as:
Code (Text):
Chance = (Reward Weight / Total Weight of All Rewards) * 100%
Example:
Reward A: Weight 10
Reward B: Weight 5
Reward C: Weight 1
Total Weight: 16
Chance of Reward A: (10/16) * 100% = 62.5%
Chance of Reward B: (5/16) * 100% = 31.25%
Chance of Reward C: (1/16) * 100% = 6.25%
Command Placeholders: These placeholders can be used in reward commands:
{player} - Player's name
{player_uuid} - Player's UUID
{world} - World name
{crate} - Crate name
{reward} - Reward ID
8. Animation Types
DreamCrates offers 5 unique animation types:
SPIN
Items rotate around the GUI border
Duration: 80 ticks (4 seconds) by default
Good for common crates
FLICKER
Item appears and disappears in the center
Duration: 80 ticks (4 seconds) by default
Good for daily/vote crates
DROP
Item drops from the top to bottom of GUI
Duration: 60 ticks (3 seconds) by default
Good for legendary crates
WHEEL
A wheel of items rotates with an indicator
Duration: 80 ticks (4 seconds) by default
Good for rare crates
CSGO
Items scroll horizontally like CS:GO cases
Duration: 100 ticks (5 seconds) by default
Good for epic crates
9. Setup Guide
Basic Setup:
Install the plugin and restart your server
Use /crate create common to create your first crate
Look at a block (like a chest) and use /crate setlocation common
Give yourself a key with /crate givekey YourName common 1 PHYSICAL
Right-click the crate block to open it
Customizing a Crate:
Open crates.yml
Find your crate section (e.g., crates.common)
Modify the display name, animation, sounds, particles, etc.
Add your own rewards under the rewards section
Set the weight for each reward to control its drop chance
Use /crate reload to apply your changes
Adding Command Rewards:
Open crates.yml
Add a new reward under your crate's rewards section
Set command-only: true for rewards that only execute commands
Add commands under the commands section
Use placeholders like {player} in your commands
Setting Up Daily Login Bonus:
Open config.yml
Set daily-login-bonus.enabled to true
Set daily-login-bonus.crate to your daily crate name
Configure the crate in crates.yml
Players will receive a key when they login each day
10. Frequently Asked Questions
Q: How do I change the animation for a crate? A: Edit the
animation property in
crates.yml for your crate. Available options are SPIN, FLICKER, DROP, WHEEL, and CSGO.
Q: Can players have multiple keys? A: Yes, players can have multiple physical or virtual keys for any crate.
Q: How do I add economy rewards? A: Add a command-only reward with the command
eco give {player} 1000 (requires an economy plugin).
Q: Can I change the particles around crates? A: Yes, modify the
particles list in
crates.yml for your crate.
Q: How do I make a reward rarer? A: Lower the
weight value for that reward in
crates.yml.
Q: Can I disable holograms? A: Yes, set
holograms.enabled to
false in
config.yml.
Q: How do I make my own crate? A: Use
/crate create <name>, then configure it in
crates.yml.
Q: How do I give all players keys? A: Use a command like
/execute as @a run crate givekey @s common 1 VIRTUAL.
11. Troubleshooting
Issue: Crate doesn't appear at location
Make sure holograms are enabled in config.yml
Try using /crate reload to refresh crates
Check if the world is loaded correctly
Issue: Animation doesn't work
Make sure the animation type is valid
Check if the GUI size is a multiple of 9
Try a different animation type
Issue: Key doesn't work
Make sure you're using the correct key for the crate
Check if the player has permission to use the crate
Try giving a new key with /crate givekey
Issue: Commands don't execute
Make sure the commands are valid
Check if you have the required plugins for economy commands
Enable debug mode in config.yml to see command execution logs
Issue: Plugin conflicts
Check for conflicts with other crate plugins
Make sure you're using the correct version for your server
Disable other plugins that might modify inventories