BattlePass

Saisonaler Battle Pass mit XP-Stufen, wöchentlichen Quests, gestaffelten Belohnungen und konfigurierbaren Menüs.

Privatv0.9.0RPG & Progression

BenötigtTypeWriter0.9QuestGUIMySQL

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

Support

Überblick

BattlePass fügt deinem Server eine saisonale Fortschrittsleiste hinzu. Eine Saison hat ein Start- und ein Enddatum und ist in Wochen unterteilt; jede Woche schaltet eine Liste von Quests frei. Schließt ein Spieler eine dieser Quests ab, erhält er XP, und XP-Schwellen werden zu Stufen. Belohnungen sind in Tiers gruppiert (zum Beispiel ein kostenloser Tier und ein Premium-Tier, der durch eine Berechtigung geschützt ist) und werden über ein Menü abgeholt.

Alles wird in einem einzigen Battle Pass Definition-Entry im Web-Panel konfiguriert: Tiers, Belohnungen, Wochen, XP-Schwellen, Zeitplan, Menü-Layout und Button-Items. Eine Belohnung ist nur eine Liste von TypeWriter-Triggern, sie kann also Items geben, Befehle ausführen, ein Kosmetikum gewähren oder alles andere, was eine Action tun kann. Die Quests stammen aus der TypeWriter-Quest-Erweiterung.

Die Erweiterung läuft auf dem BTC-Build von TypeWriter (BTC Core, Paper/Folia) und ist hier als Referenz dokumentiert. Der Fortschritt wird über ein Battle Pass Data-Artifact gespeichert, das in einem Speicher-Cache gehalten wird, sodass Menüs und Platzhalter nie auf den Speicher warten.

Funktionen

• Saisons — optionale Start- und Enddaten, eine Wochendauer in Tagen und eine IANA-Zeitzone (standardmäßig UTC).
• Wöchentliche Quests — Wochen werden automatisch oder an einem gewählten Datum freigeschaltet, und jede Quest gibt beim Abschluss eine feste Menge XP.
• XP und Stufen — eine Liste von XP-Schwellen definiert die Stufen, mit optionaler XP-Obergrenze.
• Gestaffelte Belohnungen — jeder Tier hat eine Priorität, eine optionale Berechtigung und Belohnungen, die an eine erforderliche Stufe gebunden sind.
• Sicheres Abholen — ein Abholvorgang wird reserviert, bevor die Trigger laufen, sodass eine Belohnung nicht doppelt ausgeliefert werden kann.
• Konfigurierbare Menüs — Slots, Größen und Item, Name und Lore jedes Buttons, oder ein vollständig eigenes Layout auf Basis der GUI-Erweiterung.
• Admin-Befehle — XP und Stufen für dich selbst oder andere Spieler hinzufügen, entfernen oder setzen und den Fortschritt eines Spielers auslesen.
• Platzhalter — Stufe, XP, Belohnungszähler und Wocheninformationen für Scoreboards und Menüs.
• Bearbeitbare Nachrichten — jede Chatnachricht kann in einem BattlePass Messages-Entry geändert werden.
• Netzwerktauglich — der Fortschritt wird über die MySQL-Erweiterung gespeichert, mit Cache-Invalidierung über Redis, wenn verfügbar.

Installation

1. Installiere die TypeWriter-Erweiterung Quest, die GUI-Erweiterung (GuiAndDialogs im BTC-Build) und die MySQL-Erweiterung. TypeWriter lädt BattlePass ohne sie nicht.
2. Lege die BattlePass-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.
3. Erstelle die gewünschten Quests mit der Quest-Erweiterung.
4. Wenn du einen Premium-Tier möchtest, erstelle die Berechtigung mit deinem Berechtigungs-Plugin (der Name ist dir überlassen, du gibst ihn im Tier ein).

Erste Schritte

So erstellst du eine vierwöchige Saison mit einer kostenlosen Belohnung auf Stufe 1:

