文檔總覽與核心概念
NBTExplorerCLI(執行檔 nbtcli.exe,版本 1.0.0)是專為 Minecraft Java Edition 設計的 Windows x64 獨立封裝命令列工具。無論您是一般玩家、冒險地圖創作者、翻譯團隊或自動化工具開發者,都能透過它查閱 NBT 資料結構、掃描並分頁翻譯世界文字、產生資源包,以及在具備寫前備份與中斷復原保護的機制下安全編輯世界。
認識三種操作風險分級
Section titled “認識三種操作風險分級”為了讓所有使用者都能直觀判斷每個指令是否會影響存檔,本站所有教學與命令參考皆標示以下三種清楚的風險標籤:
| 風險標籤 | 對 Minecraft 世界存檔的影響說明 |
|---|---|
| 安全查閱:不改存檔 | 僅讀取檔案或查閱外部日誌。您的 Minecraft 世界資料夾完全不會被修改。 |
| 預覽模式:僅產出計畫 | 在世界資料夾「外部」建立變更計畫檔(nbtcli.patch-plan)或儲存翻譯工作階段進度,世界存檔本身維持原狀。 |
| 修改存檔:請先關遊戲並備份 | 會實際將變更寫入指定的世界資料夾。請務必先建立世界副本、關閉 Minecraft 與其他編輯器,並加上 --world-offline 執行。 |
六大核心工作流程
Section titled “六大核心工作流程”建議依序閱讀以下指南,完成從首次查閱、安全編輯到地圖翻譯與資源包輸出的完整流程:
- 安裝驗證與安全查閱
核對發行包 ZIP 的 SHA-256 雜湊值、完整解壓縮、執行
--version與--help,並在世界副本上執行第一次唯讀get、list、search與scan。 - 安全編輯與中斷復原
學習如何用 JSON Pointer 或結構化區段(Segments)指定節點、用
set/batch/plan預覽、用apply --world-offline離線寫入,以及在程序中斷後用status與recover查詢及復原。 - 地圖翻譯工作流
建立分頁式翻譯工作階段(
translate start)、匯出待譯分頁(export)、提交經驗證的譯文回覆(submit/advance)、管理術語表與備註,最後透過plan、apply與seal完成翻譯封存。 - 資源包、語言檔與引用
區分「直接替換世界文字(
--direct)」、「轉換為翻譯鍵並附加語言檔(--keys與convert)」以及「不更動世界 NBT 的獨立語言檔/資源包輸出(export-lang、create-pack)」,並了解實體名稱引用同步(--synchronize-references)的限制。 - 備份與狀態檔管理
建立與驗證世界備份(
backup與restore),並了解外部狀態目錄(--state-root)中的掃描快取、工作階段、內容定址備份庫(objects)與復原日誌(journals)如何運作。 - 支援範圍與疑難排解
查閱支援的 Minecraft Java 版
DataVersion、退出碼(0至8及130)對照表、區分「CLI 解析驗證」與「尚待實機驗證」的邊界,以及常見錯誤的排解步驟。
若想直接查閱特定指令與旗標,請前往 CLI 命令完整參考。
統一的單行 JSON 輸出格式
Section titled “統一的單行 JSON 輸出格式”每次執行 nbtcli.exe,標準輸出(stdout)都會固定回傳單行 UTF-8 JSON 信封結構:
{ "schemaFamily": "nbtcli.cli", "schemaVersion": 1, "success": true, "command": "version", "outcome": "Success", "data": { "product": "nbtcli", "version": "1.0.0" }, "error": null}介面語言與地圖翻譯語言的區別
Section titled “介面語言與地圖翻譯語言的區別”NBTExplorerCLI 嚴格區分「工具本身的提示訊息語言」與「地圖內容的翻譯語言」:
- 工具介面語言(
--ui-locale):可於任何指令前後加上--ui-locale zh-TW(預設)或en-US,僅改變錯誤訊息與說明文字的顯示語言,不會影響 JSON 欄位名稱、錯誤代碼或世界資料。 - 地圖與資源包語言:包含
--source-language、--target-language、--lang、--original-lang與--target-lang,專門用於指定 Minecraft 內容的來源與目標語言代碼(如en_us、zh_tw)。
授權與第三方聲明
Section titled “授權與第三方聲明”本專案採用 MIT 授權條款(詳見倉庫與發行包根目錄之 LICENSE)。隨附之第三方元件保留其各自之授權條款與聲明:
- SharpZipLib(
licenses/SharpZipLib.md) - Unicode 字元資料庫(
licenses/Unicode.md) - .NET Runtime 授權與第三方聲明(Windows x64 發行包內之
licenses/dotnet-LICENSE.txt與licenses/dotnet-THIRD-PARTY-NOTICES.txt)
Minecraft 遊戲資產與使用者建立之世界存檔,均依其各自所有權人之授權條款處理。