Skip to main content

​
Overview

The Popup API allows you to display temporary, stackable notifications to players. Popups can be shown in response to events and automatically manage their lifecycle. The Popup interface represents a popup notification in BetterHud.

​
Package

kr.toxicity.hud.api.popup.Popup

​
Extends

  • HudObject - Base interface for all displayable BetterHud elements

​
Methods

​
getGroupName

Gets the group name of this popup. Popups in the same group share stack management. 
@NotNull String getGroupName()
​
return
String
The group name that this popup belongs to

​
getMaxStack

Gets the maximum number of popups that can be stacked simultaneously. 
int getMaxStack()
​
return
int
The maximum stack size for this popup

​
getLastIndex

Gets the last valid index for this popup (equals getMaxStack() - 1). 
default int getLastIndex()
​
return
int
The last index position (zero-based)

​
show

Shows the popup to a player. 
@Nullable PopupUpdater show(@NotNull UpdateEvent reason, @NotNull HudPlayer player)
​
reason
UpdateEvent
required
The event that triggered this popup to show
​
player
HudPlayer
required
The target player to show the popup to
​
return
PopupUpdater
A popup updater for managing this popup instance, or null if showing failed

​
hide

Hides all popups in this popup’s group from a player. 
default boolean hide(@NotNull HudPlayer player)
​
player
HudPlayer
required
The player to hide the popup from
​
return
boolean
True if the popup group was successfully hidden, false if the group wasn’t active

​
frameType

Gets the frame type of this popup. 
@NotNull FrameType frameType()
​
return
FrameType
The frame type (GLOBAL or LOCAL)

​
Frame Types

​
FrameType Enum

enum FrameType {
    GLOBAL,  // Uses global tick timing
    LOCAL    // Uses popup-local tick timing
}
​
GLOBAL
FrameType
Popup timing is synchronized with the global tick
​
LOCAL
FrameType
Popup has its own independent tick timing

​
PopupUpdater Interface

Manages the lifecycle of a displayed popup instance.

​
Package

kr.toxicity.hud.api.popup.PopupUpdater

​
Methods

​
update

Attempts to update the popup. 
boolean update()
​
return
boolean
True if the update was successful, false otherwise

​
getIndex

Gets the current stack index of this popup. 
int getIndex()
​
return
int
The current index in the popup stack

​
setIndex

Sets the stack index priority of this popup. 
void setIndex(int index)
​
index
int
required
The new index position for this popup

​
remove

Removes this popup from display. 
void remove()

​
PopupSortType Enum

Determines how popups are sorted in the stack. 
enum PopupSortType {
    FIRST,  // New popups appear first
    LAST    // New popups appear last
}

​
Usage Examples

​
Getting a Popup

import kr.toxicity.hud.api.BetterHud;
import kr.toxicity.hud.api.popup.Popup;

// Get popup manager
var popupManager = BetterHud.inst().getPopupManager();

// Get a specific popup by name
Popup myPopup = popupManager.getPopup("damage_indicator");

​
Showing a Popup to a Player

import kr.toxicity.hud.api.popup.Popup;
import kr.toxicity.hud.api.popup.PopupUpdater;
import kr.toxicity.hud.api.update.UpdateEvent;
import kr.toxicity.hud.api.player.HudPlayer;
import kr.toxicity.hud.api.BetterHud;
import org.bukkit.entity.Player;

public void showPopupToPlayer(Player bukkitPlayer, String popupName) {
    // Get HUD player
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Get the popup
    Popup popup = BetterHud.inst().getPopupManager().getPopup(popupName);
    if (popup == null) return;
    
    // Show the popup
    PopupUpdater updater = popup.show(UpdateEvent.EMPTY, hudPlayer);
    if (updater != null) {
        bukkitPlayer.sendMessage("Popup shown at index: " + updater.getIndex());
    } else {
        bukkitPlayer.sendMessage("Failed to show popup!");
    }
}

​
Hiding a Popup Group

public void hidePopupGroup(Player bukkitPlayer, String popupName) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    Popup popup = BetterHud.inst().getPopupManager().getPopup(popupName);
    if (popup == null) return;
    
    // Hide all popups in this group
    boolean hidden = popup.hide(hudPlayer);
    if (hidden) {
        bukkitPlayer.sendMessage("Popup group hidden!");
    }
}

​
Managing Popup Variables

import java.util.Map;

public void setPopupVariable(Player bukkitPlayer, String key, String value) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Get the player's variable map
    Map<String, String> variables = hudPlayer.getVariableMap();
    
    // Set a variable that can be used in popups
    variables.put(key, value);
}

​
Checking Active Popups

import java.util.Set;
import kr.toxicity.hud.api.popup.Popup;

public void listActivePopups(Player bukkitPlayer) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Get all active popups
    Set<Popup> activePopups = hudPlayer.getPopups();
    
    bukkitPlayer.sendMessage("Active Popups: " + activePopups.size());
    for (Popup popup : activePopups) {
        bukkitPlayer.sendMessage("- " + popup.getName() + " (group: " + popup.getGroupName() + ")");
    }
}

​
Working with Popup Iterator Groups

import kr.toxicity.hud.api.popup.PopupIteratorGroup;
import java.util.Map;

public void checkPopupGroup(Player bukkitPlayer, String groupName) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Get the popup group iterator map
    Map<String, PopupIteratorGroup> groups = hudPlayer.getPopupGroupIteratorMap();
    
    PopupIteratorGroup group = groups.get(groupName);
    if (group != null) {
        bukkitPlayer.sendMessage("Group " + groupName + " is active at index: " + group.getIndex());
    } else {
        bukkitPlayer.sendMessage("Group " + groupName + " is not active");
    }
}

​
Custom Popup Event Integration

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

public class PopupListener implements Listener {
    
    @EventHandler
    public void onCustomPopup(CustomPopupEvent event) {
        Player player = event.getPlayer();
        String popupName = event.getName();
        
        // Access custom variables
        event.getVariables().put("custom_data", "example_value");
        
        player.sendMessage("Custom popup triggered: " + popupName);
    }
}
  • HUD API - For persistent display elements
  • Triggers - Configure popup triggers
  • Events - CustomPopupEvent

​
See Also

  • Popup interface: kr.toxicity.hud.api.popup.Popup
  • PopupUpdater interface: kr.toxicity.hud.api.popup.PopupUpdater
  • PopupIterator interface: kr.toxicity.hud.api.popup.PopupIterator
  • PopupIteratorGroup interface: kr.toxicity.hud.api.popup.PopupIteratorGroup

Build docs developers (and LLMs) love

Get started for freeTalk to us