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