Nightbreak Setup and Content Management

This page is the shared setup guide for the Nightbreak-managed plugins.

It applies directly to:

• EliteMobs
• BetterStructures
• FreeMinecraftModels
• EternalTD
• ResurrectionChest
• WorldCannon

These plugins now share the same overall lifecycle:

1. Install the plugin and any hard dependencies.
2. Start the server once so files and menus are generated.
3. Run the plugin's first-time setup command if it has one.
4. Link the server to your Nightbreak account with /nightbreaklogin, then approve it at the link it prints.
5. Use the plugin setup menu to browse, install, enable, disable, and update content.
6. Use the plugin bulk download/update commands when you want a faster initial bootstrap.

What MagmaCore Actually Shares

MagmaCore is the shared layer behind the Nightbreak-managed flow. It provides:

• the shared /nightbreaklogin command, which links the server from a browser or saves a token you paste (permission nightbreak.login, defaults to OP)
• the shared /nightbreaklogout command for disconnecting the server from its Nightbreak account (permission nightbreak.login, defaults to OP)
• the shared /logify command for uploading the current server log to mclo.gs (permission logify.*, defaults to OP). It uploads logs/latest.log, or the newest .log file if that is missing, masks the digits of IPv4 addresses and ports first, and replies with a clickable link
• the shared /nightbreak plugins command for browsing the Nightbreak plugin catalog (permission nightbreak.plugins, defaults to OP)
• the shared token storage in plugins/MagmaCore/nightbreak.yml
• shared setup-menu primitives used by plugin setup menus
• shared Nightbreak access, version, and download checks
• shared bulk-download logic that downloads files into the owning plugin's imports folder
• the shared changelog inbox that tells admins in game when a plugin or an installed content package has unread release notes (see Nightbreak changelog notifications)
• restart-free plugin updates through applypluginupdate and the nightbreak.applyPluginUpdatesWithoutRestart setting (see below)
• the standard subcommand set that every Nightbreak-managed plugin registers under its own root command (see below)

/nightbreaklogin, /nightbreaklogout, /logify, and /nightbreak are registered once per server by whichever Nightbreak-managed plugin loads MagmaCore first, so they are available regardless of which plugin "owns" them at runtime.

Shared Standard Subcommands

The subcommands below are not written by each plugin. MagmaCore registers the same implementations under whatever root command the plugin declares (/em, /bs, /fmm, /etd, …), which is why they behave identically everywhere.

Subcommand	What it does	Permission
setup	Opens the plugin's setup menu. Player-only.	plugin setup permission
initialize	Opens the first-time setup menu for players when the plugin registers that flow. Preset modes are not required; FreeMinecraftModels also registers it. Check each plugin's commands page.	plugin initialize permission
recommendedplugins	Shows recommended companion plugins (menu in-game, chat list from console).	plugin setup permission
downloadpluginupdate	Downloads a plugin update jar only. No content.	plugin admin permission
applypluginupdate	Applies a downloaded plugin update without restarting the server. See Applying Updates Without a Restart.	plugin admin permission
downloadall	Downloads the plugin update and then all available content.	plugin admin permission
downloadallcontent	Downloads all available content, no plugin update. Only registered by plugins that ship content packages.	plugin setup permission
updatecontent (alias updateallcontent)	Downloads updates for already-outdated content only. Only registered by plugins that ship content packages.	plugin setup permission
forcereinstallcontent <package|all>	Re-downloads content through the normal authenticated import and reload path even when the installed version is already current. all covers every package that is downloaded, installed, or outdated; pass a package slug directly if its files are completely missing. Only registered by plugins that ship content packages.	plugin admin permission

The exact permission node behind each column is chosen by the plugin, so check the plugin's own page for its node names. initialize is a first-time guidance flow — it does not replace the setup menu or the content-management commands.

Because downloadall starts with the plugin update, it stops before the content step when the account has no token or the token failed authentication. Fix the token first, then re-run it.

