HeadDB Plugin pre Minecraft 1.20.1, 1.21.1

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

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:

• Specific head price
• More Category price
• Player-head price
• Remote category price
• 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

• Download the latest HeadDB plugin jar.
• Place the jar inside your server's plugins directory.
• Restart the server.
• 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 [player] - Opens a category for yourself or another player

Search and Lookup

Command - Description

/hdb search - 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 [player] [amount] - Gives a head to yourself or another player

Player Heads

Command - Description

/hdb 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 - Displays information about a More Head /hdb custom create - Creates a More Head from a texture /hdb custom createheld - Creates a More Head from the held item /hdb custom delete - Deletes a More Head /hdb custom rename - Renames a More Head /hdb custom give [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