Crate

Beutekisten mit gewichteten Belohnungen, virtuellen Schlüsseln, Meilensteinen und einem Kartenzieh-Minispiel zum Öffnen.

Privatv0.0.2Wirtschaft & Crafting

BenötigtTypeWriter0.9BasicGUI

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

Support

Überblick

Crate fügt deinem Server Loot-Crates hinzu. Eine Crate hat eine Liste von Belohnungen mit jeweils einer Seltenheit, und Spieler öffnen sie, indem sie einen virtuellen Schlüssel einsetzen. Die gewonnene Belohnung wird auf dem Server ausgelost, bevor eine Animation beginnt, sodass nichts, was ein Spieler während des Öffnens tut, das Ergebnis ändern kann. Jedes Öffnen einer Crate zählt für Meilensteine, die nach einer bestimmten Anzahl an Öffnungen zusätzliche Belohnungen auslösen können.

Belohnungen sind TypeWriter-Trigger, eine Belohnung kann also ein Item geben, einen Befehl ausführen, ein Cosmetic vergeben oder eine Sequence starten. Das Öffnen wird in der Welt vor dem Spieler gezeigt: eine Vorschau der Belohnungen auf schwebenden Item-Displays oder ein Karten-Minispiel. Menüs lassen Spieler die Crates und die Belohnungen jeder Crate durchstöbern.

Die Erweiterung läuft auf dem BTC-Build von TypeWriter (BTC Core, Paper/Folia) und ist hier zur Referenz dokumentiert.

Funktionen

• Gewichtete Belohnungen — Seltenheiten haben ein Gewicht, und die Chance jeder Belohnung wird in den Menüs angezeigt.
• Virtuelle Schlüssel — Schlüssel werden pro Spieler im Daten-Artifact der Crate gezählt, und bei jedem Öffnen wird einer verbraucht.
• Sichere Öffnungen — ein Schlüssel wird zuerst reserviert und erst verbraucht, wenn die Belohnung enthüllt wird; eine Trennung, ein Timeout oder ein Neustart erstattet ihn zurück.
• Meilensteine — lösen nach einer bestimmten Anzahl an Öffnungen zusätzliche Belohnungen aus.
• Karten-Minispiel — der Spieler dreht eine von mehreren verdeckten Karten um, während die Belohnung bereits feststeht.
• Vorschauen in der Welt — Belohnungen schweben in den Layouts PAGINATED, FLEX oder SIMPLE um den Spieler, mit optionalem NPC und Hologramm.
• Menüs — ein globales Crate-Menü und ein Belohnungsmenü pro Crate, mit Rahmen, Seitenwechsel und eigenen Buttons.
• Statistiken — Öffnungen, Schlüssel, verbrauchte Schlüssel, letzte Öffnung und Meilenstein, als Platzhalter verfügbar.

Installation

1. Installiere die TypeWriter-Erweiterung Basic und die Erweiterung GUI (GuiAndDialogs im BTC-Build). Crate lädt ohne sie nicht.
2. Lege die Crate-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.
3. Vergib die im Abschnitt Berechtigungen genannten Berechtigungen an dein Team.

Erste Schritte

Erstelle eine Crate mit drei Belohnungen und gib dir selbst einen Schlüssel:

1. Öffne im TypeWriter-Web-Panel eine Manifest-Page und füge ein Crate Data-Artifact hinzu. Behalte die generierte artifactId bei und verwende ein Artifact pro Crate.
2. Füge einen Crate-Entry hinzu. Setze dataArtifact auf das Artifact und schreibe die noKeyMessage.
3. Füge in rarities Common mit Gewicht 70 und Rare mit Gewicht 30 hinzu.
4. Füge in rewards drei Belohnungen hinzu: Setze bei jeder eine rarity, ein in der Vorschau angezeigtes item, einen name und in action einen Trigger, der die Belohnung vergibt. Lass grantItem aktiviert, um das item automatisch zu geben, oder deaktiviere es, wenn die Aktion das Item selbst gibt.
5. Liste in rewardSlots die Inventar-Slots des Belohnungsmenüs auf (ab 0 gezählt), zum Beispiel 10-12. Eine Crate ohne Belohnungs-Slot lässt sich nicht öffnen.
6. Setze in icon die Werte x und y der Crate im globalen Menü, ein item und einen name.
7. Füge eine Open Crate-Aktion hinzu, die auf die Crate zeigt, und löse sie von einem NPC, einem Block oder einem Item aus.
8. Veröffentliche, führe dann /tw crate give <crate entry id> 5 aus und öffne die Crate. Mit /tw crate menu kannst du die Crates durchstöbern.

