Skip to main content
BetterHud is a multiplatform server-side HUD plugin built with a modular architecture that supports Bukkit, Velocity, and Fabric servers.

​
Module Structure

BetterHud is organized into several key modules:

API Layer

Platform-agnostic interfaces for core functionality

Platform Implementations

Bukkit, Velocity, and Fabric-specific adapters

Distribution Module

Default configurations and resource pack assets

NMS Handlers

Version-specific Minecraft protocol implementations

​
API Modules

The API layer is divided into platform-specific and standard APIs: 
api/
├── standard-api/      # Platform-agnostic core interfaces
├── bukkit-api/        # Bukkit-specific extensions
├── velocity-api/      # Velocity-specific extensions
└── fabric-api/        # Fabric-specific extensions
The standard API (kr.toxicity.hud.api) contains all core interfaces like Hud, Popup, Compass, and manager classes.

​
Platform Bootstraps

Each platform has its own bootstrap module that initializes BetterHud:
  • bootstrap:bukkit - Bukkit/Spigot/Paper plugin initialization
  • bootstrap:velocity - Velocity proxy plugin initialization
  • bootstrap:fabric - Fabric server-side mod initialization

​
Core Architecture

1

Plugin Initialization

The bootstrap loads the appropriate platform adapter and initializes the BetterHud core
2

Manager Registration

All managers (HudManager, PopupManager, CompassManager, etc.) are registered and initialized
3

Configuration Loading

YAML configurations are parsed from the huds/, popups/, compasses/, etc. directories
4

Resource Pack Generation

Images, fonts, and assets are compiled into a Minecraft resource pack
5

Player Tracking

Each player gets a HudPlayer instance that manages their HUD state

​
Manager System

BetterHud uses a manager-based architecture to organize functionality:

​
Key Managers

ManagerPurposeAPI Reference
HudManagerManages persistent HUD displaysBetterHud.getInstance().getHudManager()
PopupManagerManages temporary popup notificationsBetterHud.getInstance().getPopupManager()
CompassManagerManages compass and waypoint displaysBetterHud.getInstance().getCompassManager()
PlaceholderManagerResolves placeholders in HUD elementsBetterHud.getInstance().getPlaceholderManager()
PlayerManagerManages per-player HUD stateBetterHud.getInstance().getPlayerManager()
TriggerManagerHandles event-based HUD updatesBetterHud.getInstance().getTriggerManager()
All managers are accessible through the main BetterHud interface: BetterHud.getInstance().getXxxManager()

​
HudObject System

All displayable elements inherit from the HudObject interface: 
public interface HudObject {
    @NotNull String getName();           // Unique identifier
    boolean isDefault();                  // Is it a default object?
    @NotNull HudObjectType<?> getType(); // Type information
    long tick();                          // Frame timing
    
    boolean add(@NotNull HudPlayer player);    // Add to player
    boolean remove(@NotNull HudPlayer player); // Remove from player
}
The three main implementations are:
  1. Hud - Persistent HUD elements (see Huds)
  2. Popup - Temporary notifications (see Popups)
  3. Compass - Directional indicators (see Compass)

​
HudPlayer System

Each online player has a HudPlayer instance that tracks:
  • Active HUD Objects - Currently displayed HUDs, popups, and compasses
  • Popup State - Popup queue and animation state
  • Variables - Per-player placeholder variables
  • Tick Counter - Animation and update timing
  • Pointed Locations - Compass markers and waypoints
public interface HudPlayer {
    Map<HudObject.Identifier, HudComponentSupplier<?>> getHudObjects();
    Map<String, PopupIteratorGroup> getPopupGroupIteratorMap();
    Map<String, String> getVariableMap();
    Set<PointedLocation> getPointedLocation();
    long getTick();
}
The HudPlayer API allows you to add/remove HUD elements programmatically:
Hud myHud = BetterHud.getInstance().getHudManager().getHud("my_hud");
myHud.add(hudPlayer);

​
Resource Pack Generation

BetterHud automatically generates a resource pack containing:
Custom fonts with HUD element glyphs mapped to Unicode private use characters
PNG images converted to font glyphs for display
Custom shaders for advanced rendering effects
JSON font provider files mapping characters to images
The resource pack is generated on plugin reload and must be distributed to players. See Resource Packs for details.

​
Update System

BetterHud uses a tick-based update system:
  1. Global Tick - Plugin tracks overall tick count
  2. Player Tick - Each HudPlayer has its own tick counter
  3. Object Tick - Each HudObject defines its update frequency
  4. Trigger Events - External events trigger immediate updates
# HUD objects define their tick rate
my_hud:
  layouts:
    # ... layout configuration
  update:
    tick: 20  # Update every 20 ticks (1 second)

​
Event-Driven Architecture

BetterHud uses triggers to respond to game events:
Triggers are configured in HUD/Popup YAML files. See Triggers for available trigger types.

​
Platform Abstraction

BetterHud abstracts platform differences through adapter interfaces:
  • LocationWrapper - Platform-agnostic location
  • WorldWrapper - Platform-agnostic world reference
  • BetterCommandSource - Unified command sender interface
This allows the same configuration and API to work across Bukkit, Velocity, and Fabric.

​
Next Steps

Huds

Learn about persistent HUD elements

Popups

Understand temporary notification displays

Compass

Explore directional indicators and waypoints

Resource Packs

How BetterHud generates and distributes resource packs

Build docs developers (and LLMs) love

Get started for freeTalk to us