Numerical Storage

Benannte numerische Guthaben pro Spieler mit Stufen, Zinsen, Bankmenü und Platzhaltern.

Kostenlosv0.15Wirtschaft & Crafting

BenötigtTypeWriter0.9GUI (GuiAndDialogs)PlaceholderAPIoptionalVaultoptionalProfilesoptional

HerunterladenQuellcodeSupport

Überblick

Mit Numerical Storage erstellst du für jeden Spieler benannte numerische Speicher: ein Bankkonto, einen Manapool, eine Token-Geldbörse, einen Vorrat an beliebigen Ressourcen. Du beschreibst einen Speicher einmal in einer Definition, und die Erweiterung speichert pro Spieler ein Guthaben und eine Stufe.

Ein Speicher kann Stufen haben, jede mit einer maximalen Kapazität. Spieler zahlen über ein Inventarmenü, das mit der GUI-Erweiterung gebaut wird, ein und heben ab. Das Geld kann über Vault aus deinem Wirtschafts-Plugin stammen oder aus jedem Platzhalter und Konsolenbefehl deiner Wahl. Zinsen lassen sich nach Zeitplan hinzufügen, und Speicher können per Befehl zurückgesetzt, bearbeitet oder geöffnet werden.

Guthaben werden in einem TypeWriter-Artifact gespeichert und asynchron geschrieben, sodass eine Einzahlung nie den Server-Thread blockiert. Guthaben, Stufen und Kapazität stehen als PlaceholderAPI-Platzhalter für Scoreboards, Hologramme und Menüs zur Verfügung.

Funktionen

• Mehrere Speicher — erstelle beliebig viele Definitionen, jede mit eigenem Namen, Präfix, eigenen Stufen und Menü.
• Stufen und Kapazität — jede Stufe hat ein maximales Guthaben; Spieler werten auf, um es zu erhöhen.
• Stufenvoraussetzungen — schalte eine Stufe mit Platzhalter- oder Fact-Vergleichen frei und nimm optional Kosten.
• Zinsen — ein Cron-Zeitplan, ein globaler Satz, ein Satz pro Stufe und ein Satz pro Berechtigung, mit einer Obergrenze pro Zyklus.
• Vault oder Befehle — Ein- und Auszahlungen laufen über Vault oder über einen Platzhalter plus Konsolenbefehle.
• Überweisungen — verschiebe ein Guthaben atomar zwischen zwei Speichern.
• Menü-Buttons — fester Betrag, Prozentsatz, alles, eigener Betrag (Dialog), Untermenüs, Aufwerten und Schließen.
• Sichere Persistenz — asynchrones Speichern, eine Sperre pro Artifact und eine automatische Migration alter Dateien.
• Profilmodus — optionale Guthaben pro Profil mit MMOProfiles.
• Platzhalter und Befehle — lies Werte überall aus und bearbeite sie von der Konsole.

Installation

1. Installiere die GUI-Erweiterung: Numerical Storage benötigt sie für seine Menüs. Die GUI-Erweiterung wird unter dem Namen GuiAndDialogs veröffentlicht.
2. Installiere PlaceholderAPI, wenn du die Platzhalter %typewriter_ns_...% verwenden möchtest.
3. Optional: Installiere Vault (die Erweiterung wird gegen VaultUnlocked gebaut) und ein Wirtschafts-Plugin, um den Transaktionsmodus VAULT zu nutzen.
4. Optional: Installiere MMOProfiles, um profileMode zu nutzen.
5. Lege die Numerical-Storage-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.

Das Fenster für eigene Beträge verwendet Paper-Dialoge und benötigt daher eine Paper-Version, die diese unterstützt (Minecraft 1.21.6 oder neuer).

Vor dem Update sichern

Seit Version 0.9 verwenden neue Artifacts eine technische Kennung und ein JSON-Schema in Version 2. Wird eine alte Datei zum ersten Mal gelesen, wird sie in den neuen Pfad kopiert, unter backups/numericalstorage/ gesichert und entfernt. Bewahre vor dem Update eine Kopie des TypeWriter-Ordners assets/ auf.

Erste Schritte

So erstellst du eine Bank, die mit deiner Vault-Wirtschaft bezahlt wird:

