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 會驗證 jar 的名稱和版本是否符合預期。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 或萬用權限的線上玩家會收到標題與聊天通知，告知需要重新啟動。只有當外掛程式註冊了該命令且允許免重啟更新時，通知才會附上 /<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。請參閱 手動匯入與遊戲內管理。