Head Database

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.