Avatare und Hintergründe

Automatische NPC-Avatar-Verknüpfung

Die Verknüpfung erfolgt zu 100 % automatisch, wenn der Name der Avatar-Datei mit der npc_id des NPCs übereinstimmt.

Mapping-Algorithmus

Das Plugin wandelt den BetonQuest-Namen des NPCs nach folgenden Regeln in eine npc_id um:

1. Nimmt den vollständigen Namen des NPCs, der in BetonQuest definiert ist
2. Behält nur den ersten Block vor Leerzeichen, Komma oder Semikolon
3. Entfernt alle Akzente und Nicht-ASCII-Zeichen (Normalisierung)
4. Wandelt in Kleinbuchstaben um
5. Sucht die passende PNG-Datei in avatars/

Beispiele für einfaches Mapping

NPC-Name BetonQuest	Generierte npc_id	Erwartete Datei
Andre	andre	andre.png
Kaufmann	kaufmann	kaufmann.png
Guard_Captain	guard_captain	guard_captain.png

Beispiele für komplexes Mapping

NPC-Name BetonQuest	Generierte npc_id	Erwartete Datei	Erklärung
André, der Schmied	andre	andre.png	Entfernt Akzent, nimmt Teil vor Komma
José María	jose	jose.png	Entfernt Akzente, nimmt Teil vor Leerzeichen
François-Xavier	francois-xavier	francois-xavier.png	Behält den Bindestrich, entfernt den Akzent
Müller	muller	muller.png	Normalisiert ü zu u
Señor Lopez	senor	senor.png	Normalisiert ñ zu n, nimmt Teil vor Leerzeichen
Étienne; Kapitän	etienne	etienne.png	Entfernt Akzent, nimmt Teil vor Semikolon
王小明	(leer)	nameless.png	Nicht-ASCII-Zeichen → Fallback
123_Guard	123_guard	123_guard.png	Ziffern und Unterstrich erlaubt

Standard-Avatar (Fallback)

Wenn kein Avatar der npc_id entspricht, verwendet das Plugin automatisch:

• Datei: nameless.png
• Speicherort: plugins/KGInfoServs-BQBetterHud/avatars/nameless.png
• Diese Datei wird beim ersten Start automatisch kopiert

Wo die Avatare platziert werden

Ordner

plugins/KGInfoServs-BQBetterHud/avatars/

Regeln für die Dateien

Regel	Detail
Format	Nur PNG (Alpha-Transparenz wird unterstützt)
Name	Muss exakt der npc_id entsprechen (Kleinbuchstaben, ohne Akzente)
Erweiterung	.png (erforderlich)
Empfohlene Größe	64x64, 128x128 oder 256x256 Pixel
Transparenz	Wird unterstützt (Alphakanal)

Beispiele für gültige Namen

avatars/
├── andre.png
├── kaufmann.png
├── guard_captain.png
├── francois-xavier.png
├── jose.png
├── nameless.png          # Standard-Fallback
└── senor.png

Empfohlene Abmessungen

Größe	Verwendung	Qualität
64x64	Pixel-Art-Stil	Gut
128x128	Semi-realistischer Stil	Sehr gut
256x256	Hochauflösender Stil	Exzellent
512x512	Ultra HD (nicht empfohlen)	Unnötige Belastung

Empfehlung: Verwenden Sie 128x128 für einen guten Kompromiss zwischen Qualität und Leistung.

Backgrounds (UI-Hintergründe)

Die Backgrounds werden nicht automatisch mit jedem NPC verknüpft.

Sie sind global und ersetzen den visuellen Stil der Benutzeroberfläche.

Ordner:

• plugins/KGInfoServs-BQBetterHud/backgrounds/

Unterstützte Dateien:

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

Avatar / Hintergründe verschieben und skalieren

Sie können Positionen und Größen in config.yml anpassen:

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: Verschiebung
• scale: Größe (nur bei Blöcken, die diesen Schlüssel bereitstellen)

Kompletter Workflow: Einen Avatar hinzufügen

Schritt 1: Die npc_id identifizieren

Schauen Sie sich den Namen Ihres NPCs in BetonQuest an und bestimmen Sie die npc_id:

Beispiel mit BetonQuest:

