Skip to main content

​
Overview

BetterHud fires various events throughout its lifecycle and during player interactions. You can listen to these events to integrate with BetterHud or extend its functionality.

​
Event Hierarchy

All BetterHud events implement the BetterHudEvent interface: 
package kr.toxicity.hud.api.bukkit.event;

public interface BetterHudEvent {
    HandlerList HANDLER_LIST = new HandlerList();
}

​
Available Events

BetterHud provides several event types:

Player Events

Events related to player HUD interactions

Popup Events

Events for custom popup triggers

Lifecycle Events

Plugin reload and lifecycle events

Update Events

Inventory and item update events

​
Event Categories

​
Player Events

Events that fire for individual players:
  • HudPlayerJoinEvent - When a player’s HUD data is loaded
  • HudPlayerQuitEvent - When a player leaves and their HUD data is unloaded
  • HudUpdateEvent - When a player’s HUD is updated
  • CustomPopupEvent - Triggered when a custom popup is shown

​
Lifecycle Events

  • PluginReloadStartEvent - Before BetterHud reloads
  • PluginReloadedEvent - After BetterHud finishes reloading

​
Item Events

  • UpdateItemEvent - When a player’s inventory items are updated

​
Basic Event Listening

To listen to BetterHud events, create a Bukkit event listener: 
import kr.toxicity.hud.api.bukkit.event.*;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class BetterHudListener implements Listener {
    private final JavaPlugin plugin;
    
    public BetterHudListener(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler
    public void onHudPlayerJoin(HudPlayerJoinEvent event) {
        plugin.getLogger().info("Player HUD loaded: " + event.getHudPlayer().name());
    }
    
    @EventHandler
    public void onPluginReload(PluginReloadedEvent event) {
        plugin.getLogger().info("BetterHud reloaded with state: " + event.getState());
    }
}

// Register in your plugin's onEnable:
public class MyPlugin extends JavaPlugin {
    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(new BetterHudListener(this), this);
    }
}

​
HudPlayerEvent Interface

Many events implement the HudPlayerEvent interface, which provides access to the HudPlayer: 
public interface HudPlayerEvent extends BetterHudEvent {
    @NotNull HudPlayer getHudPlayer();
}
This allows you to access the BetterHud player wrapper: 
@EventHandler
public void onHudUpdate(HudUpdateEvent event) {
    HudPlayer hudPlayer = event.getHudPlayer();
    
    // Access player data
    String name = hudPlayer.name();
    UUID uuid = hudPlayer.uuid();
    
    // Get active HUDs
    Set<Hud> huds = hudPlayer.getHuds();
    
    // Access variables
    Map<String, String> vars = hudPlayer.getVariableMap();
}

​
Event Handler List

All BetterHud events share a common HANDLER_LIST: 
HandlerList HANDLER_LIST = new HandlerList();
Each event class must implement: 
@NotNull
@Override
public HandlerList getHandlers() {
    return HANDLER_LIST;
}

public static HandlerList getHandlerList() {
    return HANDLER_LIST;
}

​
Event Priority

You can set event priority using the @EventHandler annotation: 
import org.bukkit.event.EventPriority;

@EventHandler(priority = EventPriority.HIGH)
public void onHudPlayerJoin(HudPlayerJoinEvent event) {
    // This handler runs with HIGH priority
}

@EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
public void onCustomPopup(CustomPopupEvent event) {
    // This handler runs last and only if not cancelled
}

​
Event Cancellation

Note: Most BetterHud events are informational and cannot be cancelled. Check the specific event documentation to see if it implements Cancellable.

​
Common Use Cases

​
Integrate with Your Plugin on Player Join

@EventHandler
public void onPlayerJoin(HudPlayerJoinEvent event) {
    HudPlayer hudPlayer = event.getHudPlayer();
    
    // Initialize custom HUD for this player
    Hud customHud = BetterHud.inst().getHudManager().getHud("my_custom_hud");
    if (customHud != null) {
        customHud.add(hudPlayer);
    }
    
    // Set default variables
    hudPlayer.getVariableMap().put("points", "0");
    hudPlayer.getVariableMap().put("rank", "Beginner");
}

​
Clean Up on Player Quit

@EventHandler
public void onPlayerQuit(HudPlayerQuitEvent event) {
    HudPlayer hudPlayer = event.getHudPlayer();
    
    // Save player data
    savePlayerData(hudPlayer);
    
    // Clean up resources
    clearCustomData(hudPlayer.uuid());
}

​
React to Reloads

@EventHandler
public void onReloadStart(PluginReloadStartEvent event) {
    // Save data before reload
    plugin.getLogger().info("BetterHud is reloading...");
    saveAllData();
}

@EventHandler
public void onReloaded(PluginReloadedEvent event) {
    if (event.getState().isSuccess()) {
        plugin.getLogger().info("BetterHud reload successful!");
        reinitializeIntegration();
    } else {
        plugin.getLogger().warning("BetterHud reload failed!");
    }
}

​
Track Popup Usage

@EventHandler
public void onCustomPopup(CustomPopupEvent event) {
    Player player = event.getPlayer();
    String popupName = event.getName();
    
    // Log popup usage
    logPopup(player, popupName);
    
    // Add custom variables
    event.getVariables().put("timestamp", String.valueOf(System.currentTimeMillis()));
}

​
Next Steps

Bukkit Events

Detailed documentation for each event

HUD API

Work with HUD components

Popup API

Manage popup notifications

Player API

Access HudPlayer functionality

​
See Also

  • BetterHudEvent interface: kr.toxicity.hud.api.bukkit.event.BetterHudEvent
  • HudPlayerEvent interface: kr.toxicity.hud.api.bukkit.event.HudPlayerEvent
  • HudPlayer interface: kr.toxicity.hud.api.player.HudPlayer

Build docs developers (and LLMs) love

Get started for freeTalk to us