Bukkit Java API

The Bukkit Java API is different from the public HTTP API. The HTTP API supplies catalog data to HeadDB. Other plugins normally use the Java API so they share HeadDB's loaded database, indexes, cache, and item factory.

Add the API dependency

HeadDB publishes headdb-api from the Bitworks Maven repository. Match the API version to the installed plugin and do not shade it into your jar.

<repositories>
  <repository>
    <id>bitworks-releases</id>
    <url>https://nexus.tinydc.net/repository/maven-releases/</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.bitworksmc</groupId>
  <artifactId>headdb-api</artifactId>
  <version>6.1.0</version>
  <scope>provided</scope>
</dependency>

Gradle:

repositories {
    maven { url = uri('https://nexus.tinydc.net/repository/maven-releases/') }
}

dependencies {
    compileOnly 'com.bitworksmc:headdb-api:6.1.0'
}

Declare depend: [HeadDB] in your plugin.yml when HeadDB is required, or softdepend: [HeadDB] when the integration is optional.

Obtain the service

HeadDB registers com.bitworksmc.headdb.api.HeadAPI with Bukkit's Services Manager:

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

if (registration == null) {
    getLogger().warning("HeadDB is not available");
    return;
}

HeadAPI headApi = registration.getProvider();

The catalog loads asynchronously. Prefer onReady() instead of blocking the server thread with awaitReady():

headApi.onReady()
    .thenCompose(heads -> headApi.findById(103838))
    .thenAccept(result -> Bukkit.getScheduler().runTask(this, () ->
        result.ifPresent(head -> {
            ItemStack item = head.getItem();
            getLogger().info("Loaded " + head.getName());
        })
    ));

Complete futures run through HeadDB's asynchronous database path. Create or mutate Bukkit items, worlds, entities, and inventories on the correct server thread for the target platform, as the example does.

Available lookups

Method	Result
isReady()	Whether a valid catalog is currently available.
onReady()	Future completed with the initial list of heads.
findById(int)	One stable numeric ID.
findByName(String, boolean)	One exact or lenient name match.
searchByName(String, boolean)	All exact or lenient name matches.
findByTexture(String)	One Mojang texture hash.
findByCategory(String)	Heads in a category.
findByTags(String...)	Heads matching supplied tags.
getHeads()	The complete locally loaded catalog.
findKnownCategories()	Current category names.
computeLocalHead(UUID)	A head for a player known to the server.
getCatalogStatus()	Current source, revision, size, and synchronization health.
search(SearchQuery)	Structured, sorted, paginated local catalog query.
addCatalogUpdateListener(listener)	Added, edited, and removed catalog changes.

Each Head exposes its ID, name, texture hash, full texture URL, category, tags, and getItem(). The old com.github.thesilentpro.headdb.api namespace is still present for compatibility but is deprecated; new integrations should use com.bitworksmc.headdb.api.