Configuration

Main file: plugins/KGInfoServs-BQBetterHud/config.yml

Goal of this page: explain every useful config line and what you can do with it.

BetonQuest Configuration (required)

In plugins/BetonQuest/config.yml:

conversation:
  default_io: kg_bqhud,menu,chest

In each conversation, you can also force:

conversationIO: kg_bqhud

If you still see kg_hud in default_io, replace it with kg_bqhud.

Global Structure

language: "en"
standalone:
  resource-pack:
    output-mode: "folder"
    self-host-port: 8164
    public-url: ""
    output-folder: "plugins/KGInfoServs-BQBetterHud/resourcepack"
    force-pack: false
    pack-prompt: "Resource pack required for dialogue display."
    regenerate-on-startup: false
  x-offset: 0
  layout: ...
  text-alignment: ...
  text-fonts: ...
  y-offset: -200
option-sound:
  key: "minecraft:ui.button.click"
  volume: 1.0
  pitch: 1.0
typewriter:
  enabled: true
  speed: 30
selection-mode: "scroll"
selection-indicator:
  prefix: ""
  selected-color: "<#97deaa>"
  unselected-color: "<gray>"
  hand-base-y: -25
  hand-line-height: 10
  max-option-length: 0
updater:
  auto-download: false

language

Key	Default	Effect
language	"en"	Plugin message language (en or fr)

Resource Pack (standalone.resource-pack)

Key	Default	Effect
output-mode	"folder"	Pack export mode: folder (generate a folder) or self-host (send directly to players)
self-host-port	8164	HTTP port used in self-host
public-url	""	Public pack URL in self-host (recommended in production)
output-folder	"plugins/KGInfoServs-BQBetterHud/resourcepack"	Output folder in folder mode
force-pack	false	Force pack acceptance on the client side
pack-prompt	"Resource pack required for dialogue display."	Message shown before download
regenerate-on-startup	false	Automatically regenerate the pack on every startup

Global Position (standalone)

Key	Default	Effect
x-offset	0	Moves the whole HUD on the horizontal axis (right/left)
y-offset	-200	Moves the whole HUD on the vertical axis

Layout (standalone.layout)

You can move elements with x and y.

Elements that support a scale:

• dialogue-bg.scale
• answer-bg.scale
• avatar.scale

Full reference:

Key	Default	Effect
dialogue-bg.x	0	X position of the dialogue background
dialogue-bg.y	20	Y position of the dialogue background
dialogue-bg.scale	1.0	Size of the dialogue background
answer-bg.x	180	X position of the answers background
answer-bg.y	-30	Y position of the answers background
answer-bg.scale	1.0	Size of the answers background
npc-name.x	10	X position of the NPC name (popup with options)
npc-name.y	19	Y position of the NPC name (popup with options)
npc-name-spoken.x	6	X position of the NPC name (popup without options)
npc-name-spoken.y	23	Y position of the NPC name (popup without options)
name-bg.x	0	X position of the name background
name-bg.y	14	Y position of the name background
dialogue-text.x	10	X position of the dialogue text (with options)
dialogue-text.y	32	Y position of the dialogue text (with options)
dialogue-text.split-width	166	Wrap width (auto line break) of the dialogue text
dialogue-text-spoken.x	10	X position of the dialogue text (without options)
dialogue-text-spoken.y	36	Y position of the dialogue text (without options)
options-scroll.x	226	X position of the options in scroll mode
options-scroll.y	-25	Y position of the options in scroll mode
options-scroll.line-height	14	Vertical spacing between option lines in scroll
options-fixed.x	190	X position of the options in fixed mode
options-fixed.y	-25	Y position of the options in fixed mode
options-fixed.line-height	8	Vertical spacing between option lines in fixed
options-fixed.split-width	160	Max width of the options text in fixed
hand.x	175	X position of the selection hand
hand.y	-26	Base Y position of the hand
hand.spacing	8	Vertical spacing between hands
avatar.x	-20	X position of the NPC avatar
avatar.y	0	Y position of the NPC avatar
avatar.scale	0.75	Size of the NPC avatar
text-height	8	Text rendering height. Value in pixels. Increase for larger text, decrease for more compact text.

Note: the hand.* settings are only used in selection-mode: fixed mode.

Text Alignment (standalone.text-alignment)

Possible values: left, center, right

Key	Default	Effect
dialogue	"center"	Dialogue text alignment
speaker	"left"	NPC name alignment
options	"left"	Options text alignment

Text Fonts (standalone.text-fonts)

Key	Default	Effect
dialogue	""	Reserved for per-zone font selection
speaker	""	Reserved for per-zone font selection
options	""	Reserved for per-zone font selection

Important note: in the current build, rendering mostly uses the default font from fonts.yml.

Option Sound (option-sound)

Key	Default	Effect
key	"minecraft:ui.button.click"	Sound played when the option changes
volume	1.0	Sound volume
pitch	1.0	Sound pitch

Typewriter (typewriter)

Key	Default	Effect
enabled	true	Enables/disables the typewriter effect
speed	30	Text display speed (characters per second)

Performance notes:

The plugin uses a multi-level optimization system for the typewriter effect:

• Instant transitions between dialogue steps (no lag)
• Optimized rendering with 5 performance levels
• Fast path for short dialogues

These optimizations are automatic and require no configuration.

Selection Mode (selection-mode)

Key	Default	Effect
selection-mode	"scroll"	Selection mode: scroll or fixed

