Nightbreak 设置和内容管理

本页面是 Nightbreak 管理插件的共享设置指南。

它直接适用于：

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

这些插件现在共享相同的整体生命周期：

1. 安装插件和所有必需的硬依赖项。
2. 启动服务器一次，以便生成文件和菜单。
3. 如果插件有首次设置命令，请运行它。
4. 使用 /nightbreaklogin 将服务器关联到您的 Nightbreak 账户，然后在它打印的链接处批准。
5. 使用插件设置菜单浏览、安装、启用、禁用和更新内容。
6. 当您需要更快的初始引导时，使用插件的批量下载/更新命令。

MagmaCore 实际共享的内容

MagmaCore 是 Nightbreak 管理流程背后的共享层。它提供：

• 共享命令 /nightbreaklogin，用于从浏览器关联服务器，或保存您粘贴的令牌（权限 nightbreak.login，默认为 OP）
• 共享命令 /nightbreaklogout，用于断开服务器与其 Nightbreak 账户的关联（权限 nightbreak.login，默认为 OP）
• 共享命令 /logify，用于将当前服务器日志上传到 mclo.gs（权限 logify.*，默认为 OP）。它会上传 logs/latest.log（若该文件不存在，则上传最新的 .log 文件），上传前先屏蔽 IPv4 地址和端口中的数字，并回复一个可点击的链接
• 共享命令 /nightbreak plugins，用于浏览 Nightbreak 插件目录（权限 nightbreak.plugins，默认为 OP）
• plugins/MagmaCore/nightbreak.yml 中的共享令牌存储
• 插件设置菜单使用的共享设置菜单原语
• 共享的 Nightbreak 访问、版本和下载检查
• 将文件下载到所属插件 imports 文件夹的共享批量下载逻辑
• 共享的更新日志收件箱，会在插件或已安装内容包有未读发布说明时于游戏内告知管理员（参见 Nightbreak 更新日志通知）
• 通过 applypluginupdate 和 nightbreak.applyPluginUpdatesWithoutRestart 设置实现的免重启插件更新（参见下文）
• 每个 Nightbreak 管理插件都会在自己的根命令下注册的标准子命令集（见下文）

/nightbreaklogin、/nightbreaklogout、/logify 和 /nightbreak 都由首先加载 MagmaCore 的任一 Nightbreak 管理插件在每个服务器上注册一次，因此无论运行时哪个插件“拥有”它们，这些命令都可用。

共享的标准子命令

下面这些子命令并非由每个插件各自编写。MagmaCore 会把同一套实现注册到插件所声明的任意根命令下（/em、/bs、/fmm、/etd……），这正是它们在各处行为完全一致的原因。

子命令	作用	权限
setup	打开该插件的设置菜单。仅限玩家。	插件的 setup 权限
initialize	当插件注册了首次设置流程时，为玩家打开该菜单。预设模式并非必要条件；FreeMinecraftModels 也注册了此命令。请查看各插件的命令页面。	插件的 initialize 权限
recommendedplugins	显示推荐的配套插件（游戏内为菜单，控制台为聊天列表）。	插件的 setup 权限
downloadpluginupdate	只下载插件更新 jar，不下载内容。	插件的 admin 权限
applypluginupdate	无需重启服务器即可应用已下载的插件更新。参见不重启应用更新。	插件的 admin 权限
downloadall	下载插件更新，然后下载所有可用内容。	插件的 admin 权限
downloadallcontent	下载所有可用内容，不更新插件。只有提供内容包的插件才会注册它。	插件的 setup 权限
updatecontent（别名 updateallcontent）	只下载已过期内容的更新。只有提供内容包的插件才会注册它。	插件的 setup 权限
forcereinstallcontent <package|all>	即使已安装版本已经是最新的，也通过正常的认证导入与重载路径重新下载内容。all 覆盖每一个已下载、已安装或已过期的包；如果某个包的文件完全丢失，可直接传入它的包 slug。只有提供内容包的插件才会注册它。	插件的 admin 权限

每一列背后确切的权限节点由插件自行选择，因此请查阅该插件自己的页面了解其节点名称。initialize 是首次引导流程 —— 它不会替代设置菜单或内容管理命令。

由于 downloadall 是从插件更新开始的，当账户没有令牌或令牌认证失败时，它会在进入内容步骤之前停止。请先修好令牌，然后重新运行它。

MagmaCore 还有一个单独的插件启动初始化系统，但这与此处记录的面向玩家的 initialize 命令不同。

自动更新

每个由 Nightbreak 管理的插件都会在自己的 config.yml 中写入两个共享键：