MagmaCore also has a separate plugin-startup initialization system, but that is not the same thing as the player-facing initialize commands documented here.

Automatic Updates

Every Nightbreak-managed plugin writes two shared keys into its own config.yml:

nightbreak:
  autoDownloadPluginUpdates: false
  applyPluginUpdatesWithoutRestart: never

When autoDownloadPluginUpdates is true, that plugin automatically downloads, a few minutes after startup:

• an available plugin update jar, and
• update files for any outdated content packages it manages.

Automatically downloaded content updates are used after the server restarts. A downloaded plugin update also waits for a restart, unless applyPluginUpdatesWithoutRestart applies it sooner (see Applying Updates Without a Restart). Both settings start off, so out of the box you stay on the in-game update button. The Automatic Updates button in the setup menu toolbar switches autoDownloadPluginUpdates on and off. That button and the Plugin Update entry say when a downloaded plugin update applies under the current applyPluginUpdatesWithoutRestart value. ResourcePackManager's say to restart.

ResourcePackManager only writes autoDownloadPluginUpdates, because its plugin updates always need a restart.

In-game plugin-jar downloads, automatic or started from a command or menu, require both a valid account token and an active supporter Patreon membership on the linked Nightbreak account. Without them the download is refused and the plugin tells you why, with a link to the public download page. Before a downloaded jar gets its final name, in the server's update folder or, for a new install, the plugins folder, MagmaCore validates it against the expected plugin name and version. Its SHA-256 checksum is also checked when Nightbreak supplies one. A failed check discards the temporary download instead of installing it.

Separately from the auto-download setting, each plugin quietly re-checks for a newer version roughly once an hour so the setup menu can show an accurate update state. That check never downloads anything on its own. Some plugins also log the latest public version to the console when that result changes, and tell operators who join that their version is outdated, with a download link.

Applying Updates Without a Restart

A downloaded plugin update waits in the server's update folder. Run /<root> applypluginupdate, for example /em applypluginupdate, to swap it into the running server. The command uses the plugin's admin permission and also works from the console.

The swap disables the plugin and every enabled MagmaGuy plugin that depends or soft-depends on it, replaces the jar, then loads and enables them again. Chat lists the plugins that reload with it. If the new jar does not enable, the previous jar is loaded again and the update stays in the update folder for the next restart. Updates waiting there for the other reloaded plugins also stay for the next restart; only the plugin you named changes version.

The command refuses, with a message, when:

• no downloaded update is waiting, or the waiting jar is invalid or not newer than the running version
• a plugin from another author depends or soft-depends on it. Restart the server instead
• another plugin swap is already running
• the plugin always needs a restart. ResourcePackManager refuses because its Geyser extension only loads when Geyser starts

Use this command instead of a third-party plugin reloader. Until the swap or a restart, the server keeps running the old jar.

nightbreak.applyPluginUpdatesWithoutRestart decides what happens right after a plugin update downloads, whether the download came from downloadpluginupdate, downloadall, the setup menu or an automatic download:

Value	Behavior
never	Default. The update waits for the next restart. Online players with the plugin's admin or wildcard permission get a title and a chat notice that a restart is required. The notice names /<root> applypluginupdate only when the plugin registers that command and allows restart-free updates.
when-empty	Applies the update at once if no players are online. Otherwise the plugin checks every 30 seconds and applies it when the server is empty.
immediately	Applies the update as soon as the download finishes.

Any other value behaves as never. When when-empty or immediately meets one of the refusals above, the update waits for the next restart. A swap reloads the plugin, so bosses, arenas and dungeon instances in progress end.

Recommended Server-Owner Flow

1. Install the plugin first

Drop the plugin jar and any required hard dependencies into plugins/, then start the server once.

2. Run the first-time setup flow

If the plugin exposes an initialize command, use it first. The current menus are designed to:

• mark first-time setup as complete
• point you to Nightbreak account linking, or start the link for you
• direct you toward the current setup menu
• clarify when manual imports are still valid

