MegaBlock Survivors Einrichtung

MegaBlock Survivors verwendet Nightbreak-Inhaltspakete. FreeMinecraftModels muss für Partien installiert sein, da Gegner und Waffen direkt auf dessen Modellklassen zugreifen; die Deklaration als weiche Abhängigkeit ändert daran nichts.

Voraussetzungen

• Java 21
• Ein Server, der zu deinem MegaBlock-Survivors-Build passt. Der Deskriptor deklariert API 1.21.4, der aktuelle Quellcode wird jedoch gegen Spigot 26.2 kompiliert. Der Deskriptor allein ist keine Liste unterstützter Versionen.
• FreeMinecraftModels und die für die Partie benötigten Modell-/Inhaltspakete
• WorldEdit für die Turm-, Mauer- und Baum-Schematics, die die Weltgenerierung einfügt. Das Plugin ruft die API von WorldEdit direkt auf, der Deskriptor deklariert WorldEdit aber nicht als Abhängigkeit
• Funktionierende native Unterstützung für minecraft:dialog für Auswahl- und Belohnungsbildschirme

Optionale Integrationen:

• LibsDisguises, eine Soft-Dependency für zusätzliche visuelle Darstellung

Was MegaBlock Survivors anlegt

Beim Start initialisiert MegaBlock Survivors diese Pfade unter plugins/MegaBlockSurvivors/ oder verwendet sie:

plugins/MegaBlockSurvivors/config.yml
plugins/MegaBlockSurvivors/translations.yml
plugins/MegaBlockSurvivors/content_packages/
plugins/MegaBlockSurvivors/content_markers/
plugins/MegaBlockSurvivors/imports/
plugins/MegaBlockSurvivors/schematics/
plugins/MegaBlockSurvivors/worlds/
plugins/MegaBlockSurvivors/npcs/
plugins/MegaBlockSurvivors/leaderboard.yml
plugins/MegaBlockSurvivors/meta_progression.yml
plugins/MegaBlockSurvivors/stats-dump.log
plugins/MegaBlockSurvivors/version.txt
plugins/MegaBlockSurvivors/nightbreak-changelogs.yml

nightbreak-changelogs.yml enthält den gemeinsamen Gelesen-Status der Versionshinweise, den /mbschangelog verwendet (siehe Befehle).

Das Plugin lädt außerdem eine vom Operator erstellte Lobby-Welt namens mbs_spawn, wenn deren Ordner vorhanden und die Welt noch nicht geladen ist. Installiere diese Lobby vor dem Pluginstart. Ist sie nicht verfügbar:

• Das Bestenlisten-Hologramm bei (4.5, 67, -14.5) in mbs_spawn wird nicht erzeugt; eine Informationsmeldung wird protokolliert.
• Der Lobby-Teleport beim Beitritt tut nichts. Bei geladener Lobby versucht er, Spieler nach (0.5, 65, 0.5) mit Yaw 180 zu schicken, wenn kein Match-Eintrag vorliegt oder der Name ihrer aktuellen Welt mit megablocksurvivors_ beginnt. Ein aktives Match allein umgeht diese Bedingung nicht.
• Der Match-Abbau verwendet die Position vor dem Match anstelle der Lobby.

Konfiguration

config.yml enthält:

Schlüssel	Typ	Standard	Beschreibung
setupDone	boolean	false	Verfolgt, ob die Erst-Einrichtungs-Anleitung abgeschlossen wurde
preGenerateWorldCache	boolean	false	Generiert die Survivor-Spielwelten bereits beim Start vor. Belasse den Wert auf false, um den Serverstart schlank zu halten; die Welten werden weiterhin bei Bedarf generiert, wenn ein Match sie benötigt
nightbreak.autoDownloadPluginUpdates	boolean	false	Wird nach dem Start von der geshadeten MagmaCore-Bibliothek hinzugefügt. Bei true wird ein verfügbares Plugin-Update wenige Minuten nach dem Start automatisch heruntergeladen. Automatische Plugin-Downloads benötigen ein gültiges Nightbreak-Konto-Token und eine aktive Supporter-Mitgliedschaft
nightbreak.applyPluginUpdatesWithoutRestart	string	never	Wird von MagmaCore hinzugefügt. never wartet auf den nächsten Neustart, when-empty wendet ein heruntergeladenes Update an, sobald das nächste Mal keine Spieler online sind, und immediately wendet es sofort an. Das Anwenden eines Updates lädt MegaBlock Survivors neu und beendet aktive Matches. /mbs applypluginupdate wendet ein wartendes Update von Hand an

Wie sich die gemeinsamen Update-Einstellungen in den Nightbreak-Plugins verhalten, steht unter Automatische Updates.

