Bukkit Events - BetterHud

Overview

This page documents all Bukkit events fired by BetterHud. These events allow you to integrate with BetterHud’s lifecycle and respond to player interactions.

Player Events

HudPlayerJoinEvent

Fired when a player’s HUD data is loaded, typically on join.

Package

kr.toxicity.hud.api.bukkit.event.HudPlayerJoinEvent

Extends

PlayerEvent (Bukkit)
HudPlayerEvent

Fields

hudPlayer

HudPlayer

The HudPlayer instance for the player who joined

Methods

getHudPlayer

@NotNull HudPlayer getHudPlayer()

return

HudPlayer

The HudPlayer instance

getPlayer

@NotNull Player getPlayer()

return

Player

The Bukkit Player instance (inherited from PlayerEvent)

Usage Example

import kr.toxicity.hud.api.bukkit.event.HudPlayerJoinEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class PlayerJoinListener implements Listener {
    
    @EventHandler
    public void onHudPlayerJoin(HudPlayerJoinEvent event) {
        HudPlayer hudPlayer = event.getHudPlayer();
        Player player = event.getPlayer();
        
        // Initialize default HUDs
        Hud healthHud = BetterHud.inst().getHudManager().getHud("health_bar");
        if (healthHud != null) {
            healthHud.add(hudPlayer);
        }
        
        // Set initial variables
        hudPlayer.getVariableMap().put("score", "0");
        hudPlayer.getVariableMap().put("kills", "0");
        
        player.sendMessage("HUD system loaded!");
    }
}

HudPlayerQuitEvent

Fired when a player quits and their HUD data is being unloaded.

Package

kr.toxicity.hud.api.bukkit.event.HudPlayerQuitEvent

Extends

PlayerEvent (Bukkit)
HudPlayerEvent

Fields

hudPlayer

HudPlayer

The HudPlayer instance for the player who is quitting

Methods

getHudPlayer

@NotNull HudPlayer getHudPlayer()

return

HudPlayer

The HudPlayer instance

Usage Example

import kr.toxicity.hud.api.bukkit.event.HudPlayerQuitEvent;

@EventHandler
public void onHudPlayerQuit(HudPlayerQuitEvent event) {
    HudPlayer hudPlayer = event.getHudPlayer();
    Player player = event.getPlayer();
    
    // Save player data before they quit
    Map<String, String> variables = hudPlayer.getVariableMap();
    saveToDatabase(player.getUniqueId(), variables);
    
    // Log active HUDs
    Set<Hud> activeHuds = hudPlayer.getHuds();
    plugin.getLogger().info(player.getName() + " quit with " + activeHuds.size() + " active HUDs");
}

HudUpdateEvent

Fired when a player’s HUD is updated.

Package

kr.toxicity.hud.api.bukkit.event.HudUpdateEvent

Extends

PlayerEvent (Bukkit)
HudPlayerEvent

Fields

hudPlayer

HudPlayer

The HudPlayer whose HUD is being updated

Methods

getHudPlayer

@NotNull HudPlayer getHudPlayer()

return

HudPlayer

The HudPlayer instance

Usage Example

import kr.toxicity.hud.api.bukkit.event.HudUpdateEvent;

@EventHandler
public void onHudUpdate(HudUpdateEvent event) {
    HudPlayer hudPlayer = event.getHudPlayer();
    
    // Track update frequency
    long tick = hudPlayer.getTick();
    
    // Perform custom logic on HUD updates
    if (tick % 20 == 0) { // Every second (assuming 20 ticks/second)
        updateCustomMetrics(hudPlayer);
    }
}

CustomPopupEvent

Fired when a custom popup is triggered.

Package

kr.toxicity.hud.api.bukkit.event.CustomPopupEvent

Extends

PlayerEvent (Bukkit)
BetterHudEvent

Fields

name

String

The name/identifier of the popup

variables

Map<String, String>

A mutable map of variables that can be used by the popup

Constructor

public CustomPopupEvent(@NotNull Player who, @NotNull String name)

who

Player

required

The player the popup is for

name

String

required

The identifier of the popup

Methods

getName

@NotNull String getName()

return

String

The popup identifier

getVariables

@NotNull Map<String, String> getVariables()

return

Map<String, String>

The mutable variables map for this popup

Usage Example

import kr.toxicity.hud.api.bukkit.event.CustomPopupEvent;
import org.bukkit.Bukkit;

public class CustomPopupListener implements Listener {
    
    @EventHandler
    public void onCustomPopup(CustomPopupEvent event) {
        Player player = event.getPlayer();
        String popupName = event.getName();
        
        // Add custom variables based on popup type
        if (popupName.equals("damage_indicator")) {
            event.getVariables().put("damage_amount", "10");
            event.getVariables().put("damage_type", "FIRE");
        } else if (popupName.equals("achievement")) {
            event.getVariables().put("achievement_name", "First Kill");
            event.getVariables().put("reward", "100 coins");
        }
        
        // Log the popup
        plugin.getLogger().info("Custom popup '" + popupName + "' shown to " + player.getName());
    }
    
