Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
HeadDB
HeadDB is a modern head database plugin for Paper and Folia servers. It lets players browse, search, favorite, price, edit, and obtain Minecraft head items through a clean GUI, while giving server owners full control over permissions, local custom heads, custom categories, messages, GUI layout, and optional economy pricing.
Features
Remote head database
HeadDB loads heads from a public remote database and verifies downloaded data before using it.
Features include:
- Remote head catalog
- Categories, tags, and collections
- SHA-256 artifact verification
- Local cache loading on startup
- Remote refresh support
- Cache fallback support
Paper and Folia support
HeadDB supports both Paper and Folia.
Requirements
- Java 25
- Paper or Folia
- Network access
- Vault and an economy provider if economy support is enabled
The API and core modules target Java 21. The Paper plugin targets Java 25.
Modern GUI
Players can use /hdb to open the main menu and browse heads without typing long commands.
The GUI includes:
- Category browsing
- Search
- Favorites
- Player heads
- More Heads
- More Categories
- Settings
- Admin-only hidden heads
- Paginated result pages
- Next, previous, and back navigation
GUI buttons, icons, names, lore, and layout can be configured through gui.yml.
Search and filters
Players can search for heads and browse results in a paginated inventory GUI.
Search supports:
- Text queries
- Categories
- Tags
- Collections
- Sort options
- Page navigation
Favorites
Players can favorite heads and access them later from the Favorites menu.
Favorites are stored locally and persist across restarts.
Player heads
HeadDB supports player heads separately from the remote database.
Server owners can control player-head access through permissions.
More Heads
More Heads are local custom heads created on your server.
They are useful for:
- Server-specific decorations
- Event heads
- Staff heads
- Donator heads
- Seasonal content
- Heads not present in the remote database
More Heads are stored locally and do not modify the remote database.
More Categories
More Categories are local custom categories created on your server.
A custom category can contain:
- Remote heads
- More Heads
- Player heads
This lets you create server-specific collections such as:
- Spawn decorations
- Event rewards
- Shop items
- Seasonal heads
- Staff picks
- Builder favorites
Custom categories do not change the original category of a head.
Admin Mode
Admin Mode exposes additional controls in the GUI.
Admin tools include:
- Head editing
- Button configuration
- Hidden-head browsing
- Custom category administration
- Extra debug/details in menus
This keeps normal player menus clean while still giving administrators powerful editing tools.
Local head overrides
Admins can override head metadata locally without changing the remote database.
Supported actions include:
- Rename heads
- Edit lore
- Change category
- Change tags
- Change collections
- Hide/show heads
- Reset local overrides
Optional Vault economy support
HeadDB can charge players when they take heads.
Economy support is disabled by default and requires Vault plus an economy provider.
Pricing supports:
- Global fallback price
- Player-head price
- Category prices
- Custom category prices
- Specific head prices
Price priority:
- Specific head price
- Custom category price
- Player-head price
- Normal category price
- Fallback price
Permission-first design
HeadDB uses granular permissions and top-level permission bundles.
This makes it easy to give players broad access with simple permissions, while still allowing advanced servers to control every action individually.
Common top-level permissions include:
headdb.basicheaddb.openheaddb.browseheaddb.searchheaddb.head.takeheaddb.admin
Installation
- Download the latest HeadDB jar.
- Place it in your server’s
pluginsfolder. - Restart the server.
- Configure the generated files if needed.
Generated files include:
config.ymlgui.ymleconomy.ymlmessages/en-US.ymlstorage/headdb.db
Vault is optional. Economy features only require Vault if economy is enabled.
Basic Usage
Open the main GUI:
/hdb
Open the main GUI explicitly:
/hdb open
Search heads:
/hdb search <query>
Give yourself a head:
/hdb give <id>
Get information about a head:
/hdb info <id>
Inspect the held head:
/hdb info
Verify the remote database:
/hdb verify
Refresh the database:
/hdb refresh
Reload configuration:
/hdb reload
Commands
General:
/hdb/hdb help/hdb status/hdb debug/hdb verify/hdb refresh/hdb reload
GUI:
/hdb open/hdb open <category> [player]
Search and lookup:
/hdb search <query>/hdb info [id]/hdb random [amount] [category] [player]
Giving heads:
/hdb give <id> [player] [amount]
Player heads:
/hdb player <player> [target] [amount]
More Heads:
/hdb custom list [page]/hdb custom info <id>/hdb custom create <id> <texture> <name>/hdb custom createheld <id> <name>/hdb custom delete <id>/hdb custom rename <id> <name>/hdb custom give <id> [player] [amount]
Editing:
/hdb edit [id]
Database browsing helpers:
/hdb categories [page]/hdb tags [query] [page]/hdb collections [query] [page]
Item cache:
/hdb itemcache clear
Permissions
HeadDB has two permission layers:
- Top-level permissions for easy setup
- Granular permissions for advanced control
Recommended player permission
headdb.basic
This grants basic player access:
- Open the main menu
- Browse categories
- Search heads
- Use favorites
- Take heads from GUIs
- Access basic settings/language options
Admin permission
headdb.admin
Grants full access.
Top-level permissions
headdb.adminheaddb.basicheaddb.openheaddb.browseheaddb.searchheaddb.head.takeheaddb.giveheaddb.give.othersheaddb.player-headsheaddb.player-heads.othersheaddb.more-headsheaddb.more-heads.giveheaddb.more-heads.give.othersheaddb.more-heads.adminheaddb.favoritesheaddb.more-categoriesheaddb.more-categories.adminheaddb.settingsheaddb.admin-modeheaddb.head-editheaddb.gui-adminheaddb.database
Common setups
Browse only:
headdb.openheaddb.browse
Browse and take heads:
headdb.openheaddb.browseheaddb.head.take
Normal player:
headdb.basic
Full admin:
headdb.admin
Category permissions
headdb.category.*headdb.category.<category-id>
Category permissions only control category visibility/access. They do not grant command access, GUI opening, or head taking by themselves.
Economy
Economy support is configured in economy.yml.
Default configuration:
enabled: false provider: vault
prices: any-head: 0.0 player-heads: 0.0 categories: {} custom-categories: {} heads: {}
Example:
enabled: true provider: vault
prices: any-head: 5.0 player-heads: 25.0
categories: alphabet: 10.0 animals: 12.5
custom-categories: "1": 30.0 "2": 50.0
heads: "1": 100.0 custom:melon: 75.0 player:f16df3ef-06b8-443e-9166-fba6689585b4: 200.0
If economy is disabled, heads are free.
If economy is enabled but Vault or an economy provider is unavailable, HeadDB logs a warning and does not charge players.
Head IDs
HeadDB uses typed head IDs.
Examples:
123custom:melonplayer:f16df3ef-06b8-443e-9166-fba6689585b4
Configuration
HeadDB creates several configuration files:
config.ymlgui.ymleconomy.ymlmessages/en-US.yml
config.yml
Controls:
- Remote database loading
- Cache behavior
- HTTP timeouts
- Startup refresh behavior
- Debug behavior
- Root command GUI behavior
gui.yml
Controls:
- GUI layout
- Button slots
- Materials
- Names
- Lore
- Icons
economy.yml
Controls:
- Economy enable/disable
- Economy provider
- Global prices
- Category prices
- Custom category prices
- Per-head prices
messages/en-US.yml
Controls localized messages.
API
HeadDB exposes a public Java API for other plugins.
External plugins can access HeadDB through Bukkit’s service provider system.
Example:
RegisteredServiceProvider<HeadDBService> registration = Bukkit.getServicesManager().getRegistration(HeadDBService.class);
if (registration == null) { return; }
HeadDBService headDB = registration.getProvider();
Example lookups:
headDB.find("123"); headDB.find("custom:melon"); headDB.customHeads().list(); headDB.favorites().ids(player.getUniqueId()); headDB.customCategories().list();