HeadDB

HeadDB

HeadDB is a modern head database plugin for Paper and Folia servers. It lets players browse, search, favorite, price, edit, and obtain Minecraft head items through a clean GUI, while giving server owners full control over permissions, local custom heads, custom categories, messages, GUI layout, and optional economy pricing.

---

Features

Remote head database

HeadDB loads heads from a public remote database and verifies downloaded data before using it.

Features include:

• Remote head catalog
• Categories, tags, and collections
• SHA-256 artifact verification
• Local cache loading on startup
• Remote refresh support
• Cache fallback support

Paper and Folia support

HeadDB supports both Paper and Folia.

Requirements

• Java 25
• Paper or Folia
• Network access
• Vault and an economy provider if economy support is enabled

The API and core modules target Java 21. The Paper plugin targets Java 25.

---

Modern GUI

Players can use /hdb to open the main menu and browse heads without typing long commands.

The GUI includes:

• Category browsing
• Search
• Favorites
• Player heads
• More Heads
• More Categories
• Settings
• Admin-only hidden heads
• Paginated result pages
• Next, previous, and back navigation

GUI buttons, icons, names, lore, and layout can be configured through gui.yml.

Search and filters

Players can search for heads and browse results in a paginated inventory GUI.

Search supports:

• Text queries
• Categories
• Tags
• Collections
• Sort options
• Page navigation

Favorites

Players can favorite heads and access them later from the Favorites menu.

Favorites are stored locally and persist across restarts.

Player heads

HeadDB supports player heads separately from the remote database.

Server owners can control player-head access through permissions.

More Heads

More Heads are local custom heads created on your server.

They are useful for:

• Server-specific decorations
• Event heads
• Staff heads
• Donator heads
• Seasonal content
• Heads not present in the remote database

More Heads are stored locally and do not modify the remote database.

More Categories

More Categories are local custom categories created on your server.

A custom category can contain:

• Remote heads
• More Heads
• Player heads

This lets you create server-specific collections such as:

• Spawn decorations
• Event rewards
• Shop items
• Seasonal heads
• Staff picks
• Builder favorites

Custom categories do not change the original category of a head.

Admin Mode

Admin Mode exposes additional controls in the GUI.

Admin tools include:

• Head editing
• Button configuration
• Hidden-head browsing
• Custom category administration
• Extra debug/details in menus

This keeps normal player menus clean while still giving administrators powerful editing tools.

Local head overrides

Admins can override head metadata locally without changing the remote database.

Supported actions include:

• Rename heads
• Edit lore
• Change category
• Change tags
• Change collections
• Hide/show heads
• Reset local overrides

Optional Vault economy support

HeadDB can charge players when they take heads.

Economy support is disabled by default and requires Vault plus an economy provider.

Pricing supports:

• Global fallback price
• Player-head price
• Category prices
• Custom category prices
• Specific head prices

Price priority:

1. Specific head price
2. Custom category price
3. Player-head price
4. Normal category price
5. Fallback price

Permission-first design

HeadDB uses granular permissions and top-level permission bundles.

This makes it easy to give players broad access with simple permissions, while still allowing advanced servers to control every action individually.

Common top-level permissions include:

• headdb.basic
• headdb.open
• headdb.browse
• headdb.search
• headdb.head.take
• headdb.admin

Installation

1. Download the latest HeadDB jar.
2. Place it in your server’s plugins folder.
3. Restart the server.
4. Configure the generated files if needed.

Generated files include:

• config.yml
• gui.yml
• economy.yml
• messages/en-US.yml
• storage/headdb.db

Vault is optional. Economy features only require Vault if economy is enabled.

---

Basic Usage

Open the main GUI:

/hdb

Open the main GUI explicitly:

/hdb open

Search heads:

/hdb search <query>

Give yourself a head:

/hdb give <id>

Get information about a head:

/hdb info <id>

Inspect the held head:

/hdb info

Verify the remote database:

/hdb verify

Refresh the database:

/hdb refresh

Reload configuration:

/hdb reload

---

Commands

General:

• /hdb
• /hdb help
• /hdb status
• /hdb debug
• /hdb verify
• /hdb refresh
• /hdb reload

GUI:

• /hdb open
• /hdb open <category> [player]

Search and lookup:

• /hdb search <query>
• /hdb info [id]
• /hdb random [amount] [category] [player]

Giving heads:

• /hdb give <id> [player] [amount]

Player heads:

• /hdb player <player> [target] [amount]

More Heads:

• /hdb custom list [page]
• /hdb custom info <id>
• /hdb custom create <id> <texture> <name>
• /hdb custom createheld <id> <name>
• /hdb custom delete <id>
• /hdb custom rename <id> <name>
• /hdb custom give <id> [player] [amount]

Editing:

• /hdb edit [id]

Database browsing helpers:

• /hdb categories [page]
• /hdb tags [query] [page]
• /hdb collections [query] [page]

Item cache:

• /hdb itemcache clear

---

Permissions

HeadDB has two permission layers:

• Top-level permissions for easy setup
• Granular permissions for advanced control

Recommended player permission

headdb.basic

This grants basic player access:

• Open the main menu
• Browse categories
• Search heads
• Use favorites
• Take heads from GUIs
• Access basic settings/language options

Admin permission

headdb.admin

Grants full access.

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 setups

Browse only:

• headdb.open
• headdb.browse

Browse and take heads:

• headdb.open
• headdb.browse
• headdb.head.take

Normal player:

• headdb.basic

Full admin:

• headdb.admin

Category permissions

• headdb.category.*
• headdb.category.<category-id>

Category permissions only control category visibility/access. They do not grant command access, GUI opening, or head taking by themselves.

---

Economy

Economy support is configured in economy.yml.

Default configuration:

enabled: false provider: vault

prices: any-head: 0.0 player-heads: 0.0 categories: {} custom-categories: {} heads: {}

Example:

enabled: true provider: vault

prices: any-head: 5.0 player-heads: 25.0

categories: alphabet: 10.0 animals: 12.5

custom-categories: "1": 30.0 "2": 50.0

heads: "1": 100.0 custom:melon: 75.0 player:f16df3ef-06b8-443e-9166-fba6689585b4: 200.0

If economy is disabled, heads are free.

If economy is enabled but Vault or an economy provider is unavailable, HeadDB logs a warning and does not charge players.

---

Head IDs

HeadDB uses typed head IDs.

Examples:

• 123
• custom:melon
• player:f16df3ef-06b8-443e-9166-fba6689585b4

---

Configuration

HeadDB creates several configuration files:

• config.yml
• gui.yml
• economy.yml
• messages/en-US.yml

config.yml

Controls:

• Remote database loading
• Cache behavior
• HTTP timeouts
• Startup refresh behavior
• Debug behavior
• Root command GUI behavior

gui.yml

Controls:

• GUI layout
• Button slots
• Materials
• Names
• Lore
• Icons

economy.yml

Controls:

• Economy enable/disable
• Economy provider
• Global prices
• Category prices
• Custom category prices
• Per-head prices

messages/en-US.yml

Controls localized messages.

---

API

HeadDB exposes a public Java API for other plugins.

External plugins can access HeadDB through Bukkit’s service provider system.

Example:

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

if (registration == null) { return; }

HeadDBService headDB = registration.getProvider();

Example lookups:

headDB.find("123"); headDB.find("custom:melon"); headDB.customHeads().list(); headDB.favorites().ids(player.getUniqueId()); headDB.customCategories().list();