Installation

Schritt-für-Schritt-Anleitung zur Installation und Konfiguration von KG_BQBetterHud auf Ihrem Minecraft-Server.

Voraussetzungen

Bevor Sie das Plugin installieren, stellen Sie sicher, dass Sie Folgendes haben:

Voraussetzung	Mindestversion	Empfohlen
Server	Paper 1.21+	Paper neueste Version
BetonQuest	3.0+	BetonQuest 3.0+
Java	Java 17+	Java 21
Lizenz	Gültiger KGInfoServs-Lizenzschlüssel	-

Kompatibilität

Das Plugin funktioniert nur mit Paper oder dessen Forks (Purpur, Pufferfish). Spigot wird aufgrund von API-Einschränkungen nicht unterstützt.

Schritt 1: Plugin herunterladen

1. Laden Sie die JAR-Datei aus Ihrem KGInfoServs-Kundenbereich herunter
2. Überprüfen Sie, dass die Datei folgenden Namen trägt: KGInfoServs-BQBetterHud-X.X.X.jar

Schritt 2: Installation auf dem Server

1. Stoppen Sie Ihren Server (falls gestartet)

2. Kopieren Sie die JAR-Datei in den Ordner plugins/:

   ihr-server/
   └── plugins/
       ├── BetonQuest.jar
       └── KGInfoServs-BQBetterHud-X.X.X.jar  # ← Neue Datei

3. Starten Sie den Server

Das Plugin generiert automatisch seinen Konfigurationsordner:

plugins/KGInfoServs-BQBetterHud/
├── config.yml           # Hauptkonfiguration
├── fonts.yml            # Schriftarten-Konfiguration
├── messages_en.yml      # Nachrichten auf Englisch
├── messages_fr.yml      # Nachrichten auf Französisch
├── license.key          # Lizenzdatei (auszufüllen)
├── avatars/            # Ordner für NPC-Avatare
│   └── nameless.png    # Standard-Avatar
├── backgrounds/        # Ordner für UI-Hintergründe
└── resourcepack/       # Generiertes Pack (Modus folder)

Schritt 3: Lizenzkonfiguration

1. Öffnen Sie die Datei plugins/KGInfoServs-BQBetterHud/license.key

2. Ersetzen Sie PASTE_YOUR_LICENSE_KEY_HERE durch Ihren Lizenzschlüssel

   Beispiel:

   a1b2c3d4-e5f6-7890-abcd-ef1234567890

3. Speichern Sie die Datei

4. Starten Sie den Server neu

5. Überprüfen Sie in den Logs:

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

Lizenzproblem?

Wenn Sie einen Lizenzfehler sehen, lesen Sie den Abschnitt Fehlerbehebung - Lizenzfehler.

Schritt 4: BetonQuest-Konfiguration (ERFORDERLICH)

Das Plugin benötigt eine Konfiguration in BetonQuest, um zu funktionieren.

Option 1: Globale Konfiguration (empfohlen)

Öffnen Sie plugins/BetonQuest/config.yml und ändern Sie:

conversation:
  default_io: kg_bqhud,menu,chest

Diese Konfiguration gilt standardmäßig für alle Gespräche.

Migration von kg_hud

Wenn Sie das alte Plugin kg_hud verwendet haben, ersetzen Sie es durch kg_bqhud:

# ❌ Alt (zu ersetzen)
conversation:
  default_io: kg_hud,menu,chest

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

Option 2: Konfiguration pro Gespräch

Wenn Sie das HUD lieber nur für bestimmte Gespräche aktivieren möchten:

# In Ihrer BetonQuest-Gesprächsdatei
conversations:
  guide_intro:
    quester: "Guide"
    conversationIO: kg_bqhud  # ← Aktiviert das HUD für dieses Gespräch
    first: "start"
    NPC_options:
      start:
        text: "Hallo Abenteurer!"
        pointer: choix
    player_options:
      choix:
        text:
          - "Hallo!"
          - "Wer bist du?"

BetonQuest neu laden

Nach der Änderung:

/betonquest reload
# oder starten Sie den Server neu

Schritt 5: Konfiguration des Resource Packs

Das Plugin generiert automatisch ein Resource Pack mit den visuellen Assets (Avatare, Hintergründe, Schriftarten).

Wählen Sie Ihren Verteilungsmodus:

Modus folder (empfohlen für die Produktion)

Das Plugin generiert die Dateien in einem Ordner, den Sie in Ihr Server-Pack integrieren.

Konfiguration:

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

Ablauf:

1. Das Plugin generiert die Assets in resourcepack/
2. Sie kopieren den Inhalt in Ihr Server-Pack:

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

3. Erstellen und verteilen Sie Ihr Pack über Ihren Hoster neu

Vorteile:

• Volle Kontrolle über das Pack
• Integration mit Ihren anderen Assets
• Kein Port zu öffnen

Integration mit ItemsAdder

Wenn Sie ItemsAdder zur Verwaltung Ihres Server-Resource-Packs verwenden, können Sie die Assets von KG_BQBetterHud automatisch zusammenführen.

ItemsAdder-Konfiguration:

Öffnen Sie plugins/ItemsAdder/config.yml und fügen Sie im Abschnitt merge_other_plugins_resourcepacks_folders hinzu:

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

Ablauf:

