# 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](https://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. ```text /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: 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: ```text /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 | |---|---| | `/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 ```text 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 ```text headdb.admin ``` This grants full access to HeadDB. ## Top-Level Permissions ```text 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 ```text headdb.open headdb.browse ``` ### Browse and Take Heads ```text headdb.open headdb.browse headdb.head.take ``` ### Normal Player ```text headdb.basic ``` ### Full Administrator ```text headdb.admin ``` ## Category Permissions ```text headdb.category.* headdb.category. ``` 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 ```text 123 ``` ## More Head ```text custom:melon ``` ## Player Head ```text 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 ```java RegisteredServiceProvider registration = Bukkit.getServicesManager().getRegistration(HeadDBService.class); if (registration == null) { return; } HeadDBService headDB = registration.getProvider(); ``` ## Finding Heads ```java headDB.find("123"); headDB.find("custom:melon"); headDB.find("player:f16df3ef-06b8-443e-9166-fba6689585b4"); ``` ## Accessing More Heads ```java headDB.customHeads().list(); ``` ## Accessing Favorites ```java headDB.favorites().ids(player.getUniqueId()); ``` ## Accessing More Categories ```java 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.