Nexal Heads

A player head drop plugin: when a player is killed in PvP, their head can drop as a trophy that names the victim, the killer and the time of the kill. Drop chances are configurable per permission tier and grow with Looting, drops can be switched off per world or globally, and every drop and collection is tracked for statistics and a leaderboard. With Vault, a head can be right-clicked to claim a share of the victim's balance.

Features

Configurable Drop Chance - Set the base percentage chance (0-100%) for heads to drop when players are killed by other players
Permission-Based Chance Tiers - VIP/MVP/Elite (or any tier you define) get their own drop chance; a player holding several tiers gets the highest
Looting Enchantment Bonus - Looting on the killer's weapon adds a configurable bonus per level
World Blacklist - Configure specific worlds where heads will never drop
Trophy Head Lore - Heads display killer name, victim name, date and time with customizable formatting
Kill Broadcast Messages - Server-wide announcements when heads drop
Sound Effects - Sounds when heads drop, are collected and are claimed
Statistics Tracking - How many times each player's head has dropped and how many heads they have collected. A head counts once, for the first player other than its victim who picks it up
Leaderboard System - Top head collectors with /heads top
Head Economy - With Vault, heads show a share of the victim's current balance and can be right-clicked to claim it. The value refreshes while the head is in an inventory, and disappears from the lore when the economy is turned off
Admin Commands - Give heads manually, toggle drops globally, export, import and reload
Admin GUI - /heads admin opens a menu with Configuration, a head drops toggle, Export, Import and Reload. Configuration edits every gameplay setting in config.yml (drop chance, looting bonus, chance tiers, blacklisted worlds, economy, claim percentage, head value refresh interval) and saves each change as you click
PlaceholderAPI Integration - Placeholders for stats, drop chance and the top collector, including for offline players
Dual Storage - JSON (data.json) or MySQL/MariaDB, with export and import to move between them. Statistics are kept in memory and saved off the main thread
Persistent Data Container - Uses PDC to store killer, victim and timestamp metadata on heads

Technologies

Paper API 1.20.1+ - Minecraft server API (Spigot compatible)
Utilizer - Configuration, messages, items, tasks and color formatting
ACF (Aikar Command Framework) - Annotation-based command system
nexal-core - JSON and SQL (MySQL/MariaDB) persistence, help menu
PlaceholderAPI - Placeholder integration (optional)
Vault - Economy for claiming heads (optional)

Commands

Player Commands

Command	Description	Permission
`/heads`	Show help menu	None
`/heads help [page]`	Show help menu	None
`/heads stats [player]`	View head statistics of yourself or another player, online or offline	`nexalheads.stats`
`/heads top`	View leaderboard of most heads collected	`nexalheads.top`

Aliases: /head, /nexalheads.

Admin Commands

Admin commands are hidden from players without the nexalheads.admin permission. Use /heads admin help to see available admin commands.

Command	Description	Permission
`/heads admin`	Open the admin menu (console: admin help)	`nexalheads.admin`
`/heads admin help [page]`	Show admin commands	`nexalheads.admin`
`/heads admin give \<player> \<skull_owner>`	Give a player head to someone; if their inventory is full it drops at their feet	`nexalheads.admin`
`/heads admin toggle`	Toggle head drops globally on/off (saved to `config.yml`)	`nexalheads.admin`
`/heads admin export`	Export statistics to `export/heads_stats.json`	`nexalheads.admin`
`/heads admin import`	Import statistics from `export/heads_stats.json`	`nexalheads.admin`
`/heads admin reload`	Reload `config.yml` and `messages.yml`	`nexalheads.admin`

Admin GUI

Screen	Contents
Admin menu (`/heads admin`)	Configuration, Head Drops toggle, Export Data, Import Data (shift+left click), Reload, Close
Configuration	Head Drops, Drop Chance, Looting Bonus, Chance Tiers, Blacklisted Worlds, Economy, Claim Percentage, Lore Update Interval, Back, Close
Chance Tiers	The chance of each tier under `permission-chances` (tiers are added or removed in `config.yml`); a tier whose value is not a number is marked as ignored and cannot be edited here
Blacklisted Worlds	Every loaded or blacklisted world; click to blacklist it or allow drops again

Numbers: left click +1, right click -1, shift for +10/-10. Percentages stay between 0 and 100; the refresh interval between 1 and 1200 ticks.

Permissions

Permission	Description	Default
`nexalheads.stats`	View head statistics	true
`nexalheads.top`	View leaderboard	true
`nexalheads.admin`	Admin menu and every `/heads admin` command (give, toggle, export, import, reload)	op
`nexalheads.chance.vip`	VIP drop chance (25% default)	false
`nexalheads.chance.mvp`	MVP drop chance (40% default)	false
`nexalheads.chance.elite`	Elite drop chance (60% default)	false
`nexalheads.chance.\<tier>`	Drop chance of any other tier under `permission-chances`	false

The chance permissions are false for operators too: grant them through your permissions plugin.

Placeholders

Requires PlaceholderAPI.

Placeholder	Description
`%nexalheads_dropped%`	Times the player's head has dropped (works for offline players)
`%nexalheads_collected%`	Number of heads the player has collected (works for offline players)
`%nexalheads_top_collector%`	Name of the player with the most heads collected, or `None`
`%nexalheads_chance%`	Player's current drop chance percentage (online players only)

Configuration

config.yml

# Drop chance percentage (0-100)
drop-chance: 10

# Looting enchantment bonus per level (added to base chance)
looting-bonus-per-level: 5

# Whether head drops are currently enabled
enabled: true

