Prerequisites Before installing BetterHud, ensure your server meets these requirements:
Java 21 or higher (Eclipse Adoptium recommended)
One of the supported platforms:
Bukkit/Spigot/Paper 1.20.4 - 1.21.11 (with Folia support)
Velocity 3.3 - 3.4
Fabric Server 1.21.11
Download BetterHud Choose your preferred download source:
SpigotMC Download from SpigotMC
Hangar Download from PaperMC Hangar
Modrinth Download from Modrinth
Bukkit/Paper
Velocity
Fabric Server
Download the plugin
Download BetterHud-bukkit-[version].jar from your preferred source.
Place in plugins folder
Copy the JAR file to your server’s plugins/ directory. # Navigate to your server directory cd /path/to/your/server # Place the plugin in the plugins folder cp BetterHud-bukkit- * .jar plugins/
Restart your server
Restart your server to load the plugin. BetterHud has no required dependencies for Bukkit servers.
Verify installation
Check that BetterHud loaded successfully: You should see BetterHud in green in the plugin list. Optional Dependencies While not required, these plugins enhance BetterHud functionality:
PlaceholderAPI : Use placeholders in your HUD elementsSkript : Create HUD logic using Skript syntax
Download the plugin
Download BetterHud-velocity-[version].jar from your preferred source.
Place in plugins folder
Copy the JAR file to your Velocity proxy’s plugins/ directory. # Navigate to your Velocity proxy directory cd /path/to/your/velocity # Place the plugin in the plugins folder cp BetterHud-velocity- * .jar plugins/
Restart your proxy
Restart your Velocity proxy to load the plugin. BetterHud has no required dependencies for Velocity proxies.
Verify installation
Check that BetterHud loaded successfully: You should see BetterHud in the plugin list. Velocity support allows you to manage HUDs at the proxy level, ensuring consistency across multiple backend servers.
Install Fabric API
Download and install Fabric API - this is required for BetterHud to work on Fabric. # Place Fabric API in your mods folder cp fabric-api- * .jar mods/
Download BetterHud
Download BetterHud-fabric-[version].jar from your preferred source.
Place in mods folder
Copy the JAR file to your server’s mods/ directory. # Navigate to your Fabric server directory cd /path/to/your/fabric-server # Place the mod in the mods folder cp BetterHud-fabric- * .jar mods/
Restart your server
Restart your Fabric server to load the mod.
Verify installation
Check the server console logs to confirm BetterHud loaded successfully.
Fabric API is required! BetterHud will not work on Fabric servers without it.
First-Time Setup After installation, BetterHud will automatically generate its configuration files:
plugins/BetterHud/ ├── config.yml # Main configuration ├── huds/ # HUD definitions ├── layouts/ # Layout configurations ├── images/ # Image definitions ├── texts/ # Text element definitions ├── popups/ # Popup configurations └── compasses/ # Compass marker definitions
On first startup, BetterHud will create default example HUDs to help you get started.
Resource Pack Generation BetterHud automatically generates resource packs for your HUD elements:
Auto-generation
When the server starts, BetterHud scans your configuration files and generates a resource pack.
Distribution
The resource pack is automatically sent to players when they join. You can configure the pack type in config.yml (zip, folder, or none).
Build location
By default, resource packs are built to BetterHud/build/.
Configuration Options Key settings in config.yml:
# Resource pack settings pack-type : zip # zip, folder, or none build-folder-location : "BetterHud/build" clear-build-folder : true # Set to false if using Oraxen # Self-hosting options enable-self-host : false self-host-ip : "*" self-host-port : 8163
If you use Oraxen or other resource pack plugins, set clear-build-folder: false and configure resource pack merging.
Verifying Installation Run these checks to ensure BetterHud is working correctly:
Check plugin status
BetterHud should appear in green.
Test HUD command
This should display available BetterHud commands.
View default HUD
Join the server as a player. You should see the default test HUD with health and hunger bars.
Building from Source
Advanced: Build BetterHud yourself
If you want to build BetterHud from source: # Clone the repository git clone https://github.com/toxicity188/BetterHud.git cd BetterHud # Build all platform JARs ./gradlew build # Or build specific platforms: ./gradlew pluginJar # Bukkit plugin ./gradlew velocityJar # Velocity plugin ./gradlew fabricJar # Fabric mod
Building from source requires Java 21 Eclipse Adoptium .
Built JARs will be located in build/libs/. Troubleshooting
Resource pack not applying
Check that pack-type is set to zip in config.yml
Verify the resource pack generated successfully in the build folder
Ensure players have resource packs enabled in their client settings
Check console for any resource pack generation errors
Verify you downloaded the correct JAR for your platform
Check that you have Java 21 or higher
For Fabric: Ensure Fabric API is installed
Review the server console for error messages
Check if you’re playing on Bedrock Edition (set disable-to-bedrock-player: false if needed)
Verify the default HUD is configured in config.yml
Ensure the resource pack was accepted by the client
Try /betterhud reload to reload configurations
Next Steps
Quick Start Guide Now that BetterHud is installed, learn how to create your first custom HUD!