nightbreak:
  autoDownloadPluginUpdates: false
  applyPluginUpdatesWithoutRestart: never

当 autoDownloadPluginUpdates 为 true 时，该插件会在启动几分钟后自动下载：

• 可用的插件更新 jar，以及
• 它所管理的任何已过期内容包的更新文件。

自动下载的内容更新会在服务器重启之后才生效。已下载的插件更新同样会等待重启，除非 applyPluginUpdatesWithoutRestart 让它更早应用（参见不重启应用更新）。两项设置默认都是关闭的，因此开箱即用时你仍然使用游戏内的更新按钮。设置菜单工具栏中的 Automatic Updates（自动更新）按钮用于开关 autoDownloadPluginUpdates。该按钮和 Plugin Update（插件更新）条目会根据当前的 applyPluginUpdatesWithoutRestart 值，说明已下载的插件更新何时生效。ResourcePackManager 的则提示重启。

ResourcePackManager 只写入 autoDownloadPluginUpdates，因为它的插件更新始终需要重启。

游戏内下载插件 jar（无论是自动下载，还是通过命令或菜单发起）都需要有效令牌，以及关联 Nightbreak 账户上的有效 Patreon 支持者会员资格。缺少这些条件时，下载会被拒绝，插件会告诉你原因，并附上公开下载页面的链接。已下载的 jar 在获得最终文件名之前（保存在服务器的 update 文件夹中，全新安装时则保存在 plugins 文件夹中），MagmaCore 会验证它的插件名称和版本是否符合预期。Nightbreak 提供 SHA-256 校验和时，还会进行校验和比对。任一检查失败都会丢弃临时下载，不会安装该文件。

与自动下载设置无关，每个插件还会大约每小时静默地重新检查一次是否有更新版本，以便设置菜单能显示准确的更新状态。该检查本身绝不会下载任何东西。当检查结果发生变化时，有些插件还会在控制台记录最新的公开版本，并告知加入服务器的管理员其版本已过时，同时附上下载链接。

不重启应用更新

已下载的插件更新会在服务器的 update 文件夹中等待。运行 /<root> applypluginupdate（例如 /em applypluginupdate）即可将其换入正在运行的服务器。该命令使用插件的 admin 权限，也可以在控制台中执行。

换入过程会禁用该插件以及所有依赖或软依赖它的已启用 MagmaGuy 插件，替换 jar，然后重新加载并启用它们。聊天中会列出随之重载的插件。如果新 jar 无法启用，会重新加载之前的 jar，更新则留在 update 文件夹中，等待下次重启。其他被重载插件在那里等待的更新也会留到下次重启；只有你指定的插件会更换版本。

在以下情况下，该命令会拒绝执行并给出提示：

• 没有等待中的已下载更新，或等待中的 jar 无效或版本不比正在运行的版本新
• 有其他作者的插件依赖或软依赖它。此时请改为重启服务器
• 另一次插件换入正在进行
• 该插件始终需要重启。ResourcePackManager 会拒绝，因为它的 Geyser 扩展只在 Geyser 启动时加载

请使用此命令，而不是第三方插件重载工具。在换入或重启之前，服务器会继续运行旧的 jar。

nightbreak.applyPluginUpdatesWithoutRestart 决定插件更新下载完成后立即发生什么，无论下载来自 downloadpluginupdate、downloadall、设置菜单还是自动下载：

值	行为
never	默认值。更新会等待下次重启。拥有该插件 admin 权限或通配符权限的在线玩家会收到一条标题和一条聊天通知，提示需要重启。只有当插件注册了 applypluginupdate 命令并允许免重启更新时，通知中才会写出 /<root> applypluginupdate。
when-empty	如果没有玩家在线，立即应用更新。否则插件每 30 秒检查一次，并在服务器无人时应用。
immediately	下载完成后立即应用更新。

其他任何值都按 never 处理。当 when-empty 或 immediately 遇到上述任一拒绝情况时，更新会等待下次重启。换入会重载插件，因此正在进行的 Boss 战、竞技场和地牢实例都会结束。

服务器所有者推荐流程

1. 首先安装插件

将插件 jar 文件和所有必需的硬依赖项放入 plugins/，然后启动服务器一次。

2. 运行首次设置流程

如果插件提供 initialize 命令，请先使用它。当前菜单的设计目的是：

• 将首次设置标记为已完成
• 引导您进行 Nightbreak 账户关联，或为您发起关联
• 引导您进入当前的设置菜单
• 说明何时手动导入仍然有效

此流程不要求预设模式，FreeMinecraftModels 也提供它。请查看各插件的命令页面，确认是否可用。

3. 关联您的 Nightbreak 账户

