Lootboxes
Creating Lootboxes
Example.yml
# ===========================================
# BASIC LOOTBOX CONFIGURATION DOCUMENTATION
# ===========================================
# Unique identifier for the lootbox
# Must be unique across all lootboxes
# Used in commands like /lb give <player> example
id: example
# Display name shown in inventory and when hovering
# Supports MiniMessage format for colors and effects
# Examples:
# - Simple gradient: <gradient:gold:yellow>Example Lootbox</gradient>
# - Rainbow text: <rainbow>Example Box</rainbow>
# - Basic color: <gold>Example Box</gold>
displayName: <gradient:gold:yellow>Example Lootbox</gradient>
# Lore shown when hovering over the lootbox
# Each line supports MiniMessage format
# Use empty string ('') for blank lines
lore:
- <gray>This is an example lootbox
- <gray>Contains various rewards
- '' # Empty line for spacing
- <yellow>From common to legendary items!
# Animation type when opening the lootbox
# Available types:
# - HORIZONTAL (default side-scrolling)
# - CIRCLE (rotating circle)
animationType: HORIZONTAL
# Tracks how many times this lootbox has been opened
# Automatically updated by the plugin
openedCount: 0
# List of all possible rewards
# Organized by rarity tiers for better readability
items:
# =====================
# COMMON TIER (60% total chance)
# Basic resources and materials
# =====================
'0':
id: common-stone # Unique identifier for this reward
chance: 15.0 # 15% chance to get this reward
rarity: COMMON # Affects particles and display
item:
type: STONE # Minecraft material type
amount: 32 # Amount to give
'1':
id: common-coal
chance: 15.0
rarity: COMMON
item:
type: COAL
amount: 16
'2':
id: common-logs
chance: 15.0
rarity: COMMON
item:
type: OAK_LOG
amount: 32
'3':
id: common-iron
chance: 15.0
rarity: COMMON
item:
type: IRON_INGOT
amount: 8
# =====================
# UNCOMMON TIER (25% total chance)
# Better resources and valuable materials
# =====================
'4':
id: uncommon-gold
chance: 8.0
rarity: UNCOMMON
item:
type: GOLD_INGOT
amount: 8
'5':
id: uncommon-diamonds
chance: 8.0
rarity: UNCOMMON
item:
type: DIAMOND
amount: 3
'6':
id: uncommon-emeralds
chance: 9.0
rarity: UNCOMMON
item:
type: EMERALD
amount: 5
# =====================
# RARE TIER (15% total chance)
# Valuable and hard-to-get items
# =====================
'7':
id: rare-netherite
chance: 5.0
rarity: RARE
item:
type: NETHERITE_INGOT
amount: 1
'8':
id: rare-gapple
chance: 5.0
rarity: RARE
item:
type: ENCHANTED_GOLDEN_APPLE
amount: 2
'9':
id: rare-diamond-blocks
chance: 5.0
rarity: RARE
item:
type: DIAMOND_BLOCK
amount: 2
# =====================
# EPIC TIER (7% total chance)
# End-game and special items
# =====================
'10':
id: epic-elytra
chance: 4.0
rarity: EPIC
item:
type: ELYTRA
amount: 1
'11':
id: epic-beacon
chance: 3.0
rarity: EPIC
item:
type: BEACON
amount: 1
# =====================
# LEGENDARY TIER (3% total chance)
# Extremely rare and valuable items
# =====================
'12':
id: legendary-dragon-egg
chance: 1.5
rarity: LEGENDARY
item:
type: DRAGON_EGG
amount: 1
'13':
id: legendary-nether-star
chance: 1.5
rarity: LEGENDARY
item:
type: NETHER_STAR
amount: 1
# List of placed lootbox locations
# Automatically managed by the plugin
locations: {}
# Note on chances:
# Total chances add up to 100%:
# - Common: 60% (15% × 4)
# - Uncommon: 25% (8% + 8% + 9%)
# - Rare: 15% (5% × 3)
# - Epic: 7% (4% + 3%)
# - Legendary: 3% (1.5% × 2)
# Additional features you can add:
#
# Key requirement:
#key_required: true
#key:
# material: TRIPWIRE_HOOK
# name: "<yellow>Basic Key"
# lore:
# - "<gray>Use this to open"
# - "<gray>the Example Lootbox"
#
# Custom item meta:
#item:
# type: DIAMOND_SWORD
# meta:
# display-name: "<blue>Special Sword"
# lore:
# - "<gray>A very special sword"
# enchants:
# DAMAGE_ALL: 5
# DURABILITY: 3
# glow: true
#
# Commands on win:
#action:
# type: COMMAND
# commands:
# - "give {player} diamond 1"
# - "broadcast {player} won a diamond!"
#
# Random amount ranges:
#item:
# type: DIAMOND
# amount: 1-5 # Random amount between 1 and 5
Example2.yml (custom items + virtual items)
# ===========================================
# LOOTBOX CONFIGURATION DOCUMENTATION
# ===========================================
# Unique identifier for the lootbox
# Must be unique across all lootboxes
# Used in commands and API
id: example2
# Display name of the lootbox
# Supports MiniMessage format (<color>, <gradient>, etc.)
# Examples:
# - "<red>Basic Lootbox"
# - "<gradient:red:gold>Epic Rewards</gradient>"
# - "<rainbow>Special Box</rainbow>"
displayName: <gradient:red:gold>Epic Rewards</gradient>
# Lore shown when hovering over the lootbox
# Supports MiniMessage format
# Each line is a new element in the list
# Use '' for empty lines
lore:
- <gray> • Virtual items
- <gray> • Custom weapons
- <gray> • Rare roles
- '' # Empty line
- <gold>Good luck!
# Animation type when opening the lootbox
# Available types:
# - HORIZONTAL (default sliding animation)
# - CIRCLE (items rotate in a circle)
animationType: CIRCLE
# Counter for how many times this lootbox has been opened
# Auto-incremented by the plugin
openedCount: 0
# List of possible rewards
# Each reward must have a unique ID within the lootbox
items:
# Example of a virtual currency reward
'0':
# Unique identifier for this reward
id: virtual-gold
# Chance of getting this reward (percentage)
chance: 35.0
# Rarity affects the display and particles
# Available: COMMON, UNCOMMON, RARE, EPIC, LEGENDARY
rarity: COMMON
# Item shown in the animation and given to player
item:
type: GOLD_INGOT # Minecraft material type
amount: 32
meta:
display-name: "<yellow>Pouch of gold"
lore:
- "<gold>1000 <white>gold"
# Actions executed when this reward is won
action:
type: COMMAND # Execute commands
commands:
- "eco give {player} 1000" # {player} is replaced with winner's name
# Example of a temporary permission reward (role)
'1':
id: vip-role
chance: 25.0
rarity: UNCOMMON
item:
type: NAME_TAG
meta:
display-name: "<white>[<green>VIP<white>] <gray>Role (7 days)"
lore:
- "<white>[<green>VIP<white>] <gray>rank for 7 days"
glow: true # Adds enchant glint
action:
type: PERMISSION # Grant temporary permissions
group: vip # LuckPerms group name
duration: 7d # Duration format: d(days), h(hours), m(minutes)
# Example of a custom item with enchants
'2':
id: special-elytra
chance: 20.0
rarity: RARE
item:
type: ELYTRA
meta:
display-name: "<light_purple>Wings of Freedom"
lore:
- "<gray>Legendary wings that grant"
- "<gray>unlimited flight"
enchants: # Standard Minecraft enchantments
PROTECTION_ENVIRONMENTAL: 4 # Protection IV
DURABILITY: 3 # Unbreaking III
glow: true
# Example of a longer duration role reward
'3':
id: mvp-role
chance: 15.0
rarity: EPIC
item:
type: TOTEM_OF_UNDYING
meta:
display-name: "<white>[<gold>MVP<red>++<white>] <gray>Role (30 days)"
lore:
- "<white>[<gold>MVP<red>++<white>] <gray>rank for 30 days"
glow: true
action:
type: PERMISSION
group: mvp++
duration: 30d
# Example of a permanent permission reward
'4':
id: owner-role
chance: 0.5 # Very rare: 0.5%
rarity: LEGENDARY
item:
type: DRAGON_EGG
meta:
display-name: "<white>[<dark_red><bold>Owner</bold><white>] <gray>Role (Permanent)"
lore:
- "<white>[<dark_red><bold>Owner</bold><white>] <gray>rank <gray>permanent"
glow: true
action:
type: PERMISSION
group: owner
duration: permanent # Permanent permission
# Example of an Oraxen custom item
# This item will be displayed as barrier block (unknown item)
'5':
id: excalibur-sword
chance: 0.5
rarity: LEGENDARY
oraxen_item: excalibur # Oraxen item ID
# List of placed lootbox locations
# Automatically managed by the plugin
locations: {}
# Optional key requirement
# If present, requires a key to open
# Example:
#key_required: true
#key:
# material: TRIPWIRE_HOOK
# name: "<gold>Epic Key"
# lore:
# - "<gray>Use this to open"
# - "<gray>the Epic Rewards box!"
# Additional examples of reward types:
#
# Multi-command reward:
# action:
# type: COMMAND
# commands:
# - "give {player} diamond 64"
# - "eco give {player} 5000"
# - "broadcast {player} won the jackpot!"
#
# Custom item with NBT:
# item:
# type: PLAYER_HEAD
# meta:
# display-name: "<rainbow>Rainbow Head</rainbow>"
# skull-texture: "eyJ0ZXh0dXJlcyI6ey..."
#
# Random amount reward:
# item:
# type: DIAMOND
# amount: 5-10 # Random amount between 5 and 10
#
# Multiple actions:
# action:
# - type: COMMAND
# commands: ["eco give {player} 1000"]
# - type: PERMISSION
# group: vip
# duration: 7d
Last updated