Übersetzungen

Viele Spielnachrichten, Dialoge, Bossleisten und Hologrammtexte verwenden translations.yml. Einige Inhaltspaket-Meldungen, gemeinsame Befehlsbeschreibungen und Ranglistentexte sind weiterhin fest auf Englisch hinterlegt. Unterstützt werden:

• Einfache &-Farbcodes und &#RRGGBB-Hex-Escapes.
• MagmaCore-Gradient-Tags wie <gradient:#FF0000:#00FF00>text</gradient>.
• {placeholder}-Tokens, die zur Laufzeit vom Plugin ersetzt werden.
• Fehlende Schlüssel werden als sichtbare Markierung [translations: key.name] angezeigt, damit nicht gesetzte Einträge im Spiel leicht erkennbar sind.

Die Datei wird beim ersten Start und beim Plugin-Reload mit Standardeinträgen neu erzeugt, sodass neu hinzugefügte Texte automatisch erscheinen.

Persistente Spielerdaten

Datei	Zweck
leaderboard.yml	Bestenlisten-Einträge pro Bucket (6 Sektionen: 2 Spielmodi x 3 Schwierigkeiten), begrenzt auf 100 Einträge pro Bucket.
meta_progression.yml	Soul-Echo-Guthaben und Upgrade-Stufen pro Spieler. Indiziert nach Spieler-UUID.
stats-dump.log	JSON-Lines-Log der beim Match-Abbau angehängten Zusammenfassungen. /mbs dump leert die gemeinsame Datei, bevor nach dem aktuellen oder letzten Match des Aufrufers gesucht wird. Auch ohne verfügbare Zusammenfassung wird das alte Log gelöscht.

Inhaltsordner

Ordner	Zweck
imports/	Ablagebereich für heruntergeladene / manuell platzierte Inhaltsarchive. Wird beim Start und bei /mbs reload vom MagmaCore-Importer verarbeitet.
schematics/	Struktur-Schematics, die von der Weltgenerierung verwendet werden. Die Dateien heißen Level<1-3>_<Name>.schem -- Tower, Wall / Wall1 / Wall2 sowie Tree1..Tree5 (Welt 1 und Welt 3 liefern 4 Baumvarianten, Welt 2 liefert 5). Die Endboss-Arena verwendet keine Schematics.
worlds/	Welt-Ordner, die von Inhaltspaketen installiert werden.
content_packages/	YAML-Definitionen je Paket (siehe unten).
content_markers/	Marker-Dateien, anhand derer erkannt wird, ob ein Paket bereits installiert ist.

Warnung bei Erst-Einrichtung

Solange setupDone false ist, zeigt das Plugin beim Beitritt eine Erst-Einrichtungs-Warnung für Spieler mit der Berechtigung megablocksurvivors.*. Der Hinweis ist (über NightbreakFirstTimeSetupSpec) mit nur einem Setup-Befehl konfiguriert, sodass er Spieler auf /mbs setup (den Content-Browser) verweist und nicht auf einen Initialisierungs-/Download-Schritt. /mbs initialize ist in diesem Build nicht registriert; /mbs downloadall ist registriert, lädt aber nur das Plugin-JAR herunter, da Inhaltspakete deaktiviert sind (siehe Befehle-Seite) -- verwende stattdessen /mbs setup.

Das Öffnen des Inhaltsbrowsers setzt setupDone nicht. Das Menü, das diesen Wert schreibt, ist nur über den nicht registrierten initialize-Handler erreichbar. Setze nach abgeschlossener und überprüfter Einrichtung setupDone: true in config.yml und lade das Plugin neu, um die Erinnerung zu beenden.

Empfohlener Ablauf bei der ersten Einrichtung

Gewöhnliche Gegenstände vor der Partie verstauen und ein separates Minispiel-Inventar verwenden. Die aktuelle Implementierung überschreibt den Brustpanzer und leert beim Beenden das gesamte Inventar, ohne frühere Gegenstände wiederherzustellen. Sie setzt außerdem Attribute, Gesundheit, Hunger und Sättigung zurück und entfernt Trankeffekte.

1. Installiere MegaBlock Survivors und starte den Server einmal. Übersetzungen und Konfigurationsdateien werden beim ersten Start geschrieben.
2. Verknüpfe dein Nightbreak-Konto mit /nightbreaklogin <token>.
3. Öffne mit /mbs setup den Nightbreak-Inhaltsbrowser und installiere die benötigten Pakete. Prüfe, ob FreeMinecraftModels ihre Modelle lädt; der Installationsstatus prüft nur die erfassten Pfade.
4. Führe /mbs reload nach manuellen Importen oder Änderungen an Paketkonfigurationen aus. Dadurch startet MegaBlock Survivors neu und beendet aktive Matches. Werden dabei Modelle importiert und ist FreeMinecraftModels aktiviert, werden auch die FMM-Inhalte neu geladen. Verwende für direkt in den FMM-Ordnern bearbeitete oder dorthin kopierte Dateien den eigenen Reload-Befehl von FMM.

