HeadDB

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

---

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.

/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.basic
• headdb.open
• headdb.browse
• headdb.search
• headdb.head.take
• headdb.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:

/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

headdb.basic

This 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

headdb.admin

This grants full access to HeadDB.

Top-Level Permissions

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

headdb.open
headdb.browse

Browse and Take Heads

headdb.open
headdb.browse
headdb.head.take

Normal Player

headdb.basic

Full Administrator

headdb.admin

Category Permissions

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

123

More Head

custom:melon

Player Head

player:f16df3ef-06b8-443e-9166-fba6689585b4

Typed IDs prevent collisions and make it clear which source a head belongs to.

---

Configuration

HeadDB separates configuration by responsibility.

config.yml

Controls:

• Remote database loading
• Manifest URL
• Preferred mirrors
• Cache behavior
• HTTP timeouts
• Startup refresh behavior
• Debug behavior
• Root-command GUI behavior

gui.yml

Controls:

• GUI layouts
• Button positions
• Materials
• Display names
• Lore
• Icons

economy.yml

Controls:

• Economy enablement
• Economy provider
• Global fallback pricing
• Player-head pricing
• Category pricing
• More Category pricing
• Individual head pricing

messages/en-US.yml

Controls:

• 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

RegisteredServiceProvider<HeadDBService> registration = Bukkit.getServicesManager().getRegistration(HeadDBService.class);

if (registration == null) {
    return;
}

HeadDBService headDB = registration.getProvider();

Finding Heads

headDB.find("123");
headDB.find("custom:melon");
headDB.find("player:f16df3ef-06b8-443e-9166-fba6689585b4");

Accessing More Heads

headDB.customHeads().list();

Accessing Favorites

headDB.favorites().ids(player.getUniqueId());

Accessing More Categories

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.