MegaBlock Survivors 安装

MegaBlock Survivors使用Nightbreak内容包。敌人和武器直接依赖FreeMinecraftModels的模型类，因此即使描述文件将它列为软依赖，实际比赛仍必须安装它。

系统要求

Java 21
与所用 MegaBlock Survivors 构建兼容的服务器。描述文件声明 API 1.21.4，当前源码却使用 Spigot 26.2 编译依赖；描述文件本身不是支持版本列表。
FreeMinecraftModels及比赛所需的模型与内容包
WorldEdit，用于世界生成时粘贴的塔、墙和树的 schematic。插件直接调用 WorldEdit 的 API，但描述文件并未将其声明为依赖
可正常工作的原生 minecraft:dialog 支持，供选择和奖励界面使用

可选集成：

LibsDisguises —— 软依赖，用于额外的视觉支持

MegaBlock Survivors 创建的内容

启动时，MegaBlock Survivors 会在 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 保存 /mbschangelog 使用的共享版本说明已读状态（参见指令）。

如果磁盘上存在管理员创建的 mbs_spawn 大厅世界文件夹，且该世界尚未加载，插件会加载它。请在启动插件前安装大厅。大厅不可用时：

位于 mbs_spawn 的 (4.5, 67, -14.5) 的排行榜全息图跳过生成，并记录一条信息日志。
加入服务器时的大厅传送不执行操作。大厅已加载时，如果玩家没有对局记录或当前世界名以 megablocksurvivors_ 开头，就尝试将其传送到 (0.5, 65, 0.5)、yaw 180。仅有活动对局记录不能绕过这个条件。
对局结束清理时，使用玩家对局前的位置代替大厅。

配置

config.yml 包含：

键	类型	默认值	描述
`setupDone`	boolean	`false`	记录首次安装引导是否已完成
`preGenerateWorldCache`	boolean	`false`	在启动期间预生成幸存者玩法世界。保持为 `false` 可让服务器启动更轻量；当某局对战需要时，世界仍会按需生成
`nightbreak.autoDownloadPluginUpdates`	boolean	`false`	由着色进插件的 MagmaCore 库在启动后添加。为 `true` 时，可用的插件更新会在启动数分钟后自动下载。自动下载插件需要有效的 Nightbreak 账户令牌和有效的支持者会员资格
`nightbreak.applyPluginUpdatesWithoutRestart`	string	`never`	由 MagmaCore 添加。`never` 等待下次重启，`when-empty` 在下一次没有玩家在线时应用已下载的更新，`immediately` 则立即应用。应用更新会重新加载 MegaBlock Survivors 并结束活动对局。`/mbs applypluginupdate` 可手动应用等待中的更新

共享更新设置在各 Nightbreak 插件中的行为，请参阅自动更新。

翻译

许多游戏文本使用translations.yml。部分内容包消息、共享命令描述和排行榜文本仍直接写死为英文。

使用 & 前缀的颜色代码以及 &#RRGGBB 十六进制转义。
MagmaCore 渐变标签，例如 <gradient:#FF0000:#00FF00>text</gradient>。
由插件在运行时替换的 {placeholder} 占位符。
未设置的键会渲染为可见的 [translations: key.name] 标记，便于在游戏中快速发现遗漏条目。

该文件在首次运行和插件重载时会以默认条目重新生成，因此新增的字符串会自动出现。

持久化玩家数据

文件	用途
`leaderboard.yml`	各分桶排行榜条目（共 6 个分区：2 种游戏模式 × 3 种难度），每个分桶最多 100 条。
`meta_progression.yml`	每位玩家的灵魂回响余额与升级路线等级。以玩家 UUID 作为键。
`stats-dump.log`	对局结束清理时追加摘要的 JSON 行日志。`/mbs dump` 会先清空共享文件，再查找执行者当前或最近一场对局。即使没有摘要，旧日志也会被清除。

内容文件夹

文件夹	用途
`imports/`	下载或手动放置的内容归档的投放区。由 MagmaCore 导入器在启动时以及执行 `/mbs reload` 时处理。
`schematics/`	世界生成所使用的结构原理图。文件命名为 `Level<1-3>_<Name>.schem` —— 包括 `Tower`、`Wall` / `Wall1` / `Wall2`，以及 `Tree1`..`Tree5`（世界 1 和世界 3 提供 4 种树木变体，世界 2 提供 5 种）。最终 Boss 竞技场不使用任何原理图。
`worlds/`	由内容包安装的世界文件夹。
`content_packages/`	每个内容包的 YAML 定义（见下文）。
`content_markers/`	用于检测某个内容包是否已安装的标记文件。