1. Öffne im TypeWriter-Web-Panel eine Manifest-Seite und füge ein Battle Pass Data-Artifact hinzu. Lass artifactId wie generiert und storage.mode auf PLAYER.
2. Füge auf derselben Seite einen Battle Pass Definition-Entry hinzu. Gib ihm einen name, setze data auf das Artifact und wähle ein icon wie minecraft:book.
3. Fülle in xp die levels mit steigenden XP-Schwellen (zum Beispiel 100, 250, 500) und optional max.
4. Füge in weeks eine Woche mit number 1 und einem title hinzu, wähle in quests einen Quest-Entry und gib ihm einen xpReward. Wiederhole das für die nächsten Wochen.
5. Setze in schedule den start (zum Beispiel 2026-11-01T00:00:00), weekDurationDays und timezone (zum Beispiel Europe/Paris). Die Wochen werden dann nacheinander freigeschaltet.
6. Füge in tiers einen Tier mit level 1 hinzu, und füge in rewards eine Belohnung mit levelRequired 1 und einem displayName hinzu. Verknüpfe die triggers, die die Belohnung geben, zum Beispiel eine Action, die ein Item gibt.
7. Füge eine Open Battle Pass-Action hinzu, die in battlePass auf deine Definition zeigt, und löse sie über einen NPC, ein Item oder ein Menü aus. Spieler können auch /tw battlepass eingeben.
8. Veröffentliche, schließe eine Quest der Woche ab und öffne das Menü, um die Belohnung abzuholen.

Tier-Stufe und Belohnungsstufe

Die level eines Tiers ist seine Nummer im Belohnungsmenü und muss innerhalb einer Definition eindeutig sein. Die Spielerstufe, die zum Abholen einer Belohnung nötig ist, ist das eigene levelRequired der Belohnung. Ein Tier kann eine permission tragen: Spieler ohne sie sehen seine Belohnungen als gesperrt, so baust du einen Premium-Track.

Belohnungs-IDs stabil halten

Jede Belohnung hat eine id. Lässt du sie leer, erzeugt die Erweiterung eine aus der Tier-Stufe und der Position der Belohnung (tier-1-reward-1); verschiebst du Belohnungen aber später oder fügst welche ein, verschieben sich die erzeugten IDs, und die abgeholten Belohnungen der Spieler passen nicht mehr. Setze vor Beginn der Saison bei jeder Belohnung eine explizite id und ändere sie nie.

So funktioniert es

XP werden nur verdient, wenn eine in einer der Wochen der Definition aufgeführte Quest auf COMPLETED geht, die Woche als available markiert ist, die Woche freigeschaltet ist und die Saison läuft. Eine Quest mit einem xpReward von 0 gibt nichts. Die Stufe ist die Anzahl der xp.levels-Schwellen, die der Spieler erreicht hat.

Eine Belohnung kann abgeholt werden, wenn die Saison begonnen hat (das Abholen bleibt auch nach dem Ende möglich), die Stufe des Spielers levelRequired erreicht und er die permission des Tiers hat, falls eine gesetzt ist. Belohnungen werden einmal abgeholt. Schlagen die Trigger einer Belohnung fehl, bleibt die Belohnung ausstehend und wird nicht von selbst erneut versucht, da Trigger Nebenwirkungen haben können.

Menüs

Standardmäßig öffnet die Erweiterung ihre eigenen Inventarmenüs: ein Hauptmenü, das die Wochen auflistet, ein Quest-Menü für die gewählte Woche und ein Belohnungsmenü (Tier).

• Hauptmenü — ein Button pro Woche, Buttons für vorherige und nächste Woche, ein Belohnungs-Button, ein Info-Button und ein Schließen-Button.
• Quest-Menü — die Quests der Woche mit ihrem Zustand (gesperrt, verfügbar, aktiv, abgeschlossen), Seiten-Buttons, ein Sortier-Button und ein Zurück-Button.
• Belohnungsmenü — die Belohnungen jedes Tiers mit ihrem Zustand, Seiten-Buttons und ein Zurück-Button; ein Klick auf eine freigeschaltete Belohnung holt sie ab.

