Skip to main content
The Bukkit API provides platform-specific classes and events for integrating BetterHud with Bukkit-based servers, including Spigot, Paper, and Folia.

​
Installation

repositories {
    mavenCentral()
}

dependencies {
    compileOnly("io.github.toxicity188:BetterHud-standard-api:VERSION")
    compileOnly("io.github.toxicity188:BetterHud-bukkit-api:VERSION")
    compileOnly("io.github.toxicity188:BetterCommand:VERSION")
}
Check Maven Central for the latest version.

​
Core Classes

​
BukkitBootstrap

The main entry point for accessing Bukkit-specific functionality. 
package kr.toxicity.hud.api.bukkit;

public interface BukkitBootstrap extends BetterHudBootstrap {
    @NotNull BedrockAdapter bedrockAdapter();
    @NotNull Listener triggerListener();
    @Override @NotNull NMS volatileCode();
}
Methods:
  • bedrockAdapter() - Gets the bedrock adapter that hooks into Geyser or Floodgate
  • triggerListener() - Gets the Bukkit event listener for triggers
  • volatileCode() - Gets Bukkit’s NMS (Net Minecraft Server) handler

​
BedrockAdapter

Checks if a player is connecting from a Bedrock Edition client. 
package kr.toxicity.hud.api.bukkit.bedrock;

@FunctionalInterface
public interface BedrockAdapter {
    boolean isBedrockPlayer(@NotNull UUID uuid);
}
Usage: 
BukkitBootstrap bootstrap = (BukkitBootstrap) BetterHudAPI.inst().bootstrap();
UUID playerUuid = player.getUniqueId();

if (bootstrap.bedrockAdapter().isBedrockPlayer(playerUuid)) {
    // Handle Bedrock player differently
}

​
NMS

Provides access to NMS (version-specific) code with Folia support. 
package kr.toxicity.hud.api.bukkit.nms;

public interface NMS extends VolatileCodeHandler {
    @NotNull Player getFoliaAdaptedPlayer(@NotNull Player player);
    @NotNull Entity getFoliaAdaptedEntity(@NotNull Entity entity);
    @NotNull NMSVersion getVersion();
    void registerCommand(@NotNull CommandModule<BetterCommandSource> module);
    void handleReloadCommand(@NotNull CommandModule<BetterCommandSource> module);
}
Key Methods:
  • getFoliaAdaptedPlayer(Player) - Gets a player instance safe for async access on Folia
  • getFoliaAdaptedEntity(Entity) - Gets an entity instance safe for async access on Folia
  • getVersion() - Gets the server’s NMS version
  • registerCommand(CommandModule) - Registers a brigadier command

​
Events

All Bukkit events extend BetterHudEvent and follow standard Bukkit event patterns.

​
Player Events

​
HudPlayerJoinEvent

Fired when a player’s HUD data is loaded. 
package kr.toxicity.hud.api.bukkit.event;

public class HudPlayerJoinEvent extends PlayerEvent implements HudPlayerEvent {
    public HudPlayerJoinEvent(@NotNull HudPlayer hudPlayer);
    @NotNull HudPlayer getHudPlayer();
}
Usage: 
@EventHandler
public void onHudPlayerJoin(HudPlayerJoinEvent event) {
    HudPlayer hudPlayer = event.getHudPlayer();
    Player bukkit = event.getPlayer();
    
    // Initialize custom HUD elements for the player
    hudPlayer.showPopup("welcome");
}

​
HudPlayerQuitEvent

Fired when a player quits and their HUD data is unloaded. 
package kr.toxicity.hud.api.bukkit.event;

public class HudPlayerQuitEvent extends PlayerEvent implements HudPlayerEvent {
    public HudPlayerQuitEvent(@NotNull HudPlayer hudPlayer);
    @NotNull HudPlayer getHudPlayer();
}

​
HudUpdateEvent

Fired when a player’s HUD is updated. 
package kr.toxicity.hud.api.bukkit.event;

public class HudUpdateEvent extends PlayerEvent implements HudPlayerEvent {
    public HudUpdateEvent(@NotNull HudPlayer hudPlayer);
    @NotNull HudPlayer getHudPlayer();
}
Usage: 
@EventHandler
public void onHudUpdate(HudUpdateEvent event) {
    HudPlayer player = event.getHudPlayer();
    // Perform actions when HUD updates
}