# In Ihrer Datei conversations/village.yml
quests:
  dorf_kaufmann:
    NPC_name: "André, der Schmied"
    # npc_id wird sein: andre

Schritt 2: Den Avatar erstellen

1. Erstellen oder finden Sie ein PNG-Bild Ihres NPCs
2. Skalieren Sie es auf 128x128 Pixel (empfohlen)
3. Benennen Sie die Datei: andre.png

Schritt 3: Die Datei platzieren

Kopieren Sie die Datei nach:

plugins/KGInfoServs-BQBetterHud/avatars/andre.png

Schritt 4: Das Plugin neu laden

/bqhud reload

Das Plugin wird:

1. Den Ordner avatars/ scannen
2. Ihre neue Datei erkennen
3. Das Resource Pack neu generieren
4. Dem Avatar ein Unicode-Zeichen zuweisen

Schritt 5: Je nach Modus anwenden

Modus self-host:

• Das Pack wird automatisch neu generiert
• Die Spieler erhalten das neue Pack bei der erneuten Verbindung

Modus folder:

1. Der Ordner resourcepack/ wird neu generiert
2. Integrieren Sie die Dateien in Ihr Server-Pack
3. Erstellen und veröffentlichen Sie Ihr Pack erneut

Schritt 6: Im Spiel testen

Starten Sie ein Gespräch mit dem NPC „André, der Schmied" und prüfen Sie, ob der Avatar angezeigt wird.

Ihre Änderungen anwenden

Avatare

1. PNG-Dateien in avatars/ ersetzen/hinzufügen
2. /bqhud reload ausführen
3. Im Spiel mit einem Gespräch überprüfen

Backgrounds

1. PNG-Dateien in backgrounds/ ersetzen/hinzufügen
2. /bqhud reload ausführen
3. Im Spiel mit einem Gespräch überprüfen

Je nach Resource-Pack-Modus

Modus self-host:

• Die Spieler erhalten automatisch das neue Pack
• Erneute Verbindung empfohlen, um das Neuladen zu erzwingen

Modus folder:

• Der Ordner resourcepack/ enthält die aktualisierten Assets
• Sie müssen Ihr Server-Pack manuell neu erstellen und erneut veröffentlichen

Fehlerbehebung Avatare

Der Avatar wird nicht angezeigt

1. Den Dateinamen überprüfen

Der Name muss in Kleinbuchstaben und ohne Akzente sein:

❌ Falsch:

• André.png (Großbuchstabe + Akzent)
• andre.PNG (Erweiterung in Großbuchstaben)
• andré.png (Akzent)

✅ Richtig:

• andre.png

2. Das Format überprüfen

Die Datei muss ein gültiges PNG sein. Testen Sie:

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

# Überprüfen Sie, dass der Dateityp tatsächlich PNG ist

Der Fallback nameless.png wird weiterhin angezeigt

Mögliche Ursachen:

1. Die Avatar-Datei existiert nicht für diese npc_id
2. Der Dateiname entspricht nicht exakt der npc_id
3. Die PNG-Datei ist beschädigt

Lösung:

Schauen Sie in die Logs, um die gesuchte npc_id zu sehen, und erstellen/benennen Sie Ihre Datei entsprechend um.

Beispiele für eine Avatar-Bibliothek

Organisation nach NPC-Typ

avatars/
├── dorfbewohner/
│   ├── andre.png
│   ├── kaufmann.png
│   └── marie.png
├── wachen/
│   ├── captain.png
│   ├── guard1.png
│   └── guard2.png
└── boss/
    ├── drachen_koenig.png
    └── dunkler_zauberer.png

⚠️ Hinweis: Unterordner werden nicht unterstützt. Platzieren Sie alle PNG-Dateien direkt in avatars/.

Korrekte Dateinamen

✅ Gute Namen:

andre.png
dorf_kaufmann.png
guard_captain.png
elfen_koenig.png
jose.png
francois-xavier.png

❌ Schlechte Namen:

André.png              # Akzent
Dorf Kaufmann.png      # Leerzeichen (Unterstrich verwenden)
guard captain.png      # Leerzeichen (Unterstrich verwenden)
Elfen Koenig.png      # Großbuchstabe + Leerzeichen
José.png              # Akzent

Siehe auch

• Visuelle Anpassung
• Konfiguration
• Fehlerbehebung