Fehlerbehebung

Vollständiger Leitfaden zur Lösung gängiger Probleme mit dem Plugin.

🚨 Häufige Probleme

1. Kein HUD erscheint im Dialog

Symptom: Der BetonQuest-Dialog wird als klassischer Chat statt als HUD angezeigt.

Mögliche Ursachen:

Ursache	Prüfung	Lösung
ConversationIO nicht konfiguriert	Schauen Sie in plugins/BetonQuest/config.yml	Fügen Sie kg_bqhud in conversation.default_io hinzu
Plugin nicht geladen	Konsole beim Start	Prüfen Sie die Ladefehler
BetonQuest fehlt	/plugins im Spiel	Installieren Sie BetonQuest
Konflikt mit altem KG_Hud	/plugins im Spiel	Entfernen Sie das alte Plugin kg_hud

Detaillierte Lösung:

1. Öffnen Sie plugins/BetonQuest/config.yml
2. Suchen Sie den Abschnitt conversation:
3. Ändern Sie:

conversation:
  default_io: kg_bqhud,menu,chest

4. Starten Sie den Server neu oder führen Sie /betonquest reload aus
5. Testen Sie mit einer Konversation

Alternative für eine bestimmte Konversation:

# In Ihrer BetonQuest-Konversationsdatei
conversationIO: kg_bqhud

2. Das Resource Pack wird nicht geladen

Symptom: Der HUD zeigt keine Hintergründe/Avatare an, oder Fehler "Failed to load resource pack".

Modus folder

Problem: Das generierte Pack wird nicht auf die Spieler angewendet.

Lösung:

1. Prüfen Sie, dass der Ordner existiert:

   plugins/KGInfoServs-BQBetterHud/resourcepack/

2. Integrieren Sie den Inhalt in Ihr Server-Pack:

   ihr-server-pack/
   ├── assets/
   │   └── kgbq/          # Kopieren Sie aus resourcepack/assets/kgbq/
   └── pack.mcmeta

3. Bauen Sie Ihr Server-Pack neu und veröffentlichen Sie es erneut

4. Die Spieler müssen das neue Pack herunterladen

Modus self-host

Problem: Das Plugin hostet das Pack, aber die Spieler erhalten es nicht.

Prüfungen:

1. Port erreichbar:

   standalone:
     resource-pack:
       self-host-port: 8164  # Muss in Ihrer Firewall geöffnet sein

2. Öffentliche URL konfiguriert (empfohlen):

   standalone:
     resource-pack:
       public-url: "https://ihre-domain.com"
       # oder
       public-url: "mein-server.beispiel.com:8164"

3. Testen Sie den Zugriff auf das Pack:

   • URL: http://ihre-ip:8164/pack.zip
   • Das Pack muss sich herunterladen lassen

4. Prüfen Sie die Logs:

   [PackServer] HTTP server started on port 8164
   [PackSender] Sending pack to player: PlayerName

Firewall-Problem:

Wenn der Port blockiert ist:

1. Öffnen Sie den Port 8164 (TCP) in Ihrer Firewall
2. Prüfen Sie die iptables-Regeln (Linux)
3. Konfigurieren Sie das Port-Forwarding (Hoster)

3. Die Avatare werden nicht angezeigt

Symptom: nameless.png wird für alle NPCs angezeigt, oder gar kein Avatar.

Ursachen und Lösungen:

Ursache 1: Falscher Dateiname

❌ Falsch:

plugins/KGInfoServs-BQBetterHud/avatars/
├── André.png          # Großbuchstabe + Akzent
├── dorf kaufmann.png  # Leerzeichen
└── Jose.PNG           # Endung in Großbuchstaben

✅ Richtig:

plugins/KGInfoServs-BQBetterHud/avatars/
├── andre.png
├── dorf_kaufmann.png
└── jose.png

Ursache 2: npc_id falsch identifiziert

Prüfen Sie, dass der Name Ihrer Datei dem automatischen Mapping entspricht:

Erinnerung an das Mapping:

Name in BetonQuest	npc_id	Datei
André, der Schmied	andre	andre.png
José María	jose	jose.png
Müller Schmidt	muller	muller.png

