Skip to main content

​
Installation & Setup

BetterHud supports multiple server platforms:
  • Bukkit (including Folia) - Versions 1.20.4 to 1.21.11
  • Velocity - Versions 3.3 to 3.4
  • Fabric Server - Version 1.21.11 (requires Fabric API)
BetterHud is a server-side implementation, meaning players don’t need to install anything on their client.
No! BetterHud is completely server-side. It automatically generates and distributes resource packs to players when they join the server. Players just need to accept the resource pack prompt.
BetterHud requires Java 21 Eclipse Adoptium for building from source. For running the plugin/mod on your server, check your server platform’s Java requirements.
  1. Download the appropriate version for your platform from:
  2. Place the jar file in your server’s plugins (Bukkit/Velocity) or mods (Fabric) folder
  3. Restart your server
  4. Configure BetterHud by editing the config files in the plugins/BetterHud directory

​
Configuration

After first startup, BetterHud creates a configuration folder:
  • Bukkit/Folia: plugins/BetterHud/
  • Velocity: plugins/BetterHud/
  • Fabric: config/BetterHud/
Inside you’ll find:
  • config.yml - Main configuration file
  • huds/ - HUD layout definitions
  • images/ - Image element definitions
  • texts/ - Text element definitions
  • popups/ - Popup definitions
Use the command:
/betterhud reload
This will reload all configuration files and regenerate the resource pack if needed.
Yes! BetterHud supports custom fonts and images. Place your custom resources in the appropriate directories within the BetterHud folder, and reference them in your HUD definitions. The plugin will automatically include them in the generated resource pack.
  1. Create a new YAML file in the huds/ directory
  2. Define your HUD layout using images, text, and head elements
  3. Use placeholders to make your HUD dynamic
  4. Reload BetterHud with /betterhud reload
See the HUD Elements guide for detailed examples.

​
Features & Functionality

BetterHud supports displaying:
  • Images - PNG files, including animated sequences
  • Text - Custom formatted text with various fonts
  • Player Heads - 3D player heads with different render types
  • Animations - Smooth transitions and animations
  • Popups - Temporary UI elements triggered by events
  • Compass Markers - Custom waypoint markers
Yes! BetterHud has full PlaceholderAPI support on Bukkit platforms. Use any PAPI placeholder in your text patterns:
pattern: |
  %player_name%
  Health: %player_health%
Absolutely! BetterHud provides native Skript support. You can:
  • Show and hide popups
  • Add and remove compass markers
  • Control HUD visibility per player
Example:
command /popup:
  trigger:
    show popup "test_popup" to player
See the README for more Skript examples.
BetterHud integrates with:
  • PlaceholderAPI - Placeholder support
  • Skript - Custom scripting
  • MMOCore - MMO placeholders
  • MythicMobs - Entity placeholders
  • Nexo - Custom item support (Oraxen 2.0 support dropped as of v1.10)
  • WorldEdit - Region support
  • ViaVersion/ViaBackwards - Multi-version support

​
Performance & Compatibility

Yes! BetterHud fully supports Folia, Paper’s multi-threaded fork.
BetterHud does NOT support:
  • Bedrock Edition players
  • Modified/Unofficial clients (Feather Client, etc.)
  • Optifine in some cases (closed-source compatibility issues)
  • Clients running Minecraft versions below 1.20.4
As of version 1.14.1, client support for versions ≤1.20.2 has been dropped.
No. Hybrid Bukkit implementations like ArcLight are not officially supported and may cause unexpected issues.
BetterHud is optimized for performance and is server-side only. The rendering happens on the client using Minecraft’s native resource pack system. However:
  • Very complex HUDs with many elements may impact client FPS
  • The initial resource pack download adds a small delay when joining
  • Server performance impact is minimal

​
Development & API

Yes! BetterHud provides a comprehensive API available on Maven Central:
dependencies {
  compileOnly("io.github.toxicity188:BetterHud-standard-api:VERSION")
  compileOnly("io.github.toxicity188:BetterHud-bukkit-api:VERSION")
}
See the API Documentation for details.
Example projects are available:
Yes! BetterHud is open source and available on GitHub. Contributions are welcome!

​
Getting Help

When reporting a bug, please include:
  1. Detailed description of the problem
  2. Error logs from console
  3. Screenshots or videos if applicable
  4. Your configuration files
  5. Server environment details:
    • OS (Windows/Mac/Linux)
    • Server version (e.g., 1.21.1)
    • Server platform (Spigot/Paper/Folia/Fabric/etc.)
Submit bug reports on GitHub Issues.
Yes! Feature requests are welcome on GitHub Issues. However, note that requests involving:
  • Closed-source plugin/mod support (Optifine, ItemsAdder)
  • Modified clients (Feather)
  • Bedrock platform
  • Very old versions (≤1.16.5)
  • Features impossible to implement server-side (e.g., 144 FPS HUD)
…may not be accepted.

Build docs developers (and LLMs) love

Get started for freeTalk to us