Skip to main content
BetterHud provides support for Velocity proxy servers, allowing you to display HUDs across your entire network.

​
Requirements

  • Velocity 3.3 - 3.4
  • Java 21 or higher
  • No additional dependencies required

​
Installation

  1. Download the BetterHud Velocity plugin from Hangar or Modrinth
  2. Place the JAR file in your Velocity server’s plugins folder
  3. Restart your proxy server
  4. The plugin will generate a resource pack automatically

​
Platform Features

The Velocity implementation provides proxy-wide HUD management:

​
Bootstrap API

import kr.toxicity.hud.api.velocity.VelocityBootstrap;
import kr.toxicity.hud.api.BetterHudAPI;

VelocityBootstrap bootstrap = (VelocityBootstrap) BetterHudAPI.inst().getBootstrap();

// Check platform
if (bootstrap.isVelocity()) {
    // Velocity-specific logic
}

​
Platform Detection

The VelocityBootstrap interface provides platform identification: 
boolean isVelocity = bootstrap.isVelocity(); // true
boolean isFolia = bootstrap.isFolia(); // false
boolean isPaper = bootstrap.isPaper(); // false
boolean isFabric = bootstrap.isFabric(); // false

​
Network-Wide Configuration

Configure BetterHud for your entire proxy network: 
# config.yml
debug: false
metrics: true
version-check: true
namespace: "betterhud"

# Resource pack settings
pack-type: zip # folder, zip, none
enable-self-host: false
self-host-ip: "*"
self-host-port: 8163

# Default HUDs for all players
default-hud:
  - network_hud
default-popup: []
default-compass: []

​
Resource Pack Delivery

BetterHud can serve resource packs directly from your Velocity proxy:

​
Self-Hosting

# config.yml
enable-self-host: true
self-host-ip: "*" # Bind to all interfaces
self-host-port: 8163
pack-type: zip
The resource pack will be automatically served at: 
http://your-proxy-ip:8163/resource-pack.zip

​
External Hosting

Alternatively, host the generated pack externally: 
pack-type: zip
enable-self-host: false
Then upload the pack from BetterHud/build/ to your hosting service.

​
Cross-Server HUDs

Manage player HUDs across different backend servers: 
import kr.toxicity.hud.api.BetterHudAPI;
import kr.toxicity.hud.api.player.HudPlayer;

public void updatePlayerHud(Player velocityPlayer) {
    HudPlayer hudPlayer = BetterHudAPI.inst()
        .getPlayerManager()
        .getPlayer(velocityPlayer.getUniqueId());
    
    if (hudPlayer != null) {
        // Update HUD across the network
        hudPlayer.getPopupManager().show("network_popup");
    }
}

​
Building from Source

To build the Velocity plugin: 
./gradlew velocityJar
The compiled JAR will be in dist/build/libs/.

​
API Usage

Add BetterHud to your Velocity plugin: 
repositories {
    mavenCentral()
}

dependencies {
    compileOnly("io.github.toxicity188:BetterHud-standard-api:VERSION")
}

​
Limitations

Some features available in Bukkit may not be available on Velocity:
  • Bedrock player detection (requires Geyser/Floodgate on backend servers)
  • NMS-specific features
  • Bukkit event triggers

​
Performance Considerations

​
Resource Pack Caching

Velocity caches resource packs efficiently: 
# Optimize pack delivery
force-update: false # Set to true only when pack changes

​
Network Bandwidth

Minimize resource pack size: 
# Compress and optimize
pack-type: zip
resourcepack-obfuscation: false
clear-build-folder: true

​
Multi-Server Setup

Example setup with Velocity proxy: 
Velocity Proxy (with BetterHud)
├── Backend Server 1 (Survival)
├── Backend Server 2 (Minigames)
└── Backend Server 3 (Creative)
Configure different HUDs per server using player permissions or metadata.

​
Debugging

Enable debug mode for troubleshooting: 
# config.yml
debug: true
debug-level: assets # assets, configs, all
Check logs in plugins/BetterHud/logs/.

​
Next Steps

Bukkit Platform

Configure backend servers

Placeholders

Create custom placeholders

Configuration

Configure BetterHud

API Reference

Explore the full API

Build docs developers (and LLMs) love

Get started for freeTalk to us