Rewards
Überblick
Rewards führt pro Spieler eine Warteschlange mit Belohnungen, die verdient, aber noch nicht abgeholt wurden. Statt ein Item sofort zu vergeben oder einen Befehl auszuführen, legst du eine Belohnung in die Warteschlange. Der Spieler holt sie später über ein Menü ab, wenn er online ist und Platz im Inventar hat. Nichts geht verloren, wenn der Spieler offline oder sein Inventar voll ist, während die Belohnung vergeben wird.
Eine Belohnung ist eine Vorlage, die du einmal definierst (eine Reward Definition: Anzeige-Item, Lore, erforderliche freie Slots, beim Abholen auszuführende Aktionen). Beim Vergeben wird der Warteschlange ein kleiner Datensatz hinzugefügt; beim Abholen wird der Datensatz entfernt und die mit der Definition verknüpften TypeWriter-Aktionen werden ausgelöst. Da die Wirkung beim Abholen eine Liste von TypeWriter-Aktionen ist, kann eine Belohnung Items, Geld, einen Quest-Schritt oder alles andere vergeben, was TypeWriter auslösen kann.
Die Warteschlange wird in einem einzigen Artifact gespeichert. Stellt die Erweiterung MySQL Redis bereit, werden Server, die denselben Speicher teilen, nach jedem Speichern angewiesen, das Artifact neu zu laden, sodass eine auf einem Server vergebene Belohnung auf einem anderen abgeholt werden kann.
Funktionen
- Verzögertes Abholen — Belohnungen warten in der Warteschlange, bis der Spieler sie abholt.
- Reward Definitions — eine wiederverwendbare Vorlage pro Belohnungstyp, mit Anzeige-Item, Name, Lore und einer Anforderung an freie Slots.
- Abhol-Aktionen — das Abholen löst eine beliebige TypeWriter-Aktionsliste aus statt eines Konsolenbefehls.
- Eigenständiges Abholmenü — ein paginiertes Inventar mit Belohnungs-Slots, Info-Slot, Seiten-Buttons, Sammelabholung und Zurück-Button.
- Einbettbare Buttons — Belohnungs-Slots und ein Sammelabhol-Button lassen sich über Button-Typen auf jeder GUI-Seite platzieren.
- Cron-Vergabe —
btc_give_rewardkann eine Belohnung höchstens einmal pro Cron-Zeitraum und Spieler vergeben (tägliche, wöchentliche Belohnungen). - Abhol-Event — ein Event-Entry wird bei jedem Abholen mit der Belohnungs-ID, benutzerdefinierten Daten und Zählern ausgelöst.
- Fact für ausstehende Anzahl und Platzhalter — verwende die Warteschlange in Criteria, Scoreboards und Menüs.
- Anti-Spam — ein Cooldown von 500 ms zwischen Abholungen desselben Spielers.
Installation
- Installiere die Erweiterung GUI (ihr Plugin-Name im Build ist
GuiAndDialogs) und die Erweiterung MySQL, die beide als Abhängigkeiten von Rewards deklariert sind. Redis wird nur für das serverübergreifende Aktualisieren verwendet und ist auf einem einzelnen Server nicht nötig. - Lege die Rewards-JAR in
plugins/Typewriter/extensions/ab und starte den Server neu. - Installiere optional MiniPlaceholders, um die
rewards-Platzhalter in MiniMessage-Text zu verwenden.
Erste Schritte
Vergib eine tägliche Login-Belohnung, die Spieler über ein Menü abholen.
- Öffne im TypeWriter-Web-Panel eine statische Page und füge ein Rewards Artifact hinzu. Füge nur eines hinzu: Die Platzhalter und die eingebetteten Buttons verwenden das erste, das sie finden.
- Füge einen Rewards Config-Entry hinzu (ebenfalls nur einen), um Nachrichten und das Lore-Layout der Belohnung anzupassen.
- Füge eine Reward Definition hinzu. Setze
rewardIdaufdaily_login,sourceaufdaily_login, wähle eindisplayItemund verknüpfe inonClaimActionsdie Aktionen, die die Belohnung vergeben. - Erstelle eine Give Reward-Aktion. Verknüpfe das
artifactund diereward, aktiviereuseCronund setzecronExpressionauf0 0 0 * * *für einmal pro Tag. Löse sie über ein Beitritts-Event oder einen NPC aus. - Erstelle eine Open Rewards Menu-Aktion mit demselben
artifactund löse sie über einen Befehl oder einen NPC aus. - Veröffentliche. Ein Spieler, der die Vergabe auslöst, erhält eine ausstehende Belohnung; ein Klick darauf im Menü holt sie ab.
Verwende Has Pending Rewards in einem Criteria, um eine Benachrichtigung nur anzuzeigen, solange der Spieler etwas abzuholen hat.
Funktionsweise
Die Warteschlange speichert nur die rewardId, den Vergabezeitpunkt und die benutzerdefinierten Daten. Das im Menü angezeigte Item und die auszuführenden Aktionen werden immer im Moment der Anzeige oder des Abholens aus der Definition gelesen. Eine eingereihte Belohnung, deren Definition gelöscht wurde, wird nicht angezeigt und kann nicht abgeholt werden.
Menüs
Belohnungen können auf zwei Arten angezeigt werden, die dieselbe Abhol-Logik teilen.
Eigenständiges Menü. Open Rewards Menu öffnet ein eigenes Inventar mit rows von 1 bis 6. Ausstehende Belohnungen füllen rewardSlotsConfig der Reihe nach (einen Bereich oder eine explizite Slot-Liste, wenn useRange deaktiviert ist). Gibt es mehr Belohnungen als Slots, wird das Menü mit den optionalen previousPageButton und nextPageButton paginiert. Die optionalen infoSlot, bulkClaimButton und backButton nehmen Slot-Nummern, ein Item, einen MiniMessage-Namen und Lore entgegen. backButton.command wird als der Spieler ausgeführt (ohne den führenden Schrägstrich); lass es leer, um das Menü einfach zu schließen. Leere Slots werden mit backgroundItem gefüllt, wenn es gesetzt ist. Die Slot-Nummern gehen von 0 (oben links) bis 8 in der ersten Reihe, dann 9 bis 17 und so weiter.
Buttons auf jeder GUI-Seite. Setze in einem GUI-Menü den buttonType eines Items auf einen der Rewards-Marker. Das von dir konfigurierte Item behält Position und Stil; bei Belohnungs-Slots wird es durch das eigene Anzeige-Item der Belohnung ersetzt.
| Button-Typ | Verhalten |
|---|---|
rewards_button:REWARD_SLOT#<n> | Zeigt die n-te ausstehende Belohnung des Betrachters (ab 0 gezählt); ein Linksklick holt sie ab. Nach der letzten Belohnung ist der Slot leer. |
rewards_button:BULK_CLAIM | Ein Linksklick holt jede ausstehende Belohnung ab, für die der Spieler Platz hat. |
Abholregeln, in beiden Modi:
- Die Belohnung benötigt
requiredInventorySlotsleere Slots im Spielerinventar (0 bedeutet keine Prüfung). Ist nicht genug Platz, wird das Abholen abgelehnt undinventoryFullMessagegesendet. - Das Abholen löst die
onClaimActionsder Definition aus und anschließend jeden Reward Claimed-Event-Entry. Ein Sammelabholen geht von der zuletzt eingereihten Belohnung zur ersten und löst das Event einmal mit der Belohnungs-IDbulk_claimaus. - Erfolgs- und Sammelnachrichten stammen aus dem Rewards-Config-Entry. Bei eingebetteten Buttons wird der erste gefundene Rewards-Config-Entry verwendet.
Die Lore eines Belohnungs-Items wird aus dem additionalLore der Definition aufgebaut, dann einem Trenner und den Zeilen zu Quelle und freien Slots, danach einem abschließenden Tipp; die Beschriftungen stammen aus dem Rewards-Config-Entry.
Platzhalter
MiniPlaceholders-Expansion rewards, in MiniMessage-Text als Tags nutzbar.
| Platzhalter | Gibt zurück |
|---|---|
<rewards_pending> | Anzahl der ausstehenden Belohnungen des Spielers. |
<rewards_pending:rewardId> | Anzahl der ausstehenden Belohnungen mit dieser rewardId. |
<rewards_source:source> | Anzahl der ausstehenden Belohnungen, deren Definition diese source hat (ohne Beachtung der Groß- und Kleinschreibung). Belohnungen mit gelöschter Definition werden nicht gezählt. |
<rewards_claimed_total> | Anzahl der Belohnungen, die der Spieler insgesamt abgeholt hat. |
Die Belohnungs-ID ist ein Argument des Tags: Schreibe <rewards_pending:daily_login>, nicht <rewards_pending_daily_login>. Alle Platzhalter liefern nichts, wenn kein Rewards Artifact existiert.
Entries
7 Einträge, aus dem Quellcode der Erweiterung generiert.
Aktionen2
- BTC Give RewardAdds a reward to a player's pending queue (with optional cron scheduling)
- BTC Open Rewards MenuOpens the rewards queue menu for a player
Ereignisse1
- BTC Reward Claimed EventTriggered when a player successfully claims a reward
Fakten1
- BTC Has Pending RewardsReturns the count of pending rewards for a player
Artefakte1
- BTC Rewards ArtifactStores pending rewards and claim history for all players
Manifeste2
- BTC Reward DefinitionDefines a reward type that can be given and claimed by players
- BTC Rewards ConfigGlobal configuration for the rewards system (sounds, toasts, messages)
Fehlerbehebung
Das Menü öffnet sich nicht, und das Log meldet, die GUI-Erweiterung sei nicht installiert. btc_open_rewards_menu benötigt die GUI-Erweiterung zur Laufzeit. Installiere sie und starte neu. Die Aktion bewirkt außerdem mit einer Warnung nichts, wenn ihr Feld artifact leer ist.
Give Reward bewirkt nichts. Das Log zeigt eine Warnung, wenn die Aktion kein artifact, keine reward hat oder wenn die verknüpfte Definition eine leere rewardId hat. Fülle die drei Felder aus.
Eine Cron-Belohnung wird nur einmal vergeben. Bei aktiviertem useCron wird der Zeitpunkt der letzten Vergabe pro Spieler und pro Aktions-Entry gespeichert. Die nächste Vergabe erfolgt erst, nachdem der Cron-Ausdruck nach diesem Zeitpunkt das nächste Mal zutrifft. Teste mit einem kurzen Ausdruck oder verwende pro Zeitplan einen anderen Aktions-Entry.
Eine ausstehende Belohnung ist unsichtbar oder lässt sich nicht abholen. Das Menü überspringt eingereihte Belohnungen, deren Definition nicht über die rewardId gefunden werden kann. Ändere die rewardId einer Definition nicht, nachdem Belohnungen vergeben wurden.
Abholen mit der Nachricht „Inventar voll“ abgelehnt. Der Spieler hat weniger leere Slots als requiredInventorySlots. Beachte, dass die Prüfung jeden leeren Slot des Spielerinventar-Objekts zählt, einschließlich Rüstungs- und Nebenhand-Slots.
Toasts, Sounds, noRewardsMessage und onClaimFailActions haben keine Wirkung. Diese Felder existieren in Rewards Config und Reward Definition, aber der Code dieser Version liest sie nie. Nur die Nachrichten für Abholen, volles Inventar und Sammelabholung sowie das Lore-Layout werden angewendet.
Belohnungen erscheinen nicht auf einem anderen Server. Das serverübergreifende Aktualisieren stützt sich auf Redis aus der MySQL-Erweiterung und darauf, dass beide Server denselben Artifact-Speicher lesen. Ohne Redis sieht jeder Server nur seine eigene Kopie, bis er neu gestartet wird.