arcaniax-development / headdatabase-api

API for the famous HeadDatabase plugin

---

Head Database is a fast and user-friendly plugin that allows you to obtain thousands of custom Minecraft skulls that feature unique designs. This easy-to-use heads plugin gives you access to creative designing opportunities that overall enhances the quality of your builds, and gives creative freedom to yourself and your players.

This is the API repository for HeadDatabase. This is not HeadDatabase. If you are looking for the plugin HeadDatabase, get it from spigot.

Links

• Discord
• Issues
• JavaDocs

How to use the API

Releases are published to the central repository, snapshots are published to S01 OSS Sonatype.

Gradle

repositories {
    mavenCentral()
}

dependencies {
    compileOnly("com.arcaniax:HeadDatabase-API:1.3.2")
}

Maven

<!-- HeadDatabase-API -->
<dependency>
    <groupId>com.arcaniax</groupId>
    <artifactId>HeadDatabase-API</artifactId>
    <version>1.3.2</version>
    <scope>provided</scope>
</dependency>

Building

Gradle is the recommended way to build the project. Use ./gradlew build in the main project directory to build the project.

Suggestions

Suggestions are welcome! We have a separate issue form for suggestions, that can be found here.

Example usage

import me.arcaniax.hdb.api.DatabaseLoadEvent;
import me.arcaniax.hdb.api.HeadDatabaseAPI;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.inventory.ItemStack;
import org.bukkit.plugin.java.JavaPlugin;

public class HeadDatabaseAPIPlugin extends JavaPlugin implements Listener {

    public void onEnable() {
        this.getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onDatabaseLoad(DatabaseLoadEvent e) {
        HeadDatabaseAPI api = new HeadDatabaseAPI();
        try {
            ItemStack item = api.getItemHead("7129");
            getLogger().info(api.getItemID(item));
        } catch (NullPointerException nullPointerException) {
            getLogger().info("Could not find the head you were looking for");
        }
    }
}

Tips:

• Don't forget to add HeadDatabase to depend or softdepend section of your plugin.yml
• Listen to DatabaseLoadEvent and register your events afterwards. The event is fired once HeadDatabase is loaded successfully.

headdatabase-api's Issues

add method to get head from block

HeadDatabase-API Feature Suggestion:

I need a way to get the head from a block
How should it be implemented?

public ItemStack getHeadFrom(BlockState s);

Issue with new 4.18.1

[23:18:54] [Server thread/ERROR]: Could not pass event PlayerPickupItemEvent to HeadDatabase v4.18.1
java.lang.NullPointerException: Cannot invoke "String.equalsIgnoreCase(String)" because the return value of "org.bukkit.inventory.meta.SkullMeta.getOwner()" is null
	at me.arcaniax.hdb.listener.ItemPickupListener.onItemPickup(ItemPickupListener.java:36) ~[HeadDatabase_4.18.1.jar:?]
	at com.destroystokyo.paper.event.executor.asm.generated.GeneratedEventExecutor744.execute(Unknown Source) ~[?:?]
	at org.bukkit.plugin.EventExecutor$2.execute(EventExecutor.java:77) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:?]
	at co.aikar.timings.TimedEventExecutor.execute(TimedEventExecutor.java:81) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:git-Paper-223]
	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:70) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:?]
	at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-1.20.2.jar:git-Paper-223]
	at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:126) ~[paper-1.20.2.jar:git-Paper-223]
	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:615) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:?]
	at net.minecraft.world.entity.item.ItemEntity.playerTouch(ItemEntity.java:468) ~[?:?]
	at net.minecraft.world.entity.player.Player.touch(Player.java:638) ~[?:?]
	at net.minecraft.world.entity.player.Player.aiStep(Player.java:603) ~[?:?]
	at net.minecraft.world.entity.LivingEntity.tick(LivingEntity.java:3041) ~[?:?]
	at net.minecraft.world.entity.player.Player.tick(Player.java:277) ~[?:?]
	at net.minecraft.server.level.ServerPlayer.doTick(ServerPlayer.java:763) ~[?:?]
	at net.minecraft.server.network.ServerGamePacketListenerImpl.tick(ServerGamePacketListenerImpl.java:337) ~[?:?]
	at net.minecraft.network.Connection.tick(Connection.java:592) ~[?:?]
	at net.minecraft.server.network.ServerConnectionListener.tick(ServerConnectionListener.java:240) ~[?:?]
	at net.minecraft.server.MinecraftServer.tickChildren(MinecraftServer.java:1578) ~[paper-1.20.2.jar:git-Paper-223]
	at net.minecraft.server.dedicated.DedicatedServer.tickChildren(DedicatedServer.java:446) ~[paper-1.20.2.jar:git-Paper-223]
	at net.minecraft.server.MinecraftServer.tickServer(MinecraftServer.java:1379) ~[paper-1.20.2.jar:git-Paper-223]
	at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1156) ~[paper-1.20.2.jar:git-Paper-223]
	at net.minecraft.server.MinecraftServer.lambda$spin$0(MinecraftServer.java:315) ~[paper-1.20.2.jar:git-Paper-223]
	at java.lang.Thread.run(Thread.java:1583) ~[?:?]

