Heads and Local Data

HeadDB combines verified public data with server-local content and overrides.

Public remote heads

Remote heads are downloaded from the HeadDB catalog and use numeric IDs such as:

123

The public database provides categories, tags, collections, textures, and revocations. Remote artifacts are verified before activation and cached locally.

Typed IDs

HeadDB distinguishes head sources through typed identifiers:

123
custom:server-logo
player:f16df3ef-06b8-443e-9166-fba6689585b4

Use typed IDs when storing references outside HeadDB.

Player heads

Player heads are generated separately from the remote catalog and use player UUID identity. They may be resolved from known players or through external profile lookup when enabled.

/hdb player <name-or-uuid> [target] [amount]

Custom Heads

Custom Heads are server-local records created by administrators. They can be created through the GUI or /hdb custom commands and can use a supplied texture or compatible held head.

Custom Heads support drafts and publication. Drafts remain visible only to authorized administrators.

/hdb custom list
/hdb custom create <id> <texture> [name]
/hdb custom createheld <id> [name]

Custom Categories

Custom Categories are local organizational categories that appear alongside public categories in Browse. They support their own name, icon, description, permission ID, visibility, draft state, and membership.

Assigning a remote head to a Custom Category is a local override and does not modify the public database.

Custom tags and collections

Local tags and collections can be created through the GUI or supported commands. They can be assigned to remote and Custom Heads without changing the public catalog.

Metadata overrides

Administrators can locally override remote head properties:

• Name
• Lore
• Category
• Tags
• Collections
• Visibility

Overrides can be reset to the remote values.

Persistent storage

Server-local data is stored in:

plugins/HeadDB/storage/headdb.db

This includes:

• Favorites
• Custom Heads and drafts
• Custom Categories and drafts
• Custom tags and collections
• Hidden heads
• Remote metadata overrides
• Player-head cache records

Back up this database before migrations, major upgrades, or destructive administration.

Cache versus storage

cache/ contains reproducible verified remote artifacts and can be downloaded again.

storage/headdb.db contains unique server-local state and should not be treated as disposable.