Installation

Step-by-step guide to install and configure KG_BQBetterHud on your Minecraft server.

Requirements

Before installing the plugin, make sure you have:

Requirement	Minimum version	Recommended
Server	Paper 1.21+	Latest Paper version
BetonQuest	3.0+	BetonQuest 3.0+
Java	Java 17+	Java 21
License	Valid KGInfoServs license key	-

Compatibility

The plugin only works on Paper or its forks (Purpur, Pufferfish). Spigot is not supported due to API limitations.

Step 1: Download the plugin

1. Download the JAR file from your KGInfoServs client area
2. Check that the file is named: KGInfoServs-BQBetterHud-X.X.X.jar

Step 2: Installation on the server

1. Stop your server (if running)

2. Copy the JAR into the plugins/ folder:

   your-server/
   └── plugins/
       ├── BetonQuest.jar
       └── KGInfoServs-BQBetterHud-X.X.X.jar  # ← New file

3. Start the server

The plugin will automatically generate its configuration folder:

plugins/KGInfoServs-BQBetterHud/
├── config.yml           # Main configuration
├── fonts.yml            # Font configuration
├── messages_en.yml      # English messages
├── messages_fr.yml      # French messages
├── license.key          # License file (to be filled in)
├── avatars/            # Folder for NPC avatars
│   └── nameless.png    # Default avatar
├── backgrounds/        # Folder for UI backgrounds
└── resourcepack/       # Generated pack (folder mode)

Step 3: License configuration

1. Open the file plugins/KGInfoServs-BQBetterHud/license.key

2. Replace PASTE_YOUR_LICENSE_KEY_HERE with your license key

   Example:

   a1b2c3d4-e5f6-7890-abcd-ef1234567890

3. Save the file

4. Restart the server

5. Check the logs:

   [BQBetterHud] License validated successfully
   [BQBetterHud] Standalone mode initialized

License issue?

If you see a license error, check the Troubleshooting - License error section.

Step 4: BetonQuest configuration (REQUIRED)

The plugin requires a configuration in BetonQuest to work.

Option 1: Global configuration (recommended)

Open plugins/BetonQuest/config.yml and edit:

conversation:
  default_io: kg_bqhud,menu,chest

This configuration applies to all conversations by default.

Migrating from kg_hud

If you were using the old kg_hud plugin, replace it with kg_bqhud:

# ❌ Old (to be replaced)
conversation:
  default_io: kg_hud,menu,chest

# ✅ New
conversation:
  default_io: kg_bqhud,menu,chest

Option 2: Per-conversation configuration

If you prefer to enable the HUD only for certain conversations:

# In your BetonQuest conversation file
conversations:
  guide_intro:
    quester: "Guide"
    conversationIO: kg_bqhud  # ← Enables the HUD for this conversation
    first: "start"
    NPC_options:
      start:
        text: "Hello adventurer!"
        pointer: choix
    player_options:
      choix:
        text:
          - "Hello!"
          - "Who are you?"

Reload BetonQuest

After making changes:

/betonquest reload
# or restart the server

Step 5: Resource pack configuration

The plugin automatically generates a resource pack containing the visual assets (avatars, backgrounds, fonts).

Choose your distribution mode:

folder mode (recommended for production)

The plugin generates the files in a folder, and you integrate them into your server pack.

Configuration:

standalone:
  resource-pack:
    output-mode: "folder"
    output-folder: "plugins/KGInfoServs-BQBetterHud/resourcepack"
    regenerate-on-startup: false

Workflow:

1. The plugin generates the assets in resourcepack/
2. You copy the content into your server pack:

   your-server-pack/
   ├── assets/
   │   ├── minecraft/
   │   └── kgbq/          # ← Copy from resourcepack/assets/kgbq/
   └── pack.mcmeta

3. Rebuild and redistribute your pack via your host

Advantages:

• Full control over the pack
• Integration with your other assets
• No port to open

Integration with ItemsAdder

If you use ItemsAdder to manage your server resource pack, you can automatically merge KG_BQBetterHud assets.

ItemsAdder configuration:

Open plugins/ItemsAdder/config.yml and add to the merge_other_plugins_resourcepacks_folders section:

