Head Database

HeadDB 6.1.0 Changelog

Managed catalog and compatibility

- Moved the head catalog to the managed API at [headdb.net](https://headdb.net). - Added revision-based updates and an on-disk recovery cache for modern Paper servers. - Added complete-catalog support for legacy servers from 1.8.8 to 1.20.6. - Switched submitted skins to Mojang-hosted textures for reliable rendering. - Added /hdb submit, headdb.net submission links throughout the modern menus, and an optional post-search link that carries supported filters into the web catalog.

Commands and catalog operations

- Added /hdb status, /hdb sync, /hdb reload, /hdb inspect, /hdb recent, and /hdb language to both modern and legacy artifacts. - Added self-targeting /hdb give <head> and /hdb give <amount> <head> forms while preserving the administrator player-target form. - Aligned in-game and website search with quoted filters, multiple IDs, and all/any matching. Website copy actions now emit valid plugin commands. - Stored catalog IDs on modern head items so held heads can be inspected reliably and linked to their managed website records.

API and storage

- Added structured, sorted, paginated Java API searches, catalog health status, and added/edited/removed update listeners while keeping Java 8 API bytecode. - Added optional MySQL player storage for proxy networks. SQLite remains the default and existing local data remains compatible. - Added English/Spanish personal language selection and server-provided message pack discovery.

Paper, Folia, and reliability

- Restored the modern Folia support declaration after isolating inventory trees per open and replacing shared page/navigation registries with concurrent implementations. - Runtime reloads rebuild menus and localization safely; catalog synchronization reports its source, revision, last success, and failure details.

Integrated headdb.net release

- Added favorites, public/private collections, share pages, and YAML export. - Added recent-update discovery, submission editing, withdrawal and resubmission, webhook retry, head reports, published metadata edits, removal recovery, and merge redirects. - Added durable account submission cooldowns, application and Nginx request throttles, and optional encrypted Restic off-host PostgreSQL backups.

Separate modern and legacy artifacts

- HeadDB-6.0.3.jar is the Java 21 modern artifact for Paper 1.21.0 and newer. - HeadDB-6.0.3-legacy.jar is the Java 8-bytecode artifact for Bukkit-compatible servers from 1.8.8 through 1.20.6. - Legacy material and player-profile operations are selected at runtime across the pre- and post-flattening server APIs. - The previous -Spigot.jar classifier has been removed. - The public headdb-api module now targets Java 8 so integrations can use the same service interfaces with either server artifact.

Legacy feature coverage

The legacy module includes asynchronous database loading and fallback sources, indexed and structured searches, public API service registration, legacy textured-skull creation, browsing and purchase menus, favorites, local heads, custom categories, persistent player settings, Vault economy integration, configurable messages and sounds, update notifications, metrics, scheduled database refreshes, and the info, search, give, open, and sounds commands. It uses the same configuration and data schema as the modern jar so servers can switch artifacts without rebuilding their HeadDB data. Legacy menus use Bukkit inventories rather than the modern Paper menu framework. Interactive purchase quantities are provided as inventory presets, and advanced MiniMessage effects are simplified to formatting supported by older clients. Runtime smoke tests passed on every historical Paper release published across the supported range: 1.8.8, 1.9.4, 1.10.2, 1.11.2, 1.12-1.12.2, 1.13-1.13.2, 1.14-1.14.4, 1.15-1.15.2, 1.16.1-1.16.5, 1.17-1.17.1, 1.18-1.18.2, 1.19-1.19.4, and the published Paper releases from 1.20 through 1.20.6. Each test reached server-ready state, enabled HeadDB, and loaded the complete 86,248-head database without a HeadDB startup error.

HeadDB 6.0.2 Changelog

Compatibility

- Updated the project, plugin metadata, CI, and release builds for Paper 26.2 and Java 25. - Aligned Adventure and SQLite dependencies with the 26.2 runtime. - Fixed Paper/Spigot shading so bundled libraries are isolated and Adventure is only bundled in the Spigot artifact. - Replaced a Paper-only localization superclass that made the Spigot artifact binary-incompatible. - Removed the unsafe Folia support declaration; the current menu dependency is not region-thread safe.

Reliability and Performance

- Made database refreshes atomic, coalesced concurrent refreshes, added HTTP timeouts, gzip, and fallback handling, and preserved the last good snapshot after a failed update. - Made the 86,000+ head menus lazy, cached per-GUI page assets, and changed full preloading to an opt-in batched task. - Refreshed category, custom-category, and main menus after successful database updates. - Fixed page tracking after a menu shrinks and mixed local/database favorites pagination. - Serialized transactional player saves, tolerated damaged rows, and safely imported pre-v6 player data from the plugin data folder. - Shut down HeadDB executors and closed registered inventory views safely during plugin disable.

Commands, Config, and Economy

- Fixed invalid /hdb give amounts and IDs, full-inventory item loss, blocking tab completion, and command and alias casing. - Fixed empty or invalid searches, permission-filtered results, async error reporting, and accidental broad 86,000-head searches. - Added validation for menu sizes, materials, sounds, prices, storage intervals, worker counts, buy limits, and custom category IDs. - Fixed economy.provider: NONE using economy lore and corrected the documented indexing.by.tags option while retaining the old alias. - Rejected non-finite or negative economy values and enforced the configured maximum on preset purchase buttons. - Added /hdb sounds and made the persisted per-player sound preference take effect. - Added the missing headdb.command.info permission declaration so /hdb info works for operators and administrators as intended.

Permissions

- Fixed category-specific denials being ignored when headdb.category.* was granted. For example, headdb.category.local: false now overrides the wildcard. - Fixed /hdb open <category> bypassing category permissions. - Re-checked category permissions when a head is selected or purchased, preventing stale or open menus from bypassing a later permission change. - Hid inaccessible category and local heads from the favorites menu, and omitted inaccessible categories from /hdb open suggestions.

Update Checker

- Added an asynchronous GitHub Releases update checker with semantic version comparison, timeouts, rate-limit handling, and ETag caching. - Added configurable console and player download notices controlled by headdb.update.notify; links are clickable on Paper and shown as plain URLs on Spigot.

HeadDB 6.0.1 Changelog

Last updated: March 18, 2026 Release status: In progress

Fixes (Permissions)

- Added support for headdb.category.* as a global category permission. - Added support for headdb.category as a parent permission for all categories. - Unified category permission checks across main menu, local heads, favorites, and custom categories. - Fixed default category checks so category names with spaces/symbols can be granted via normalized permission nodes. - Fixed custom category permission validation to use the custom category identifier instead of the object instance string. - Standardized favorites permission around headdb.category.favorites while keeping headdb.favorites as a backward-compatible alias.

Permission Tree Updates

- Updated plugin.yml to add: - headdb.category - headdb.category.* - headdb.category.favorites - Updated headdb.admin children to include category-wide nodes. - Linked headdb.favorites to headdb.category.favorites for compatibility with existing setups.

HeadDB 6.0.0 Changelog

Last updated: March 11, 2026 Release status: In progress

CI/CD Updates (March 11, 2026)

- Added Maven distributionManagement to headdb-api/pom.xml for: - nexus-releases (https://nexus.bitworksmc.com/repository/maven-releases/) - nexus-snapshots (https://nexus.bitworksmc.com/repository/maven-snapshots/) - Replaced the old build upload pipeline with .github/workflows/publish.yml to deploy headdb-api on master pushes and manual runs. - Added .github/workflows/release.yml to build on v* tags (or manual tag input) and create GitHub Releases using changelog/<version>.md when available.

Additional Updates (March 11, 2026)

- Made the Discord join message clickable in chat (open_url) from: - Main menu info item - Heads GUI info item - Favorites GUI info item - Local Heads GUI info item - Custom Categories GUI info item - Updated main menu control slots: - More Categories moved to slot 47 - Search moved to slot 48 - Local Heads moved to slot 50 - Favorites moved to slot 51

Pending Commit Summary

refactor: migrate HeadDB to com.bitworksmc with legacy API support

Pending Commit Description

- Moved plugin source packages from com.github.thesilentpro.headdb.* to com.bitworksmc.headdb.*. - Updated plugin main class references and build metadata to the new package namespace. - Switched Maven project coordinates for this project to com.bitworksmc. - Introduced new API namespace under com.bitworksmc.headdb.api.*. - Kept legacy API namespace (com.github.thesilentpro.headdb.api.*) for migration and marked it as deprecated. - Added a runtime adapter to register both legacy and modern HeadAPI services in Bukkit. - Updated documentation and release notes to reflect the migration and compatibility path.

Highlights

- Full v6 rewrite foundation was introduced. - Added/expanded config system work (config manager, sound config, head customization, item factory relocation). - Added Folia 1.21.11 support and related compatibility fixes. - Head database source moved to a configurable URL option. - Menu pagination issues were fixed. - Vault economy integration was modernized to work with VaultUnlocked API expectations, with safer fallback behavior. - Project namespace migration started from com.github.thesilentpro to com.bitworksmc.

Breaking Changes (6.0.0)

- Primary plugin code package moved to com.bitworksmc.headdb.*. - Bukkit plugin main class changed to com.bitworksmc.headdb.core.HeadDB. - Maven project group changed to com.bitworksmc. - Primary API namespace is now com.bitworksmc.headdb.api.*.

Compatibility Notes

- Legacy API package com.github.thesilentpro.headdb.api.* is still present for migration and marked @Deprecated(forRemoval = true, since = "6.0.0"). - HeadDB now registers both API service interfaces in Bukkit ServicesManager: - com.bitworksmc.headdb.api.HeadAPI (new) - com.github.thesilentpro.headdb.api.HeadAPI (legacy adapter)

Migration Guide

1. Update imports from com.github.thesilentpro.headdb.* to com.bitworksmc.headdb.*. 2. Update dependency coordinates to com.bitworksmc:*. 3. Move service lookups to com.bitworksmc.headdb.api.HeadAPI. 4. Keep legacy imports only temporarily while migrating; they are deprecated for removal.

Commit History Included In 6.0.0 Line

- cd526e7 v6 rewrite - d072e51 Update jitpack.yml - 97e0d7e Update README.md - 9df1f6d Added sounds.yml Added head customization Added config manager Added (and relocated) item creation to item factories - a15cbe7 Merge remote-tracking branch 'origin/master' - 84e316d feat: add Folia 1.21.11 support and fix head name rendering - 3f1c4df Update HDBCommandSearch.java - 8b2ff96 Merge pull request #1 from EarthPol/folia - 127cc75 Migrate head database json to a config option url - 9091ba2 Update heads.json - a8c0de6 Fix pagination on menu - 3f81e57 Migrate to Bitworks - Fix Vault

Working Tree Updates Tracked For 6.0.0 (Pending Commit)

- Added new API namespace interfaces: - com.bitworksmc.headdb.api.HeadAPI - com.bitworksmc.headdb.api.HeadDatabase - com.bitworksmc.headdb.api.model.Head - Added legacy runtime adapter: - com.bitworksmc.headdb.core.api.LegacyHeadAPIAdapter - Updated docs and build metadata to point to com.bitworksmc coordinates and package paths. - Updated plugin metadata and shade main class references to the new namespace.