Belohnungsklicks im Belohnungsmenü

Im Belohnungsmenü einer Crate löst ein Klick auf eine Belohnung direkt die action dieser Belohnung aus, ohne dass ein Schlüssel verbraucht wird und ohne Statistiken. Gib Spielern keinen Zugang zum Belohnungsmenü, wenn die Aktion einer Belohnung etwas Wertvolles vergibt, oder behalte das Menü dem Team vor.

Schlüssel vergeben

Schlüssel werden mit /tw crate give <crate> <amount> [targets] hinzugefügt. Es gibt keine eigene Aktion für Schlüssel, aber eine Befehlsaktion kann diesen Befehl ausführen, zum Beispiel aus einer Quest-Belohnung oder einem Shop.

Funktionsweise

Die Chance einer Belohnung ist das Gewicht ihrer Seltenheit geteilt durch das Gesamtgewicht aller Belohnungen. Eine Belohnung, deren Seltenheit nicht in rarities aufgeführt ist, hat das Gewicht 1. Wenn die Belohnung enthüllt wird, wird der Schlüssel verbraucht, die Zähler für Öffnungen und verbrauchte Schlüssel steigen, jeder überschrittene Meilenstein wird ausgelöst, dann wird das Item gegeben (wenn grantItem aktiviert ist) und die action der Belohnung ausgeführt. Ein Spieler kann jeweils nur eine Öffnung gleichzeitig haben.

Menüs

• Globales Menü — geöffnet mit /tw crate menu. Es zeigt ein Icon pro Crate, platziert bei x (0 bis 8) und y (0 bis 5) des Icons, und ein Klick auf ein Icon öffnet das Belohnungsmenü dieser Crate. Ein optionaler Crate Main Menu-Entry legt Größe, Titel, Rahmen, Buttons, Items pro Seite und die für die Seitenwechsel-Pfeile reservierte Spalte fest.
• Belohnungsmenü — geöffnet per Klick auf ein Icon oder mit der Aktion Open Crate Menu. Es zeigt die Belohnungen in rewardSlots mit Name, Lore und optionalen Zeilen für Chance und Seltenheit (chanceLore und rarityLore, mit {chance} und {rarity}). guiLayout ist PAGINATED, FLEX (zentriert, vier Spalten) oder SIMPLE. frameItem, itemsPerPage und paginationColumn passen Rahmen und Seitenwechsel an, und buttons fügen eigene Buttons mit einer Aktion hinzu.

Buttons haben einen Typ (INFORMATION, NEXT, PREVIOUS, FILL) und eine Position. Ein FILL-Button wird in jeden leeren Slot kopiert. Die crate_button:-Marker (CRATE_OPEN, CRATE_PREVIEW, CRATE_GLOBAL_BROWSE, CRATE_REWARD_SLOT, NAV_BACK, NAV_CLOSE) werden im GUI-Editor angeboten, zeigen in dieser Version aber nur ein Platzhalter-Item.

Konfiguration

Crate hat keine Konfigurationsdatei. Alles wird in Entries konfiguriert. Die Spielerdaten liegen im Artifact Crate Data: Schlüssel, Öffnungen, verbrauchte Schlüssel, Zeitpunkt der letzten Öffnung, Meilenstein und ausstehende Öffnungen. Es wird asynchron geschrieben, und durch einen Absturz hinterlassene ausstehende Öffnungen werden beim Start wiederhergestellt (der Schlüssel wird erstattet).

Befehle

Alle Befehle sind Unterbefehle des TypeWriter-Befehls und beginnen daher mit /typewriter oder /tw. <crate> ist der Entry einer Crate und wird automatisch vervollständigt.