1. Öffne im TypeWriter-Web-Panel eine Manifest-Seite und füge ein Player Numerical Storage-Artifact hinzu. Lass artifactId leer: TypeWriter generiert sie.
2. Füge eine Numerical Storage Definition hinzu. Setze displayName (zum Beispiel Bank) und prefix und verknüpfe das Artifact in artifact.
3. Füge in levels die erste Stufe mit einem limit von 1000 hinzu, dann eine zweite mit 5000. Fülle depositMessage und levelUpMessage, wenn du eigenen Text möchtest.
4. Setze in transaction den transactionMode auf VAULT.
5. Füge in menu.transactionButtons einen Button vom Typ DEPOSIT mit amountType FIXED, einem amount von 100 und dem anzuzeigenden Item hinzu. Füge einen zweiten vom Typ WITHDRAW hinzu.
6. Füge eine Open Numerical Storage Menu-Action hinzu. Verknüpfe die definition.
7. Füge in ihrem layoutPool ein simple-Layout mit der id main hinzu und setze mainLayoutId auf main. Füge im Layout ein Item hinzu, bei dem buttonPrefix auf numericalstorage_button: und buttonType auf DEPOSIT_FIXED:100 gesetzt sind. Tu dasselbe mit WITHDRAW_FIXED:100, UPGRADE_LEVEL und NAV_CLOSE.
8. Verknüpfe die Action mit einem NPC-Dialog oder einem Befehls-Event, veröffentliche und öffne die Bank im Spiel. Du kannst auch /typewriter ns open <definition> ausführen.

Ein Open-Menu-Entry pro Definition

Nach jeder Transaktion wird das Menü erneut geöffnet, um das neue Guthaben anzuzeigen. Die Erweiterung sucht dafür einen Open-Numerical-Storage-Menu-Entry, der mit derselben Definition verknüpft ist. Gibt es keinen, wird das Menü einfach geschlossen.

So funktioniert es

Menüs

Das Menü ist ein normales GUI-Layout. Die Open-Menu-Action öffnet es mit dem Titel und der Reihenzahl der Definition (menu.title, menu.rows, 1 bis 6), und dein layoutPool bestimmt, wo jedes Item steht. Die Erweiterung macht ein Item zu einem funktionierenden Button, wenn das Item buttonPrefix auf numericalstorage_button: und einen buttonType aus dieser Liste hat:

buttonType	Was der Button tut
DEPOSIT_FIXED	Zahlt einen festen Betrag ein. Hänge den Betrag nach einem Doppelpunkt an, zum Beispiel DEPOSIT_FIXED:100.
DEPOSIT_PERCENT	Zahlt einen Prozentsatz des Quellguthabens ein, zum Beispiel DEPOSIT_PERCENT:50.
DEPOSIT_CUSTOM	Schließt das Menü und fragt in einem Dialog nach einem Betrag.
DEPOSIT_ALL	Zahlt das Quellguthaben ein, bis zur verbleibenden Kapazität. Dafür ist ein amountPlaceholder nötig: Im Modus VAULT versucht der Button, die gesamte verbleibende Kapazität einzuzahlen, und schlägt fehl, wenn das Wirtschaftsguthaben niedriger ist.
DEPOSIT_SUBMENU	Öffnet ein Untermenü mit Einzahlungs-Buttons. Die Untermenü-ID folgt nach dem Doppelpunkt.
WITHDRAW_FIXED, WITHDRAW_PERCENT, WITHDRAW_CUSTOM, WITHDRAW_ALL, WITHDRAW_SUBMENU	Wie oben, für Abhebungen. Der Prozentsatz wird vom gespeicherten Guthaben genommen.
TRANSFER_FIXED, TRANSFER_PERCENT, TRANSFER_ALL	Verschiebt Guthaben in eine andere Definition. Der Button stammt aus einem transactionButtons-Eintrag vom Typ TRANSFER mit einem transferTarget.
SUB_MENU	Öffnet das Untermenü, dessen ID nach dem Doppelpunkt folgt, zum Beispiel SUB_MENU:deposit_options.
UPGRADE_LEVEL	Wertet auf die nächste Stufe auf oder zeigt das Item für die Maximalstufe.
NAV_CLOSE	Schließt das Menü.

Hat buttonType einen Betrag (DEPOSIT_FIXED:100), wählt die Erweiterung den Eintrag aus menu.transactionButtons mit demselben Typ, Betragstyp und Betrag und verwendet dessen template als Item. Ohne Betrag nimmt sie den ersten passenden Eintrag. Passt nichts, wird ein einfaches Farbstoff-Item mit der Standardbeschriftung angezeigt.

Untermenüs werden in menu.subMenus definiert, als Zuordnung von einer ID zu einem Titel, einer Reihenzahl, in slots platzierten Transaktions-Buttons, einem Zurück-Button und einem Schließen-Button.