1. KG_BQBetterHud generiert seine Assets in resourcepack/
2. ItemsAdder führt diese Assets automatisch in sein Pack zusammen
3. ItemsAdder verteilt das finale Pack an die Spieler

Vorteile:

• Automatische Zusammenführung mit Ihren eigenen Items
• Vereinfachte Verteilung über ItemsAdder
• Keine manuelle Bearbeitung von Dateien

Neu laden

Führen Sie nach der Änderung /iazip aus, um das ItemsAdder-Pack mit den KG_BQBetterHud-Assets neu zu generieren.

Modus self-host (Entwicklung/Test)

Das Plugin hostet und sendet das Pack automatisch an die Spieler.

Konfiguration:

standalone:
  resource-pack:
    output-mode: "self-host"
    self-host-port: 8164
    public-url: "https://ihre-domain.com"  # Empfohlen
    force-pack: false
    pack-prompt: "Ressourcenpaket erforderlich für die Dialoganzeige."

Voraussetzungen:

• Port 8164 (TCP) in Ihrer Firewall geöffnet
• Öffentlich erreichbare URL (Domain oder öffentliche IP)

Vorteile:

• Automatische Aktualisierung nach /bqhud reload
• Keine manuelle Bearbeitung
• Ideal für Tests

Produktion

Der Modus self-host wird für die Produktion nicht empfohlen. Verwenden Sie folder und einen dedizierten Resource-Pack-Hoster (CDN, Website usw.).

Schritt 6: Erste Konfiguration

Bevor Sie im Spiel testen, konfigurieren Sie die Grundeinstellungen.

1. Sprache der Nachrichten

language: "fr"  # oder "en"

2. Globale Position des HUD

standalone:
  x-offset: 0      # Horizontale Verschiebung (0 = zentriert)
  y-offset: -200   # Vertikale Verschiebung (-200 = Standardposition)

3. Auswahlmodus

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

• scroll: Klassische Scroll-Liste
• fixed: Feste Liste mit Handzeiger

4. Typewriter-Effekt

typewriter:
  enabled: true
  speed: 30  # Zeichen pro Sekunde

5. Konfiguration neu laden

/bqhud reload

Schritt 7: Test im Spiel

1. Verbinden Sie sich mit dem Server

2. Akzeptieren Sie das Resource Pack (falls angefragt)

3. Starten Sie ein Gespräch mit BetonQuest bei einem NPC:

   /q conversation <konversation_name> <ihr_name>

4. Überprüfen Sie, dass das HUD korrekt angezeigt wird

Prüfliste

• Das HUD wird angezeigt (BossBar mit Dialoghintergrund)
• Der Name des NPC ist sichtbar
• Der Dialogtext wird angezeigt
• Die Antwortoptionen werden angezeigt
• Die Auswahl ändert sich mit den Tasten (standardmäßig: Zahlen)
• Der Typewriter-Effekt funktioniert (falls aktiviert)

Anzeigeproblem?

Wenn das HUD nicht angezeigt wird, lesen Sie Fehlerbehebung - Kein HUD im Dialog.

Schritt 8: Anpassung (optional)

Sobald das Plugin funktioniert, können Sie Folgendes anpassen:

NPC-Avatare

Platzieren Sie Ihre PNGs in plugins/KGInfoServs-BQBetterHud/avatars/

Beispiel:

avatars/
├── andre.png       # Für einen NPC namens "André"
├── kaufmann.png
└── wache.png

Siehe Avatare und Hintergründe für die detaillierte Zuordnung.

Benutzerdefinierte Hintergründe

Platzieren Sie Ihre PNGs in plugins/KGInfoServs-BQBetterHud/backgrounds/

Verfügbare Dateien:

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

Positionen und Größen

Passen Sie in config.yml an:

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

Siehe Visuelle Anpassung für die vollständige Anleitung.

Benutzerdefinierte Schriftarten

Platzieren Sie Ihre TTF-Dateien in plugins/KGInfoServs-BQBetterHud/fonts/

Konfigurieren Sie fonts.yml:

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

Siehe Konfiguration - Erweiterte Schriftarten für weitere Details.

Administratorbefehle

Befehl	Beschreibung	Permission
/bqhud reload	Lädt die Konfiguration neu und regeneriert das Resource Pack	bqhud.admin
/bqhud update	Lädt ein verfügbares Update herunter	bqhud.admin
/bqhud	Zeigt die Hilfe an	bqhud.admin

Plugin-Update

Um auf eine neue Version zu aktualisieren:

1. Stoppen Sie den Server
2. Ersetzen Sie die JAR-Datei in plugins/
3. Starten Sie den Server
4. Überprüfen Sie die Logs auf die neue Version
5. Führen Sie /bqhud reload aus

Sicherung

Sichern Sie vor jedem Update Ihren Ordner plugins/KGInfoServs-BQBetterHud/, um Ihre Konfigurationen und Assets zu erhalten.

Problembehebung

Wenn bei der Installation Probleme auftreten, lesen Sie:

• Fehlerbehebung - Vollständiger Leitfaden zur Fehlerbehebung
• Discord KGInfoServs - Community-Support

Nächste Schritte

Jetzt, da das Plugin installiert ist:

1. Passen Sie die Avatare Ihrer NPCs an
2. Passen Sie Positionen und Farben an
3. Testen Sie mit Ihren Spielern
4. Lesen Sie die Vollständige Konfiguration

Willkommen im KG_BQBetterHud-Ökosystem! 🎉