Skip to main content

​
Overview

The Compass API enables you to create directional indicators that point toward specific locations in the world. Compasses dynamically update based on player position and orientation.

​
Compass Interface

The Compass interface represents a directional indicator in BetterHud.

​
Package

kr.toxicity.hud.api.compass.Compass

​
Extends

  • HudObject - Base interface for all displayable BetterHud elements

​
Methods

​
indicate

Creates a compass indicator for a player pointing to a location. 
@NotNull HudComponentSupplier<Compass> indicate(@NotNull HudPlayer player)
​
player
HudPlayer
required
The target player for whom to create the compass indicator. The compass will use the player’s pointed location provider.
​
return
HudComponentSupplier<Compass>
A component supplier that provides the rendered compass output based on the player’s location and orientation

​
Inherited from HudObject

​
getName

Gets the internal name/identifier of the compass. 
@NotNull String getName()
​
return
String
The unique identifier for this compass

​
isDefault

Checks if this compass is a default compass. 
boolean isDefault()
​
return
boolean
True if this is a default compass, false otherwise

​
tick

Gets the frame time/update interval for this compass. 
long tick()
​
return
long
The tick interval for compass updates

​
add

Adds this compass to a player’s display. 
default boolean add(@NotNull HudPlayer player)
​
player
HudPlayer
required
The player to add this compass to
​
return
boolean
True if the compass was successfully added, false if it was already present

​
remove

Removes this compass from a player’s display. 
default boolean remove(@NotNull HudPlayer player)
​
player
HudPlayer
required
The player to remove this compass from
​
return
boolean
True if the compass was successfully removed, false if it wasn’t present

​
PointedLocation

Compass indicators use the PointedLocation system to determine where to point. Players maintain a set of pointed locations that compasses reference.

​
Working with Pointed Locations

import kr.toxicity.hud.api.player.PointedLocation;
import java.util.Set;

// Get a player's pointed locations
Set<PointedLocation> locations = hudPlayer.getPointedLocation();

// Get the internal pointers
Set<PointedLocation> pointers = hudPlayer.pointers();

​
Usage Examples

​
Getting a Compass

import kr.toxicity.hud.api.BetterHud;
import kr.toxicity.hud.api.compass.Compass;

// Get compass manager
var compassManager = BetterHud.inst().getCompassManager();

// Get a specific compass by name
Compass myCompass = compassManager.getCompass("waypoint_compass");

​
Adding a Compass to a Player

import kr.toxicity.hud.api.player.HudPlayer;
import kr.toxicity.hud.api.compass.Compass;
import kr.toxicity.hud.api.BetterHud;
import org.bukkit.entity.Player;

public void addCompassToPlayer(Player bukkitPlayer, String compassName) {
    // Get the HUD player wrapper
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Get the compass
    Compass compass = BetterHud.inst().getCompassManager().getCompass(compassName);
    if (compass == null) return;
    
    // Add the compass to the player
    boolean added = compass.add(hudPlayer);
    if (added) {
        bukkitPlayer.sendMessage("Compass added!");
    } else {
        bukkitPlayer.sendMessage("Compass already active!");
    }
}

​
Removing a Compass from a Player

public void removeCompassFromPlayer(Player bukkitPlayer, String compassName) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    Compass compass = BetterHud.inst().getCompassManager().getCompass(compassName);
    if (compass == null) return;
    
    // Remove the compass from the player
    boolean removed = compass.remove(hudPlayer);
    if (removed) {
        bukkitPlayer.sendMessage("Compass removed!");
    }
}

​
Getting All Active Compasses

import java.util.Set;

public void listPlayerCompasses(Player bukkitPlayer) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Get all active compasses
    Set<Compass> activeCompasses = hudPlayer.getCompasses();
    
    bukkitPlayer.sendMessage("Active Compasses: " + activeCompasses.size());
    for (Compass compass : activeCompasses) {
        bukkitPlayer.sendMessage("- " + compass.getName());
    }
}

​
Creating a Waypoint System

import kr.toxicity.hud.api.player.PointedLocation;
import org.bukkit.Location;

public class WaypointSystem {
    
