Plugin configuration

Configure HeadDB menus, catalog refreshes, economy, storage, and custom categories.

Edit files under plugins/HeadDB/. /hdb reload safely applies messages, sounds, menus, prices, website links, and categories. Database endpoints, player-storage backends, worker counts, and task intervals require a restart; Bukkit /reload is not a safe substitute.

Common settings

Setting	Default	Effect
`updater`	`true`	Periodically applies catalog additions, edits, and removals.
`preloadHeads`	`false`	Creates all head items during startup; leave disabled for the full catalog.
`trackPage`	`true`	Reopens a category on the player's previous page.
`showInfoItem`	`true`	Shows the contribution information control.
`website.searchHint.enabled`	`true`	Shows a clickable headdb.net link after an in-game search.
`maxBuyAmount`	`2304`	Maximum amount accepted by give and purchase flows.
`headsMenu.rows`	`4`	Number of content rows; valid values are 1–5.
`storage.player.saveInterval`	`1800`	Player-data save interval in seconds.
`storage.player.backend`	`SQLITE`	Local SQLite or shared `MYSQL` player preferences.

head.name and head.lore accept the documented placeholders {id}, {name}, {category}, {tags}, and {cost}. Modern messages use MiniMessage formatting. The head.omit list removes selected lore lines from heads given to players.

Website links

HeadDB directs browsing and submissions to the same public site used by the managed API:

website:
  url: "https://headdb.net"
  searchHint:
    enabled: true

/hdb submit links to /submit, and the contribution controls in modern menus use the same destination. After /hdb search, the plugin carries compatible name, category, tag, or single-ID filters into /heads so players can continue in the browser and copy a command. Multi-ID and all/any filters are also preserved. Set website.searchHint.enabled to false to suppress only the post-search chat message.

Managed catalog

The recommended 6.1.0 configuration is:

updater: true

database:
  sourceUrl: "https://headdb.net/api/v1/catalog/snapshot"
  syncUrl: "https://headdb.net/api/v1/catalog/changes"
  syncIntervalMinutes: 15
  fallbackSourceUrls:
    - "https://headdb.net/api/v1/legacy/heads.json"
    - "https://raw.githubusercontent.com/BitworksMC/HeadDB/refs/heads/master/heads.json"
  threads: 1
  apiThreads: 1

Existing configurations use the managed defaults when these keys are absent. Set database.syncUrl to an empty string only if the server should download a complete source on every refresh instead of using revision changes.

HeadDB indexes IDs, textures, categories, and tags by default. Disabling an index reduces its memory use but makes the corresponding lookup scan the full catalog.

Economy support

HeadDB works without an economy. To charge for heads, install Vault plus a compatible economy provider and change:

economy:
  provider: "VAULT"
  cost:
    category:
      alphabet: 1
      decoration: 2.5
    head:
      103838: 100

A head-specific price overrides its category price. Category keys are lowercase category names. If Vault or an economy provider cannot be found, HeadDB logs the problem and disables economy features.

Custom categories

categories.yml creates server-local collections from heads already known to HeadDB. The category ID must use letters, numbers, periods, underscores, or hyphens and cannot replace a built-in category.

server-icons:
  enabled: true
  icon:
    name: "<aqua>Server icons"
    head: "a0825e771a1c66f08708003d57a04a147e2774469459d9fb3041f549865f1fd3"
  heads:
    - "a0825e771a1c66f08708003d57a04a147e2774469459d9fb3041f549865f1fd3"
    - "7605917c9389a79c20c3e207ae7dab5089d36685e070a3d020baa2049c35327"

The head and heads values are texture hashes from published catalog entries. Players need headdb.category.custom to open the custom-category menu and headdb.category.server-icons to open this example category.

Updates and player data

The updateChecker section controls GitHub release checks separately from catalog synchronization. Player favorites and sound preferences are saved to data/data.db; back up that file with the rest of the server. The catalog cache can be rebuilt from the API, but retaining it allows faster and more resilient startup during a network outage.

For a proxy network, point each server at the same MySQL database:

storage:
  player:
    backend: "MYSQL"
    mysql:
      url: "jdbc:mysql://db.internal:3306/headdb"
      username: "headdb"
      password: "use-a-secret"
    saveInterval: 1800

This shares favorites, selected language, and interface-sound preferences. Keep credentials out of publicly distributed configuration archives. When the MySQL table is empty, HeadDB imports an existing local SQLite player database once; keep the SQLite file until the first successful shared-storage startup.