Configuration

HeadDB separates configuration by responsibility.

File	Purpose
config.yml	Core runtime, remote database, cache, storage, player heads, language, scheduled refreshes, and updater behavior.
gui.yml	Menu layouts, buttons, icons, names, lore, and slots.
sounds.yml	GUI, command, economy, validation, and administration sounds.
economy.yml	Optional Vault integration and pricing.
messages/<locale>.yml	Localized player and administrator messages.
storage/headdb.db	Persistent server-local data.

HeadDB writes comments and missing defaults when supported by the active configuration loader. Back up files before major release upgrades.

config.yml

Remote database

remote:
  manifest-url: https://data.headsdb.com/manifest.json
  preferred-mirror-id: primary

Normal servers should keep the official manifest URL. The preferred mirror is selected when present; HeadDB falls back to another manifest-provided mirror when needed.

Cache and item cache

cache:
  directory: cache
  item:
    enabled: true
    max-size: 4096

The artifact cache stores verified remote database files. The item cache stores reusable head-item prototypes and clones them when needed.

Database refresh

refresh:
  load-cache-on-startup: true
  refresh-on-startup: true
  scheduled:
    enabled: true
    interval-hours: 6

Setting	Meaning
refresh.load-cache-on-startup	Loads the last verified local database immediately during startup.
refresh.refresh-on-startup	Checks the remote manifest after startup.
refresh.scheduled.enabled	Enables recurring remote database checks.
refresh.scheduled.interval-hours	Hours between checks; valid range is 1 through 168.

Scheduled checks download only the manifest when catalog and revocation descriptors are unchanged. Changed artifacts are verified, cached, and atomically activated.

HTTP

http:
  connect-timeout-seconds: 10
  read-timeout-seconds: 30

Increase these only when the server network is consistently slow. Very high values can delay failure reporting.

Local storage and features

storage:
  sqlite:
    file: storage/headdb.db

remote-overrides:
  enabled: true

custom-heads:
  enabled: true

storage/headdb.db contains favorites, Custom Heads, Custom Categories, drafts, custom tags and collections, hidden heads, metadata overrides, and player-head cache records. Do not delete it unless you intentionally want to remove local data.

Player heads

player-heads:
  enabled: true
  cache-ttl-hours: 24
  failed-cache-ttl-minutes: 10
  allow-external-lookup: true

Setting	Meaning
player-heads.enabled	Enables player-head services and GUI functionality.
player-heads.cache-ttl-hours	Retains successful profile lookups.
player-heads.failed-cache-ttl-minutes	Temporarily caches failed lookups.
player-heads.allow-external-lookup	Allows profile resolution outside known local players.

Messages and locale

messages:
  directory: messages
  default-locale: en-US
  console-locale: en-US

The default locale is used when a player has no valid selection. Console messages use the configured console locale and are logged under the HeadDB logger.

Root command GUI behavior

gui:
  open-main-command: true

When enabled, /hdb opens the main menu for players with the required permissions. When disabled, it prints the root command overview.

Update checker

update-checker:
  enabled: true
  check-on-startup: true
  notify-console: true
  notify-admins: true
  include-prereleases: true
  include-builds: false

Prereleases include alpha, beta, and release-candidate builds. Build metadata releases such as 7.0.0-rc.6+build.3 are controlled separately.

Automatic plugin installation

auto-updater:
  install-updates: false

When enabled, HeadDB downloads an allowed update in place when possible or stages it in the server update directory. A server restart is always required to load the new JAR.

Debug mode

debug: false

Debug mode enables additional startup diagnostics and validation logs. It is not required for normal operation.

gui.yml

gui.yml controls menu titles, layouts, slots, display items, head icons, lore, navigation controls, confirmation menus, search controls, settings, and administrative GUI actions.

After an upgrade with major GUI changes, back up and remove an outdated gui.yml so HeadDB can generate the current structure.

See GUI.

sounds.yml

Global control:

sounds:
  enabled: true

Each event supports:

sounds:
  menu-open:
    enabled: true
    sound: UI_BUTTON_CLICK
    volume: 0.55
    pitch: 1.25

Sound entries cover navigation, searches, head actions, favorites, visibility, settings, drafts, publishing, deletion, validation, economy outcomes, refreshes, reloads, verification, debugging, categories, tags, collections, and price changes.

Sound identifiers may use Bukkit-style enum names or supported namespaced/resource-pack sound keys.

economy.yml

Controls Vault enablement and price resolution. See Economy.

messages/

Locale files contain command feedback, errors, economy messages, language messages, and interface text. Preserve message keys when translating.