MegaBlock Survivors Setup

The MegaBlock Survivors setup flow is built around Nightbreak-managed content packages, with optional model support through FreeMinecraftModels.

Requirements

• Java 21
• A Paper/Spigot-compatible server on the 1.21.4 API line

Optional integrations:

• FreeMinecraftModels -- custom mob and weapon models (soft dependency)
• 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/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

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

Translations

All user-facing strings (chat lines, dialog titles, boss bars, hologram text, command descriptions) are loaded from translations.yml. Server operators can localize or re-skin every line without touching the jar. Supported 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	Append-only JSON-lines log of every completed match, written on match teardown.

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

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.