HeadDB
A modern, configurable head database for Paper and Folia servers.
A modern, configurable head database for Paper and Folia servers.
HeadDB gives players a clean, inventory-based interface for browsing, searching, favoriting, editing, optionally purchasing, and obtaining Minecraft heads.
Server administrators retain full control over permissions, pricing, More Heads, More Categories, messages, GUI layouts, database behavior, and administrative tools.
Browse the public database: headsdb.com
Wiki: wiki.headsdb.com
Support: Discord
---
## Features
- Heads
- Categories
- Tags
- Collections
- Search
- Favorites
- More Categories
- More Heads
- Player Heads
- Local head visibility controls
- Modern inventory-based interface
- Advanced category browsing
- Powerful search, filtering, and sorting
- Optional Vault economy integration
- Granular permission system
- In-game administrative editing
- Local caching and offline fallback
- Configurable GUI layouts and messages
- Public Java API for integrations
---
## Paper and Folia Support
HeadDB supports both Paper and Folia servers.
### Requirements
- Java 25
- Paper or Folia
- Network access
---
## Modern GUI
Players can open HeadDB with
/hdb and browse heads without relying on long or complicated commands.The interface includes:
- Category browsing
- Search
- Favorites
- Player heads
- More Heads
- More Categories
- Player settings
- Administrative controls
- Hidden-head browsing
- Paginated result pages
- Previous, next, and back navigation
GUI buttons can be configured through
gui.yml, including:- Slots
- Materials
- Icons
- Display names
- Lore
- Layout
---
## Search, Filtering, and Sorting
HeadDB provides a paginated search interface for quickly locating heads.
Search supports:
- Text queries
- Categories
- Tags
- Collections
- Sorting
- Page navigation
Players can search through commands or use the graphical interface.
Code:
/hdb search <query>---
## Favorites
Players can favorite heads and access them later from the dedicated Favorites menu.
Favorites are:
- Stored locally
- Saved per player
- Persistent across server restarts
- Available throughout supported head-browsing interfaces
---
## Player Heads
Player heads are handled separately from the remote HeadDB catalog.
Administrators can independently control:
- Access to player heads
- Giving player heads to yourself
- Giving player heads to other players
- Player-head economy pricing
---
## More Heads
More Heads are locally managed custom heads created directly on your server.
They are suitable for:
- Server-specific decorations
- Event rewards
- Staff heads
- Donator content
- Seasonal content
- Custom shop items
- Heads not available in the remote database
More Heads are stored locally and never modify the public remote catalog.
Custom heads can be created from:
- A texture value
- A compatible head held by the administrator
---
## More Categories
More Categories are locally managed custom categories created specifically for your server.
A More Category can contain:
- Remote database heads
- More Heads
- Player heads
This makes it possible to build curated collections such as:
- Spawn decorations
- Event rewards
- Shop inventories
- Seasonal collections
- Staff selections
- Builder favorites
- Donator rewards
Adding a head to a More Category does not change its original category.
---
## Admin Mode
Admin Mode exposes additional editing and management controls throughout the GUI.
Administrative tools include:
- Head editing through the GUI using the drop-item key, usually
Q - GUI button configuration
- Hidden-head browsing
- More Heads administration
- More Categories administration
- Additional database and debug information
Normal player menus remain clean while administrators retain access to advanced controls.
---
## Head Metadata Overrides
Administrators can override remote head metadata locally without modifying the public database.
Supported overrides include:
- Renaming heads
- Editing lore
- Changing categories
- Changing tags
- Changing collections
- Hiding or showing heads
- Resetting local changes
Overrides are stored locally and remain under the server owner's control.
---
## Optional Economy Integration
HeadDB can charge players when they obtain heads.
Economy support is disabled by default. Enabling it requires:
- Vault
- A Vault-compatible economy provider
Pricing can be configured for:
- Any head
- Player heads
- Remote categories
- More Categories
- Individual heads
### Price Priority
When multiple prices apply, HeadDB uses the most specific configured value:
1. Specific head price
2. More Category price
3. Player-head price
4. Remote category price
5. Global fallback price
When economy support is disabled, heads are free.
When economy support is enabled but Vault or a compatible provider is unavailable, HeadDB logs a warning and does not charge players.
---
## Permission-First Design
HeadDB uses both top-level permissions and granular permissions.
This allows simple setups to grant broad access with one permission while advanced servers can control individual features independently.
Common top-level permissions include:
headdb.basicheaddb.openheaddb.browseheaddb.searchheaddb.head.takeheaddb.admin
---
# Installation
1. Download the latest HeadDB plugin jar.
2. Place the jar inside your server's
plugins directory.3. Restart the server.
4. Review and configure the generated files.
---
# Usage
All commands can be viewed with the help command:
Code:
/hdb help---
# Command Reference
## General
| Command | Description |
|---|---|
|
/hdb | Opens the main HeadDB menu ||
/hdb help | Displays command help ||
/hdb status | Displays database and plugin status ||
/hdb debug | Displays detailed diagnostic information ||
/hdb verify | Verifies the remote database ||
/hdb refresh | Refreshes the remote database ||
/hdb reload | Reloads HeadDB configuration |## GUI
| Command | Description |
|---|---|
|
/hdb open | Opens the main GUI ||
/hdb open <category> [player] | Opens a category for yourself or another player |## Search and Lookup
| Command | Description |
|---|---|
|
/hdb search <query> | Searches for matching heads ||
/hdb info [id] | Displays information about a head or the held item ||
/hdb random [amount] [category] [player] | Gives one or more random heads |## Giving Heads
| Command | Description |
|---|---|
|
/hdb give <id> [player] [amount] | Gives a head to yourself or another player |## Player Heads
| Command | Description |
|---|---|
|
/hdb player <player> [target] [amount] | Gives a player's head to yourself or another player |## More Heads
| Command | Description |
|---|---|
|
/hdb custom list [page] | Lists locally stored More Heads ||
/hdb custom info <id> | Displays information about a More Head ||
/hdb custom create <id> <texture> <name> | Creates a More Head from a texture ||
/hdb custom createheld <id> <name> | Creates a More Head from the held item ||
/hdb custom delete <id> | Deletes a More Head ||
/hdb custom rename <id> <name> | Renames a More Head ||
/hdb custom give <id> [player] [amount] | Gives a More Head |## Editing
| Command | Description |
|---|---|
|
/hdb edit [id] | Opens the head editor for a specified or held head |## Database Browsing
| Command | Description |
|---|---|
|
/hdb categories [page] | Lists available categories ||
/hdb tags [query] [page] | Lists or searches available tags ||
/hdb collections [query] [page] | Lists or searches available collections |## Item Cache
| Command | Description |
|---|---|
|
/hdb itemcache clear | Clears the generated head-item cache |---
# Permission Reference
HeadDB provides two permission layers:
1. Top-level permissions for straightforward server configuration
2. Granular permissions for precise access control
## Recommended Player Permission
Code:
headdb.basicThis grants access to common player functionality:
- Opening the main menu
- Browsing categories
- Searching for heads
- Using favorites
- Taking heads from GUIs
- Accessing basic player settings
- Changing supported language options
## Administrator Permission
Code:
headdb.adminThis grants full access to HeadDB.
## Top-Level Permissions
Code:
headdb.admin
headdb.basic
headdb.open
headdb.browse
headdb.search
headdb.head.take
headdb.give
headdb.give.others
headdb.player-heads
headdb.player-heads.others
headdb.more-heads
headdb.more-heads.give
headdb.more-heads.give.others
headdb.more-heads.admin
headdb.favorites
headdb.more-categories
headdb.more-categories.admin
headdb.settings
headdb.admin-mode
headdb.head-edit
headdb.gui-admin
headdb.database## Common Permission Setups
### Browse Only
Code:
headdb.open
headdb.browse### Browse and Take Heads
Code:
headdb.open
headdb.browse
headdb.head.take### Normal Player
Code:
headdb.basic### Full Administrator
Code:
headdb.admin## Category Permissions
Code:
headdb.category.*
headdb.category.<category-id>Category permissions only control access to individual categories.
They do not independently grant permission to:
- Open HeadDB
- Use commands
- Browse the GUI
- Take heads
The required base permissions must still be granted.
---
# Head IDs
HeadDB uses typed identifiers to distinguish between remote, More Heads, and player heads.
## Remote Head
Code:
123## More Head
Code:
custom:melon## Player Head
Code:
player:f16df3ef-06b8-443e-9166-fba6689585b4Typed IDs prevent collisions and make it clear which source a head belongs to.
---
# Configuration
HeadDB separates configuration by responsibility.
##
config.ymlControls:
- Remote database loading
- Manifest URL
- Preferred mirrors
- Cache behavior
- HTTP timeouts
- Startup refresh behavior
- Debug behavior
- Root-command GUI behavior
##
gui.ymlControls:
- GUI layouts
- Button positions
- Materials
- Display names
- Lore
- Icons
##
economy.ymlControls:
- Economy enablement
- Economy provider
- Global fallback pricing
- Player-head pricing
- Category pricing
- More Category pricing
- Individual head pricing
##
messages/en-US.ymlControls:
- Player-facing messages
- Administrative messages
- Command feedback
- Error messages
- Localized interface text
---
# Developer API
HeadDB exposes a public Java API for integrations with other plugins.
The API is registered through Bukkit's service provider system.
## Accessing the API
Java:
RegisteredServiceProvider<HeadDBService> registration = Bukkit.getServicesManager().getRegistration(HeadDBService.class);
if (registration == null) {
return;
}
HeadDBService headDB = registration.getProvider();## Finding Heads
Java:
headDB.find("123");
headDB.find("custom:melon");
headDB.find("player:f16df3ef-06b8-443e-9166-fba6689585b4");## Accessing More Heads
Java:
headDB.customHeads().list();## Accessing Favorites
Java:
headDB.favorites().ids(player.getUniqueId());## Accessing More Categories
Java:
headDB.customCategories().list();The API and core modules target Java 21, allowing integrations to use HeadDB's domain model and services independently from the Java 25 Paper runtime.