    public void setWaypoint(Player bukkitPlayer, Location targetLocation) {
        HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
        if (hudPlayer == null) return;
        
        // Get the compass
        Compass compass = BetterHud.inst().getCompassManager().getCompass("waypoint");
        if (compass == null) return;
        
        // Note: PointedLocation management depends on your PointedLocationProvider implementation
        // This is typically configured through your compass YAML configuration
        
        // Add compass to player
        if (compass.add(hudPlayer)) {
            bukkitPlayer.sendMessage("Waypoint compass activated!");
            bukkitPlayer.sendMessage("Target: " + targetLocation.getBlockX() + ", " 
                + targetLocation.getBlockY() + ", " + targetLocation.getBlockZ());
        }
    }
    
    public void clearWaypoint(Player bukkitPlayer) {
        HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
        if (hudPlayer == null) return;
        
        Compass compass = BetterHud.inst().getCompassManager().getCompass("waypoint");
        if (compass == null) return;
        
        // Remove compass from player
        if (compass.remove(hudPlayer)) {
            bukkitPlayer.sendMessage("Waypoint compass deactivated!");
        }
    }
}

​
Working with Pointed Locations

import kr.toxicity.hud.api.player.PointedLocation;
import java.util.Set;

public void inspectPointedLocations(Player bukkitPlayer) {
    HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
    if (hudPlayer == null) return;
    
    // Get all pointed locations
    Set<PointedLocation> locations = hudPlayer.getPointedLocation();
    
    bukkitPlayer.sendMessage("Pointed Locations: " + locations.size());
    for (PointedLocation location : locations) {
        // Access location data
        // (specific methods depend on PointedLocation implementation)
        bukkitPlayer.sendMessage("- Location: " + location.toString());
    }
}

​
Dynamic Compass Management

import org.bukkit.scheduler.BukkitRunnable;
import org.bukkit.plugin.Plugin;

public class DynamicCompass {
    
    public void trackEntity(Plugin plugin, Player bukkitPlayer, String compassName, int durationTicks) {
        HudPlayer hudPlayer = BetterHud.inst().getBootstrap().player(bukkitPlayer.getUniqueId());
        if (hudPlayer == null) return;
        
        Compass compass = BetterHud.inst().getCompassManager().getCompass(compassName);
        if (compass == null) return;
        
        // Add compass
        compass.add(hudPlayer);
        
        // Auto-remove after duration
        new BukkitRunnable() {
            @Override
            public void run() {
                compass.remove(hudPlayer);
                bukkitPlayer.sendMessage("Compass tracking ended");
            }
        }.runTaskLater(plugin, durationTicks);
    }
}

​
Checking Compass Properties

public void displayCompassInfo(Player bukkitPlayer, String compassName) {
    Compass compass = BetterHud.inst().getCompassManager().getCompass(compassName);
    if (compass == null) {
        bukkitPlayer.sendMessage("Compass not found!");
        return;
    }
    
    bukkitPlayer.sendMessage("Compass Info:");
    bukkitPlayer.sendMessage("- Name: " + compass.getName());
    bukkitPlayer.sendMessage("- Default: " + compass.isDefault());
    bukkitPlayer.sendMessage("- Tick: " + compass.tick());
    bukkitPlayer.sendMessage("- Type: " + compass.getType());
}

​
Integration with PointedLocationProvider

Compass indicators reference the player’s PointedLocationProvider to determine target locations. Configure this through your compass YAML files: 
# Example compass configuration
compass:
  name: "waypoint"
  # ... other settings
The actual location tracking is managed by BetterHud’s internal systems based on your configuration.
  • HUD API - For persistent display elements
  • Popup API - For temporary notifications
  • Events - Listen to HUD-related events

​
See Also

  • Compass interface: kr.toxicity.hud.api.compass.Compass
  • HudPlayer interface: kr.toxicity.hud.api.player.HudPlayer
  • PointedLocation: kr.toxicity.hud.api.player.PointedLocation
  • PointedLocationProvider: kr.toxicity.hud.api.player.PointedLocationProvider

Build docs developers (and LLMs) love

Get started for freeTalk to us