/nightbreaklogin <token> wird vom gemeinsamen Nightbreak/MagmaCore-Konto-Flow bereitgestellt, nicht von der plugin.yml von MegaBlock Survivors.

Inhaltspakete

Inhaltspakete werden über YAML-Dateien im Ordner content_packages/ konfiguriert. Jedes Paket kann definieren:

Feld	Typ	Beschreibung
isEnabled	boolean	Gespeicherte Metadaten. Die aktuelle Installationserkennung prüft, ob die Dateien vorhanden sind, und verwendet diesen Wert nicht zum Ein- oder Ausschalten von Spielinhalten
name	string	Anzeigename des Pakets
description	string list	Beschreibungszeilen
downloadLink	string	Manuelle Download-URL
version	integer	Paket-Versionsnummer
nightbreakSlug	string	Nightbreak-Content-Slug für automatische Downloads
schematicFiles	string list	Im Paket enthaltene Schematic-Dateien
worldFolders	string list	Enthaltene Welt-Ordner
worldContainerFolders	string list	Enthaltene Welt-Container-Ordner
modelFolders	string list	Modell-Ordner für FreeMinecraftModels
markerFileName	string	Marker-Datei, anhand derer erkannt wird, ob das Paket installiert ist
category	enum	FREE, PREMIUM oder RESOURCES
toggleable	boolean	Standard false. Der aktuelle Deinstallationshandler zeigt immer Anweisungen zum manuellen Entfernen an. Dieses Flag bietet keinen funktionierenden Ausschalter

Ein Paket gilt als installiert, wenn mindestens eine Ressource erfasst ist und alle erfassten Ressourcen vorhanden sind. Geprüft werden Pfade, nicht Dateiinhalte oder geladene Modelle. Auch ein Modellordner im Verzeichnis für deaktivierte FreeMinecraftModels-Modelle zählt als vorhanden. Fehlende Teilbestände führen zum Status einer Teilinstallation. Das Anklicken eines installierten, aktuellen Pakets zeigt Anweisungen zur manuellen Bereinigung. isEnabled allein deaktiviert die importierten Spielinhalte nicht.

NPC-Konfiguration

NPCs werden über YAML-Dateien in npcs/ konfiguriert. Registrierte NPCs werden beim erneuten Laden ihres Chunks erzeugt. War ihre Welt bei der Initialisierung nicht verfügbar, lade sie und danach MegaBlock Survivors neu, um die NPCs zu registrieren. Ein Rechtsklick führt den interactionCommand als Spieler mit dessen Berechtigungen aus.

Zwei NPCs werden mit dem Plugin ausgeliefert und automatisch in mbs_spawn gespawnt, sobald diese Welt geladen ist:

NPC	Standard-Position	Disguise	Interaktions-Befehl
Match Starter	mbs_spawn, 0, 67, -15	VILLAGER	mbs start
Meta Progression	mbs_spawn, -9, 66, -13	PIGLIN	mbs meta

Beide lassen sich durch Bearbeiten ihrer YAML in npcs/ und anschließenden Plugin-Reload deaktivieren, verschieben oder mit einer anderen Aktion versehen. Mit LibsDisguises verwendet der NPC einen Villager als Basis-Entity und die konfigurierte Verkleidung. Ohne LibsDisguises versucht das Plugin den konfigurierten Bukkit-Entity-Typ und weicht auf einen Villager aus, wenn dieser Typ keine erzeugbare lebende Entity ist.

NPC-YAML-Felder

Feld	Typ	Beschreibung
isEnabled	boolean	Ob der NPC spawnt
name	string	Interner Name
location	string	Format world,x,y,z oder world,x,y,z,yaw,pitch
disguise	string	LibsDisguises-Entity-Typ (optional)
interactionCommand	string	Befehl, der beim Rechtsklick eines Spielers auf den NPC ausgeführt wird
nameTag	string	Sichtbarer benutzerdefinierter Name der NPC-Entity (Farbcodes erlaubt)

Benachrichtigungen bei Versionsupdates

Ist die aktuelle Version neuer als die in version.txt gespeicherte Version, benachrichtigt das Plugin die Konsole und angemeldete OPs. Ein erster Start ohne gespeicherte Version, eine unveränderte Version oder ein Downgrade löst diesen Upgrade-Hinweis nicht aus.