We have a plugin called CMI that we allow to drop mobheads with a chance of x%
When the head drops HDB throws this error in console.

Throw exceptions instead of returning null (for this imitation of the internal api's namespace)

Obviously this is an imitation of the internal HeadDatabase API namespace. So rather than returning null, throw an exception for the idiots (like myself) who forget to set the scope to provided. Otherwise this will shade and cause a massive headache trying to figure out why the API doesn't work and always returns null items...

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• Update dependency gradle to v8.9

Detected dependencies

github-actions

.github/workflows/build.yml

• actions/checkout v4
• gradle/actions v3
• actions/setup-java v4
• actions/upload-artifact v4

gradle

settings.gradle.kts

build.gradle.kts

• com.diffplug.spotless 6.25.0
• io.github.gradle-nexus.publish-plugin 2.0.0
• com.destroystokyo.paper:paper-api 1.16.5-R0.1-SNAPSHOT

gradle-wrapper

gradle/wrapper/gradle-wrapper.properties

• gradle 8.8

---

• Check this box to trigger a request for Renovate to run again on this repository

setBlockSkin method always returns false

Bug Report Template:

Required Information section:

ALL FIELDS IN THIS SECTION ARE REQUIRED, and must contain appropriate information

HeadDatabase version:

4.12.6

Server build info:

This server is running Paper version git-Paper-778 (MC: 1.16.5) (Implementing API version 1.16.5-R0.1-SNAPSHOT)
You are 10 version(s) behind
Previous version: git-Paper-771 (MC: 1.16.5)

Description of the problem:

The setBlockSkin() method always returns false despite the block containing a playerhead and the ID being accurate.

How to replicate:

Placed a regular player_head on the ground. Tried to convert to a particular hdb head using an ID, but failed.

Additional Information:

The information here is optional for you to provide, however it may help us to more readily diagnose any compatibility and bug issues.

Other plugins being used on the server:

Relevant console output, log lines, and/or screenshots:

@EventHandler
    public void PlayerRightClickBlock(PlayerInteractEvent e) {
    	if(e.getHand() == EquipmentSlot.HAND) return;
        Player p = e.getPlayer();
        Block b = e.getClickedBlock();
        if (b.getType() == Material.PLAYER_HEAD) {
			HeadDatabaseAPI hdbApi = new HeadDatabaseAPI();
			Bukkit.getLogger().info(Boolean.toString(hdbApi.isHead("29431")));
			Bukkit.getLogger().info(Boolean.toString(hdbApi.setBlockSkin(b, "29431")));
			return;
		}
}

prints
true
false

(using api version 1.2 maven dependency)

Additional relevant comments/remarks:

Using Shockbyte

AFFIRMATION OF COMPLETION:

• I included all information required in the sections above
• I made sure there are no duplicates of this report (Use Search)
• I made sure I am using an up-to-date version of HeadDatabase & HeadDatabaseAPI
• I made sure the bug/error is not caused by any other plugin

Save ItemNTB from Head Database heads after placting and breaking

When a head has some name and lore it got lost after placing.. sadly..

Well i saw plugins like EvenMoreFish that offer Heads that keep their Information
(They dont work with an extra database they get the info from the item itself. i aspect its saved in the ntb somewhere.)

HEre i made a video
https://streamable.com/24c74k

Would be nice to have this for Heads from Headdatabase too. because it often happens that someone placed a head somewhere. that was made as special item and not to be placed :3

Before placing its namestring was:

Afer breaking it its namestring is:

You see currently after placing and breaking it aggain an HDB-Head losts moified name and lore and gets back his old Name that you can alsofind in the HDB-database

getItemHead() return always null

HeadDatabase version:

HeadDatabase version 4.12.6

Server build info:

This server is running Paper version git-Paper-189 (MC: 1.16.2) (Implementing API version 1.16.2-R0.1-SNAPSHOT)

Description of the problem:

getItemHead() return always null

How to replicate:

prom.xml:

...
        <repository>
            <id>headdatabase-api</id>
            <url>https://mvn.intellectualsites.com/content/repositories/thirdparty/</url>
        </repository>
...
        <dependency>
            <groupId>me.arcaniax</groupId>
            <artifactId>HeadDatabase-API</artifactId>
            <version>1.0.0</version>
        </dependency>
...

Code:

    @EventHandler(priority = EventPriority.LOWEST, ignoreCancelled = true)
    public void onBlockBreak(BlockBreakEvent event){
        if(event.getBlock().getType() == Material.PLAYER_HEAD || event.getBlock().getType() == Material.PLAYER_WALL_HEAD){
            event.setCancelled(true);

            HeadDatabaseAPI api = new HeadDatabaseAPI();
            ItemStack is = api.getItemHead("31775");
            if(is != null){
                ItemMeta meta = is.getItemMeta();
                meta.setDisplayName("§fMega Frucht");
                is.setItemMeta(meta);
                event.getPlayer().getInventory().addItem(is);
            }else{
                System.out.println("NULL");
            }
        }
    }

Additional Information:

have tried other ids

Other plugins being used on the server:

[23:50:19 INFO]: Plugins (15): Chairs, Citizens, ColoredBooked, HeadDatabase*, HolographicDisplays, LuckPerms, nexus, NexusEconomy, ProtocolLib, Sentinel, UltimateTimber, Unsign*, Vault, VoidSpawn, WorldEdit

Relevant console output, log lines, and/or screenshots:

[23:40:06 INFO]: NULL

Additional relevant comments/remarks:

AFFIRMATION OF COMPLETION:

• I included all information required in the sections above
• I made sure there are no duplicates of this report (Use Search)
• I made sure I am using an up-to-date version of HeadDatabase & HeadDatabaseAPI
• I made sure the bug/error is not caused by any other plugin
• [] I didn't read but checked everything above.

Feature Req: Adding a searchHeads function

HeadDatabase-API Feature Suggestion:
A function to search for heads like the /hdb search <name> command.

How should it be implemented?
Something like public List<Head> searchHeads(String query) where the returning list is the result set for the search query.

Additional context
Why i need this feaure or why is it useful?

• Creating a tool, that convert blocks (dirt/logs/what ever) in heads
• Let players search for heads in custom GUIs or systems
• ...

Checklist:

• I made sure there are no duplicates of my suggestion (Use search)
• I made sure my suggestion is useful for the majority of HeadDatabase-API users

API hoster is down

Execution failed for task ':compileKotlin'.
> Error while evaluating property 'filteredArgumentsMap' of task ':compileKotlin'
   > Could not resolve all files for configuration ':compileClasspath'.
      > Could not resolve me.arcaniax:HeadDatabase-API:[1.0.0,).
        Required by:
            project :
         > Failed to list versions for me.arcaniax:HeadDatabase-API.
            > Unable to load Maven meta-data from https://mvn.intellectualsites.com/content/repositories/thirdparty/me/arcaniax/HeadDatabase-API/maven-metadata.xml.
               > Could not HEAD 'https://mvn.intellectualsites.com/content/repositories/thirdparty/me/arcaniax/HeadDatabase-API/maven-metadata.xml'.
                  > Connect to mvn.intellectualsites.com:443 [mvn.intellectualsites.com/51.195.138.243] failed: Connection timed out: no further information

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

Your provider is not there anymore

1.20.2 Error occurred while enabling HeadDatabase v4.17.3

When starting HDB in 1.20.2 the console always throws an error

MinecraftVersion: CraftBukkit version 3886-Spigot-17ca32d-f0661c3 (MC: 1.20.2) (Implementing API version 1.20.2-R0.1-SNAPSHOT)

HeadDatabase: 4.17.3

[08:37:39] [Server thread/INFO]: [HeadDatabase] Enabling HeadDatabase v4.17.3
[08:37:40] [Server thread/INFO]: [HeadDatabase] §bUsing default §3"en_US.lang" §bcreated by §6Arcaniax
[08:37:40] [Server thread/ERROR]: Error occurred while enabling HeadDatabase v4.17.3 (Is it up to date?)
java.lang.NullPointerException: Profile name must not be null
at java.util.Objects.requireNonNull(Objects.java:259) ~[?:?]
at com.mojang.authlib.GameProfile.(GameProfile.java:31) ~[authlib-5.0.47.jar:?]
at me.arcaniax.hdb.util.HeadUtil.create(HeadUtil.java:97) ~[?:?]
at me.arcaniax.hdb.HeadDatabaseManager.(HeadDatabaseManager.java:120) ~[?:?]
at me.arcaniax.hdb.Main.onEnable(Main.java:55) ~[?:?]
at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:266) ~[spigot-api-1.20.2-R0.1-SNAPSHOT.jar:?]
at org.bukkit.plugin.java.JavaPluginLoader.enablePlugin(JavaPluginLoader.java:342) ~[spigot-api-1.20.2-R0.1-SNAPSHOT.jar:?]
at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:480) ~[spigot-api-1.20.2-R0.1-SNAPSHOT.jar:?]
at org.bukkit.craftbukkit.v1_20_R2.CraftServer.enablePlugin(CraftServer.java:548) ~[spigot-1.20.2-R0.1-SNAPSHOT.jar:3886-Spigot-17ca32d-f0661c3]
at org.bukkit.craftbukkit.v1_20_R2.CraftServer.enablePlugins(CraftServer.java:462) ~[spigot-1.20.2-R0.1-SNAPSHOT.jar:3886-Spigot-17ca32d-f0661c3]
at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:577) ~[spigot-1.20.2-R0.1-SNAPSHOT.jar:3886-Spigot-17ca32d-f0661c3]
at net.minecraft.server.MinecraftServer.loadLevel(MinecraftServer.java:400) ~[spigot-1.20.2-R0.1-SNAPSHOT.jar:3886-Spigot-17ca32d-f0661c3]
at net.minecraft.server.dedicated.DedicatedServer.e(DedicatedServer.java:250) ~[spigot-1.20.2-R0.1-SNAPSHOT.jar:3886-Spigot-17ca32d-f0661c3]
at net.minecraft.server.MinecraftServer.w(MinecraftServer.java:954) ~[spigot-1.20.2-R0.1-SNAPSHOT.jar:3886-Spigot-17ca32d-f0661c3]
at net.minecraft.server.MinecraftServer.lambda$0(MinecraftServer.java:298) ~[spigot-1.20.2-R0.1-SNAPSHOT.jar:3886-Spigot-17ca32d-f0661c3]
at java.lang.Thread.run(Thread.java:1623) ~[?:?]