Größen und Positionen stammen aus layout. Jede Größe muss ein Vielfaches von 9 zwischen 9 und 54 sein, und jeder Slot muss hineinpassen. Slots akzeptieren einzelne Zahlen oder Bereiche wie 10-16. Lass einen Slot leer, um die Standardposition zu verwenden (54-Slot-Layout mit Wochen in Reihe 2, Quests in den Reihen 2 bis 4, Schließen in Slot 49), oder schalte einen Button mit seinem Feld ...Enabled ab. Jeder Button hat in buttons ein item, einen name und eine lore, in denen du Platzhalter in geschweiften Klammern verwenden kannst, etwa {week_title}, {quest_name}, {tier_level} oder {reward_state}. Die Feldhilfe im Panel listet die für jeden Button verfügbaren Platzhalter auf.

Setzt du baseMenuId, menuLayoutPool, menuViews oder menuMainLayoutId, öffnet sich der Pass stattdessen in deinem eigenen GUI-Chassis, mit drei Views (home, levels, quests), deren IDs in menuHomeViewId, menuLevelsViewId und menuQuestsViewId festgelegt sind. Der GUI-Editor bietet dann battlepass_button:-Items an: WEEK_SLOT, TIER_MENU, REWARD_SLOT, CLAIM, QUEST_SLOT, SORT, INFO, PAGE_NEXT, PAGE_PREV, BACK und CLOSE. Die Beschreibungen der Button-Typen im Editor sind auf Französisch.

Menü-Interaktionen sind intern in der GUI-Session: Sie sind keine Bukkit-Befehle und können nicht von Spielern eingegeben werden.

Befehle

BattlePass-Befehle sind Unterbefehle des TypeWriter-Befehls, beginnen also mit /typewriter oder seinem Alias /tw. Die Basisberechtigung ist typewriter.battlepass. Das Argument <pass> ist die ID oder der Name einer Battle Pass Definition und wird automatisch vervollständigt. Das optionale Argument [targets] ist ein Spielerselektor; ohne ihn gilt der Befehl für den Absender.

Befehl	Beschreibung
/tw battlepass	Öffnet das Menü der ersten Definition, nach ID sortiert.
/tw battlepass menu	Wie /tw battlepass.
/tw battlepass open	Wie /tw battlepass.
/tw battlepass <pass> xp add <amount> [targets]	Fügt XP hinzu (das Vorzeichen des Betrags wird ignoriert).
/tw battlepass <pass> xp remove <amount> [targets]	Entfernt XP.
/tw battlepass <pass> xp set <amount> [targets]	Setzt die XP (nicht unter null).
/tw battlepass <pass> level add <amount> [targets]	Erhöht die Stufe.
/tw battlepass <pass> level remove <amount> [targets]	Senkt die Stufe.
/tw battlepass <pass> level set <amount> [targets]	Setzt die Stufe.
/tw battlepass <pass> info [targets]	Zeigt XP und Stufe eines Spielers für den Pass an.

Berechtigungen

Berechtigung	Erlaubt
typewriter.battlepass	Jeden /tw battlepass-Befehl, einschließlich des Menüs und der Admin-Unterbefehle.
permission eines Tiers	Eine Berechtigung deiner Wahl, an einem Tier gesetzt, die zum Abholen der Belohnungen dieses Tiers nötig ist.

Platzhalter

Dies sind MiniPlaceholders-Tags der Expansion battlepass, nutzbar in jedem MiniMessage-Text, der Platzhalter unterstützt. Ersetze def durch die ID des Battle-Pass-Definition-Entrys. Zähler sind Zahlen; Wahr-/Falsch-Werte werden als 1 oder 0 geliefert.

