Friend

Freundeslisten, Anfragen und Teleport zu Freunden, mit GUI-Menü und optionaler serverübergreifender Synchronisierung.

Privatv0.1.0Soziales

BenötigtTypeWriter0.9.0-beta-177 (BTC build)GUI (TypeWriter extension)MySQL (TypeWriter extension)optionalRedis or Valkeyoptional

Für das BornToCraft-Netzwerk entwickelt. Diese Erweiterung ist zu Referenzzwecken dokumentiert und wird nicht verteilt.

Support

Überblick

Friend gibt jedem Spieler eine Freundesliste. Spieler senden eine Anfrage, der andere Spieler nimmt sie an oder lehnt sie ab, und angenommene Freunde sehen gegenseitig ihren Online-Status und können sich zueinander teleportieren. Alles ist über /friend-Befehle, über TypeWriter-Aktionen und -Facts sowie über ein Menü verfügbar, das du selbst im Web-Panel gestaltest.

Eine Freundschaft wird anhand der Spieler-UUID gespeichert und übersteht daher eine Namensänderung. Die Liste liegt in einem einzigen Friend Artifact. Ist die MySQL-Bridge mit aktiviertem Redis installiert, werden Anfragen, Freundschaften und die Online-Präsenz zwischen allen Servern eines Netzwerks geteilt, und /friend tp kann einen Spieler auf den Server bringen, auf dem sich sein Freund befindet.

Das Menü ist ein GUI-Menü: Du baust sein Layout im Web-Panel und markierst einige Items als Friend-Buttons. Die Freundesköpfe selbst werden von der Erweiterung platziert.

Funktionen

• Freundschaftsanfragen — Freunde per Befehl, Action-Entry oder Menüklick senden, annehmen, ablehnen und entfernen.
• Anfragen-Schalter — jeder Spieler kann eingehende Anfragen mit /friend toggle abschalten.
• Freundesmenü — ein Entry enthält jeden Bildschirm (Freunde, Anfragen, Tabs) mit Spielerköpfen, Seitenwechsel und einem Füller für leere Slots.
• Teleportation zu einem Freund — auf demselben Server oder über den Proxy zum Server des Freundes in einem Netzwerk.
• Online-Status — lokale Spieler und, mit Redis, Spieler auf anderen Servern derselben Gruppe.
• Story-Anbindung — ein Fact für „ist dieser Spieler ein Freund“ und einer für „wie viele Freunde sind online“.
• Platzhalter — Anzahlen, Listen, indizierte Namen und der Server eines Freundes, nutzbar in jedem MiniMessage-Text.
• Admin-Werkzeuge — mit /friend admin die Freunde beliebiger Spieler auflisten, untersuchen und erzwungen verknüpfen oder trennen.

Installation

1. Installiere die Erweiterung GUI, die das Menü zeichnet.
2. Optional, für mehrere Server: Installiere die Erweiterung MySQL und aktiviere Redis (oder Valkey) in ihrer Konfiguration, mit derselben redis.group-id auf jedem Server. Siehe Serverübergreifendes Verhalten.
3. Lege die Friend-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.
4. Erstelle einen Friend Artifact-Entry auf einer statischen Page und veröffentliche ihn. Ohne ihn wird nichts gespeichert.

Die Berechtigungen friend.use und friend.tp sind standardmäßig an alle vergeben, friend.admin an Operatoren.

Erste Schritte

Baue ein Freundesmenü, das mit /friend geöffnet wird:

1. Öffne im TypeWriter-Web-Panel eine statische Page und füge ein Friend Artifact hinzu. Belasse artifactId bei friend_data.
2. Öffne eine Page und füge einen Friend Menu-Entry hinzu. Der Befehl /friend öffnet das erste gefundene Friend Menu, du brauchst normalerweise also nur eines.
3. Setze inventoryTitle, inventoryRows und guiType, baue dann das Layout in layoutPool und lass mainLayoutId auf das Wurzel-Layout zeigen. Zu Layouts und Frames siehe die GUI-Anleitungen.
4. Platziere deine Dekoration und Buttons. Wähle bei einem Item in buttonType einen Friend-Wert, zum Beispiel FRIEND_STATUS für einen Zähler, FRIEND_SETTINGS_TOGGLE_REQUESTS für den Anfragen-Schalter oder NAV_CLOSE, um das Menü zu schließen.
5. Deklariere die Bildschirme: Füge pro Bildschirm einen Eintrag zu views hinzu und liste dann die IDs, die Freunde anzeigen, in friendListViewIds und die IDs, die eingehende Anfragen anzeigen, in requestListViewIds auf.
6. Lege mit contentX, contentY, contentColumns und contentRows fest, wo die Spielerköpfe erscheinen.
7. Veröffentliche und führe dann im Spiel /friend aus.

Um das Menü von einer Quest, einem NPC oder einem Item aus zu öffnen, verknüpfe den Friend-Menu-Entry in den triggers eines anderen Entries oder führe ihn als Aktion aus.

Dialoge an Freundschaft knüpfen

Verwende den Fact Is Friend mit targetName auf einen Spielernamen gesetzt und nutze den Fact dann in einem Criteria (der Wert 1 bedeutet Freunde). Verwende Online Friends Count für Belohnungen, die mit einer aktiven Freundesliste wachsen.

Funktionsweise

Die Daten jedes Spielers werden geladen, wenn dieser Spieler auf dem Server online ist, und im Hintergrund im Artifact gespeichert. Jede Änderung wird zusätzlich auf dem Social-Nachrichtenbus veröffentlicht, sodass der Server, auf dem sich der andere Spieler befindet, sie ebenfalls anwendet.

Menüs

Der Entry Friend Menu ist ein GUI-Menü mit drei Friend-spezifischen Teilen.

Spielerköpfe. Auf einem in friendListViewIds deklarierten Bildschirm ist jeder Freund ein Spielerkopf, Online-Freunde zuerst. Ein Linksklick teleportiert zum Freund, ein Rechtsklick entfernt den Freund. Auf einem in requestListViewIds deklarierten Bildschirm nimmt ein Linksklick die Anfrage an und ein Rechtsklick lehnt sie ab. Die Köpfe füllen ein Raster aus contentColumns mal contentRows Slots, beginnend bei contentX und contentY. Freie Felder zeigen emptySlotItem.

Buttons. Ein Item, dessen buttonType einer der folgenden Werte ist, wird beim Rendern ersetzt:

buttonType	Was der Spieler sieht oder tut
FRIEND_STATUS	Anzahl der Online-Freunde, Offline-Freunde und Freunde insgesamt.
FRIEND_LIST	Gesamtzahl der Freunde oder „keine Freunde“, wenn die Liste leer ist.
FRIEND_REQUESTS	Anzahl ausstehender Anfragen. Ein Klick öffnet die Ansicht requests, wenn mindestens eine existiert.
FRIEND_SETTINGS_TOGGLE_REQUESTS	Klicken, um eingehende Anfragen ein- oder auszuschalten.
FRIEND_ONLINE_HEADER, FRIEND_OFFLINE_HEADER	Dekorative Abschnittsüberschriften.
PAGE_NAV	Seitenpfeil. Ein Linksklick geht vor, ein Rechtsklick zurück, der Name zeigt den Seitenzähler. Ausgeblendet, wenn eine Seite genügt.
NAV_BACK, NAV_CLOSE	Zum vorherigen Menü zurückgehen, das Menü schließen.
FRIEND_ADD, FRIEND_REMOVE, FRIEND_ACCEPT, FRIEND_DECLINE, FRIEND_TP, FRIEND_MSG, FRIEND_PLAYER_SLOT	Anzeige-Items mit festem Namen und fester Lore, ohne eigene Aktion.

