HeadDB is a Paper/Folia plugin for browsing, searching, and giving Minecraft head items from a public remote database.
- Java 25 for the Paper plugin.
- Paper/Folia.
- Network access.
- Vault and an economy provider if economy support is enabled.
The API and core modules target Java 21. The Paper plugin targets Java 25.
- Public remote head database.
- Verified remote downloads using SHA-256.
- Local cache with startup cache loading.
- Search and category browsing.
- Player heads.
- Local custom heads.
- Favorites.
- Custom categories.
- Admin editing tools.
- Configurable GUI layout and messages.
- Optional Vault economy integration.
- Paper/Folia support.
- API/core modules for external integrations.
headdb-api
Public API: models, identifiers, queries, and database interfaces.
headdb-core
Database implementation: remote loading, verification, parsing, cache, and refresh.
headdb-platforms/headdb-paper
Paper/Folia plugin: commands, GUI, local storage, messages, economy, and item generation.
Documentation: https://silentdevelopment.github.io/HeadDB/
Build or download the Paper plugin jar and place it in your server plugins folder.
Start the server once to generate config files.
plugins/HeadDB/
config.yml
gui.yml
economy.yml
messages/
en-US.yml
Basic player usage:
/hdb
Useful admin commands:
/hdb status
/hdb verify
/hdb refresh
/hdb reload
/hdb debug
The main GUI provides browsing, searching, favorites, player heads, custom heads, custom categories, and settings.
Add the API module as a dependency if you want to integrate with HeadDB from another plugin.
<dependency>
<groupId>io.github.silentdevelopment.headdb</groupId>
<artifactId>headdb-api</artifactId>
<version>7.0.0-rc.3</version>
<scope>provided</scope>
</dependency>Example: search the database.
importio.github.silentdevelopment.headdb.database.HeadDatabase;
importio.github.silentdevelopment.headdb.model.Head;
importio.github.silentdevelopment.headdb.query.HeadQuery;
importio.github.silentdevelopment.headdb.query.HeadQueryResult;
publicfinalclassHeadSearchExample {
privatefinalHeadDatabasedatabase;
publicHeadSearchExample(HeadDatabasedatabase) {
this.database = database;
}
publicvoidsearch() {
HeadQueryquery = HeadQuery.builder()
.query("stone")
.page(1)
.pageSize(28)
.build();
HeadQueryResultresult = database.search(query);
for (Headhead : result.heads()) {
System.out.println(head.id().display() + " - " + head.name());
}
}
}Example: find a head by ID.
importio.github.silentdevelopment.headdb.database.HeadDatabase;
importio.github.silentdevelopment.headdb.model.Head;
importio.github.silentdevelopment.headdb.model.HeadId;
importjava.util.Optional;
publicfinalclassHeadLookupExample {
privatefinalHeadDatabasedatabase;
publicHeadLookupExample(HeadDatabasedatabase) {
this.database = database;
}
publicOptional<Head> find(Stringinput) {
HeadIdid = HeadId.parse(input);
returndatabase.find(id);
}
}Remote heads can usually be referenced by their visible ID. Custom and player heads use typed IDs.
123
custom:melon
player:f16df3ef-06b8-443e-9166-fba6689585b4
Verify API/core with Java 21:
mvn -B -ntp -pl headdb-api,headdb-core -am verifyPackage the Paper plugin with Java 25:
mvn -B -ntp -pl headdb-platforms/headdb-paper -am clean packageThe plugin jar is produced at:
headdb-platforms/headdb-paper/target/HeadDB.jar
Build the documentation site locally:
cd docs
npm install
npm run docs:buildHeadDB is a multi-license project.
headdb-api
Apache-2.0
headdb-core
Apache-2.0
headdb-platforms/headdb-paper
GPL-3.0-or-later
Full license texts are stored in:
LICENSES/Apache-2.0.txt
LICENSES/GPL-3.0-or-later.txt
Unless a file states otherwise, files are licensed under the license of the module they belong to.