Avatars and backgrounds

Automatic NPC avatar linking

Linking is 100% automatic if the avatar filename matches the NPC's npc_id.

Mapping algorithm

The plugin converts the BetonQuest NPC name into an npc_id using these rules:

1. Takes the NPC's full name defined in BetonQuest
2. Keeps only the first block before a space, comma, or semicolon
3. Removes all accents and non-ASCII characters (normalization)
4. Converts to lowercase
5. Looks for the matching PNG file in avatars/

Simple mapping examples

BetonQuest NPC name	Generated npc_id	Expected file
Andre	andre	andre.png
Merchant	merchant	merchant.png
Guard_Captain	guard_captain	guard_captain.png

Complex mapping examples

BetonQuest NPC name	Generated npc_id	Expected file	Explanation
André, the Blacksmith	andre	andre.png	Removes accent, takes text before comma
José María	jose	jose.png	Removes accents, takes text before space
François-Xavier	francois-xavier	francois-xavier.png	Keeps the hyphen, removes the accent
Müller	muller	muller.png	Normalizes ü to u
Señor Lopez	senor	senor.png	Normalizes ñ to n, takes text before space
Étienne; Captain	etienne	etienne.png	Removes accent, takes text before semicolon
王小明	(empty)	nameless.png	Non-ASCII characters -> fallback
123_Guard	123_guard	123_guard.png	Digits and underscore allowed

Default avatar (fallback)

If no avatar matches the npc_id, the plugin automatically uses:

• File: nameless.png
• Location: plugins/KGInfoServs-BQBetterHud/avatars/nameless.png
• This file is automatically copied on first startup

Where to place avatars

Folder

plugins/KGInfoServs-BQBetterHud/avatars/

File rules

Rule	Detail
Format	PNG only (alpha transparency supported)
Name	Must exactly match the npc_id (lowercase, no accents)
Extension	.png (required)
Recommended size	64x64, 128x128 or 256x256 pixels
Transparency	Supported (alpha channel)

Examples of valid names

avatars/
├── andre.png
├── merchant.png
├── guard_captain.png
├── francois-xavier.png
├── jose.png
├── nameless.png          # Default fallback
└── senor.png

Recommended dimensions

Size	Use	Quality
64x64	Pixel art style	Good
128x128	Semi-realistic style	Very good
256x256	High definition style	Excellent
512x512	Ultra HD (not recommended)	Unnecessary overhead

Recommendation: Use 128x128 for a good quality/performance trade-off.

Backgrounds (UI backgrounds)

Backgrounds are not linked automatically to each NPC.

They are global and replace the interface's visual style.

Folder:

• plugins/KGInfoServs-BQBetterHud/backgrounds/

Supported files:

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

Moving and scaling the avatar / backgrounds

You can adjust positions and sizes in config.yml:

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

• x / y: offset
• scale: size (only on blocks that expose this key)

Full workflow: adding an avatar

Step 1: Identify the npc_id

Look at your NPC's name in BetonQuest and determine the npc_id:

Example with BetonQuest:

# In your conversations/village.yml file
quests:
  village_merchant:
    NPC_name: "André, the Blacksmith"
    # npc_id will be: andre

Step 2: Create the avatar

1. Create or find a PNG image of your NPC
2. Resize it to 128x128 pixels (recommended)
3. Name the file: andre.png

Step 3: Place the file

Copy the file into:

plugins/KGInfoServs-BQBetterHud/avatars/andre.png

Step 4: Reload the plugin

/bqhud reload

The plugin will:

1. Scan the avatars/ folder
2. Detect your new file
3. Regenerate the resource pack
4. Assign a Unicode character to the avatar

Step 5: Apply according to your mode

self-host mode:

• The pack is automatically regenerated
• Players receive the new pack on reconnection

folder mode:

1. The resourcepack/ folder is regenerated
2. Integrate the files into your server pack
3. Rebuild and republish your pack

Step 6: Test in game

Start a conversation with the NPC "André, the Blacksmith" and check that the avatar displays.

Applying your changes

Avatars

1. Replace/add your PNGs in avatars/
2. Run /bqhud reload
3. Check in game with a conversation

Backgrounds

1. Replace/add your PNGs in backgrounds/
2. Run /bqhud reload
3. Check in game with a conversation

Depending on your resource pack mode

self-host mode:

• Players automatically receive the new pack
• Reconnecting is recommended to force the reload

folder mode:

• The resourcepack/ folder contains the updated assets
• You must manually rebuild and republish your server pack

Troubleshooting avatars

The avatar does not display

1. Check the filename

The name must be in lowercase and without accents:

❌ Incorrect:

• André.png (uppercase + accent)
• andre.PNG (uppercase extension)
• andré.png (accent)

✅ Correct:

• andre.png

2. Check the format

The file must be a valid PNG. Test with:

# Windows (via PowerShell)
Get-ItemProperty plugins/KGInfoServs-BQBetterHud/avatars/andre.png

# Check that the file type is indeed PNG

The nameless.png fallback always displays

Possible causes:

1. The avatar file does not exist for this npc_id
2. The filename does not exactly match the npc_id
3. The PNG file is corrupted

Solution:

Check the logs to see the npc_id that was looked up, then create/rename your file accordingly.

Avatar library examples

Organization by NPC type

avatars/
├── villagers/
│   ├── andre.png
│   ├── merchant.png
│   └── marie.png
├── guards/
│   ├── captain.png
│   ├── guard1.png
│   └── guard2.png
└── boss/
    ├── dragon_king.png
    └── dark_sorcerer.png

⚠️ Note: Subfolders are not supported. Place all PNGs directly in avatars/.

Correct filenames

✅ Good names:

andre.png
village_merchant.png
guard_captain.png
elf_king.png
jose.png
francois-xavier.png

❌ Bad names:

André.png              # Accent
Village Merchant.png   # Space (use underscore)
guard captain.png      # Space (use underscore)
Elf King.png          # Uppercase + space
José.png              # Accent

See also

• Visual Customization
• Configuration
• Troubleshooting