MegaBlock Survivors Setup

The MegaBlock Survivors setup flow uses Nightbreak-managed content packages. FreeMinecraftModels is required for the mobs and weapons used in matches, despite being declared as a soft dependency in the plugin descriptor.

Requirements

• Java 21
• A server compatible with your MegaBlock Survivors build. The descriptor declares API 1.21.4, while the current source compiles against Spigot 26.2; the descriptor alone is not a supported-version matrix.
• FreeMinecraftModels and the required model/content packages for gameplay
• WorldEdit for the tower, wall and tree schematics that world generation pastes. The plugin calls WorldEdit's API directly, but the descriptor does not declare it as a dependency
• Working native minecraft:dialog support for the selection and reward screens

Optional integrations:

• LibsDisguises -- soft dependency for additional visual support

What MegaBlock Survivors Creates

On startup, MegaBlock Survivors initializes or uses these paths under plugins/MegaBlockSurvivors/:

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 holds the shared release-notes read state used by /mbschangelog (see Commands).

It also loads an operator-authored lobby world named mbs_spawn if its folder exists on disk and the world is not already loaded. Install that lobby before starting the plugin. When the lobby is unavailable:

• The leaderboard hologram (anchored at (4.5, 67, -14.5) in mbs_spawn) skips spawning and logs an informational message.
• The on-join lobby teleport does nothing. When the lobby is loaded, it attempts to send players to (0.5, 65, 0.5), yaw 180, if they have no match record or their current world's name starts with megablocksurvivors_. An active match record alone does not bypass this condition.
• Post-match teardown uses the player's pre-match location instead of the lobby.

Configuration

config.yml contains:

Key	Type	Default	Description
setupDone	boolean	false	Tracks whether the first-time setup guidance has been completed
preGenerateWorldCache	boolean	false	Pre-generates survivor gameplay worlds during startup. Leave false to keep server boot lightweight; worlds still generate on demand when a match needs them
nightbreak.autoDownloadPluginUpdates	boolean	false	Added by the shaded MagmaCore library after startup. When true, an available plugin update downloads automatically a few minutes after startup. Automatic plugin downloads need a valid Nightbreak account token and an active supporter membership
nightbreak.applyPluginUpdatesWithoutRestart	string	never	Added by MagmaCore. never waits for the next restart, when-empty applies a downloaded update the next time no players are online, and immediately applies it right away. Applying an update reloads MegaBlock Survivors and ends active matches. /mbs applypluginupdate applies a waiting update by hand

See Automatic Updates for how the shared update settings behave across Nightbreak plugins.

Translations

Many gameplay messages, dialogs, boss bars, and hologram strings use translations.yml. Some content-package messages, shared command descriptions, and leaderboard text remain hardcoded in English. Supported translation features include:

• Plain &-prefixed color codes and &#RRGGBB hex escapes.
• MagmaCore gradient tags like <gradient:#FF0000:#00FF00>text</gradient>.
• {placeholder} tokens that are substituted by the plugin at runtime.
• Missing keys render as a visible [translations: key.name] marker so unset entries are easy to spot in-game.

The file is regenerated with default entries on first run and on plugin reload, so newly added strings appear automatically.

Persistent Player Data

File	Purpose
leaderboard.yml	Per-bucket leaderboard entries (6 sections: 2 game modes x 3 difficulties), capped at 100 entries per bucket.
meta_progression.yml	Per-player Soul Echo balance and upgrade-track levels. Keyed by player UUID.
stats-dump.log	JSON-lines log of match summaries, appended on match teardown. /mbs dump clears the shared file before looking for the caller's current-or-most-recent run. If no summary exists, the previous log is still cleared.

Content Folders

Folder	Purpose
imports/	Drop zone for downloaded / manually placed content archives. Processed by the MagmaCore importer on startup and on /mbs reload.
schematics/	Structure schematics used by world generation. Files are named Level<1-3>_<Name>.schem -- Tower, Wall / Wall1 / Wall2, and Tree1..Tree5 (World 1 and World 3 ship 4 tree variants, World 2 ships 5). The final-boss arena uses no schematics.
worlds/	World folders installed by content packages.
content_packages/	Per-package YAML definitions (see below).
content_markers/	Marker files used to detect whether a package is already installed.

First-Time Setup Warning

