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 Paper/Spigot-compatible server on the 1.21.4 API line
• FreeMinecraftModels and the required model/content packages for gameplay

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

It also auto-loads an operator-authored lobby world named mbs_spawn if its folder exists on disk. The plugin does not create or modify this world -- it only loads it. Several plugin features silently fall back to default behaviour if mbs_spawn is missing:

• The leaderboard hologram (anchored at (4.5, 67, -14.5) in mbs_spawn) skips spawning and logs a warning.
• The on-join teleport (SpawnLobbyListener) sends joining players to (0.5, 65, 0.5) in mbs_spawn facing yaw 180 -- bypassed when the player has an active match.
• Post-match teardown returns the player to mbs_spawn if it exists.

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

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 file and writes only the caller's current-or-most-recent run, so the operator can be sure they are reading a fresh result.

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.

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 / enable the packages you want.
4. Run /mbs reload if you drop content into imports/ manually, or after toggling packages in content_packages/.

/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	Whether the package is active
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	Whether the package can be toggled on/off

NPC Configuration

NPCs (lobby quest-givers, shopkeepers) are configured via YAML files in npcs/. NPCs are respawned on chunk load so they survive lobby chunk unload/reload cycles. Right-clicking an NPC runs its configured interactionCommand.

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/. Disguises require LibsDisguises to render; without it the NPC still spawns as a base entity at the configured location.

NPC YAML fields

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

Version Update Notifications

When the plugin detects a version change (by comparing against version.txt), it notifies the console and all online OPs.