Skip to main content

​
Overview

The HudPlayer interface represents a player’s HUD data and provides methods to control HUD elements, popups, and player-specific settings. It extends BetterCommandSource for command operations.

​
Getting a HudPlayer

import kr.toxicity.hud.api.BetterHudAPI;
import kr.toxicity.hud.api.manager.PlayerManager;
import kr.toxicity.hud.api.player.HudPlayer;

PlayerManager manager = BetterHudAPI.inst().getPlayerManager();
HudPlayer hudPlayer = manager.getHudPlayer(playerUUID);

​
Player Identification

​
Get UUID

UUID uuid()
Gets the player’s unique identifier.
​
return
UUID
The player’s UUID
Example: 
UUID playerId = hudPlayer.uuid();

​
Get Name

String name()
Gets the player’s scoreboard name.
​
return
String
The player’s name
Example: 
String playerName = hudPlayer.name();
System.out.println("Player: " + playerName);

​
Get Handle

Object handle()
Gets the original platform player object (e.g., Bukkit Player).
​
return
Object
The underlying platform player object
Example: 
Object platformPlayer = hudPlayer.handle();
if (platformPlayer instanceof Player bukkitPlayer) {
    bukkitPlayer.sendMessage("Hello!");
}

​
Location and World

​
Get Location

LocationWrapper location()
Gets the player’s current location.
​
return
LocationWrapper
Wrapper containing player coordinates and orientation
Example: 
LocationWrapper loc = hudPlayer.location();
double x = loc.getX();
double y = loc.getY();
double z = loc.getZ();

​
Get World

WorldWrapper world()
Gets the player’s current world.
​
return
WorldWrapper
Wrapper for the player’s world
Example: 
WorldWrapper world = hudPlayer.world();
String worldName = world.getName();

​
HUD Components

​
Get HUD Component

WidthComponent getHudComponent()
Gets the player’s last rendered HUD component.
​
return
WidthComponent
The current HUD component displayed to the player
Example: 
WidthComponent component = hudPlayer.getHudComponent();
int componentWidth = component.width();

​
Set Additional Component

void setAdditionalComponent(WidthComponent component)
Sets an additional component to display alongside the HUD.
​
component
WidthComponent
The component to add, or null to remove
Example: 
WidthComponent customComponent = createCustomComponent();
hudPlayer.setAdditionalComponent(customComponent);

// Remove additional component
hudPlayer.setAdditionalComponent(null);

​
Get Additional Component

WidthComponent getAdditionalComponent()
Gets the current additional component.
​
return
WidthComponent
The additional component, or null if none is set
Example: 
WidthComponent additional = hudPlayer.getAdditionalComponent();
if (additional != null) {
    System.out.println("Additional component width: " + additional.width());
}

​
HUD Control

​
Check HUD Enabled

boolean isHudEnabled()
Checks whether HUD updates are enabled for this player.
​
return
boolean
true if HUD is enabled
Example: 
if (hudPlayer.isHudEnabled()) {
    // HUD is active
}

​
Set HUD Enabled

void setHudEnabled(boolean toEnable)
Enables or disables HUD updates for this player.
​
toEnable
boolean
required
true to enable HUD, false to disable
Example: 
// Disable HUD
hudPlayer.setHudEnabled(false);

// Enable HUD
hudPlayer.setHudEnabled(true);

​
Tick and Updates

​
Get Tick

long getTick()
Gets the player’s current tick count. This represents the number of times update() has been called.
​
return
long
The tick count
Example: 
long currentTick = hudPlayer.getTick();
if (currentTick % 20 == 0) {
    // Every second (20 ticks)
}

​
Update

void update()
Manually triggers a HUD update for this player. Example: 
hudPlayer.update(); // Force immediate HUD refresh

​
Start Tick

void startTick()
Cancels any existing tick task and starts a new one. Example: 
hudPlayer.startTick(); // Restart the update cycle