Befehl	Beschreibung	Berechtigung
/tw crate menu	Öffnet das globale Crate-Menü.	typewriter.crate.menu
/tw crate open <crate>	Öffnet die Crate und verbraucht einen Schlüssel.	typewriter.crate.open
/tw crate give <crate> [targets]	Gibt dir oder den ausgewählten Spielern einen Schlüssel.	typewriter.crate.give
/tw crate give <crate> <amount> [targets]	Gibt mehrere Schlüssel.	typewriter.crate.give
/tw crate remove <crate> [targets]	Entfernt einen Schlüssel, nur wenn der Spieler einen hat.	typewriter.crate.remove
/tw crate remove <crate> <amount> [targets]	Entfernt mehrere Schlüssel, nur wenn der Spieler genug hat.	typewriter.crate.remove

Die Basis-Berechtigung typewriter.crate schützt den gesamten Befehl. Die Erweiterung registriert einen internen Befehl /cratemenu, der bei Menüklicks verwendet wird; er ist nicht zum Eintippen gedacht.

Berechtigungen

Berechtigung	Gewährt
typewriter.crate	Zugriff auf den Befehl /tw crate.
typewriter.crate.menu	/tw crate menu.
typewriter.crate.open	/tw crate open.
typewriter.crate.give	/tw crate give.
typewriter.crate.remove	/tw crate remove.

Platzhalter

Das sind MiniPlaceholders-Tags der Expansion crate. Ersetze id durch die Entry-ID der Crate. Eine unbekannte Crate liefert einen leeren Wert.

Platzhalter	Gibt zurück
<crate_openings:id>	Anzahl der Öffnungen dieser Crate durch den Spieler.
<crate_keys:id>	Schlüssel, die der Spieler besitzt.
<crate_keys_used:id>	Schlüssel, die der Spieler verbraucht hat.
<crate_last_open:id>	Zeitpunkt der letzten Öffnung, in Millisekunden seit dem 1. Januar 1970.
<crate_milestone:id>	Den höchsten erreichten Meilenstein.

Verwende in hologramLines stattdessen die Tokens {openings}, {keys}, {last_open} und {milestone}.

Entries

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

Aktionen2

• Open CrateOuvre une caisse
• Open Crate MenuOuvre le menu d'une caisse

Artefakte1

• Crate ArtifactDonnées de caisse

Manifeste3

• CrateDéfinition d’une caisse
• Crate Main MenuApparence du menu principal
• Crate Minigame CardsMini-jeu Caisse : Cartes

Fehlerbehebung

„This crate is not configured correctly“. Die Crate hat die Validierung nicht bestanden, und das Server-Log listet die Gründe auf: keine Belohnungen, ein ungültiges Seltenheitsgewicht (es muss größer als null sein), kein rewardSlots oder Slots außerhalb von 0 bis 53 oder doppelt vergeben, ein Button oder icon außerhalb des 9-mal-6-Rasters, oder Meilensteine bei null Öffnungen oder doppelt. Dieselben Prüfungen laufen beim Start und schreiben eine Warnung.

Der Spieler erhält die noKeyMessage. Der Spieler hat keinen Schlüssel für diese Crate, oder die Crate hat kein dataArtifact. Vergib Schlüssel mit /tw crate give und prüfe die Artifact-Verknüpfung.

„You are already opening a crate“. Für diesen Spieler läuft bereits eine Öffnung. Sie endet, wenn die Belohnung enthüllt wird oder der Spieler die Verbindung trennt.

Statistiken und Schlüssel ändern sich nach einer Öffnung nicht. Sie ändern sich erst, wenn die Belohnung enthüllt wird. Hat der Spieler vorher den Server verlassen oder der Server angehalten, wird der Schlüssel erstattet, und die Zähler bleiben gleich.

Die Vorschau zeigt nichts oder die falschen Belohnungen. Die Vorschau verwendet das item jeder Belohnung. Belohnungen mit leerem item werden übersprungen, und preview.maxVisibleRewards begrenzt, wie viele gleichzeitig angezeigt werden. preview.distance und die *Location-Versätze verschieben die Anzeige.

Das Karten-Minispiel startet nicht. Verknüpfe einen Crate Minigame: Cards-Entry im Feld minigame der Crate. Seine columns gehen bis 10 und rows bis 10, und cardCount ist auf 100 begrenzt.

Eine Belohnung wird doppelt vergeben. Lass grantItem nur dann aktiviert, wenn die action das Item nicht ebenfalls vergibt.

Verwandte Erweiterungen

• GUI — Menü-Engine, die für die Crate-Menüs verwendet wird.