DreamCrates |  Advanced Animated Crates & Rewards ✨ [1.21.1+] 1.0.0 icon

DreamCrates | Advanced Animated Crates & Rewards ✨ [1.21.1+] 1.0.0 -----

An amazing customizable crate plugin with animations, particles, and more!



DreamCrates Documentation

Table of Contents
  1. Installation
  2. Commands
  3. Permissions
  4. Configuration
  5. Crate Types
  6. Key System
  7. Reward System
  8. Animation Types
  9. Setup Guide
  10. FAQ
  11. Troubleshooting
  12. Support


1. Installation

  1. Download the latest version of DreamCrates
  2. Place the JAR file in your server's plugins folder
  3. Restart your server
  4. The plugin will generate default configuration files
  5. Edit the configuration files to customize crates and rewards
  6. 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

# Plugin Settings
settings:
  # Debug mode (enables additional logging for commands, etc.)
  debug: false

  # Language file to use
  language: "en_US"

  # Use holographic displays for crate names
  use-holograms: true

  # Check for updates on startup
  check-for-updates: true

# Hologram Settings
holograms:
  enabled: true
  height: 1.5
  line-spacing: 0.25

# 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!"

# Daily Login Bonus Settings
daily-login-bonus:
  enabled: true
  crate: "daily"
  key-type: "VIRTUAL"
  message: "&aYou received a daily login bonus key!"
  sound: "ENTITY_PLAYER_LEVELUP"

# Animation Settings
animations:
  # Spin animation settings
  spin:
    duration: 80
    sound: "BLOCK_NOTE_BLOCK_PLING"
    sound-volume: 0.5
    sound-pitch: 1.0

  # Flicker animation settings
  flicker:
    duration: 80
    sound: "BLOCK_NOTE_BLOCK_HAT"
    sound-volume: 0.5
    sound-pitch: 1.0

  # Drop animation settings
  drop:
    duration: 60
    sound: "ENTITY_ITEM_PICKUP"
    sound-volume: 0.5
    sound-pitch: 1.0

  # Wheel animation settings
  wheel:
    duration: 80
    sound: "BLOCK_NOTE_BLOCK_PLING"
    sound-volume: 0.5
    sound-pitch: 1.0

  # CSGO animation settings
  csgo:
    duration: 100
    sound: "UI_BUTTON_CLICK"
    sound-volume: 0.5
    sound-pitch: 1.0
 

crates.yml
Defines all crate types and their rewards:

Code (Text):

crates:
  # Common Crate
  common:
    display-name: "&aCommon Crate"
    gui-size: 27
    animation: "SPIN"
    key-type: "PHYSICAL"
    key-material: "TRIPWIRE_HOOK"
    hologram-color: "&a" # Green for common
    sounds:
      - "ENTITY_PLAYER_LEVELUP"
      - "ENTITY_FIREWORK_ROCKET_BLAST"
    particles:
      - "END_ROD"
      - "WITCH"
    rewards:
      iron_ingot:
        material: "IRON_INGOT"
        amount: 8
        display-name: "&fIron Ingot"
        lore:
          - "&7A common metal."
          - "&7From Common Crate"
        rarity: "COMMON"
        weight: 10.0
        commands:
          - "eco give {player} 50"
          - "tell {player} You received 50 coins with your iron ingots!"

      diamond:
        material: "DIAMOND"
        amount: 1
        display-name: "&bDiamond"
        lore:
          - "&7A rare gem."
          - "&7From Common Crate"
        rarity: "RARE"
        weight: 1.0
       
  # 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):

Code (Text):

locations:
  cd28c032-c3b8-4ac0-b7b7-63bd438f1836:
    crate-name: "common"
    world: "world"
    x: 100.5
    y: 64.0
    z: 200.5
  7ae3bd12-a7f1-42c8-9531-d2b6842f5e92:
    crate-name: "rare"
    world: "world"
    x: 120.5
    y: 65.0
    z: 210.5
 


5. Crate Types

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:

  1. Install the plugin and restart your server
  2. Use /crate create common to create your first crate
  3. Look at a block (like a chest) and use /crate setlocation common
  4. Give yourself a key with /crate givekey YourName common 1 PHYSICAL
  5. Right-click the crate block to open it

Customizing a Crate:

  1. Open crates.yml
  2. Find your crate section (e.g., crates.common)
  3. Modify the display name, animation, sounds, particles, etc.
  4. Add your own rewards under the rewards section
  5. Set the weight for each reward to control its drop chance
  6. Use /crate reload to apply your changes

Adding Command Rewards:

  1. Open crates.yml
  2. Add a new reward under your crate's rewards section
  3. Set command-only: true for rewards that only execute commands
  4. Add commands under the commands section
  5. Use placeholders like {player} in your commands

Setting Up Daily Login Bonus:

  1. Open config.yml
  2. Set daily-login-bonus.enabled to true
  3. Set daily-login-bonus.crate to your daily crate name
  4. Configure the crate in crates.yml
  5. 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


12. Support

If you need help with DreamCrates, you can:


Reporting Bugs:
When reporting bugs, please include:
  • Plugin version
  • Server version
  • Error messages (if any)
  • Steps to reproduce the issue
  • Relevant configuration files

Thank you for using DreamCrates!
Resource Information
Author:
----------
Total Downloads: 352
First Release: May 28, 2025
Last Update: May 28, 2025
Category: ---------------
All-Time Rating:
3 ratings
Version -----
Released: --------------------
Downloads: ------
Version Rating:
----------------------
-- ratings