HeadDB

Features

• More than 100,000 Minecraft heads
• Categories, tags, and collections
• Fast text search with advanced filtering and sorting
• Modern inventory-based navigation
• Favorites
• Player heads
• Custom heads and custom categories
• Custom tags and collections
• Local metadata overrides
• Optional Vault economy integration
• Granular permissions
• In-game administration
• Configurable GUIs, messages, and sounds
• Automatic remote database updates
• Verified local caching and offline fallback
• Paper and Folia support
• Public Java API

Requirements

• Java 25 or newer
• Paper or Folia
• Network access for the initial database download and future updates

After a successful database download, HeadDB can load its verified local cache when the remote database is temporarily unavailable.


Installation

1. Download the latest HeadDB plugin JAR.
2. Place it inside the server's plugins directory.
3. Restart the server.
4. Review the generated configuration files.
5. Grant players headdb.basic or configure more granular permissions.

Open HeadDB in-game with:


Browsing and Search

Players can browse HeadDB without relying on long or complicated commands.

The graphical interface provides:

• Category browsing
• Tags and collections
• Text search
• Advanced search filters
• Sorting
• Favorites
• Player heads
• Paginated results
• Previous, next, and back navigation
• Personal settings

Players can also search directly:


Favorites

Players can mark frequently used heads as favorites and access them later from a dedicated menu.

Favorites are stored per player.


Player Heads

Player heads are handled separately from the public HeadDB catalog.

Administrators can independently control:

• Access to player-head functionality
• Whether players may obtain only their own head
• Whether players may obtain other players' heads
• Player-head economy pricing
• External profile lookups

Custom Heads

Custom Heads are server-local heads managed directly through HeadDB.

They are suitable for:

• Server-specific decorations
• Event rewards
• Staff heads
• Donator content
• Seasonal content
• Custom shop items
• Heads not included in the public database

Custom Heads can be created through the graphical interface or from compatible held head items and texture values.

They can be assigned to categories, tags, and collections and are stored locally for the server.

Custom Heads are not added to the public HeadDB database.


Custom Categories

Custom Categories are server-local categories used to organize curated selections of remote and custom heads.

They can be used for:

• Spawn decorations
• Event rewards
• Shop inventories
• Seasonal selections
• Staff collections
• Builder resources
• Donator rewards

Custom Categories appear alongside public database categories in the Browse menu.

Adding a head to a Custom Category does not modify its original public database category.


Custom Tags and Collections

Administrators can create local tags and collections to organize both remote and custom heads.

Custom tags and collections can be created, searched, selected, and managed through the graphical interface or supported commands.

They remain local to the server and do not modify the public database.


Administration

Admin Mode exposes additional management controls throughout the HeadDB interface.

Administrators can:

• Create and manage Custom Heads
• Create and manage Custom Categories
• Create custom tags and collections
• Edit head metadata
• Hide or restore heads
• Configure GUI buttons
• Verify or refresh the remote database
• Access runtime and diagnostic information

Local Metadata Overrides

Remote heads remain immutable in the public database, but administrators can apply local overrides for their own server.

Supported overrides include:

• Name
• Lore
• Category
• Tags
• Collections
• Visibility

Overrides can be reset without modifying the original remote data.


Economy Integration

HeadDB can optionally charge players when they obtain heads.

Economy support requires:

• Vault
• A Vault-compatible economy provider

Pricing can be configured for:

• Remote heads
• Player heads
• Remote categories
• Custom categories
• Individual heads
• A global fallback price

When economy support is disabled, heads are free.

See the HeadDB wiki for economy setup and pricing precedence.


Automatic Database Updates

HeadDB periodically checks the remote database for newly published heads.

Scheduled refreshes are enabled by default and avoid downloading database artifacts when the published catalog has not changed.

Administrators can still perform an immediate refresh:

The refresh schedule can be configured in config.yml.


Commands

Common commands include:

• /hdb — Opens the main HeadDB menu
• /hdb help — Displays available commands
• /hdb search <query> — Searches for heads
• /hdb status — Displays database status
• /hdb refresh — Checks for database updates
• /hdb reload — Reloads HeadDB
• /hdb update — Downloads an available plugin update

Run /hdb help in-game or visit the HeadDB wiki for the complete command reference.


Permissions

For a standard player setup, grant:

For complete administrative access, grant:

Individual category access can be controlled with:

HeadDB also provides granular permissions for individual commands, GUI actions, player heads, custom heads, custom categories, favorites, editing, and database administration.

Some internal permission nodes retain legacy names for compatibility.

See the HeadDB wiki for the complete permission reference.


Configuration

HeadDB separates configuration by responsibility.

config.yml

Controls core plugin behavior, including:

• Remote database settings
• Local cache behavior
• Startup and scheduled refreshes
• HTTP timeouts
• Player heads
• Custom content
• Update checking
• Automatic plugin updates
• Diagnostics

gui.yml

Controls:

• Menu layouts
• Button positions
• Materials
• Head icons
• Display names
• Lore

sounds.yml

Controls configurable sound effects for:

• GUI navigation
• Head interactions
• Favorites
• Visibility changes
• Purchases
• Confirmations
• Errors
• Administrative actions
• Commands

economy.yml

Controls:

• Vault integration
• Global pricing
• Player-head pricing
• Category pricing
• Custom-category pricing
• Individual head pricing

messages/

Contains localized:

• Player-facing messages
• Command feedback
• Administrative messages
• Errors
• Interface text

Full configuration documentation is available on the HeadDB wiki.


Local Storage

HeadDB stores server-specific data locally, including:

• Custom Heads
• Custom Categories
• Custom tags and collections
• Favorites
• Player-head cache data
• Hidden heads
• Remote metadata overrides
• Draft content

Local content persists across server restarts and remains under the server owner's control.


Remote Database and Cache

HeadDB downloads a verified remote catalog containing public heads, categories, tags, collections, and revocations.

Downloaded database artifacts are stored in a local cache.

On startup, HeadDB can load the cached database immediately and then check whether a newer remote version is available.

If the remote service is temporarily unavailable, the last verified cached database remains usable.


Developer API

HeadDB exposes a public Java API through Bukkit's service provider system.

Integrations can access:

• Remote and custom heads
• Categories
• Tags
• Collections
• Search
• Favorites
• Custom Heads
• Custom Categories
• Player-head functionality

The API and core modules target Java 21.

The Paper platform module targets Java 25.

See the HeadDB wiki for dependency setup, API documentation, and integration examples.