The flow does not require preset modes; FreeMinecraftModels also provides it. Check each plugin's commands page for availability.

3. Link your Nightbreak account

Run:

/nightbreaklogin

Open the link it prints, sign in, and approve the server. The server saves your account token by itself. You can still paste a token from the Nightbreak account page with /nightbreaklogin <token>. See Nightbreak account linking.

The token is shared through MagmaCore, so one linked token can be reused by all compatible MagmaGuy plugins on that server.

4. Use the setup menu for day-to-day content management

The setup menus are the current source of truth for:

• package states
• access states
• installed vs downloaded content
• partially installed content that needs repair
• out-of-date content
• content filters by category

If you have a linked token, the setup menus are the recommended place to install and update content.

5. Use bulk install/update when you want speed

Use the downloadall command when you want to bootstrap a server quickly and the updatecontent command when you want to refresh everything that is outdated.

The shared bulk downloader only attempts Nightbreak-managed packages that have a Nightbreak slug. From those:

• downloadall and downloadallcontent pick packages that are not downloaded yet or are out of date. Nightbreak's authenticated download check decides access, so a package your account cannot access is listed as failed at the end.
• updatecontent first refreshes package versions, then picks only out-of-date packages, skipping any that the access check already marked as locked.

Interactive bulk commands ask the owning plugin to reload after at least one successful download. Automatic startup content downloads deliberately do not reload the plugin; they take effect after the server restarts.

Shared Concepts

Downloaded vs installed

A package can exist locally without being enabled. The exact meaning varies slightly by plugin, but the setup menu state matters more than whether a zip exists in imports.

Bulk downloads also land in the same plugin imports folder used by manual imports before the plugin-specific import/reload step finishes.

Access-aware content

Setup menus can now distinguish between content that:

• is available to your token
• needs to be purchased or unlocked
• is installed
• is only partially installed
• is downloaded but disabled
• is outdated

A plugin can list a package before Nightbreak releases it. Once the plugin has loaded Nightbreak's list of published packages and that package is not on it, clicking the package says it hasn't been released on Nightbreak yet. Access checks and the bulk commands, including forcereinstallcontent, skip it. If Nightbreak still answers a request for it with "not found", the console notes once that the package has not been released instead of logging an API error.

Content updates archive dropped files

When an updated package no longer ships a file that its previous version installed, the import moves that file to plugins/MagmaCore/outdated files/ instead of leaving it loaded. See Files a package update stops shipping.

Manual imports are still valid

Nightbreak-managed plugins still support manual import workflows. Manual import is now the fallback path, not the default path. See Manual imports vs in-game management.

Plugin Catalog and Recommendations

/nightbreak plugins lists MagmaGuy's plugins, as a menu in game and as a chat list from the console. In the menu, clicking an installed plugin opens its setup menu. Clicking a missing plugin downloads its jar straight into the plugins folder under its catalog filename, which needs a linked token and supporter access; the chat message then asks you to restart the server so the new plugin loads. If the plugins folder already holds a jar for that plugin that the server did not load, the download goes to the update folder under that jar's name instead. Without a token or access, the message links the public download page instead.

/<root> recommendedplugins lists the companion plugins for one plugin, each labeled Required, Recommended or Encouraged. MagmaGuy's plugins behave as in /nightbreak plugins. External plugins, such as WorldEdit, WorldGuard, LibsDisguises and PacketEvents, link to their official pages. The setup menu's Recommended Plugins button opens the same list and turns green once every listed plugin is installed.

Plugins That Do Not Use This Flow

Not every plugin in this wiki uses Nightbreak-managed downloadable content.

• BetterFood does not use Nightbreak package management
• ResourcePackManager manages resource packs, not Nightbreak DLC packages

Both of those plugins still register the shared setup shell and the shared plugin-update and changelog commands; what they lack is Nightbreak content packages.

ResurrectionChest and WorldCannon are not exceptions — both declare content packages, both register the shared content subcommands, and both run the shared importer, so they accept hand-placed package zips too. See Manual imports vs in-game management.