Ein Überweisungs-Button benötigt das transferTarget der anderen Definition (ihre Entry-ID), und der Spieler muss im Zielspeicher Platz haben.

Befehle

Alle Befehle sind Unterbefehle von /typewriter (Alias /tw). <definition> ist ein Definition-Entry. Das optionale [target] wählt einen anderen Spieler; ohne es gilt der Befehl für den Absender.

Befehl	Berechtigung	Beschreibung
/typewriter ns open <definition> [target]	typewriter.ns.open	Öffnet das Menü des Speichers über seinen Open-Menu-Entry.
/typewriter ns add <definition> <amount> [target]	typewriter.ns.add	Addiert zum Guthaben. Die Kapazität wird nicht geprüft.
/typewriter ns remove <definition> <amount> [target]	typewriter.ns.remove	Zieht vom Guthaben ab, bis höchstens 0.
/typewriter ns level <definition> <level> [target]	typewriter.ns.level	Setzt die Stufe und das Guthaben auf 0 zurück.
/typewriter ns reset <definition> [target]	typewriter.ns.reset	Setzt die Stufe auf 1 und das Guthaben auf 0 zurück.

Die Befehle /typewriter numstorage tx ..., upgrade und back_main werden intern von den Menü-Buttons verwendet. Für einen Spieler ohne geöffnetes Menü bewirken sie nichts.

Bei aktivem profileMode ändern add, remove, level und reset Guthaben und Level des Profils des Ziels, wie es das Menü tut.

Befehlsantworten

Die Antworten von add, remove, level, reset und open sowie die Fehlerantworten unten sind die Felder von adminMessages an der Definition. Sie sind MiniMessage. Jede kann <player>, <storage> (die ID der Definition) und <prefix> verwenden.

Feld	Zusätzlicher Platzhalter	Standardwert
resetMessage	keine	Numerical storage reset for <player>.
levelSetMessage	<level>	Set numerical storage level to <level> for <player>.
addMessage	<amount>	Added <amount> to <player>.
removeMessage	<amount>	Removed <amount> from <player>.
noMenuMessage	keine	Die Nachricht, die angezeigt wird, wenn der Speicher keinen Open-Menu-Eintrag hat.
invalidAmountMessage	<amount> (der eingegebene Wert)	Invalid amount '<amount>'. Use a positive number. Wird von add und remove angezeigt, wenn der Betrag keine positive Zahl ist.
noArtifactMessage	keine	Die Nachricht, die add, remove, level und reset anzeigen, wenn der Definition kein Artifact zugeordnet ist.
noActiveProfileMessage	keiner	<player> has no active profile. Wird von add, remove, level und reset angezeigt, sowie einem Spieler, der eine Menüaktion anklickt, wenn profileMode an ist und der Spieler kein aktives MMOProfiles-Profil hat. Es wird nichts geschrieben.

Die Standardwerte beginnen mit dem Typewriter-Präfix. Drei Texte gehören zu keiner Definition und sind deshalb stattdessen Snippets in snippets.yml: numericalstorage.command.player_only (die Menü-Button-Befehle, die von einem Nicht-Spieler ausgeführt werden) sowie die Platzhaltertexte numericalstorage.placeholder.interest_disabled (Disabled), numericalstorage.placeholder.interest_error (Error) und numericalstorage.placeholder.capacity_unlimited (das Unendlichkeitszeichen). Die Zeiteinheiten von interest_cooldown sind die Snippets numericalstorage.duration.days, hours, minutes, seconds (jeweils eine Vorlage mit {value}, standardmäßig {value}j) und numericalstorage.duration.separator.

Berechtigungen

Berechtigung	Erlaubt
typewriter.ns.open	/typewriter ns open.
typewriter.ns.add	/typewriter ns add.
typewriter.ns.remove	/typewriter ns remove.
typewriter.ns.level	/typewriter ns level.
typewriter.ns.reset	/typewriter ns reset.
Berechtigungen in interestRates	Geben einem Spieler einen bestimmten Zinssatz. Es wird die erste Berechtigung der Liste verwendet, die der Spieler hat.

Platzhalter

Ersetze <id> durch die Entry-ID der Definition. Sie benötigen PlaceholderAPI und werden aus einem Cache gelesen, sind also in Scoreboards sicher nutzbar. Bei aktivem profileMode folgen balance, level, capacity und interest dem Profil, mit dem der Spieler gerade spielt, wie es das Menü tut.