Die übrigen vom Editor angebotenen Werte (NAV_PREV, NAV_NEXT, PENDING_REQUESTS, FRIEND_SLOT, REQUEST_ACCEPT, REQUEST_DECLINE) bleiben so, wie du sie konfiguriert hast.

Slot-Befehle. Ein Item kann Befehle ausführen, die mit friend beginnen: friend open [view], friend page next|prev|<number>, friend tp <name>, friend remove <name>, friend accept <name>, friend decline <name>, friend toggle, friend add <name>. Sie werden als der Spieler ausgeführt, der geklickt hat, ein %player% ist nicht nötig.

Sprache

Die eingebauten Menütexte (Standardtitel „Amis“, Button-Namen und Kopf-Lore) sind auf Französisch. Überschreibe sie mit den Item-Namen und der Lore, die du im Layout festlegst, und mit inventoryTitle. Chatnachrichten, die von den Befehlen gesendet werden, sind auf Englisch.

Serverübergreifendes Verhalten

Friend funktioniert auf einem einzelnen Server ohne weiteres Plugin. In einem Netzwerk installierst du MySQL und aktivierst Redis oder Valkey, und gibst dann jedem Server des Netzwerks dieselbe redis.group-id und einen anderen redis.server-name. Ohne group-id bleibt der Social-Nachrichtenbus stumm, und jeder Server sieht nur seine eigenen Änderungen.

Bei verbundener Bridge:

• werden Anfragen, neue Freundschaften, Entfernungen und der Anfragen-Schalter an die anderen Server gesendet;
• gilt ein Freund als online, wenn Redis weiß, auf welchem Server er sich befindet;
• bittet /friend tp bei einem Freund auf einem anderen Server den Proxy, dich mit diesem Server zu verbinden (der Proxy muss den Kanal btc:bridge verstehen). Du kommst auf dem Server an, nicht an der Position des Freundes.

Artifacts folgen dem aktiven Speicher: Ist mysql.enabled in der MySQL-Konfiguration true, wird das Friend Artifact in der gemeinsamen Datenbank gespeichert, sodass jeder Server dieselbe Freundesliste liest.

Befehle

Alle Befehle erfordern friend.use. Aliase: /friends, /f, /amis. Der Befehl ohne Argument öffnet das erste Friend Menu und gibt nichts aus, wenn keines existiert.

Befehl	Beschreibung
/friend	Öffnet das Freundesmenü.
/friend add <player>	Sendet eine Freundschaftsanfrage.
/friend accept <player>	Nimmt eine ausstehende Anfrage an.
/friend decline <player>	Lehnt eine ausstehende Anfrage ab.
/friend remove <player>	Entfernt einen Freund.
/friend list	Gibt deine Freunde mit ihrem Online-Status im Chat aus.
/friend toggle	Schaltet eingehende Freundschaftsanfragen ein oder aus.
/friend tp <player>	Teleportiert dich zu einem Freund (erfordert zusätzlich friend.tp).
/friend admin list <player>	Listet die Freunde eines Online-Spielers auf (erfordert friend.admin).
/friend admin requests <player>	Listet die ausstehenden Anfragen eines Online-Spielers auf.
/friend admin add <player> <player>	Macht zwei Online-Spieler zu Freunden, ohne Anfrageschritt.
/friend admin remove <player> <friend>	Entfernt einen Freund aus der Liste eines Online-Spielers.

Berechtigungen

Berechtigung	Standard	Gewährt
friend.use	Alle	Jeden /friend-Befehl. Menüklicks führen dieselben Aktionen aus, ohne sie zu prüfen.
friend.tp	Alle	/friend tp. Der Klick auf einen Kopf im Menü führt die Teleportation direkt aus und prüft diese Berechtigung nicht.
friend.admin	Operatoren	Die /friend admin-Befehle.

Platzhalter

