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`	由 shade 進插件的 MagmaCore 函式庫在啟動後加入。設為 `true` 時，可用的插件更新會在啟動幾分鐘後自動下載。自動下載插件需要有效的 Nightbreak 帳號 token 與有效的贊助者會員資格
`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 種遊戲模式 x 3 種難度），每個分組上限 100 筆。
`meta_progression.yml`	每位玩家的 Soul Echo 餘額與升級分支等級。以玩家 UUID 作為索引。
`stats-dump.log`	比賽摘要的 JSON-lines 紀錄檔，於比賽清理時追加寫入。`/mbs dump` 會先清空共用檔案，再查找呼叫者目前或最近一場比賽；即使沒有摘要，舊紀錄仍會被清除。

內容資料夾

資料夾	用途
`imports/`	已下載／手動放置的內容壓縮檔的投放區。由 MagmaCore 匯入器在啟動時以及 `/mbs reload` 時處理。
`schematics/`	世界生成所使用的建築 schematic。檔案命名為 `Level<1-3>_<Name>.schem` -- 包含 `Tower`、`Wall` / `Wall1` / `Wall2`，以及 `Tree1`..`Tree5`（第 1 與第 3 世界提供 4 種樹木變體，第 2 世界提供 5 種）。最終首領競技場不使用任何 schematic。
`worlds/`	由內容包安裝的世界資料夾。
`content_packages/`	各內容包的 YAML 定義（見下方）。
`content_markers/`	用以偵測某個內容包是否已安裝的標記檔。

首次安裝警告

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

版本更新通知​

需求