Configuration

Fichier principal: plugins/KGInfoServs-BQBetterHud/config.yml

Objectif de cette page: expliquer chaque ligne utile de configuration et ce que vous pouvez faire avec.

Configuration BetonQuest (obligatoire)

Dans plugins/BetonQuest/config.yml:

conversation:
  default_io: kg_bqhud,menu,chest

Dans chaque conversation, vous pouvez aussi forcer:

conversationIO: kg_bqhud

Si vous voyez encore kg_hud dans default_io, remplacez-le par kg_bqhud.

Structure globale

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

Cle	Defaut	Effet
language	"en"	Langue des messages plugin (en ou fr)

Resource Pack (standalone.resource-pack)

Cle	Defaut	Effet
output-mode	"folder"	Mode d export du pack: folder (generation dossier) ou self-host (envoi direct aux joueurs)
self-host-port	8164	Port HTTP utilise en self-host
public-url	""	URL publique du pack en self-host (recommande en prod)
output-folder	"plugins/KGInfoServs-BQBetterHud/resourcepack"	Dossier de sortie en mode folder
force-pack	false	Force l acceptation du pack cote client
pack-prompt	"Resource pack required for dialogue display."	Message affiche avant telechargement
regenerate-on-startup	false	Regenerer automatiquement le pack a chaque demarrage

Position globale (standalone)

Cle	Defaut	Effet
x-offset	0	Deplace tout le HUD sur l axe horizontal (droite/gauche)
y-offset	-200	Deplace tout le HUD sur l axe vertical

Layout (standalone.layout)

Vous pouvez deplacer les elements avec x et y.

Les elements qui supportent un scale:

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

Reference complete:

Cle	Defaut	Effet
dialogue-bg.x	0	Position X du fond de dialogue
dialogue-bg.y	20	Position Y du fond de dialogue
dialogue-bg.scale	1.0	Taille du fond de dialogue
answer-bg.x	180	Position X du fond des reponses
answer-bg.y	-30	Position Y du fond des reponses
answer-bg.scale	1.0	Taille du fond des reponses
npc-name.x	10	Position X du nom NPC (popup avec options)
npc-name.y	19	Position Y du nom NPC (popup avec options)
npc-name-spoken.x	6	Position X du nom NPC (popup sans options)
npc-name-spoken.y	23	Position Y du nom NPC (popup sans options)
name-bg.x	0	Position X du fond du nom
name-bg.y	14	Position Y du fond du nom
dialogue-text.x	10	Position X du texte dialogue (avec options)
dialogue-text.y	32	Position Y du texte dialogue (avec options)
dialogue-text.split-width	166	Largeur de coupure (retour ligne auto) du texte dialogue
dialogue-text-spoken.x	10	Position X du texte dialogue (sans options)
dialogue-text-spoken.y	36	Position Y du texte dialogue (sans options)
options-scroll.x	226	Position X des options en mode scroll
options-scroll.y	-25	Position Y des options en mode scroll
options-scroll.line-height	14	Espacement vertical des lignes d options en scroll
options-fixed.x	190	Position X des options en mode fixed
options-fixed.y	-25	Position Y des options en mode fixed
options-fixed.line-height	8	Espacement vertical des lignes d options en fixed
options-fixed.split-width	160	Largeur max du texte options en fixed
hand.x	175	Position X de la main de selection
hand.y	-26	Position Y de base de la main
hand.spacing	8	Espacement vertical entre mains
avatar.x	-20	Position X de l avatar NPC
avatar.y	0	Position Y de l avatar NPC
avatar.scale	0.75	Taille de l avatar NPC
text-height	8	Hauteur de rendu du texte

Text Alignment (standalone.text-alignment)

Valeurs possibles: left, center, right

Cle	Defaut	Effet
dialogue	"center"	Alignement du texte dialogue
speaker	"left"	Alignement du nom NPC
options	"left"	Alignement du texte des options

Text Fonts (standalone.text-fonts)

Cle	Defaut	Effet
dialogue	""	Reserve pour la selection de police par zone
speaker	""	Reserve pour la selection de police par zone
options	""	Reserve pour la selection de police par zone

Note importante: dans la build actuelle, le rendu utilise surtout la police par defaut de fonts.yml.

Option Sound (option-sound)

Cle	Defaut	Effet
key	"minecraft:ui.button.click"	Son joue lors du changement d option
volume	1.0	Volume du son
pitch	1.0	Pitch du son

Typewriter (typewriter)

Cle	Defaut	Effet
enabled	true	Active/desactive l effet machine a ecrire
speed	30	Vitesse d affichage du texte (caracteres par seconde)

Notes de performance :

Le plugin utilise un système d'optimisation multi-niveaux pour l'effet typewriter :

• Transitions instantanées entre étapes de dialogue (pas de lag)
• Rendu optimisé avec 5 niveaux de performance
• Fast path pour les dialogues courts

Ces optimisations sont automatiques et ne nécessitent aucune configuration.

Selection Mode (selection-mode)

Cle	Defaut	Effet
selection-mode	"scroll"	Mode de selection: scroll ou fixed

Différences entre les modes

Mode scroll (par défaut) :

• Liste déroulante classique
• L'option sélectionnée reste toujours visible
• Défilement automatique si plus d'options que l'espace disponible
• Position configurée via standalone.layout.options-scroll

Mode fixed :

• Liste fixe avec indicateur de main
• Toutes les options affichées simultanément
• Fenêtre glissante pour scroll illimité
• Retour à la ligne automatique selon split-width
• Position configurée via standalone.layout.options-fixed

