# Lootboxes

### Creating Lootboxes

#### Example.yml

```yaml
# ===========================================
# 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)

```yaml
# ===========================================
# 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

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rabbit-tale-studio.gitbook.io/rabbit-tale-plugins/plugin-wiki/quickstart/configuration/lootboxes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.