API

HeadDB exposes a public API module for integrations with head identifiers, models, queries, database access, favorites, custom content, and player-head functionality.

Modules

Module	Purpose
headdb-api	Public models, IDs, queries, database interfaces, and service interfaces.
headdb-core	Internal database implementation. External plugins normally should not depend on it.
headdb-platforms/headdb-paper	Installed Paper/Folia runtime. Treat it as the service provider, not an API dependency.

Use headdb-api with provided scope.

Maven dependency

<dependency>
    <groupId>io.github.silentdevelopment.headdb</groupId>
    <artifactId>headdb-api</artifactId>
    <version>7.0.0-rc.6</version>
    <scope>provided</scope>
</dependency>

Use the API version matching the HeadDB release you target.

Access the service

import io.github.silentdevelopment.headdb.HeadDBService;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

RegisteredServiceProvider<HeadDBService> registration =
        Bukkit.getServicesManager().getRegistration(HeadDBService.class);

if (registration == null) {
    return;
}

HeadDBService headDB = registration.getProvider();

Declare HeadDB as an optional or required plugin dependency according to your integration behavior, and do not access the service before HeadDB has registered it.

Head IDs

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

import io.github.silentdevelopment.headdb.model.HeadId;

HeadId id = HeadId.parse("custom:server-logo");

Store HeadDB IDs rather than copying raw textures whenever possible.

Finding heads

headDB.find("123");
headDB.find("custom:server-logo");
headDB.find("player:f16df3ef-06b8-443e-9166-fba6689585b4");

Handle missing heads gracefully because remote records may be revoked and local records may be deleted.

Favorites and local content

headDB.favorites().ids(player.getUniqueId());
headDB.customHeads().list();
headDB.customCategories().list();

Integration guidance

Do:

• Depend only on headdb-api.
• Retrieve HeadDBService through Bukkit services.
• Handle loading, failure, and missing-record states.
• Store typed HeadDB IDs.
• Treat returned models as public API values.

Do not:

• Read cache artifacts directly.
• Modify storage/headdb.db while the server is running.
• Depend on GUI, command, cache, scheduler, or Paper implementation classes.
• Assume every remote ID remains available forever.

The API and core modules target Java 21. Integrations may target Java 21 unless their own server platform requirements are higher.