resource-pack:
  merge_other_plugins_resourcepacks_folders:
    - KGInfoServs-BQBetterHud/resourcepack

Workflow:

1. KG_BQBetterHud generates its assets in resourcepack/
2. ItemsAdder automatically merges these assets into its pack
3. ItemsAdder distributes the final pack to players

Advantages:

• Automatic merging with your custom items
• Simplified distribution via ItemsAdder
• No manual file manipulation

Reload

After making changes, run /iazip to regenerate the ItemsAdder pack with the KG_BQBetterHud assets.

self-host mode (development/testing)

The plugin hosts and automatically sends the pack to players.

Configuration:

standalone:
  resource-pack:
    output-mode: "self-host"
    self-host-port: 8164
    public-url: "https://your-domain.com"  # Recommended
    force-pack: false
    pack-prompt: "Resource pack required to display dialogues."

Requirements:

• Port 8164 (TCP) open on your firewall
• Publicly accessible URL (domain or public IP)

Advantages:

• Automatic update after /bqhud reload
• No manual manipulation
• Ideal for testing

Production

self-host mode is not recommended for production. Use folder and a dedicated resource pack host (CDN, website, etc.).

Step 6: Initial configuration

Before testing in-game, configure the basic settings.

1. Message language

language: "fr"  # or "en"

2. Global HUD position

standalone:
  x-offset: 0      # Horizontal offset (0 = centered)
  y-offset: -200   # Vertical offset (-200 = default position)

3. Selection mode

selection-mode: "scroll"  # or "fixed"

• scroll: Classic scrolling list
• fixed: Fixed list with a hand indicator

4. Typewriter effect

typewriter:
  enabled: true
  speed: 30  # Characters per second

5. Reload the configuration

/bqhud reload

Step 7: In-game testing

1. Connect to the server

2. Accept the resource pack (if prompted)

3. Start a conversation with a BetonQuest NPC:

   /q conversation <conversation_name> <your_name>

4. Check that the HUD displays correctly

Verification checklist

• The HUD is displayed (BossBar with dialogue background)
• The NPC's name is visible
• The dialogue text is displayed
• The response options are displayed
• The selection changes with the keys (numbers by default)
• The typewriter effect works (if enabled)

Display issue?

If the HUD does not display, check Troubleshooting - No HUD in dialogue.

Step 8: Customization (optional)

Once the plugin is working, you can customize:

NPC avatars

Place your PNGs in plugins/KGInfoServs-BQBetterHud/avatars/

Example:

avatars/
├── andre.png       # For an NPC named "Andre"
├── merchant.png
└── guard.png

See Avatars and Backgrounds for the detailed mapping.

Custom backgrounds

Place your PNGs in plugins/KGInfoServs-BQBetterHud/backgrounds/

Available files:

• dialogue.png
• answer.png
• hand.png
• name_start.png, name_mid.png, name_end.png

Positions and sizes

Adjust in config.yml:

standalone:
  layout:
    avatar:
      x: -20
      y: 0
      scale: 0.75
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.0

See Visual Customization for the complete guide.

Custom fonts

Place your TTF files in plugins/KGInfoServs-BQBetterHud/fonts/

Configure fonts.yml:

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

See Configuration - Advanced fonts for more details.

Administrator commands

Command	Description	Permission
/bqhud reload	Reloads the configuration and regenerates the resource pack	bqhud.admin
/bqhud update	Downloads an available update	bqhud.admin
/bqhud	Displays help	bqhud.admin

Updating the plugin

To update to a new version:

1. Stop the server
2. Replace the JAR in plugins/
3. Start the server
4. Check the logs for the new version
5. Run /bqhud reload

Backup

Before any update, back up your plugins/KGInfoServs-BQBetterHud/ folder to keep your configurations and assets.

Troubleshooting

If you run into issues during installation, check:

• Troubleshooting - Complete troubleshooting guide
• KGInfoServs Discord - Community support

Next steps

Now that the plugin is installed:

1. Customize your NPC avatars
2. Adjust the positions and colors
3. Test with your players
4. Check out the Complete configuration

Welcome to the KG_BQBetterHud ecosystem! 🎉