Skip to main content
The Compass system provides directional indicators and waypoint navigation directly in the player’s HUD. Players can track locations, see cardinal directions, and navigate to custom markers without opening maps.

​
What is a Compass?

A Compass is a HudObject that:
  • Shows cardinal directions (N, S, E, W) relative to player view
  • Displays custom waypoints (“pointed locations”) in the world
  • Updates in real-time as the player looks around
  • Supports distance fading and scaling effects
  • Can show multiple markers simultaneously
Compasses are persistent like Huds, but their content updates based on the player’s view direction and position.

​
Basic Structure

Compasses are defined in YAML files in the compasses/ directory: 
my_compass:
  type: circle        # Compass type
  default: true       # Show to all players
  file:              # Direction icons
    n:
      name: "compass/n.png"
    s:
      name: "compass/s.png"
    # ...
  gui:
    x: 50            # Screen position
    y: 0
  pixel:
    x: 0
    y: 20

​
Real Example: Default Circle Compass

Here’s the actual default compass from BetterHud’s source: 
default_compass:
  type: circle
  default: true
  file:
    n: 
      name: "compass/n.png"   # North indicator
    s: 
      name: "compass/s.png"   # South
    w: 
      name: "compass/w.png"   # West
    e: 
      name: "compass/e.png"   # East
    nw: 
      name: "compass/nw.png"  # Northwest
      y: 2
    ne: 
      name: "compass/ne.png"  # Northeast
      y: 2
    sw: 
      name: "compass/sw.png"  # Southwest
      y: 2
    se: 
      name: "compass/se.png"  # Southeast
      y: 2
    chain: 
      name: "compass/chain.png"  # Connector between markers
    point: 
      name: "compass/point.png"  # Custom waypoint marker
      y: -8
  scale: 0.75
  scale-equation: 1 - t/20   # Fade in effect
  length: 20                  # Visible length of compass arc
  space: 2                    # Spacing between elements
  gui:
    x: 50                     # Center horizontally
    y: 0                      # Top of screen
  pixel:
    x: 0
    y: 20                     # 20 pixels down from top
  apply-opacity: true         # Enable transparency effects
This creates a compass that:
1

Shows at top-center

Positioned at 50% horizontal (center) and near the top of screen
2

Displays 8 directions

All cardinal (N,S,E,W) and intercardinal (NE,NW,SE,SW) directions
3

Shows waypoints

Custom point markers for tracked locations
4

Fades in smoothly

Uses scale-equation: 1 - t/20 to fade in over time

​
Compass Types

BetterHud supports different compass visualization styles: 
type: circle
A circular compass that shows directions around the player’s view.
Most common type. Shows all directions in a circular arc.

​
Direction Indicators

Define icons for each cardinal and intercardinal direction: 
file:
  # Cardinal directions (required)
  n:
    name: "compass/north.png"
    y: 0
  s:
    name: "compass/south.png"
  e:
    name: "compass/east.png"
  w:
    name: "compass/west.png"
  
  # Intercardinal directions (optional)
  ne:
    name: "compass/northeast.png"
    y: 2  # Pixel offset
  nw:
    name: "compass/northwest.png"
  se:
    name: "compass/southeast.png"
  sw:
    name: "compass/southwest.png"
  
  # Waypoint marker (required for points)
  point:
    name: "compass/marker.png"
    y: -8
  
  # Connector line (optional)
  chain:
    name: "compass/line.png"
The y offset allows you to adjust individual icon positions for perfect alignment.

​
Waypoints (Pointed Locations)

Add custom markers that players can navigate to:

​
Adding Waypoints via API

import kr.toxicity.hud.api.player.PointedLocation;
import kr.toxicity.hud.api.adapter.LocationWrapper;

// Create a waypoint
LocationWrapper location = // ... your location
PointedLocation waypoint = new PointedLocation(
    "home",              // Unique identifier
    location,            // World location
    "Home Base",         // Display name
    "home_icon"         // Icon name (optional)
);

// Add to player
hudPlayer.getPointedLocation().add(waypoint);

// Remove waypoint
hudPlayer.getPointedLocation().removeIf(
    p -> p.getName().equals("home")
);

​
With Skript

BetterHud provides Skript syntax for managing waypoints: 
command /sethome:
    trigger:
        # Add waypoint at player location
        point add location at player named "home" to player
        send "Home location set!"

command /home:
    trigger:
        # Remove waypoint
        point remove "home" to player

​
With Custom Icons

command /markquest:
    trigger:
        # Add waypoint with custom icon
        point add location at 100, 64, 200 in world "world" named "quest" with icon "quest_marker" to player
The icon name must match an icon defined in the compass configuration’s file section.

​
Compass Configuration

​
Length and Spacing

Control the visible arc of the compass: 
length: 20    # How many units of compass to show
space: 2      # Spacing between elements (pixels)

Length

Higher values show more of the compass arc. Lower values show a narrower view.

Space

Controls spacing between direction indicators and waypoint markers.

​
Scale and Scaling