Das Plugin wandelt automatisch um:

• In Kleinbuchstaben
• Entfernt die Akzente
• Behält nur das erste Wort

Ursache 3: Beschädigte PNG-Datei

Test:

Öffnen Sie die PNG-Datei mit einem Bildbearbeitungsprogramm. Lässt sie sich nicht öffnen, ist die Datei beschädigt.

Lösung:

Exportieren Sie das Bild mit einer zuverlässigen Software erneut als PNG (GIMP, Photoshop, Paint.NET).

Ursache 4: Pack nicht neu geladen

Lösung:

/bqhud reload

Im Modus folder bauen Sie Ihr Server-Pack neu und veröffentlichen es erneut.

4. Die Hintergründe ändern sich nicht

Symptom: Die benutzerdefinierten Hintergründe werden nicht angewendet.

Checkliste:

• Dateien in plugins/KGInfoServs-BQBetterHud/backgrounds/ abgelegt
• Exakte Namen (Groß-/Kleinschreibung beachten):
  • dialogue.png
  • answer.png
  • hand.png
  • name_start.png
  • name_mid.png
  • name_end.png
• Gültiges PNG-Format
• /bqhud reload ausgeführt
• Server-Pack neu gebaut (Modus folder)

Schnelle Prüfung:

# Listen Sie die Hintergrunddateien auf
ls plugins/KGInfoServs-BQBetterHud/backgrounds/

Prüfen Sie, dass die Namen exakt übereinstimmen.

5. Positionen/Skalierung werden nicht angewendet

Symptom: Änderungen an config.yml bewirken visuell nichts.

Mögliche Ursachen:

Ursache 1: YAML-Syntaxfehler

Beispiel eines Fehlers:

# ❌ Falsch (Tabulatoren verwendet)
standalone:
	layout:
		avatar:
			x: -20

# ✅ Richtig (Leerzeichen verwendet)
standalone:
  layout:
    avatar:
      x: -20

Lösung:

1. Prüfen Sie die YAML-Syntax mit einem Online-Validator
2. Verwenden Sie Leerzeichen (keine Tabulatoren)
3. Schauen Sie nach /bqhud reload in die Logs auf Fehler

Ursache 2: Werte außerhalb der Grenzen

Manche Werte können ignoriert werden, wenn sie außerhalb vernünftiger Grenzen liegen.

Empfohlene Werte:

Parameter	Min	Max	Standard
x-offset	-500	500	0
y-offset	-400	0	-200
scale	0.1	3.0	1.0

Ursache 3: Client-Cache

Lösung:

1. Führen Sie /bqhud reload auf dem Server aus
2. Der Spieler verbindet sich erneut
3. Oder erzwingen Sie das Neuladen des Resource Packs (F3 + T im Spiel)

6. Benutzerdefinierte Schriftart wird nicht angezeigt

Symptom: Der Text verwendet trotz Konfiguration in fonts.yml die Standardschriftart.

Prüfungen:

1. TTF-Datei korrekt platziert:

   plugins/KGInfoServs-BQBetterHud/fonts/meineschrift.ttf

2. Korrekte Konfiguration in fonts.yml:

   default:
     scale: 16
     file: "meineschrift.ttf"  # Exakter Dateiname
     use-unifont: false

3. Logs nach /bqhud reload:

   [FontManager] Loading font: meineschrift.ttf
   [FontManager] Font loaded successfully

Häufige Fehler:

Fehler in den Logs	Ursache	Lösung
Font file not found: meineschrift.ttf	Datei fehlt	Prüfen Sie den Pfad und den Namen
Failed to load font: invalid format	TTF beschädigt	Laden Sie eine neue Datei herunter
Font rendering error	Java-Inkompatibilität	Verwenden Sie eine standardmäßige TTF-Schriftart

7. Typewriter-Effekt funktioniert nicht

Symptom: Der Text wird sofort angezeigt statt mit dem Schreibmaschineneffekt.

Prüfung:

typewriter:
  enabled: true   # Muss true sein
  speed: 30       # Zeichen pro Sekunde (bei Bedarf anpassen)