Das sind MiniPlaceholders-Tags, die in MiniMessage-Text als <friend_count> geschrieben werden. Boolesche Werte liefern 1 oder 0.

Platzhalter	Gibt zurück
<friend_count>	Anzahl der Freunde des Spielers.
<friend_online_count>	Anzahl der Freunde, die auf diesem Server online sind.
<friend_online_network_count>	Anzahl der Freunde, die bekanntermaßen auf einem beliebigen Server der Gruppe online sind.
<friend_requests_count>	Anzahl ausstehender Anfragen.
<friend_requests_enabled>	1, wenn eingehende Anfragen erlaubt sind.
<friend_list>	Freundesnamen, durch Komma getrennt.
<friend_online_list>	Namen der Freunde, die auf diesem Server online sind.
<friend_name:index>	Freundesname an dieser Position, ab 0.
<friend_online_name:index>	Name des Online-Freundes an dieser Position, ab 0.
<friend_is_friend:name>	1, wenn der genannte Spieler ein Freund ist.
<friend_server:name>	Server, auf dem der genannte Spieler online ist, leer, wenn unbekannt.

Entries

8 Einträge, aus dem Quellcode der Erweiterung generiert.

Aktionen5

• Accept Friend RequestAccept a friend request
• Friend MenuFriend Menu
• Remove FriendRemove a friend
• Send Friend RequestSend a friend request
• Teleport to FriendTeleport to a friend

Fakten2

• Is FriendCheck if player is Friend
• Online Friends CountNumber of online friends

Artefakte1

• Friend ArtifactFriend Data Artifact

Fehlerbehebung

Freunde verschwinden nach einem Neustart. Es ist kein Friend Artifact veröffentlicht, die Daten liegen also nur im Speicher. Füge das Artifact auf einer statischen Page hinzu und veröffentliche.

/friend bewirkt nichts. Der Befehl öffnet den ersten Friend-Menu-Entry und bleibt stumm, wenn es keinen gibt. Erstelle und veröffentliche ein Friend Menu. Die Unterbefehle wie /friend list funktionieren auch ohne Menü.

Die Anfrage wurde gesendet, aber der andere Spieler erhält sie nie. Der Empfänger muss beim Senden der Anfrage auf einem Server des Netzwerks online sein. Anfragen an Offline-Spieler werden nicht aufbewahrt, und dem Absender wird dennoch mitgeteilt, dass die Anfrage gesendet wurde. Prüfe bei mehreren Servern, ob redis.group-id überall auf denselben Wert gesetzt ist, sonst gelangen Anfragen nicht zwischen den Servern.

Die Freundesliste ist auf einem zweiten Server leer. Jeder Server benötigt dieselbe redis.group-id, einen eindeutigen redis.server-name, und mysql.enabled muss true sein, damit das Artifact über die Datenbank geteilt wird. Prüfe die Logs der MySQL-Erweiterung auf Redis-Verbindungsfehler.

Das Kopfraster ist leer oder zeigt nur Füll-Items. Der aktuelle Bildschirm ist nicht in friendListViewIds oder requestListViewIds aufgeführt. Deklariert das Menü views, zeigen nur die dort aufgeführten IDs Köpfe an. Setze ohne views view auf friends oder requests.

Die Teleportation zu einem Freund auf einem anderen Server bewirkt nichts. Der Proxy muss den Kanal btc:bridge verarbeiten, und die Redis-Präsenz muss funktionieren. Ohne Netzwerkverbindung funktioniert /friend tp nur, wenn sich der Freund auf demselben Server befindet.

Verwandte Erweiterungen

• MySQL — Redis-Nachrichten, Präsenz und gemeinsamer Speicher für serverübergreifende Freunde.
• GUI — Layouts, Ansichten und Buttons, die das Freundesmenü verwendet.
• Party und Guild — die anderen sozialen Systeme auf demselben Nachrichtenbus.
• BTC Sky — verknüpft Coop-Inselmitglieder automatisch als Freunde.