Platzhalter	Liefert
%typewriter_ns_balance_<id>%	Das aktuelle Guthaben.
%typewriter_ns_level_<id>%	Die aktuelle Stufe, beginnend bei 1.
%typewriter_ns_capacity_<id>%	Die Kapazität der aktuellen Stufe oder das Unendlichkeitszeichen, wenn keine Stufe definiert ist.
%typewriter_ns_interest_<id>%	Den für den Spieler geltenden Zinssatz in Prozent.
%typewriter_ns_interest_cooldown_<id>%	Die Zeit bis zum nächsten geplanten Zinszyklus oder Disabled.
%typewriter_ns_name_<id>%	Den displayName der Definition.
%typewriter_ns_prefix_<id>%	Das prefix der Definition.

Entries

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

Aktionen2

• Numericalstorage MenuOpens a Numerical Storage menu
• Numericalstorage Open MenuOpens a Numerical Storage menu (triggerable)

Artefakte1

• Player Numericalstorage ArtifactStores the numericalstorage amount per player

Manifeste1

• Numericalstorage DefinitionDefines a configurable numerical storage

Fehlerbehebung

Das Menü öffnet sich leer oder Buttons tun nichts. Prüfe, ob jedes Item genau buttonPrefix numericalstorage_button: und einen gültigen buttonType hat. Ist das Präfix falsch, bleibt das Item ein normales Item ohne Aktion. Prüfe außerdem, ob mainLayoutId zur id eines Layouts im layoutPool passt.

Das Menü schließt sich nach jeder Einzahlung. Das Menü wird über einen Open Numerical Storage Menu-Entry erneut geöffnet, der mit derselben Definition verknüpft ist. Füge einen hinzu, auch wenn du das Menü mit einem anderen Entry öffnest.

„Cannot add ... Would exceed limit“. Der Speicher ist an der Kapazität der Stufe des Spielers (levels[].limit). Werte die Stufe auf oder erhöhe das Limit. Ist keine Stufe definiert, gibt es kein Limit.

Eine Einzahlung im Modus INTERNAL schlägt fehl. Das Quellguthaben des Spielers wird mit amountPlaceholder gelesen und muss eine einfache Zahl liefern. Der addCommand wird vor der Einzahlung von der Konsole ausgeführt und muss erfolgreich sein. Verwende {player} und {amount} im Befehl.

„Economy system is not available.“ transactionMode ist VAULT, aber Vault oder ein Wirtschafts-Provider fehlt. Installiere beides und starte neu.

Zinsen werden nicht ausgezahlt. Zinsen werden beim Beitritt eines Spielers für die Cron-Zyklen angewendet, die seit seiner letzten Zahlung vergangen sind (höchstens 100 Zyklen). interestEnabled muss aktiv und interestCron ausgefüllt sein. Beim ersten Beitritt wird nur die Startzeit festgehalten. Ein Guthaben an der Kapazität seiner Stufe bringt nichts ein.

Das Aufwerten verlangt die Kapazität als Kosten. Hat die nächste Stufe keine criteria, sind die Kosten eines Upgrades das limit der aktuellen Stufe, vom gespeicherten Guthaben genommen. Füge der nächsten Stufe criteria hinzu, um eine andere Voraussetzung zu definieren.

Platzhalter zeigen das Guthaben eines anderen Profils. Bei aktivem profileMode lesen die Platzhalter und die Upgrade-Schaltfläche Guthaben und Stufe des vom Spieler gewählten Profils. Ohne MMOProfiles lesen sie das eigene Guthaben des Spielers. Mit MMOProfiles und ohne aktives Profil (Auswahlbildschirm, nach /mmoprofiles quit) zeigen sie 0, weil die UUID des Spielers die ID seines Main-Profils ist und dessen Guthaben weder angezeigt noch gutgeschrieben werden darf. Schreibvorgänge werden mit noActiveProfileMessage abgelehnt, und die Zinsen eines Profils werden bei dessen Auswahl abgerechnet.

Ein Platzhalter ist direkt nach einem Neustart leer. Der Speicher wird beim Beitritt im Hintergrund geladen: Das erste Lesen kann vor dem Ende des Ladens kommen; das nächste zeigt den gespeicherten Wert.

Der Platzhalter ist leer. Die ID im Platzhalter muss die Entry-ID der Definition sein, nicht ihr Name. Teste mit /papi parse me %typewriter_ns_balance_<id>%.

Verwandte Erweiterungen

• GUI — die Menü-Engine, die für Layouts und Buttons verwendet wird.
• MMOProfiles — optional, wird von profileMode verwendet.