MegaBlock Survivors Einrichtung

Der Einrichtungsablauf von MegaBlock Survivors basiert auf von Nightbreak verwalteten Inhaltspaketen, mit optionaler Modellunterstützung durch FreeMinecraftModels.

Voraussetzungen

• Java 21
• Ein Paper/Spigot-kompatibler Server auf der API-Linie 1.21.4

Optionale Integrationen:

• FreeMinecraftModels -- benutzerdefinierte Mob- und Waffenmodelle (optionale Abhängigkeit)
• LibsDisguises -- optionale Abhängigkeit für zusätzliche visuelle Unterstützung

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/imports/
plugins/MegaBlockSurvivors/worlds/
plugins/MegaBlockSurvivors/npcs/
plugins/MegaBlockSurvivors/leaderboard.yml
plugins/MegaBlockSurvivors/meta_progression.yml
plugins/MegaBlockSurvivors/stats-dump.log
plugins/MegaBlockSurvivors/version.txt

Außerdem lädt das Plugin automatisch eine vom Operator erstellte Lobby-Welt namens mbs_spawn, sofern deren Ordner auf der Festplatte existiert. Das Plugin erstellt oder verändert diese Welt nicht -- es lädt sie nur. Mehrere Plugin-Funktionen greifen stillschweigend auf das Standardverhalten zurück, falls mbs_spawn fehlt:

• Das Bestenlisten-Hologramm (verankert bei (4.5, 67, -14.5) in mbs_spawn) wird nicht erzeugt und es wird eine Warnung protokolliert.
• Der Beitritts-Teleport (SpawnLobbyListener) schickt beitretende Spieler nach (0.5, 65, 0.5) in mbs_spawn mit Yaw 180 -- übersprungen, wenn der Spieler bereits in einem aktiven Match ist.
• Der Match-Abbau bringt den Spieler nach mbs_spawn zurück, falls vorhanden.

Konfiguration

config.yml enthält:

Schlüssel	Typ	Standard	Beschreibung
setupDone	boolean	false	Verfolgt, ob die Erst-Einrichtungs-Anleitung abgeschlossen wurde

Übersetzungen

Alle für den Spieler sichtbaren Texte (Chat-Zeilen, Dialogtitel, Bossbalken, Hologrammtexte, Befehlsbeschreibungen) werden aus translations.yml geladen. Serverbetreiber können jede Zeile lokalisieren oder umgestalten, ohne das JAR anzufassen. Unterstützt werden u.a.:

• 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	Nur-anfügbares JSON-Lines-Log jedes abgeschlossenen Matches, beim Match-Abbau geschrieben.

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.

Empfohlener Erst-Einrichtungs-Ablauf

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. Führe /mbs setup aus, um den Nightbreak-Content-Browser zu öffnen und die gewünschten Pakete zu installieren / zu aktivieren.
4. Führe /mbs reload aus, wenn du Inhalte manuell in imports/ ablegst oder nachdem du Pakete in content_packages/ umgeschaltet hast.

/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	Ob das Paket aktiv ist
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	Ob das Paket aktiviert/deaktiviert werden kann

NPC-Konfiguration

NPCs (Lobby-Questgeber, Händler) werden über YAML-Dateien in npcs/ konfiguriert. NPCs werden beim Chunk-Laden neu erzeugt, damit sie das Entladen/Neuladen der Lobby-Chunks überleben. Ein Rechtsklick auf einen NPC führt seinen konfigurierten interactionCommand 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 können deaktiviert, verschoben oder umgebunden werden, indem die entsprechende YAML in npcs/ bearbeitet wird. Disguises benötigen LibsDisguises zur Darstellung; ohne dieses spawnt der NPC dennoch als Basis-Entity an der konfigurierten Position.

NPC-YAML-Felder

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

Benachrichtigungen bei Versionsupdates

Wenn das Plugin eine Versionsänderung erkennt (durch Abgleich mit version.txt), benachrichtigt es die Konsole und alle online befindlichen OPs.