    // You can also fire custom popups programmatically:
    public void showCustomPopup(Player player, String popupName) {
        CustomPopupEvent event = new CustomPopupEvent(player, popupName);
        Bukkit.getPluginManager().callEvent(event);
    }
}

Lifecycle Events

PluginReloadStartEvent

Fired before BetterHud begins reloading its configuration.

Package

kr.toxicity.hud.api.bukkit.event.PluginReloadStartEvent

Extends

Event (Bukkit)
BetterHudEvent

Constructor

public PluginReloadStartEvent()

This event is fired asynchronously (super(true)).

Usage Example

import kr.toxicity.hud.api.bukkit.event.PluginReloadStartEvent;

@EventHandler
public void onReloadStart(PluginReloadStartEvent event) {
    // Save any data before reload
    plugin.getLogger().info("BetterHud is starting reload...");
    
    // Pause any integrations
    pauseCustomUpdates();
    
    // Save current state
    for (Player player : Bukkit.getOnlinePlayers()) {
        HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(player.getUniqueId());
        if (hudPlayer != null) {
            savePlayerState(hudPlayer);
        }
    }
}

PluginReloadedEvent

Fired after BetterHud has completed reloading its configuration.

Package

kr.toxicity.hud.api.bukkit.event.PluginReloadedEvent

Extends

Event (Bukkit)
BetterHudEvent

Fields

state

ReloadState

The result state of the reload operation

Constructor

public PluginReloadedEvent(@NotNull ReloadState state)

state

ReloadState

required

The reload state indicating success or failure

This event is fired asynchronously (super(true)).

Methods

getState

@NotNull ReloadState getState()

return

ReloadState

The reload state

Usage Example

import kr.toxicity.hud.api.bukkit.event.PluginReloadedEvent;
import kr.toxicity.hud.api.plugin.ReloadState;

@EventHandler
public void onReloaded(PluginReloadedEvent event) {
    ReloadState state = event.getState();
    
    if (state.isSuccess()) {
        plugin.getLogger().info("BetterHud reload completed successfully!");
        
        // Re-initialize integrations
        reinitializeHuds();
        reloadPlayerData();
        
        // Notify admins
        for (Player player : Bukkit.getOnlinePlayers()) {
            if (player.hasPermission("betterhud.admin")) {
                player.sendMessage("BetterHud reloaded successfully!");
            }
        }
    } else {
        plugin.getLogger().warning("BetterHud reload failed!");
        plugin.getLogger().warning("Check BetterHud logs for details.");
        
        // Notify admins of failure
        for (Player player : Bukkit.getOnlinePlayers()) {
            if (player.hasPermission("betterhud.admin")) {
                player.sendMessage("BetterHud reload failed! Check console.");
            }
        }
    }
}

Item Events

UpdateItemEvent

Fired when a player’s inventory items are updated with HUD overlays or modifications.

Package

kr.toxicity.hud.api.bukkit.event.UpdateItemEvent

Extends

PlayerEvent (Bukkit)
BetterHudEvent

Fields

itemStack

ItemStack

The item being updated

original

Event

The original Bukkit event that triggered this update

Constructor

public UpdateItemEvent(
    @NotNull Player player, 
    @NotNull ItemStack itemStack, 
    @NotNull Event original
)

player

Player

required

The player whose item is being updated

itemStack

ItemStack

required

The item being updated

original

Event

required

The original event that caused this item update

Methods

getItemStack

@NotNull ItemStack getItemStack()

return

ItemStack

The item being updated

getOriginal

@NotNull Event getOriginal()

return

Event

The original Bukkit event that triggered this update

getItemMeta

public synchronized @NotNull ItemMeta getItemMeta()

return

ItemMeta

The item’s metadata (lazily loaded and cached)

Usage Example

import kr.toxicity.hud.api.bukkit.event.UpdateItemEvent;
import org.bukkit.inventory.ItemStack;
import org.bukkit.inventory.meta.ItemMeta;

@EventHandler
public void onUpdateItem(UpdateItemEvent event) {
    Player player = event.getPlayer();
    ItemStack item = event.getItemStack();
    Event originalEvent = event.getOriginal();
    
    // Get the item meta
    ItemMeta meta = event.getItemMeta();
    
    // Add custom modifications
    if (item.getType().name().contains("SWORD")) {
        // Add custom data or modify the item
        List<String> lore = meta.getLore();
        if (lore == null) {
            lore = new ArrayList<>();
        }
        lore.add("Modified by BetterHud");
        meta.setLore(lore);
        item.setItemMeta(meta);
    }
    
    // Log the original event type
    plugin.getLogger().info("Item updated from event: " + originalEvent.getEventName());
}

Complete Event Listener Example