Recommandation :

• scroll : idéal pour 2-5 options courtes
• fixed : idéal pour 3-10 options avec texte long

Selection Indicator (selection-indicator)

Cle	Defaut	Effet
prefix	""	Prefixe ajoute a l option selectionnee
selected-color	"<#97deaa>"	Couleur de l option selectionnee
unselected-color	"<gray>"	Couleur des autres options
hand-base-y	-25	Base Y de calcul de la main de selection
hand-line-height	10	Ecart Y entre 2 lignes pour la main
max-option-length	0	Longueur max option (0 = illimite)

Updater (updater)

Cle	Defaut	Effet
auto-download	false	Auto telechargement des updates quand disponibles

Comment appliquer les changements

1. Modifier config.yml.
2. Executer /bqhud reload.
3. Verifier en jeu.

Pour les changements visuels (layout, x-offset, y-offset, avatars/backgrounds), faites toujours un test en condition reelle.

Fonts avancés (fonts.yml)

Fichier: plugins/KGInfoServs-BQBetterHud/fonts.yml

Le plugin utilise Java AWT pour le rendu des fonts, ce qui permet une flexibilité maximale.

Système de rendu

Le plugin supporte deux modes de rendu de texte :

1. Java AWT (par défaut) : rendu avec fonts système ou TTF personnalisées
2. Minecraft fonts : utilise les fonts bitmap de Minecraft (ascii.png, etc.)

Configuration par défaut

default:
  # Taille de la police en pixels (16 = taille normale Minecraft)
  scale: 16

  # Chemin vers fichier TTF (relatif à plugins/KGInfoServs-BQBetterHud/fonts/)
  # Exemples: "font.ttf", "minecraft.ttf", "custom/myfont.ttf"
  # Laisser vide pour utiliser la police système Java par défaut
  file: ""

  # Utiliser les fonts Minecraft au lieu du rendu Java AWT
  # true = utilise minecraft:font/ascii.png (fonts bitmap)
  # false = rendu avec Java AWT (TTF ou système)
  use-unifont: false

  # Fusionner avec les fonts bitmap Minecraft (caractères spéciaux)
  # Inclut: ascii.png, accented.png, nonlatin_european.png
  # Uniquement utilisé quand use-unifont est true
  merge-default-bitmap: true

  # Filtres de langue (non utilisés avec Java AWT)
  include: []

Priorité de chargement des fonts

Le plugin charge les fonts dans cet ordre :

1. Si file est spécifié et existe → Charge le fichier TTF
2. Si file est vide ou manquant → Utilise la police système Java
3. Si use-unifont est true → Utilise uniquement les fonts Minecraft

Fonts personnalisées

Vous pouvez définir plusieurs polices nommées :

fonts:
  # Police TTF personnalisée
  custom_ttf:
    file: "font.ttf"        # Placer dans plugins/KGInfoServs-BQBetterHud/fonts/
    scale: 16
    use-unifont: false
    merge-default-bitmap: false
    include: []

  # Police petite pour sous-titres
  small_text:
    file: ""
    scale: 12
    use-unifont: false
    merge-default-bitmap: false
    include: []

  # Police grande pour titres
  large_title:
    file: ""
    scale: 24
    use-unifont: false
    merge-default-bitmap: false
    include: []

Référencer une police dans config.yml

Note importante : Dans la version actuelle, le rendu utilise principalement la police default définie dans fonts.yml.

Les clés standalone.text-fonts dans config.yml sont réservées pour de futures fonctionnalités :

# Réservé pour sélection de police par zone (future feature)
standalone:
  text-fonts:
    dialogue: ""   # Futur : référence à fonts.custom_ttf
    speaker: ""
    options: ""

Exemples d'utilisation

Utiliser une police système

default:
  scale: 16
  file: ""              # Vide = police système
  use-unifont: false

Utiliser une police TTF personnalisée

1. Placez votre fichier mafonte.ttf dans plugins/KGInfoServs-BQBetterHud/fonts/
2. Configurez fonts.yml :

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

3. Rechargez : /bqhud reload

Utiliser les fonts Minecraft

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

Tailles recommandées

Scale	Taille	Usage recommandé
8	Très petit	Texte secondaire, annotations
12	Petit	Sous-titres
16	Normal	Texte dialogue standard (défaut Minecraft)
20	Grand	Titres
24	Très grand	Titres importants

Polices compatibles

Le système Java AWT supporte :

• TTF (TrueType Font) ✅
• OTF (OpenType Font) ✅
• Polices système installées ✅

Troubleshooting fonts

La police personnalisée ne s'affiche pas

Causes possibles :

1. Fichier TTF mal placé (vérifiez le dossier fonts/)
2. Nom de fichier incorrect dans fonts.yml
3. Fichier TTF corrompu

Solution :

# Vérifier les logs après reload
/bqhud reload
# Regardez les messages "[FontManager]" dans la console

Le texte est trop petit/grand

Ajustez le scale dans fonts.yml :

default:
  scale: 20  # Augmenter pour agrandir

Puis rechargez : /bqhud reload

Caractères spéciaux manquants

Si vous utilisez une police TTF qui n'a pas tous les caractères, activez le merge :

default:
  file: "mafonte.ttf"
  use-unifont: false
  merge-default-bitmap: true  # Ajoute les caractères Minecraft

Performance

Le rendu Java AWT est optimisé :

• Génération des glyphes à la création du resource pack (pas en temps réel)
• Cache des textures dans le pack
• Pas de surcharge serveur pendant les dialogues

Voir aussi

• Customisation Visuelle
• Troubleshooting