HeadDB

# HeadDB **A modern, configurable head database for Paper and Folia servers.** HeadDB gives players an intuitive inventory interface for browsing, searching, favoriting, purchasing, and obtaining more than 100,000 Minecraft heads. Server administrators retain control over permissions, economy pricing, custom content, GUI layouts, sounds, messages, database updates, and administrative tools. [Browse the public head database](https://headsdb.com) [Documentation and configuration guide](https://wiki.headsdb.com) --- ## 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: ```text /hdb ``` --- ## 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: ```text /hdb search ``` --- ## 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](https://wiki.headsdb.com) 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: ```text /hdb refresh ``` The refresh schedule can be configured in `config.yml`. --- ## Commands Common commands include: | Command | Description | |---|---| | `/hdb` | Opens the main HeadDB menu | | `/hdb help` | Displays available commands | | `/hdb search ` | 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](https://wiki.headsdb.com) for the complete command reference. --- ## Permissions For a standard player setup, grant: ```text headdb.basic ``` For complete administrative access, grant: ```text headdb.admin ``` Individual category access can be controlled with: ```text headdb.category. ``` 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](https://wiki.headsdb.com) 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](https://wiki.headsdb.com). --- ## 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](https://wiki.headsdb.com) for dependency setup, API documentation, and integration examples. --- ## Links - [Public head database](https://headsdb.com) - [Documentation](https://wiki.headsdb.com) - [GitHub repository](https://github.com/SilentDevelopment/HeadDB)