​
Cancel Tick

void cancelTick()
Cancels the player’s tick task, stopping automatic updates. Example: 
hudPlayer.cancelTick(); // Stop automatic updates

​
Cancel

void cancel()
Cancels and closes all player HUD data. Called when player disconnects. Example: 
hudPlayer.cancel(); // Cleanup player data

​
Player Head

​
Get Head

HudPlayerHead getHead()
Gets the player’s head data for rendering.
​
return
HudPlayerHead
Player head information
Example: 
HudPlayerHead head = hudPlayer.getHead();
// Use for custom HUD rendering

​
Variables

​
Get Variable Map

Map<String, String> getVariableMap()
Gets the mutable map of player-specific local variables.
​
return
Map<String, String>
Mutable map of variable names to values
Example: 
Map<String, String> vars = hudPlayer.getVariableMap();
vars.put("custom_value", "100");
vars.put("player_rank", "VIP");

String rank = vars.get("player_rank");

​
Popups

​
Get Popup Key Map

Map<Object, PopupUpdater> getPopupKeyMap()
Gets the mutable map of active popup updaters.
​
return
Map<Object, PopupUpdater>
Map of popup keys to their updaters
Example: 
Map<Object, PopupUpdater> popups = hudPlayer.getPopupKeyMap();
for (Map.Entry<Object, PopupUpdater> entry : popups.entrySet()) {
    PopupUpdater updater = entry.getValue();
    // Manage popup
}

​
Get Popup Group Iterator Map

Map<String, PopupIteratorGroup> getPopupGroupIteratorMap()
Gets the mutable map of popup iterator groups.
​
return
Map<String, PopupIteratorGroup>
Map of group names to popup iterators
Example: 
Map<String, PopupIteratorGroup> groups = hudPlayer.getPopupGroupIteratorMap();
PopupIteratorGroup questGroup = groups.get("quests");

​
HUD Objects

​
Get HUD Objects

Map<HudObject.Identifier, HudComponentSupplier<?>> getHudObjects()
Gets all currently active HUD objects for this player.
​
return
Map<HudObject.Identifier, HudComponentSupplier<?>>
Map of HUD object identifiers to their suppliers
Example: 
Map<HudObject.Identifier, HudComponentSupplier<?>> objects = hudPlayer.getHudObjects();
for (HudObject.Identifier id : objects.keySet()) {
    System.out.println("Active HUD: " + id);
}

​
Get Popups

Set<Popup> getPopups()
Gets all currently active popups for this player.
​
return
Set<Popup>
Set of active popups
Example: 
Set<Popup> activePopups = hudPlayer.getPopups();
for (Popup popup : activePopups) {
    System.out.println("Popup: " + popup.getName());
}

​
Get HUDs

Set<Hud> getHuds()
Gets all currently active HUDs for this player.
​
return
Set<Hud>
Set of active HUDs
Example: 
Set<Hud> activeHuds = hudPlayer.getHuds();
boolean hasHealthBar = activeHuds.stream()
    .anyMatch(hud -> hud.getName().equals("health_bar"));

​
Get Compasses

Set<Compass> getCompasses()
Gets all currently active compasses for this player.
​
return
Set<Compass>
Set of active compasses
Example: 
Set<Compass> compasses = hudPlayer.getCompasses();
for (Compass compass : compasses) {
    System.out.println("Compass: " + compass.getName());
}

​
Pointed Locations

​
Get Pointed Location

Set<PointedLocation> getPointedLocation()
Gets all locations pointed by the player (for compass/waypoint systems).
​
return
Set<PointedLocation>
Set of pointed locations
Example: 
Set<PointedLocation> points = hudPlayer.getPointedLocation();
for (PointedLocation point : points) {
    // Process waypoint
}

​
Get Pointers

