Skip to main content
BetterHud works by automatically generating a Minecraft resource pack that contains all your HUD images, fonts, and shaders. This resource pack must be distributed to players for them to see your custom HUD elements.

How It Works

BetterHud displays HUD elements using a clever technique:
1

Convert images to font glyphs

PNG images from your images/ directory are converted into custom font characters
2

Generate font files

Font JSON files are created mapping Unicode characters to your images
3

Package into resource pack

All assets are compiled into a standard Minecraft resource pack (.zip file)
4

Display via boss bars

Special Unicode characters are rendered on boss bars to show your HUD
BetterHud uses boss bars as the rendering surface because they’re always visible and positioned consistently across clients.

Resource Pack Location

The generated resource pack is saved in:
plugins/BetterHud/pack/
  ├── pack.zip           # Generated resource pack
  └── pack/              # Unpacked contents (for inspection)
The resource pack is regenerated automatically whenever you /hud reload or restart the server.

Resource Pack Contents

Inside the generated pack:
pack.zip
├── pack.mcmeta                    # Resource pack metadata
├── assets/
│   └── minecraft/
│       ├── font/
│       │   └── default.json       # Font provider mapping
│       ├── textures/
│       │   └── betterhud/
│       │       ├── images/        # Your HUD images
│       │       ├── compass/       # Compass icons
│       │       └── ...            # Other textures
│       └── shaders/               # Custom shaders (if any)
└── ...

Font Provider Files

BetterHud generates font JSON files that map characters to images:
{
  "providers": [
    {
      "type": "bitmap",
      "file": "betterhud:images/health_bar.png",
      "ascent": 8,
      "height": 16,
      "chars": ["\uE000"]
    },
    {
      "type": "bitmap",
      "file": "betterhud:images/hunger_bar.png",
      "ascent": 8,
      "height": 16,
      "chars": ["\uE001"]
    }
  ]
}
BetterHud uses Unicode Private Use Area characters (\uE000 - \uF8FF) to avoid conflicts with normal text.

Distribution Methods

Players need to download the resource pack to see your HUD. There are several ways to distribute it:

Automatic Download

Configure Minecraft to automatically send the pack to players:1. Host the pack publiclyUpload pack.zip to:
  • GitHub Releases
  • Dropbox / Google Drive (direct download link)
  • Your own web server
  • MC-Packs.net
2. Configure server.properties
resource-pack=https://example.com/path/to/pack.zip
resource-pack-sha1=<sha1-hash-of-pack>
require-resource-pack=true
3. Get the SHA1 hash
sha1sum pack.zip
Set require-resource-pack=true to force players to use the pack, or kick them if they decline.

Pack Versioning

BetterHud includes metadata in pack.mcmeta:
{
  "pack": {
    "pack_format": 15,
    "description": "BetterHud Resource Pack"
  }
}

Pack Format by Version

Minecraft VersionPack Format
1.20.422
1.20.318
1.20-1.20.215
1.19.413
1.19.312
BetterHud automatically sets the correct pack_format based on your server version.

Custom Assets

Add your own images and fonts to the resource pack:

Adding Custom Images

1. Create image file Place PNG files in:
plugins/BetterHud/images/
  └── my_custom_image.png
2. Reference in configuration
# images/custom-images.yml
my_custom_image:
  type: single
  file: my_custom_image.png
3. Reload BetterHud
/hud reload
The image will be included in the generated pack automatically.

Image Requirements

  • Must be PNG format
  • Supports transparency (alpha channel)
  • 32-bit RGBA recommended
  • Must be power of 2 dimensions (e.g., 16x16, 32x32, 64x64, 128x128)
  • Maximum recommended: 512x512
  • Larger images = larger resource pack size
  • Use smallest size that looks good
  • Compress with tools like PNGGauntlet
  • Remove unnecessary metadata
Keep your resource pack under 50 MB for faster downloads. Optimize images aggressively.

Custom Fonts

BetterHud supports custom font files: 1. Add font file
plugins/BetterHud/fonts/
  └── my_font.ttf
2. Configure font
# texts/custom-fonts.yml
my_font:
  type: ttf
  file: my_font.ttf
  size: 16
3. Use in layouts
my_layout:
  texts:
    1:
      name: my_font
      pattern: "Custom text!"
TTF and OTF font formats are supported. Fonts are converted to bitmap fonts in the resource pack.

Troubleshooting

Symptoms: HUD elements invisible or showing as blank barsSolutions:
  • Ensure players have downloaded the resource pack
  • Check if resource pack prompt was declined
  • Verify require-resource-pack=true in server.properties
  • Confirm pack URL is publicly accessible
  • Check SHA1 hash matches
Symptoms: /hud reload succeeds but no pack.zip createdSolutions:
  • Check console for errors during reload
  • Verify image files are valid PNG format
  • Ensure file permissions allow writing to plugins/BetterHud/pack/
  • Check disk space
Symptoms: Images display incorrectly or with artifactsSolutions:
  • Verify PNG files are valid (open in image editor)
  • Check image dimensions are power of 2
  • Remove non-standard PNG metadata
  • Ensure transparency is properly configured
Symptoms: Players timeout downloading the packSolutions:
  • Compress images (use smaller dimensions)
  • Remove unused images from images/ directory
  • Use external hosting with fast CDN
  • Consider splitting into multiple packs

Updating the Pack

When you modify HUD configurations:
1

Make changes

Edit YAML files or add new images
2

Reload BetterHud

Run /hud reload to regenerate the pack
3

Re-host pack.zip

Upload the new pack.zip to your hosting location
4

Update SHA1 hash

Calculate new hash and update server.properties
5

Players rejoin

Players must reconnect to download the updated pack
Players won’t automatically re-download the pack unless they reconnect or the SHA1 hash changes.

Advanced: Pack Overlays

Combine BetterHud packs with other resource packs: 1. Extract BetterHud pack
unzip pack.zip -d betterhud_pack/
2. Merge with your pack Copy contents into your existing resource pack:
YourPack/
├── pack.mcmeta
├── assets/
│   └── minecraft/
│       ├── font/
│       │   └── default.json  # Merge font providers
│       └── textures/
│           └── betterhud/    # Copy entire directory
3. Merge font providers Combine the providers arrays in font JSON files:
{
  "providers": [
    // ... your existing providers
    // ... BetterHud providers
  ]
}
Use tools like ResourcePack Merger to automate pack merging.

Best Practices

  • Keep total pack size under 50 MB
  • Use smallest viable image dimensions
  • Compress images without quality loss
  • Remove unused images and fonts
  • Use CDN or fast hosting for large packs
  • Enable require-resource-pack to ensure all players have it
  • Provide fallback download links
  • Test pack download speed from different regions
  • Version your packs (e.g., pack-v1.2.3.zip)
  • Keep backup copies of working packs
  • Document pack changes in changelog
  • Test pack thoroughly before distributing

Next Steps

Images

Configure HUD images and animations

Fonts

Set up custom fonts for text displays

Shaders

Add advanced rendering effects

Architecture

Understand how BetterHud’s internals work

Build docs developers (and LLMs) love