Differences between the modes

scroll mode (default):

• Classic scrolling list
• The selected option always stays visible
• Automatic scrolling if there are more options than available space
• Position configured via standalone.layout.options-scroll

fixed mode:

• Fixed list with a hand indicator
• All options displayed simultaneously
• Sliding window for unlimited scrolling
• Automatic line break based on split-width
• Position configured via standalone.layout.options-fixed

Recommendation:

• scroll: ideal for 2-5 short options
• fixed: ideal for 3-10 options with long text

Selection Indicator (selection-indicator)

Key	Default	Effect
prefix	""	Text added before the selected option (e.g. "▶ " or "> ")
selected-color	"<#97deaa>"	Color of the selected option
unselected-color	"<gray>"	Color of the other options
hand-base-y	-25	Base Y used to compute the selection hand
hand-line-height	10	Y gap between 2 lines for the hand
max-option-length	0	Max option length (0 = unlimited)

Updater (updater)

Key	Default	Effect
auto-download	false	Auto-download updates when available

How to Apply Changes

1. Edit config.yml.
2. Run /bqhud reload.
3. Check in game.

For visual changes (layout, x-offset, y-offset, avatars/backgrounds), always test under real conditions.

Advanced Fonts (fonts.yml)

File: plugins/KGInfoServs-BQBetterHud/fonts.yml

The plugin uses Java AWT to render fonts, which allows maximum flexibility.

Rendering System

The plugin supports two text rendering modes:

1. Java AWT (default): rendering with system fonts or custom TTF fonts
2. Minecraft fonts: uses Minecraft's bitmap fonts (ascii.png, etc.)

Default Configuration

default:
  # Font size in pixels (16 = normal Minecraft size)
  scale: 16

  # Path to the TTF file (relative to plugins/KGInfoServs-BQBetterHud/fonts/)
  # Examples: "font.ttf", "minecraft.ttf", "custom/myfont.ttf"
  # Leave empty to use the default Java system font
  file: ""

  # Use Minecraft fonts instead of Java AWT rendering
  # true = uses minecraft:font/ascii.png (bitmap fonts)
  # false = rendering with Java AWT (TTF or system)
  use-unifont: false

  # Merge with Minecraft's bitmap fonts (special characters)
  # Includes: ascii.png, accented.png, nonlatin_european.png
  # Only used when use-unifont is true
  merge-default-bitmap: true

  # Language filters (not used with Java AWT)
  include: []

Font Loading Priority

The plugin loads fonts in this order:

1. If file is set and exists -> Loads the TTF file
2. If file is empty or missing -> Uses the Java system font
3. If use-unifont is true -> Uses only Minecraft fonts

Custom Fonts

You can define several named fonts:

fonts:
  # Custom TTF font
  custom_ttf:
    file: "font.ttf"        # Place in plugins/KGInfoServs-BQBetterHud/fonts/
    scale: 16
    use-unifont: false
    merge-default-bitmap: false
    include: []

  # Small font for subtitles
  small_text:
    file: ""
    scale: 12
    use-unifont: false
    merge-default-bitmap: false
    include: []

  # Large font for titles
  large_title:
    file: ""
    scale: 24
    use-unifont: false
    merge-default-bitmap: false
    include: []

Referencing a Font in config.yml

Important note: In the current version, rendering mainly uses the default font defined in fonts.yml.

The standalone.text-fonts keys in config.yml are reserved for future features:

# Reserved for per-zone font selection (future feature)
standalone:
  text-fonts:
    dialogue: ""   # Future: reference to fonts.custom_ttf
    speaker: ""
    options: ""

Usage Examples

Using a System Font

default:
  scale: 16
  file: ""              # Empty = system font
  use-unifont: false

Using a Custom TTF Font

1. Place your myfont.ttf file in plugins/KGInfoServs-BQBetterHud/fonts/
2. Configure fonts.yml:

default:
  scale: 16
  file: "myfont.ttf"
  use-unifont: false

3. Reload: /bqhud reload

Using Minecraft Fonts

default:
  scale: 16
  file: ""
  use-unifont: true
  merge-default-bitmap: true

Recommended Sizes

Scale	Size	Recommended Use
8	Very small	Secondary text, annotations
12	Small	Subtitles
16	Normal	Standard dialogue text (Minecraft default)
20	Large	Titles
24	Very large	Important titles

Compatible Fonts

The Java AWT system supports:

• TTF (TrueType Font) ✅
• OTF (OpenType Font) ✅
• Installed system fonts ✅

Font Troubleshooting

The Custom Font Does Not Display

Possible causes:

1. TTF file placed incorrectly (check the fonts/ folder)
2. Incorrect file name in fonts.yml
3. Corrupted TTF file

Solution:

# Check the logs after reload
/bqhud reload
# Look for "[FontManager]" messages in the console

The Text Is Too Small/Large

Adjust the scale in fonts.yml:

default:
  scale: 20  # Increase to make it bigger

Then reload: /bqhud reload

Missing Special Characters

If you use a TTF font that does not have all the characters, enable the merge:

default:
  file: "myfont.ttf"
  use-unifont: false
  merge-default-bitmap: true  # Adds Minecraft characters

Performance

Java AWT rendering is optimized:

• Glyphs are generated when the resource pack is created (not in real time)
• Textures are cached in the pack
• No server overhead during dialogues

See Also

• Visual Customization
• Troubleshooting