MegaBlock Survivors 安裝設定

MegaBlock Survivors 的安裝流程是以 Nightbreak 管理的內容包為核心構建的，並可選擇透過 FreeMinecraftModels 取得模型支援。

需求

Java 21
採用 1.21.4 API 版本的 Paper/Spigot 相容伺服器

選用整合：

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`	紀錄首次安裝引導是否已完成

翻譯

所有面向使用者的字串（聊天訊息、對話視窗標題、首領血條、全像投影文字、指令描述）都會從 translations.yml 載入。伺服器管理員無需動到 jar 檔即可在地化或重新美化每一行。支援的功能包括：

以 & 為前綴的色碼以及 &#RRGGBB 十六進位跳脫色碼。
MagmaCore 漸層標籤，例如 <gradient:#FF0000:#00FF00>text</gradient>。
{placeholder} 替換符號，插件會在執行時替換為實際內容。
缺少的鍵會顯示為可見的 [translations: key.name] 標記，方便在遊戲中找出未設定的條目。

該檔案在首次執行時與插件重新載入時會以預設值重新產生，因此新增的字串會自動出現。

持久化玩家資料

檔案	用途
`leaderboard.yml`	各分組的排行榜條目（6 個區段：2 種遊戲模式 x 3 種難度），每個分組上限 100 筆。
`meta_progression.yml`	每位玩家的 Soul Echo 餘額與升級分支等級。以玩家 UUID 作為索引。
`stats-dump.log`	每場結束時寫入的僅追加 JSON-lines 紀錄檔，於比賽拆除時寫入。

首次安裝警告

當 setupDone 為 false 時，具備 megablocksurvivors.* 權限的玩家加入伺服器時，插件會顯示首次安裝警告。該警告器（透過 NightbreakFirstTimeSetupSpec）僅設定了一個安裝指令，因此會把玩家導向 /mbs setup（內容瀏覽器），而不是初始化/下載步驟。/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`

兩者皆可透過編輯 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 欄位​

版本更新通知​

需求