Adjust compass size and dynamic scaling: 
scale: 0.75              # Overall scale (0.75 = 75% size)
scale-equation: 1 - t/20 # Dynamic scaling over time
The scale-equation uses time variable t:
  • t = 0 when waypoint first appears
  • t increases over time
  • Use for fade-in/fade-out effects

​
Distance-based Effects

max-distance: 500        # Hide markers beyond 500 blocks
apply-opacity: true      # Fade markers based on distance
With apply-opacity: true, markers become more transparent as they get farther away.
Combine scale-equation with apply-opacity for smooth fade-in effects when waypoints appear.

​
Positioning

Position the compass on screen: 
gui:
  x: 50      # 0-100 (percentage from left)
  y: 0       # 0-100 (percentage from top)
pixel:
  x: 0       # Pixel offset horizontal
  y: 20      # Pixel offset vertical

​
Common Positions

gui:
  x: 50
  y: 0
pixel:
  x: 0
  y: 20

​
Working with Compasses via API

Manage compasses programmatically: 
import kr.toxicity.hud.api.BetterHud;
import kr.toxicity.hud.api.compass.Compass;

// Get compass by name
Compass compass = BetterHud.getInstance()
    .getCompassManager()
    .getCompass("default_compass");

// Add to player
if (compass != null) {
    compass.add(hudPlayer);
}

// Remove from player
compass.remove(hudPlayer);

// Check active compasses
Set<Compass> activeCompasses = hudPlayer.getCompasses();

​
Location Providers

Create dynamic waypoints that update automatically: 
import kr.toxicity.hud.api.player.PointedLocationProvider;

public class QuestLocationProvider implements PointedLocationProvider {
    @Override
    public @NotNull Set<PointedLocation> provide(@NotNull HudPlayer player) {
        Set<PointedLocation> locations = new HashSet<>();
        
        // Add active quest locations for this player
        for (Quest quest : getPlayerQuests(player)) {
            locations.add(new PointedLocation(
                "quest_" + quest.getId(),
                quest.getLocation(),
                quest.getName(),
                "quest_marker"
            ));
        }
        
        return locations;
    }
}

// Register provider
BetterHud.getInstance()
    .getPlayerManager()
    .registerLocationProvider(new QuestLocationProvider());
Location providers are called each tick, allowing waypoints to move and update dynamically.

​
Custom Waypoint Icons

Define multiple waypoint icon types: 
my_compass:
  type: circle
  file:
    # ... direction icons
    point:              # Default waypoint
      name: "compass/point.png"
    quest_marker:       # Quest waypoint
      name: "compass/quest.png"
      y: -10
    npc_marker:         # NPC waypoint
      name: "compass/npc.png"
      y: -8
    danger_marker:      # Danger zone
      name: "compass/danger.png"
      y: -12
Then specify the icon when creating waypoints: 
new PointedLocation("quest_1", location, "Find the temple", "quest_marker")
new PointedLocation("npc_1", location, "Talk to merchant", "npc_marker")

​
Multiple Compasses

Players can have multiple compasses active simultaneously: 
# compasses/main_compass.yml
main_compass:
  default: true
  type: circle
  gui:
    x: 50
    y: 0
  # ...

# compasses/mini_compass.yml
mini_compass:
  default: false
  type: bar
  scale: 0.5
  gui:
    x: 90
    y: 90
  # ...
Activate different compasses for different purposes: 
// Show main compass by default
mainCompass.add(hudPlayer);

// Show mini compass in dungeons
if (inDungeon) {
    miniCompass.add(hudPlayer);
}
Each compass can have different waypoint filters and display styles.

​
Complete Example

A feature-rich quest compass: 
quest_compass:
  type: circle
  default: false
  
  # Icons
  file:
    n:
      name: "compass/n.png"
    s:
      name: "compass/s.png"
    e:
      name: "compass/e.png"
    w:
      name: "compass/w.png"
    ne:
      name: "compass/ne.png"
      y: 2
    nw:
      name: "compass/nw.png"
      y: 2
    se:
      name: "compass/se.png"
      y: 2
    sw:
      name: "compass/sw.png"
      y: 2
    chain:
      name: "compass/chain.png"
    point:
      name: "compass/quest_marker.png"
      y: -10
  
  # Display settings
  scale: 0.8
  scale-equation: 1 - t/15
  length: 25
  space: 3
  max-distance: 1000
  apply-opacity: true
  
  # Position
  gui:
    x: 50
    y: 5
  pixel:
    x: 0
    y: 0

​
Best Practices

  • Set reasonable max-distance to avoid rendering distant markers
  • Limit the number of active waypoints per player
  • Use apply-opacity for smooth distance-based fading
  • Don’t clutter the compass with too many waypoints
  • Use distinct icons for different waypoint types
  • Consider allowing players to toggle the compass on/off
  • Test compass visibility against different biomes/skyboxes
  • Ensure icons are readable at the configured scale
  • Use contrasting colors for waypoint markers

​
Next Steps

API: Compass

Work with compasses programmatically

Images

Create custom compass icons

Huds

Learn about persistent HUD elements

Resource Packs

How compass assets are packaged

Build docs developers (and LLMs) love

Get started for freeTalk to us