Empfohlene Geschwindigkeiten:

• 10: Sehr langsam (dramatischer Effekt)
• 30: Normal (Standard)
• 60: Schnell
• 100: Sehr schnell

Hinweis: Bei enabled: false wird der Text sofort angezeigt.

8. Auswahlmodus fixed funktioniert nicht

Symptom: Der Modus fixed ändert nichts, es bleibt beim Modus scroll.

Erforderliche Konfiguration:

selection-mode: "fixed"  # Nicht "Fixed" oder "FIXED"

Visuelle Unterschiede:

Modus	Verhalten
scroll	Scrollbare Liste, ausgewählte Option in Farbe
fixed	Feste Liste, Handzeiger (hand.png)

Wenn Sie die Hand im Modus fixed nicht sehen, prüfen Sie, dass backgrounds/hand.png existiert.

9. Befehl /bqhud verweigert

Symptom: "You don't have permission to use this command"

Lösung:

Fügen Sie Ihrer Gruppe oder Ihrem Spieler die Berechtigung hinzu:

# In Ihrem Berechtigungsplugin (LuckPerms usw.)
permissions:
  - bqhud.admin

Schnelltest (nur OP):

/op IhrName
/bqhud reload

10. Lizenzfehler beim Start

Symptom: Das Plugin lädt nicht und zeigt einen Lizenzfehler an.

Mögliche Fehlermeldungen:

[BQBetterHud] License validation failed
[BQBetterHud] License key not found
[BQBetterHud] Unable to contact license server

Lösungen:

1. Lizenzdatei prüfen:

   plugins/KGInfoServs-BQBetterHud/license.key

2. Inhalt der Datei:

   • Eine einzige Zeile
   • Keine Leerzeichen davor/danach
   • Gültiges UUID-Format

3. Internetzugang: Der Server muss den Lizenzserver kontaktieren können. Prüfen Sie:

   • Ausgehende Firewall
   • Internetverbindung des Servers
   • Proxy, falls zutreffend

4. Support kontaktieren: Wenn das Problem bestehen bleibt, kontaktieren Sie KGInfoServs auf Discord.

🔧 Diagnosewerkzeuge

Den Status des Plugins prüfen

/plugins
# Suchen Sie "KGInfoServs-BQBetterHud" in Grün

Logs in Echtzeit ansehen

Linux:

tail -f logs/latest.log | grep -i bqhud

Windows (PowerShell):

Get-Content logs/latest.log -Wait | Select-String -Pattern "bqhud" -CaseSensitive:$false

Eine BetonQuest-Konversation testen

/q conversation <konversation_name> <spieler>

Das Neuladen des Resource Packs erzwingen (Client)

Drücken Sie im Spiel F3 + T, um die Ressourcen neu zu laden.

📋 Checkliste zur schnellen Fehlerbehebung

Bevor Sie um Hilfe bitten, prüfen Sie:

• plugins/BetonQuest/config.yml enthält kg_bqhud in conversation.default_io
• /bqhud reload nach jeder Änderung ausgeführt
• Resource-Pack-Modus korrekt konfiguriert (folder oder self-host)
• Avatare/Hintergründe an den richtigen Orten mit den richtigen Namen
• Server-Logs auf Fehler geprüft
• Berechtigung bqhud.admin gewährt
• BetonQuest installiert und funktionsfähig
• Unterstützte Minecraft-Version (1.21+)

🆘 Um Hilfe bitten

Wenn das Problem nach Befolgen dieses Leitfadens bestehen bleibt:

1. Sammeln Sie die Informationen:

   • Minecraft-Version
   • Paper/Spigot-Version
   • BetonQuest-Version
   • KG_BQBetterHud-Version
   • Server-Logs (letzte 50 Zeilen mit Fehlern)
   • Ihre config.yml

2. Kontaktieren Sie den Support:

   • Discord KGInfoServs: https://discord.gg/SZhD9AGUXW
   • Erstellen Sie ein Ticket mit allen oben genannten Informationen

📚 Siehe auch

• Konfiguration
• Avatare und Hintergründe
• Visuelle Anpassung
• Installation