Set<PointedLocation> pointers()
Gets the mutable set of internal player pointers.
​
return
Set<PointedLocation>
Mutable set of pointers
Example: 
Set<PointedLocation> pointers = hudPlayer.pointers();
pointers.add(new CustomPointedLocation(x, y, z));

​
BossBar

​
Get Bar Color

BossBar.Color getBarColor()
Gets the player’s current bossbar color.
​
return
BossBar.Color
The bossbar color, or null if using default
Example: 
BossBar.Color color = hudPlayer.getBarColor();
if (color == BossBar.Color.RED) {
    // Player has red bossbar
}

​
Set Bar Color

void setBarColor(BossBar.Color color)
Sets the player’s bossbar color.
​
color
BossBar.Color
The color to set, or null to use default
Example: 
import net.kyori.adventure.bossbar.BossBar;

// Set red bossbar
hudPlayer.setBarColor(BossBar.Color.RED);

// Reset to default
hudPlayer.setBarColor(null);

​
Data Management

​
Reload

void reload()
Reloads this player’s HUD data from configuration. Example: 
hudPlayer.reload(); // Refresh player's HUD

​
Save

void save()
Saves this player’s data to the current database. Example: 
// Modify player data
hudPlayer.getVariableMap().put("score", "1000");

// Save to database
hudPlayer.save();

​
Complete Example

import kr.toxicity.hud.api.BetterHudAPI;
import kr.toxicity.hud.api.manager.PlayerManager;
import kr.toxicity.hud.api.player.HudPlayer;
import kr.toxicity.hud.api.popup.Popup;
import kr.toxicity.hud.api.hud.Hud;
import net.kyori.adventure.bossbar.BossBar;
import java.util.UUID;
import java.util.Map;
import java.util.Set;

public class HudPlayerExample {
    
    public void managePlayer(UUID playerUUID) {
        // Get player
        PlayerManager manager = BetterHudAPI.inst().getPlayerManager();
        HudPlayer hudPlayer = manager.getHudPlayer(playerUUID);
        
        if (hudPlayer == null) {
            return; // Player not found
        }
        
        // Player info
        String name = hudPlayer.name();
        long tick = hudPlayer.getTick();
        
        // Control HUD
        if (!hudPlayer.isHudEnabled()) {
            hudPlayer.setHudEnabled(true);
        }
        
        // Set custom variables
        Map<String, String> vars = hudPlayer.getVariableMap();
        vars.put("kills", "10");
        vars.put("deaths", "3");
        vars.put("kdr", "3.33");
        
        // Check active HUDs
        Set<Hud> activeHuds = hudPlayer.getHuds();
        System.out.println("Active HUDs: " + activeHuds.size());
        
        // Check active popups
        Set<Popup> activePopups = hudPlayer.getPopups();
        for (Popup popup : activePopups) {
            System.out.println("Showing popup: " + popup.getName());
        }
        
        // Set bossbar color based on health
        if (isLowHealth(hudPlayer)) {
            hudPlayer.setBarColor(BossBar.Color.RED);
        } else {
            hudPlayer.setBarColor(BossBar.Color.GREEN);
        }
        
        // Force update
        hudPlayer.update();
        
        // Save data
        hudPlayer.save();
    }
    
    public void disableHudTemporarily(UUID playerUUID) {
        PlayerManager manager = BetterHudAPI.inst().getPlayerManager();
        HudPlayer hudPlayer = manager.getHudPlayer(playerUUID);
        
        if (hudPlayer != null) {
            // Disable HUD updates
            hudPlayer.setHudEnabled(false);
            hudPlayer.cancelTick();
            
            // Re-enable after delay
            scheduleTask(() -> {
                hudPlayer.setHudEnabled(true);
                hudPlayer.startTick();
            }, 20 * 5); // 5 seconds
        }
    }
    
    private boolean isLowHealth(HudPlayer player) {
        // Custom logic
        return false;
    }
    
    private void scheduleTask(Runnable task, long delay) {
        // Platform-specific scheduler
    }
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us