​
Custom Events

​
CustomPopupEvent

Fired when a custom popup is displayed to a player. 
package kr.toxicity.hud.api.bukkit.event;

public class CustomPopupEvent extends PlayerEvent implements BetterHudEvent {
    public CustomPopupEvent(@NotNull Player who, @NotNull String name);
    String getName();
    Map<String, String> getVariables();
}
Usage: 
@EventHandler
public void onCustomPopup(CustomPopupEvent event) {
    String popupName = event.getName();
    Map<String, String> vars = event.getVariables();
    
    // Add custom variables to the popup
    vars.put("custom_value", "123");
}

​
Plugin Events

​
PluginReloadStartEvent

Fired when BetterHud starts reloading. 
package kr.toxicity.hud.api.bukkit.event;

public class PluginReloadStartEvent extends Event implements BetterHudEvent {
    public PluginReloadStartEvent();
}

​
PluginReloadedEvent

Fired when BetterHud finishes reloading. 
package kr.toxicity.hud.api.bukkit.event;

public class PluginReloadedEvent extends Event implements BetterHudEvent {
    public PluginReloadedEvent(@NotNull ReloadState state);
    ReloadState getState();
}
Usage: 
@EventHandler
public void onReload(PluginReloadedEvent event) {
    ReloadState state = event.getState();
    if (state.success()) {
        getLogger().info("BetterHud reloaded successfully");
    } else {
        getLogger().warning("BetterHud reload failed: " + state.message());
    }
}

​
Triggers

​
HudBukkitEventTrigger

Wraps Bukkit events for use as HUD triggers. 
package kr.toxicity.hud.api.bukkit.trigger;

public interface HudBukkitEventTrigger<T extends Event> extends HudTrigger<T> {
    @NotNull Class<T> getEventClass();
}
Usage: 
// Register a custom event trigger
HudBukkitEventTrigger<PlayerDeathEvent> deathTrigger = 
    new HudBukkitEventTrigger<PlayerDeathEvent>() {
        @Override
        public @NotNull Class<PlayerDeathEvent> getEventClass() {
            return PlayerDeathEvent.class;
        }
        
        @Override
        public void invoke(@NotNull PlayerDeathEvent event) {
            HudPlayer player = BetterHudAPI.inst().getHudPlayer(event.getPlayer().getUniqueId());
            if (player != null) {
                player.showPopup("death_screen");
            }
        }
    };

BetterHudAPI.inst().registerTrigger("player_death", deathTrigger);

​
Complete Example

Here’s a complete example plugin using the Bukkit API: 
import kr.toxicity.hud.api.BetterHudAPI;
import kr.toxicity.hud.api.bukkit.BukkitBootstrap;
import kr.toxicity.hud.api.bukkit.event.*;
import kr.toxicity.hud.api.player.HudPlayer;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class MyHudPlugin extends JavaPlugin implements Listener {
    
    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
        
        // Access Bukkit-specific features
        BukkitBootstrap bootstrap = (BukkitBootstrap) BetterHudAPI.inst().bootstrap();
        getLogger().info("Running on NMS version: " + bootstrap.volatileCode().getVersion());
    }
    
    @EventHandler
    public void onPlayerJoin(HudPlayerJoinEvent event) {
        HudPlayer hudPlayer = event.getHudPlayer();
        Player player = event.getPlayer();
        
        // Show welcome popup
        hudPlayer.showPopup("welcome");
        
        // Check if Bedrock player
        BukkitBootstrap bootstrap = (BukkitBootstrap) BetterHudAPI.inst().bootstrap();
        if (bootstrap.bedrockAdapter().isBedrockPlayer(player.getUniqueId())) {
            getLogger().info(player.getName() + " is a Bedrock player");
        }
    }
    
    @EventHandler
    public void onCustomPopup(CustomPopupEvent event) {
        // Add custom variables to popups
        if (event.getName().equals("level_up")) {
            Player player = event.getPlayer();
            event.getVariables().put("level", String.valueOf(player.getLevel()));
        }
    }
    
    @EventHandler
    public void onReloadComplete(PluginReloadedEvent event) {
        if (event.getState().success()) {
            getLogger().info("BetterHud reloaded successfully!");
        }
    }
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us