运行：

/nightbreaklogin

打开它打印的链接，登录并批准该服务器。服务器会自行保存您的账户令牌。您仍然可以通过 /nightbreaklogin <token> 粘贴从 Nightbreak 账户页面获取的令牌。参见 Nightbreak 账户关联。

令牌通过 MagmaCore 共享，因此一个已关联的令牌可以被该服务器上所有兼容的 MagmaGuy 插件重复使用。

4. 使用设置菜单进行日常内容管理

设置菜单是以下内容的当前权威来源：

• 包状态
• 访问状态
• 已安装与已下载的内容
• 需要修复的部分安装内容
• 过时的内容
• 按类别筛选的内容

如果您有已关联的令牌，设置菜单是安装和更新内容的推荐位置。

5. 需要速度时使用批量安装/更新

当您想快速搭建服务器时使用 downloadall 命令，当您想刷新所有过时内容时使用 updatecontent 命令。

共享批量下载器只会尝试具有 Nightbreak slug 的 Nightbreak 管理包。在这些包中：

• downloadall 和 downloadallcontent 会选择尚未下载或已过时的包。访问权限由 Nightbreak 的认证下载检查决定，因此你的账户无法访问的包会在最后被列为失败。
• updatecontent 会先刷新包版本，然后只选择已过时的包，并跳过访问检查已标记为锁定的包。

交互式批量命令在至少一次下载成功之后，会要求所属插件重新加载。启动时的自动内容下载则刻意不重新加载插件；它们会在服务器重启之后生效。

共享概念

已下载与已安装

一个包可以在本地存在但未启用。确切含义因插件而略有不同，但设置菜单状态比 imports 中是否存在 zip 文件更重要。

批量下载也会进入与手动导入使用的相同插件 imports 文件夹，在插件特定的导入/重载步骤完成之前。

访问感知内容

设置菜单现在可以区分以下内容：

• 对您的令牌可用
• 需要购买或解锁
• 已安装
• 仅部分安装
• 已下载但已禁用
• 已过时

插件可以在 Nightbreak 发布某个包之前就把它列出来。一旦插件已加载 Nightbreak 的已发布包列表，而该包不在其中，点击该包会提示它尚未在 Nightbreak 上发布。访问检查和批量命令（包括 forcereinstallcontent）会跳过它。如果 Nightbreak 对该包的请求仍然回答“not found”，控制台只会提示一次该包尚未发布，而不会记录 API 错误。

内容更新会归档被丢弃的文件

当更新后的包不再附带其上一版本安装的某个文件时，导入会把该文件移到 plugins/MagmaCore/outdated files/，而不是让它继续被加载。参见更新后的包不再附带的文件。

手动导入仍然有效

Nightbreak 管理的插件仍然支持手动导入工作流。手动导入现在是备用路径，而非默认路径。请参阅手动导入与游戏内管理。

插件目录与推荐

/nightbreak plugins 会列出 MagmaGuy 的插件，在游戏内显示为菜单，在控制台中显示为聊天列表。在菜单中，点击已安装的插件会打开其设置菜单。点击未安装的插件会把它的 jar 以目录中的文件名直接下载到 plugins 文件夹中，这需要已关联的令牌和支持者权限；随后聊天消息会提示你重启服务器，以加载新插件。如果 plugins 文件夹中已有该插件的 jar，而服务器并未加载它，则下载会改为保存到 update 文件夹中，并沿用那个 jar 的文件名。如果没有令牌或权限，消息会改为提供公开下载页面的链接。

/<root> recommendedplugins 会列出某个插件的配套插件，每个都标注为 Required（必需）、Recommended（推荐）或 Encouraged（建议）。MagmaGuy 的插件的行为与 /nightbreak plugins 中相同。外部插件（例如 WorldEdit、WorldGuard、LibsDisguises 和 PacketEvents）会链接到其官方页面。设置菜单中的 Recommended Plugins（推荐插件）按钮会打开同一列表，并在列出的所有插件都安装后变为绿色。

不使用此流程的插件

并非此 Wiki 中的每个插件都使用 Nightbreak 管理的可下载内容。

• BetterFood 不使用 Nightbreak 包管理
• ResourcePackManager 管理资源包，而非 Nightbreak DLC 包

这两个插件仍然会注册共享的设置外壳，以及共享的插件更新命令和更新日志命令；它们缺少的只是 Nightbreak 内容包。

ResurrectionChest 和 WorldCannon 不是例外 —— 两者都声明了内容包，都注册了共享的内容子命令，也都运行共享导入器，因此它们同样接受手动放置的包 zip。请参阅手动导入与游戏内管理。