Visual Customization

This guide explains how to customize the visual appearance of the dialogue HUD.

🎨 Overview

The standalone rendering system lets you customize:

• Backgrounds: interface backgrounds (dialogue, answers, NPC name)
• Avatars: NPC images
• Layout: X/Y positions of each element
• Scale: size of visual elements

📁 Folder Structure

plugins/KGInfoServs-BQBetterHud/
├── avatars/          # NPC avatars (PNG)
├── backgrounds/      # Interface backgrounds (PNG)
├── fonts/           # Custom fonts (TTF)
└── resourcepack/    # Generated pack (folder mode)

🖼️ Backgrounds (interface backgrounds)

Available Files

Backgrounds are global (not tied to a specific NPC):

File	Use	Recommended dimensions
dialogue.png	Dialogue box background	Variable
answer.png	Answer area background	Variable
hand.png	Selection indicator (hand)	8x8 pixels
name_start.png	Start of the NPC name background	Variable
name_mid.png	Middle of the NPC name background	Variable
name_end.png	End of the NPC name background	Variable

Customization process

1. Create your PNGs with the desired dimensions
2. Place the files in plugins/KGInfoServs-BQBetterHud/backgrounds/
3. Reload with /bqhud reload
4. Test in-game

Tip

The files name_start.png, name_mid.png, and name_end.png form a "9-slice" system to adapt the background width to the NPC's name.

Example: Dark theme

To create a custom dark theme:

# Structure of your files
backgrounds/
├── dialogue.png      # Semi-transparent black background
├── answer.png        # Dark gray background
├── hand.png          # White hand for contrast
├── name_start.png    # Black left border
├── name_mid.png      # Repeatable black background
└── name_end.png      # Black right border

After adding them:

/bqhud reload

Folder mode vs self-host

• folder mode: after /bqhud reload, you must rebuild and republish your server resource pack
• self-host mode: after /bqhud reload, the pack is automatically regenerated and sent back to players

🎭 NPC Avatars

See the Avatars and Backgrounds page for the avatar system.

📐 Layout: Positioning elements

Coordinate system

The HUD uses a coordinate system in pixels:

• Origin (0, 0): reference point of the BossBar
• Positive X: to the right
• Negative X: to the left
• Positive Y: upward
• Negative Y: downward

Global offsets

Before positioning individual elements, you can move the entire HUD:

standalone:
  x-offset: 0      # Moves everything horizontally
  y-offset: -200   # Moves everything vertically

Examples:

• x-offset: 50 → HUD shifted 50 pixels to the right
• y-offset: -250 → HUD lower on the screen
• y-offset: -150 → HUD higher on the screen

Configurable elements

Interface backgrounds

standalone:
  layout:
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.0    # Size (1.0 = 100%, 1.5 = 150%)

    answer-bg:
      x: 180
      y: -30
      scale: 1.0

    name-bg:
      x: 0
      y: 14

Text and NPC name

standalone:
  layout:
    # NPC name (with options)
    npc-name:
      x: 10
      y: 19

    # NPC name (no options, "spoken")
    npc-name-spoken:
      x: 6
      y: 23

    # Dialogue text (with options)
    dialogue-text:
      x: 10
      y: 32
      split-width: 166  # Width before line wrap

    # Dialogue text (no options, "spoken")
    dialogue-text-spoken:
      x: 10
      y: 36

    # Text height
    text-height: 8

Answer options

Two modes available: scroll and fixed

Scroll mode (scrolling list):

standalone:
  layout:
    options-scroll:
      x: 226
      y: -25
      line-height: 14  # Spacing between lines

Fixed mode (fixed list with indicator):

standalone:
  layout:
    options-fixed:
      x: 190
      y: -25
      line-height: 8
      split-width: 160  # Max width before line wrap

    hand:  # Selection indicator
      x: 175
      y: -26
      spacing: 8  # Vertical spacing between hands

NPC Avatar

standalone:
  layout:
    avatar:
      x: -20
      y: 0
      scale: 0.75  # Avatar size (0.5 = 50%, 1.0 = 100%)

Custom layout examples

Centered layout

standalone:
  x-offset: 0
  y-offset: -180
  layout:
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.2
    dialogue-text:
      x: 15
      y: 35
      split-width: 180
    avatar:
      x: -25
      y: 5
      scale: 1.0

Layout shifted to the right

standalone:
  x-offset: 100
  y-offset: -200
  layout:
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.0
    answer-bg:
      x: 200
      y: -30
      scale: 1.0

Compact layout (small screen)

standalone:
  x-offset: 0
  y-offset: -220
  layout:
    dialogue-bg:
      x: 0
      y: 15
      scale: 0.8
    dialogue-text:
      x: 8
      y: 25
      split-width: 140
    avatar:
      x: -15
      y: 0
      scale: 0.6

🎨 Text alignment

You can choose the alignment for each section:

standalone:
  text-alignment:
    dialogue: center  # left, center, right
    speaker: left     # NPC name
    options: left     # Answer options

Usage examples:

• dialogue: center → Centered text for a cinematic style
• dialogue: left → Left-aligned text for a classic style
• options: right → Right-aligned options

🔧 Customization workflow

Step 1: Prepare your assets

1. Create your PNGs in an image editor (GIMP, Photoshop, Paint.NET)
2. Use transparency (alpha channel) for empty areas
3. Follow the recommended dimensions

Step 2: Test locally

1. Place your files in the appropriate folders
2. Run /bqhud reload
3. Test with a BetonQuest dialogue in-game
4. Adjust the positions in config.yml

Step 3: Iteration

Repeat until you get the desired result:

# 1. Edit config.yml
# 2. Reload
/bqhud reload
# 3. Test in-game
# 4. Adjust and repeat

Step 4: Deployment

Folder mode:

1. The plugins/KGInfoServs-BQBetterHud/resourcepack folder contains the generated assets
2. Integrate this content into your server resource pack
3. Rebuild and redistribute your pack

Self-host mode:

1. The pack is automatically regenerated
2. Players receive the update on reconnection

📊 Scale summary table

Element	Config key	Default scale	Effect of scale
Dialogue background	dialogue-bg.scale	1.0	Enlarges/shrinks the background
Answer background	answer-bg.scale	1.0	Enlarges/shrinks the background
NPC avatar	avatar.scale	0.75	Enlarges/shrinks the avatar

Recommended values:

• 0.5: Very small (50%)
• 0.75: Small (75%)
• 1.0: Normal (100%)
• 1.25: Large (125%)
• 1.5: Very large (150%)

🚀 Performance tips

PNG optimization

For better performance:

1. Compress your PNGs with tools like TinyPNG or pngquant
2. Use reasonable dimensions (max 512x512 for backgrounds)
3. Avoid oversized images that bloat the resource pack

Resource pack size

The plugin generates an optimized pack:

• Automatic ZIP compression
• No unnecessary files
• SHA-1 cache to avoid redownloads

❓ Frequently asked questions

The layout does not apply after /bqhud reload

Solution:

1. Check the YAML syntax in config.yml
2. Look at the server logs to detect errors
3. In folder mode, you must rebuild your server pack

Backgrounds are not displayed

Possible causes:

1. PNG files misnamed (respect the exact case)
2. Corrupted files or invalid format
3. Resource pack not loaded by the client

Solution:

/bqhud reload
# Check the logs to see if the backgrounds are detected

How do I revert to the default layout?

Remove your changes in config.yml and restore the default values, then:

/bqhud reload

📖 See also

• Full configuration
• Avatars and Backgrounds
• Troubleshooting