MINECRAFTBIBLE
Loading...
The #1 central database for heads.
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
HeadDB supports both Paper and Folia servers.
Players can open HeadDB with /hdb and browse heads without relying on long or complicated commands.
The interface includes:
GUI buttons can be configured through gui.yml, including:
HeadDB provides a paginated search interface for quickly locating heads.
Search supports:
Players can search through commands or use the graphical interface.
/hdb search <query>
Players can favorite heads and access them later from the dedicated Favorites menu.
Favorites are:
Player heads are handled separately from the remote HeadDB catalog.
Administrators can independently control:
More Heads are locally managed custom heads created directly on your server.
They are suitable for:
More Heads are stored locally and never modify the public remote catalog.
Custom heads can be created from:
More Categories are locally managed custom categories created specifically for your server.
A More Category can contain:
This makes it possible to build curated collections such as:
Adding a head to a More Category does not change its original category.
Admin Mode exposes additional editing and management controls throughout the GUI.
Administrative tools include:
QNormal player menus remain clean while administrators retain access to advanced controls.
Administrators can override remote head metadata locally without modifying the public database.
Supported overrides include:
Overrides are stored locally and remain under the server owner's control.
HeadDB can charge players when they obtain heads.
Economy support is disabled by default. Enabling it requires:
Pricing can be configured for:
When multiple prices apply, HeadDB uses the most specific configured value:
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.
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.adminplugins directory.All commands can be viewed with the help command:
/hdb help
| 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 |
| Command | Description |
|---|---|
/hdb open |
Opens the main GUI |
/hdb open <category> [player] |
Opens a category for yourself or another player |
| 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 |
| Command | Description |
|---|---|
/hdb give <id> [player] [amount] |
Gives a head to yourself or another player |
| Command | Description |
|---|---|
/hdb player <player> [target] [amount] |
Gives a player's head to yourself or another player |
| 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 |
| Command | Description |
|---|---|
/hdb edit [id] |
Opens the head editor for a specified or held head |
| 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 |
| Command | Description |
|---|---|
/hdb itemcache clear |
Clears the generated head-item cache |
HeadDB provides two permission layers:
headdb.basic
This grants access to common player functionality:
headdb.admin
This grants full access to HeadDB.
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
headdb.open
headdb.browse
headdb.open
headdb.browse
headdb.head.take
headdb.basic
headdb.admin
headdb.category.*
headdb.category.<category-id>
Category permissions only control access to individual categories.
They do not independently grant permission to:
The required base permissions must still be granted.
HeadDB uses typed identifiers to distinguish between remote, More Heads, and player heads.
123
custom:melon
player:f16df3ef-06b8-443e-9166-fba6689585b4
Typed IDs prevent collisions and make it clear which source a head belongs to.
HeadDB separates configuration by responsibility.
config.ymlControls:
gui.ymlControls:
economy.ymlControls:
messages/en-US.ymlControls:
HeadDB exposes a public Java API for integrations with other plugins.
The API is registered through Bukkit's service provider system.
RegisteredServiceProvider<HeadDBService> registration = Bukkit.getServicesManager().getRegistration(HeadDBService.class);
if (registration == null) {
return;
}
HeadDBService headDB = registration.getProvider();
headDB.find("123");
headDB.find("custom:melon");
headDB.find("player:f16df3ef-06b8-443e-9166-fba6689585b4");
headDB.customHeads().list();
headDB.favorites().ids(player.getUniqueId());
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.