首次安装警告

当 setupDone 为 false 时，拥有 megablocksurvivors.* 权限的玩家加入服务器时会看到首次安装警告。该提示器（通过 NightbreakFirstTimeSetupSpec 配置）仅配有一个安装指令，因此它会把玩家指向 /mbs setup（内容浏览器），而非某个 initialize/download 步骤。本构建未注册 /mbs initialize；/mbs downloadall 已注册，但由于内容包被禁用，它只会拉取插件 jar（详见「指令」页）——请改用 /mbs setup。

打开内容浏览器不会设置 setupDone。写入该标记的菜单只能通过未注册的 initialize 处理器打开。完成并检查安装后，在 config.yml 中设置 setupDone: true 并重载插件，即可停止提醒。

内容包

内容包通过 content_packages/ 文件夹中的 YAML 文件进行配置。每个内容包可以定义：

字段	类型	描述
`isEnabled`	boolean	保存的元数据；当前安装检测依据资源路径是否存在，不将此字段用作玩法开关
`name`	string	内容包显示名称
`description`	string list	描述行
`downloadLink`	string	手动下载 URL
`version`	integer	内容包版本号
`nightbreakSlug`	string	用于自动下载的 Nightbreak 内容 slug
`schematicFiles`	string list	内容包内包含的 schematic 文件
`worldFolders`	string list	包含的世界文件夹
`worldContainerFolders`	string list	包含的世界容器文件夹
`modelFolders`	string list	用于 FreeMinecraftModels 的模型文件夹
`markerFileName`	string	用于检测内容包是否安装的标记文件
`category`	enum	`FREE`、`PREMIUM` 或 `RESOURCES`
`toggleable`	boolean	默认 `false`。当前卸载处理器始终给出手动删除说明，此字段不提供可用的关闭开关

内容包必须登记至少一项资源，且全部资源都存在，才算已安装。这只检查路径，不检查文件内容或模型是否就绪；FreeMinecraftModels 已禁用模型目录中的文件夹也算存在。缺少部分资源时显示部分安装状态。点击已安装且为最新版本的包会显示手动清理说明；仅修改 isEnabled 不会禁用已导入的游戏资源。

NPC 配置

NPC 通过 npcs/ 中的 YAML 配置。已登记的 NPC 会在所属区块重新加载时生成。如果初始化时其世界不可用，请先加载世界，再重载 MegaBlock Survivors 来登记 NPC。右键点击会以玩家身份、使用玩家权限运行 interactionCommand。

插件随附两个 NPC，并在 mbs_spawn 世界加载时自动生成：

NPC	默认位置	伪装	交互指令
Match Starter	`mbs_spawn, 0, 67, -15`	VILLAGER	`mbs start`
Meta Progression	`mbs_spawn, -9, 66, -13`	PIGLIN	`mbs meta`

编辑 npcs/ 中对应的 YAML 并重载插件，可以禁用、移动 NPC 或修改交互。安装 LibsDisguises 时，NPC 使用村民作为基础实体并应用配置的伪装；未安装时，插件尝试使用配置的 Bukkit 实体类型，如果不是可生成的生物实体，则改用村民。

NPC YAML 字段

字段	类型	描述
`isEnabled`	boolean	NPC 是否生成
`name`	string	内部名称
`location`	string	`world,x,y,z` 或 `world,x,y,z,yaw,pitch` 格式
`disguise`	string	LibsDisguises 实体类型（可选）
`interactionCommand`	string	玩家右键点击 NPC 时执行的指令
`nameTag`	string	NPC 实体可见的自定义名称（支持颜色代码）

版本更新通知

当前版本比 version.txt 中保存的版本更新时，插件会通知控制台及在线 OP。首次启动且没有保存版本、版本未变或降级，都不会触发这条升级通知。

系统要求​

MegaBlock Survivors 创建的内容​

配置​

翻译​

持久化玩家数据​

内容文件夹​

首次安装警告​

推荐的首次安装流程​

内容包​

NPC 配置​

NPC YAML 字段​

版本更新通知​