Platzhalter	Liefert
<battlepass_name:def>	Den Namen des Passes.
<battlepass_active:def>	1, solange Spieler XP verdienen können (Saison läuft), sonst 0.
<battlepass_level:def>	Die Stufe des Spielers.
<battlepass_xp:def>	Die XP des Spielers.
<battlepass_xp_max:def>	Die XP-Obergrenze oder, wenn keine gesetzt ist, die höchste Schwelle.
<battlepass_xp_next:def>	Die XP-Schwelle der nächsten Stufe.
<battlepass_xp_remaining:def>	Fehlende XP bis zur nächsten Stufe.
<battlepass_rewards:def> und <battlepass_rewards_total:def>	Die Gesamtzahl der Belohnungen.
<battlepass_rewards_claimed:def>	Bereits abgeholte Belohnungen.
<battlepass_rewards_available:def>	Belohnungen, die der Spieler jetzt abholen kann.
<battlepass_rewards_unclaimed:def>	Gesamtbelohnungen minus abgeholte Belohnungen.
<battlepass_rewards_pending:def>	Reservierte, aber noch nicht ausgelieferte Belohnungen.
<battlepass_week_state:def:N>	Die Zustandsbezeichnung von Woche N.
<battlepass_week_active:def:N>	1, wenn Woche N weder gesperrt noch nicht verfügbar ist.
<battlepass_week_available:def:N>	1, wenn die Woche als available markiert ist.
<battlepass_week_title:def:N>	Der Titel von Woche N.
<battlepass_week_description:def:N>	Die Beschreibung von Woche N.
<battlepass_week_release:def:N>	Das Freischaltdatum von Woche N.
<battlepass_week_release_in:def:N>	Die Zeit bis zur Freischaltung von Woche N, leer, sobald freigeschaltet.

Entries

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

Aktionen1

• Open Battle PassOpen a battle pass menu

Fakten1

• Battle Pass Quest ActiveCheck if a battle pass week is active

Artefakte1

• Battle Pass Data ArtifactStore battle pass runtime data

Manifeste1

• Battlepass DefinitionRegister a battle pass definition

Weitere Einträge1

• Battlepass MessagesBattlePass Messages

Fehlerbehebung

Die Erweiterung lädt nicht. BattlePass benötigt die Erweiterungen Quest, GUI (GuiAndDialogs) und MySQL. Suche im Startlog von TypeWriter nach einer fehlenden Abhängigkeit.

Das Log meldet „Ignoring invalid battle pass definition“. Die Definition hat die Validierung nicht bestanden, ist daher nicht registriert, und /tw battlepass meldet „Aucun Battle Pass n'est actuellement chargé“. Die Logzeile listet die Probleme auf: ein leerer name, eine Menügröße, die kein Vielfaches von 9 zwischen 9 und 54 ist, ein Slot außerhalb des Menüs, doppelte Tier-Stufen, Wochennummern oder Belohnungs-IDs, nicht streng aufsteigende xp.levels oder ein schedule.start, der nicht vor schedule.end liegt.

Das Abschließen einer Quest gibt keine XP. Die Quest muss in einer Woche der Definition mit einem xpReward über 0 aufgeführt sein, die Woche muss available und freigeschaltet sein, die Saison muss aktiv sein, und die Definition benötigt ein data-Artifact (das Log warnt, wenn es fehlt). Eine unbekannte timezone fällt auf UTC zurück, und Datumsangaben, die nicht geparst werden können, werden ignoriert.

Eine Belohnung kann nicht abgeholt werden. Die Stufe muss levelRequired erreichen, der Spieler benötigt die permission des Tiers, die Saison muss begonnen haben, und die Belohnung darf nicht bereits abgeholt oder ausstehend sein. Sind ihre Trigger fehlgeschlagen, meldet das Log „remains pending after delivery failure“, und die Belohnung bleibt ausstehend, bis ein Administrator entscheidet, was zu tun ist.

Abgeholte Belohnungen erscheinen nach dem Bearbeiten der Belohnungen erneut. Belohnungs-IDs, die aus Positionen erzeugt wurden, haben sich geändert. Gib jeder Belohnung eine explizite id und ändere sie nicht mehr.

Der Fortschritt wird nicht gespeichert. Die artifactId des Artifacts muss eine gültige, vom Web-Panel erzeugte UUID bleiben; die Erweiterung weigert sich, etwas anderes zu verwenden. Verschiebe oder benenne die gespeicherten Dateien nicht von Hand um.

Verwandte Erweiterungen

• GUI — Menü-Engine für die Layouts und Buttons.
• MySQL — Speicherung und Redis-Cache-Invalidierung für den Fortschritt.