# 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 ` Give yourself a head: `/hdb give ` Get information about a head: `/hdb info ` 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 [player]` Search and lookup: - `/hdb search ` - `/hdb info [id]` - `/hdb random [amount] [category] [player]` Giving heads: - `/hdb give [player] [amount]` Player heads: - `/hdb player [target] [amount]` More Heads: - `/hdb custom list [page]` - `/hdb custom info ` - `/hdb custom create ` - `/hdb custom createheld ` - `/hdb custom delete ` - `/hdb custom rename ` - `/hdb custom give [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 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();

Published on	June 23, 2026
Downloads	1

HeadDB

Beta 7.0.0-rc.2

Silent released HeadDB version 7.0.0-rc.2 on Yesterday 11:01 AM

Information

Platforms

Dependencies

Beta
7.0.0-rc.2