Skip to main content
The config.yml file is the main configuration file for BetterHud. It controls global plugin behavior, resource pack generation, and default settings.

​
Location

The configuration file is located at:
  • Bukkit/Paper: plugins/BetterHud/config.yml
  • Velocity: plugins/betterhud/config.yml
  • Fabric: config/betterhud/config.yml

​
Configuration Options

​
Debug Settings

​
debug
boolean
default:"false"
Enable debug mode for detailed logging
​
debug-level
string
default:"assets"
Debug verbosity level. Options:
  • assets - Asset loading information
  • verbose - Detailed debugging
  • silent - Minimal logging

​
Performance Settings

​
tick-speed
integer
default:"1"
HUD update speed in ticks (20 ticks = 1 second). Lower values update more frequently.
​
auto-save-time
integer
default:"300"
Auto-save interval in seconds for player data
​
location-provide-time
integer
default:"1"
Location update interval in ticks for compass and distance calculations

​
Plugin Behavior

​
metrics
boolean
default:"true"
Enable bStats metrics collection
​
version-check
boolean
default:"true"
Check for new plugin versions on startup
​
number-format
string
default:"#,###.#"
Number formatting pattern for placeholder values. Uses Java DecimalFormat syntax.

​
Namespaces and Fonts

​
namespace
string
default:"betterhud"
Resource pack namespace for all BetterHud resources
​
default-font-name
string
default:"font.ttf"
Default font file name to use for text rendering

​
Boss Bar Configuration

​
bossbar-line
integer
default:"1"
Number of boss bar lines to use for HUD elements
​
bossbar-resource-pack-line
integer
default:"0"
Number of boss bar lines reserved for resource pack HUDs
​
merge-boss-bar
boolean
default:"true"
Merge multiple boss bars into a single line when possible

​
Resource Pack Generation

​
build-folder-location
string
default:"BetterHud/build"
Directory where the resource pack is generated
​
pack-type
string
default:"zip"
Resource pack distribution format. Options:
  • zip - Generate a ZIP file
  • folder - Keep as a folder
  • none - Don’t generate a pack
​
clear-build-folder
boolean
default:"true"
Clear the build folder before generating. Set to false if you use plugins like Oraxen that also generate resources.
​
resourcepack-obfuscation
boolean
default:"false"
Obfuscate resource pack file names for protection
​
merge-other-folders
array
default:"[]"
List of additional folders to merge into the resource pack
merge-other-folders:
  - "plugins/OtherPlugin/resources"
  - "custom_resources"
​
merge-with-external-resources
boolean
default:"true"
Merge with external resource pack files

​
Self-Hosting

​
enable-self-host
boolean
default:"false"
Enable built-in HTTP server for resource pack distribution
​
self-host-ip
string
default:"*"
IP address for the self-host server. Use * for all interfaces.
​
self-host-port
integer
default:"8163"
Port for the self-host HTTP server
​
enable-protection
boolean
default:"false"
Require players to have the resource pack to join
​
force-update
boolean
default:"false"
Force players to re-download the resource pack on every join

​
Default HUD Elements

​
default-hud
array
default:"[test_hud]"
List of HUDs to show to all players by default
default-hud:
  - test_hud
  - health_bar
  - action_bar
​
default-popup
array
default:"[]"
List of popups to enable by default
​
default-compass
array
default:"[]"
List of compasses to show by default

​
Bedrock Support

​
disable-to-bedrock-player
boolean
default:"true"
Disable HUDs for Bedrock Edition players (Geyser/Floodgate)
​
loading-head
string
default:"random"
Player head to show during loading. Options: steve, alex, random, or a specific username

​
Minecraft Assets

​
load-minecraft-default-textures
boolean
default:"false"
Include default Minecraft textures in the generated pack
​
included-minecraft-list
array
default:"[block, item]"
Categories of Minecraft textures to include when load-minecraft-default-textures is enabled
​
minecraft-jar-version
string
default:"bukkit"
Minecraft version to use for extracting default textures. Options: bukkit, 1.21, 1.20.4, etc.

​
Legacy Compatibility

​
use-legacy-format
boolean
default:"false"
Enable legacy color code format. Only enable if necessary for compatibility.
​
legacy-serializer
string
default:"ampersand"
Legacy color code format. Options:
  • ampersand - Use & for color codes
  • section - Use § for color codes
  • both - Accept both formats
​
remove-default-hotbar
boolean
default:"false"
Remove the default Minecraft hotbar
​
disable-legacy-offset
boolean
default:"true"
Disable legacy offset calculations for compatibility

​
Complete Example

config.yml
debug: false
auto-save-time: 300
location-provide-time: 1
debug-level: assets
metrics: true
version-check: true
number-format: "#,###.#"
tick-speed: 1
namespace: "betterhud"
default-font-name: "font.ttf"
bossbar-line: 1
bossbar-resource-pack-line: 0
merge-boss-bar: true
disable-to-bedrock-player: true
build-folder-location: "BetterHud/build"
pack-type: zip
enable-protection: false
enable-self-host: false
force-update: false
self-host-ip: "*"
self-host-port: 8163
merge-other-folders: []
loading-head: random
default-hud:
  - test_hud
default-popup: []
default-compass: []
load-minecraft-default-textures: false
included-minecraft-list:
  - block
  - item
resourcepack-obfuscation: false
clear-build-folder: true
use-legacy-format: false
legacy-serializer: ampersand
minecraft-jar-version: bukkit
remove-default-hotbar: false
disable-legacy-offset: true
merge-with-external-resources: true

​
Reloading Configuration

After modifying the configuration, reload BetterHud: 
/hud reload

​
See Also

Database Configuration

Configure MySQL or SQLite for player data

Font Configuration

Customize font rendering settings

Shader Configuration

Configure visual effects and shaders

HUD Configuration

Create custom HUD elements

Build docs developers (and LLMs) love

Get started for freeTalk to us