Getting Started

This is the recommended first configuration pass after installing HeadDB.

1. Start the server once

HeadDB generates its data folder during startup:

plugins/HeadDB/

Important files:

File	Purpose
config.yml	Core runtime, remote database, cache, storage, player heads, language, GUI behavior, scheduled refresh, and updater settings.
gui.yml	GUI layouts, buttons, icons, names, lore, and slots.
sounds.yml	Configurable sounds for GUI, economy, commands, confirmations, and administrative actions.
economy.yml	Optional Vault integration and pricing.
messages/en-US.yml	Default localized messages.
storage/headdb.db	Durable local data such as favorites, Custom Heads, Custom Categories, drafts, overrides, and player-head cache entries.

2. Confirm database health

Run:

/hdb version
/hdb status
/hdb verify

A healthy installation should report a loaded database and non-zero head, category, tag, and collection counts.

Database: LOADED from CACHE is normal after startup. It means HeadDB loaded the last verified local artifacts and can still check the remote manifest for updates.

3. Assign permissions

Simple setup:

Players: headdb.basic
Staff:   headdb.admin

For restricted servers, grant individual command and GUI permissions instead. See Permissions.

4. Decide whether heads cost money

Economy support is disabled by default. To charge players:

1. Install Vault.
2. Install a Vault-compatible economy provider.
3. Enable economy support in economy.yml.
4. Configure fallback, category, player-head, custom-category, or individual-head prices.

See Economy.

5. Review automatic database refreshes

Scheduled remote checks are enabled by default:

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

HeadDB only downloads database artifacts when the catalog or revocations resource changed. Manual refreshes remain available through /hdb refresh.

6. Back up local data

Back up these files before major upgrades or migrations:

config.yml
gui.yml
sounds.yml
economy.yml
messages/
storage/headdb.db

The database cache can be recreated. storage/headdb.db contains server-specific persistent data and should be treated as important state.