Here’s a complete example integrating multiple events:

import kr.toxicity.hud.api.bukkit.event.*;
import kr.toxicity.hud.api.BetterHud;
import kr.toxicity.hud.api.player.HudPlayer;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class CompleteBetterHudListener implements Listener {
    private final JavaPlugin plugin;
    
    public CompleteBetterHudListener(JavaPlugin plugin) {
        this.plugin = plugin;
    }
    
    @EventHandler(priority = EventPriority.NORMAL)
    public void onPlayerJoin(HudPlayerJoinEvent event) {
        HudPlayer hudPlayer = event.getHudPlayer();
        
        // Load player data from database
        loadPlayerData(hudPlayer);
        
        // Initialize default HUDs
        initializeDefaultHuds(hudPlayer);
    }
    
    @EventHandler(priority = EventPriority.NORMAL)
    public void onPlayerQuit(HudPlayerQuitEvent event) {
        HudPlayer hudPlayer = event.getHudPlayer();
        
        // Save player data
        savePlayerData(hudPlayer);
    }
    
    @EventHandler(priority = EventPriority.MONITOR)
    public void onHudUpdate(HudUpdateEvent event) {
        // Monitor HUD updates for debugging
        if (plugin.getConfig().getBoolean("debug")) {
            HudPlayer hudPlayer = event.getHudPlayer();
            plugin.getLogger().fine("HUD updated for " + hudPlayer.name() + " at tick " + hudPlayer.getTick());
        }
    }
    
    @EventHandler
    public void onCustomPopup(CustomPopupEvent event) {
        String popupName = event.getName();
        
        // Add variables based on popup type
        switch (popupName) {
            case "levelup" -> {
                Player p = event.getPlayer();
                event.getVariables().put("level", String.valueOf(p.getLevel()));
            }
            case "achievement" -> {
                event.getVariables().put("timestamp", String.valueOf(System.currentTimeMillis()));
            }
        }
    }
    
    @EventHandler
    public void onReloadStart(PluginReloadStartEvent event) {
        plugin.getLogger().info("BetterHud reload starting - saving data...");
        saveAllData();
    }
    
    @EventHandler
    public void onReloaded(PluginReloadedEvent event) {
        if (event.getState().isSuccess()) {
            plugin.getLogger().info("BetterHud reload successful - reinitializing...");
            reinitialize();
        } else {
            plugin.getLogger().severe("BetterHud reload failed!");
        }
    }
    
    @EventHandler
    public void onUpdateItem(UpdateItemEvent event) {
        // Track item updates for statistics
        trackItemUpdate(event.getPlayer(), event.getItemStack());
    }
    
    // Helper methods
    private void loadPlayerData(HudPlayer hudPlayer) { /* ... */ }
    private void savePlayerData(HudPlayer hudPlayer) { /* ... */ }
    private void initializeDefaultHuds(HudPlayer hudPlayer) { /* ... */ }
    private void saveAllData() { /* ... */ }
    private void reinitialize() { /* ... */ }
    private void trackItemUpdate(Player player, ItemStack item) { /* ... */ }
}

Getting Started

Core API

Platform APIs

Components

Events

Examples

​Overview

​Player Events

​HudPlayerJoinEvent

​Package

​Extends

​Fields

​Methods

getHudPlayer

getPlayer

​Usage Example

​HudPlayerQuitEvent

​Package

​Extends

​Fields

​Methods

getHudPlayer

​Usage Example

​HudUpdateEvent

​Package

​Extends

​Fields

​Methods

getHudPlayer

​Usage Example

​Popup Events

​CustomPopupEvent

​Package

​Extends

​Fields

​Constructor

​Methods

getName

getVariables

​Usage Example

​Lifecycle Events

​PluginReloadStartEvent

​Package

​Extends

​Constructor

​Usage Example

​PluginReloadedEvent

​Package

​Extends

​Fields

​Constructor

​Methods

getState

​Usage Example

​Item Events

​UpdateItemEvent

​Package

​Extends

​Fields

​Constructor

​Methods

getItemStack

getOriginal

getItemMeta

​Usage Example

​Complete Event Listener Example

​See Also

Build docs developers (and LLMs) love

Overview

Player Events

HudPlayerJoinEvent

Package

Extends

Fields

Methods

Usage Example

HudPlayerQuitEvent

Package

Extends

Fields

Methods

Usage Example

HudUpdateEvent

Package

Extends

Fields

Methods

Usage Example

Popup Events

CustomPopupEvent

Package

Extends

Fields

Constructor

Methods

Usage Example

Lifecycle Events

PluginReloadStartEvent

Package

Extends

Constructor

Usage Example

PluginReloadedEvent

Package

Extends

Fields

Constructor

Methods

Usage Example

Item Events

UpdateItemEvent

Package

Extends

Fields

Constructor

Methods

Usage Example

Complete Event Listener Example

See Also