💀 Head Plugin

---

✨ Overview

A feature-rich plugin that adds a rewarding mechanic to PvP and PvE: dropping player heads on death! Fully customizable with lore support to memorialize epic battles.

---

🚧 Development & Support

HeadPlugin is currently in active development! Many more features, flexible layouts, and extended customization options are planned for future updates.

If you need support, want to report an issue, or have a great idea for a new feature you'd like to see added, please join our Discord Server! We would love to hear your feedback and suggestions.

---

🌟 Features

• 🎯 Customizable Drop Rates: Set the percentage chance (0% - 100%) for a head to drop.
• 📜 Rich Lore Support: Heads can display:
  • Name of the Victim
  • Name of the Killer (if PvP)
  • Cause of Death (if PvE)
  • Date and Time of death
• 📍 Flexible Drop Locations:
  • Ground: Drop item naturally at the death location.
  • Inventory: Directly place the head in an inventory.
• 🎒 Inventory Targeting: Choose who gets the head - the Victim, the Killer, or Both.
• 🛑 Anti-Abuse Limits: Set a maximum lifetime limit of heads a player can drop to prevent farming.
• 🏗️ Placement Protection: Optionally prevent players from placing heads to ensure the lore is preserved and not lost to block data.
• 📢 Broadcast System: Announce head drops to the entire server.

---

📜 Commands & Permissions

Command	Description	Permission
/headplugin reload	🔄 Reloads the configuration	headplugin.admin
/headplugin status	📡 Displays plugin version	(None)
(None)	🎁 Ability to drop heads on death	headplugin.drop

---

📷 Photo Examples

Note: If it's another player that killed the victim, it will show "Killed by..." (see config.yml below). Conversely, if it's an environmental death, the cause will be displayed as shown in the example.

---

🎥 Video

---

⚙️ Configuration

Customize drop rates, messages, and lore formats in config.yml.

# HeadPlugin Configuration v1.0
#
# A plugin that drops player heads on death with customizable lore, names, and limits.
#

# The percentage chance that a head will drop (0.0 to 100.0)
drop-chance: 100.0

# Where the head should appear:
# - GROUND: Drops items on the ground where the player died.
# - INVENTORY: Added directly to the player's inventory (see inventory-target).
spawn-location: GROUND

# If spawn-location is INVENTORY, who should receive the head?
# Options: VICTIM, KILLER, BOTH
# Default: VICTIM (to match original behavior)
inventory-target: BOTH

# If true, heads will ONLY drop if the player was killed by another player (PvP).
# If false, heads can drop from any death cause (PvE, ✨, etc).
victim-only: false

# Prevent players from placing the head on the ground?
# This prevents the lore (Killer, Date) from being lost.
# Default: true
prevent-head-placement: true

# Maximum number of heads a player can drop IN TOTAL (Lifetime limit).
# If a player has already dropped this many heads, they will not drop any more.
max-heads: 1

# Message sent to player when they receive a head (leave empty to disable)
# %player% is replaced with the name of the head owner.
head-received-message: "&aYou have retrieved %player%'s head!"
head-received-killer-message: "&aYou executed %player% and took their head!"

# ==========================================
#              Head Customization
# ==========================================

# The display name of the head item.
# Placeholders: <player>
head-name: "&d<player>'s Head"

# Lore (Item Description) Configuration
lore:
    # Date format used in the date line (Java SimpleDateFormat)
    # Common examples: "dd/MM/yyyy HH:mm", "MM-dd-yyyy"
    date-format: "dd/MM/yyyy HH:mm"

    # Line displayed when a player is killed by another entity/player
    # Placeholders: <killer>
    killer-line: "&cKilled by <killer>"
    
    # Line displayed when a player dies from the environment (fall, lava, etc.)
    # Placeholders: <cause>
    environment-line: "&cDied by <cause>"
    
    # Line displayed for the date
    # Placeholders: <date>
    date-line: "&cDate: <date>"

# ==========================================
#                Broadcasts
# ==========================================

broadcast:
    # Whether to announce head drops in chat to everyone.
    enabled: true
    
    # Message to broadcast
    # Placeholders: <player>, <killer> (empty if no killer)
    # Note: If there is no killer, you might want a generic message or the plugin handles "Unknown" for <killer>.
    message: "&6<player> dropped their head!"

---

📥 Installation

1. Download the HeadPlugin.jar file.
2. Upload it to your server's plugins folder.
3. Restart your server to generate the default config.yml.
4. Customize the config.yml to set drop rates and lore messages.
5. Type /headplugin reload or restart your server to apply changes.

---

💎 Credits

• 👨‍💻 Development: Obsyron