# World blacklist - worlds where heads won't drop
blacklisted-worlds:
  - "spawn"
  - "hub"

# Permission-based chance modifiers
# "nexalheads.chance.\<key>" gives this chance instead of the base chance.
# A player holding several tiers gets the highest one. Values must be plain numbers.
permission-chances:
  vip: 25
  mvp: 40
  elite: 60

# Head item customization
head:
  # Placeholders: %victim%, %killer%, %date%, %time%
  display-name: "<gradient:#FF69B4:#FF85C8>\<bold>%victim%'s Head\</bold>\</gradient>"
  lore:
    - ""
    - "<gradient:#AAAAAA:#BBBBBB>● Victim »\</gradient> \<white>%victim%\</white>"
    - "<gradient:#AAAAAA:#BBBBBB>● Killer »\</gradient> \<white>%killer%\</white>"
    - "<gradient:#AAAAAA:#BBBBBB>● Date »\</gradient> <gradient:#FF9DCE:#FFB8DC>%date%\</gradient>"
    - "<gradient:#AAAAAA:#BBBBBB>● Time »\</gradient> <gradient:#FF9DCE:#FFB8DC>%time%\</gradient>"
    - ""
  # Extra lines shown only while the economy is enabled. Placeholder: %balance%
  economy-lore:
    - "<gradient:#2ECC71:#52D68A>● Value »\</gradient> \<white>$%balance%\</white>"
    - ""
    - "<gradient:#FFC107:#FFCD38>Right-click to claim!\</gradient>"

# Storage type: "json" or "sql"
storage:
  type: json
  sql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

# Economy settings (requires Vault)
economy:
  enabled: false
  # Percentage of the victim's balance a head is worth (0-100)
  balance-percentage: 10
  # How often head lore updates with the current balance (in ticks, 20 = 1 second)
  update-interval: 20

messages.yml

All messages are fully customizable using MiniMessage format with gradient support, and can carry a sound. Messages added in an update that your messages.yml does not have yet use the bundled text; the file itself is not changed. The plugin uses a pink color scheme:

PRIMARY: <gradient:#FF69B4:#FF85C8> (pink)
SECONDARY: <gradient:#FF9DCE:#FFB8DC> (light pink)

Messages include:

Head drop broadcasts and head collection notifications
Statistics displays and leaderboard formatting
Head claim messages for the claimer and the victim, and claim errors
Admin action confirmations
Error messages

You can customize all colors by using find-and-replace in your text editor.

Data Storage

Statistics are kept in memory. Changes are saved off the main thread every 5 seconds, and once more when the server stops.

JSON

With storage.type: json, everything lives in a single data.json:

&#123;
  "nexalheads_stats": &#123;
    "uuid-1": &#123;
      "id": "uuid-1",
      "player_name": "Player1",
      "heads_dropped": 5,
      "heads_collected": 12,
      "last_updated": 1704312000000
    &#125;
  &#125;
&#125;

Database Schema

With storage.type: sql, the plugin creates the following table:

`nexalheads_stats`

Column	Type	Key	Description
`id`	VARCHAR(36)	PK	Player UUID
`player_name`	VARCHAR(16)		Player's last known name
`heads_dropped`	INT		Number of times this player's head has dropped
`heads_collected`	INT		Number of heads this player has collected
`last_updated`	BIGINT		Last update timestamp (milliseconds)

Key Legend: PK = Primary Key

Migrating between JSON and SQL

/heads admin export writes every player's statistics to plugins/NexalHeads/export/heads_stats.json
Set storage.type in config.yml and restart the server
/heads admin import loads the file into the new storage, overwriting players already stored

Head Metadata

Each dropped head carries PersistentDataContainer (PDC) metadata:

killer - UUID of the player who got the kill
victim - UUID of the player whose head dropped
timestamp - Time when the head was created (milliseconds)
collected - Set on the first pickup that counted, so picking the head up again does not count twice
economy_lore - Set while the head shows its claimable value

This metadata is used to tell plugin heads apart from regular player heads. Heads given with /heads admin give have none of it: they are decorative and cannot be claimed.

Drop Chance Calculation

The plugin calculates drop chance as follows:

Check Permission Chances - If the killer holds any nexalheads.chance.\<tier> permissions, use the highest of those tiers' chances
Use Base Chance - Without a tier permission, use the drop-chance config value
Add Looting Bonus - If the killer's weapon has Looting, add looting-bonus-per-level * level

Example:

Base chance: 10%
Killer has the VIP (25%) and Elite (60%) permissions: Elite wins
Killer has a Looting III sword (+15% bonus)
Total chance: 75%

Installation

Download the plugin JAR
Place it in your server's /plugins folder
Restart the server
(Optional) Edit config.yml and messages.yml to customize settings
(Optional) Install PlaceholderAPI for placeholder support and Vault for the head economy
Use /heads admin reload to apply config changes without restarting

Usage Examples

For Players

/heads stats           # View your own statistics
/heads stats Notch     # View Notch's statistics, even while Notch is offline
/heads top             # See who has collected the most heads

For Admins

/heads admin                   # Open the admin menu
/heads admin give Steve Notch  # Give Steve a head of Notch
/heads admin toggle            # Disable/enable head drops
/heads admin reload            # Reload config after changes

Features​

Technologies​

Commands​

Player Commands​

Admin Commands​

Admin GUI​

Permissions​

Placeholders​

Configuration​

config.yml​

messages.yml​

Data Storage​

JSON​

Database Schema​

nexalheads_stats​

Migrating between JSON and SQL​

Head Metadata​

Drop Chance Calculation​

Installation​

Usage Examples​

For Players​

For Admins​