HeadDatabaseAPI is NULL

HeadDatabase version:

Plugin version: 4.17.0
API version: 1.3.1

Server build info:

This server is running CraftBukkit version
3832-Spigot-3374045-a94277a (MC: 1.20.1)
(Implementing API version 1.20.1-R0.1-SNAPSHOT)

Description of the problem:

I have a wrapper class, which hooks into HeadDatabase, however accessing the api from a different class always return NULL. To be honest I'm not really sure if my code is messed up, if there's compatibility issues for 1.20.1 or if I just managed to break Java once again.

How to replicate:

public class HeadDatabase implements Listener {
    @Getter @Setter private HeadDatabaseAPI api;

    public HeadDatabase() {
    }

    @EventHandler
    public void registerApi(DatabaseLoadEvent e) {
        Bukkit.getLogger().info("Registering HDB");
        api = new HeadDatabaseAPI();
    }
}

Additional Information:

I can definitely see the "Registering HDB" output in console, logging the api will also show me an Object, but when I access it from another class I need to call new HeadDatabaseAPI() again, but after that it just works.

HeadDatabaseAPI api = headDatabase.getApi();

if (api == null) {
    Bukkit.getLogger.info("API is null");
    api = new HeadDatabaseAPI();
    headDatabase.setApi(api);
}

Relevant console output, log lines, and/or screenshots:

[20:17:38] [Server thread/INFO]: Registering HDB
[20:17:38] [Craft Scheduler Thread - 0/INFO]: [HeadDatabase] Successfully loaded 18 featured tags!
[20:17:38] [Craft Scheduler Thread - 1/WARN]: [HeadDatabase] ºcYou are using an outdated version!
[20:17:38] [Craft Scheduler Thread - 1/WARN]: [HeadDatabase] Latest version: ºa4.17.3ºe. You are on version: ºc4.17.0ºe.
[20:17:38] [Craft Scheduler Thread - 1/WARN]: [HeadDatabase] Update here: ºbhttps://www.spigotmc.org/resources/head-database.14280/
[20:18:02] [Server thread/INFO]: API is null

AFFIRMATION OF COMPLETION:

• I included all information required in the sections above
• I made sure there are no duplicates of this report (Use Search)
• [] I made sure I am using an up-to-date version of HeadDatabase & HeadDatabaseAPI
• [] I made sure the bug/error is not caused by any other plugin

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: undefined. Note: this is a nested preset so please contact the preset author if you are unable to fix it yourself.