When setupDone is false, the plugin shows a first-time setup warning to players with the megablocksurvivors.* permission when they join. The warner is configured (via NightbreakFirstTimeSetupSpec) with only a setup command, so it points players at /mbs setup (the content browser) and not at an initialize/download step. /mbs initialize is not registered on this build; /mbs downloadall is registered but only fetches the plugin jar since content packages are disabled (see Commands page) -- use /mbs setup instead.

Opening the content browser does not set setupDone. The menu that writes that flag is only reached through the unregistered initialize handler. After completing and checking setup, set setupDone: true in config.yml and reload the plugin to stop the reminder.

Recommended First-Time Flow

Store ordinary items before starting a match, and use a dedicated minigame inventory. The current implementation overwrites chest armor and clears the entire inventory at match teardown without restoring your previous items. It also resets player attributes, health, food and saturation, and removes potion effects.

1. Install MegaBlock Survivors and start the server once. Translations and config files are written on first run.
2. Link your Nightbreak account with /nightbreaklogin <token>.
3. Run /mbs setup to open the Nightbreak content browser and install the required packages. Confirm that FreeMinecraftModels loads their models; the package's installed status only checks tracked paths.
4. Run /mbs reload after manual imports or package-config edits. This restarts MegaBlock Survivors and ends active matches. Importing model assets during this reload triggers FreeMinecraftModels' content reload when FMM is enabled. For files edited or copied directly into FMM's folders, use FMM's own reload command.

/nightbreaklogin <token> is provided by the shared Nightbreak/MagmaCore account flow, not by MegaBlock Survivors' plugin.yml.

Content Packages

Content packages are configured via YAML files in the content_packages/ folder. Each package can define:

Field	Type	Description
isEnabled	boolean	Stored metadata; current installed-state detection uses asset presence and does not enforce this as a gameplay toggle
name	string	Display name of the package
description	string list	Description lines
downloadLink	string	Manual download URL
version	integer	Package version number
nightbreakSlug	string	Nightbreak content slug for automatic downloads
schematicFiles	string list	Schematic files included in the package
worldFolders	string list	World folders included
worldContainerFolders	string list	World container folders included
modelFolders	string list	Model folders for FreeMinecraftModels
markerFileName	string	Marker file for detecting if the package is installed
category	enum	FREE, PREMIUM, or RESOURCES
toggleable	boolean	Defaults to false. The current uninstall handler always gives manual-removal instructions; this flag does not provide a working off toggle

A package counts as installed when it tracks at least one asset and all tracked assets are present. This checks paths, not file contents or model readiness; a model folder in FreeMinecraftModels' disabled-model directory also counts as present. Partial assets produce a partial-install state. Clicking a current installed package gives manual cleanup instructions; changing isEnabled alone does not disable its imported gameplay assets.

NPC Configuration

NPCs are configured via YAML files in npcs/. Registered NPCs are respawned when their chunk reloads. If their world was unavailable during initialization, load it and reload MegaBlock Survivors to register them. Right-clicking an NPC runs its configured interactionCommand as the player, with that player's permissions.

Two NPCs ship with the plugin and auto-spawn in mbs_spawn when that world is loaded:

NPC	Default location	Disguise	Interaction command
Match Starter	mbs_spawn, 0, 67, -15	VILLAGER	mbs start
Meta Progression	mbs_spawn, -9, 66, -13	PIGLIN	mbs meta

Either can be disabled, moved, or rebound by editing the corresponding YAML in npcs/ and reloading the plugin. With LibsDisguises, the NPC uses a villager backing entity and the configured disguise. Without it, the plugin tries the configured Bukkit entity type and falls back to a villager if that type is not a spawnable living entity.

NPC YAML fields

Field	Type	Description
isEnabled	boolean	Whether the NPC spawns
name	string	Internal name
location	string	world,x,y,z or world,x,y,z,yaw,pitch format
disguise	string	LibsDisguises entity type (optional)
interactionCommand	string	Command to run when a player right-clicks the NPC
nameTag	string	Visible custom name on the NPC entity (color codes allowed)

Version Update Notifications

When the current version is newer than the saved version in version.txt, the plugin notifies the console and online OPs. A first startup without a saved version, an unchanged version, or a downgrade does not trigger this upgrade notice.