MegaBlock Survivors 安装

MegaBlock Survivors 的安装流程围绕 Nightbreak 托管的内容包构建，并可通过 FreeMinecraftModels 获得可选的模型支持。

系统要求

Java 21
兼容 Paper/Spigot、运行在 1.21.4 API 版本上的服务器

可选集成：

FreeMinecraftModels —— 自定义生物与武器模型（软依赖）
LibsDisguises —— 软依赖，提供额外视觉支持

MegaBlock Survivors 创建的内容

启动时，MegaBlock Survivors 会在 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

如果磁盘上存在名为 mbs_spawn 的运维方自建大厅世界文件夹，它还会自动加载该世界。插件不会创建或修改这个世界——只会加载它。若缺失 mbs_spawn，多项插件功能会静默地回退到默认行为：

排行榜全息图（锚定于 mbs_spawn 中的 (4.5, 67, -14.5)）会跳过生成并记录一条警告。
加入服务器时的传送（SpawnLobbyListener）会把加入的玩家送到 mbs_spawn 中的 (0.5, 65, 0.5)，朝向 yaw 180——若玩家正在进行的对局中，则会绕过此逻辑。
对局结束后的拆卸会把玩家送回 mbs_spawn（如果存在）。

配置

config.yml 包含：

键	类型	默认值	描述
`setupDone`	boolean	`false`	记录首次安装引导是否已完成

翻译

所有面向用户的文本（聊天文本、对话框标题、Boss 血条、全息图文本、指令描述）均从 translations.yml 加载。服务器运维方无需修改 jar 即可对每一条文本进行本地化或换皮。支持的功能包括：

使用 & 前缀的颜色代码以及 &#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 行日志，记录每一场已完成的对局，于对局拆卸时写入。

首次安装警告

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

内容包

内容包通过 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	内容包是否可被开关切换

NPC 配置

NPC（例如大厅任务发布者、商人）通过 npcs/ 中的 YAML 文件进行配置。NPC 在区块加载时会被重生，因此能在大厅区块的卸载/重载循环中持续存在。右键点击 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`

任意一个 NPC 都可以通过编辑 npcs/ 中对应的 YAML 来禁用、移动或重新绑定指令。伪装需要 LibsDisguises 才能渲染；若未安装，NPC 仍会以基础实体的形式在配置位置生成。

NPC YAML 字段

字段	类型	描述
`isEnabled`	boolean	NPC 是否生成
`name`	string	内部名称
`location`	string	`world,x,y,z,pitch,yaw` 格式
`disguise`	string	LibsDisguises 实体类型（可选）
`interactionCommand`	string	玩家右键点击 NPC 时执行的指令
`nameTag`	string	NPC 上方的浮空全息图（允许使用颜色代码）

版本更新通知

当插件检测到版本变更（通过比对 version.txt）时，会通知控制台以及所有在线 OP。

系统要求​

MegaBlock Survivors 创建的内容​

配置​

翻译​

持久化玩家数据​

首次安装警告​

推荐的首次安装流程​

内容包​

NPC 配置​

NPC YAML 字段​

版本更新通知​