安全編輯與中斷復原
NBTExplorerCLI 的核心設計原則是「絕不盲目覆寫存檔」。任何針對世界的修改都遵循 查閱型別 -> 預覽計畫(Preview Plan) -> 確認遊戲關閉 -> 離線套用(Apply) -> 寫後讀回驗證 的安全流程,並在外部狀態目錄自動保留寫前備份與執行日誌(Journal)。
get --typesset / plan / batchapply --world-offlinestatus / recover1. 修改世界前的三項基本原則
Section titled “1. 修改世界前的三項基本原則”- 務必在世界副本上測試:在修改重要存檔前,請先複製一份世界副本(例如
D:\WorldCopy)確認流程。 - 寫入前關閉 Minecraft 與其他工具:執行任何帶有
--apply或apply的指令前,請先關閉 Minecraft 遊戲與其他地圖編輯工具,再傳入--world-offline。 - 狀態與輸出檔放在世界資料夾外:請勿將
--state-root或--output指向世界資料夾內部,建議統一存放在獨立目錄(如D:\Plans)。
2. 指定節點位址與使用明確型別(typed-nbt)
Section titled “2. 指定節點位址與使用明確型別(typed-nbt)”為了防止因猜測型別而破壞 NBT 資料(例如誤把 Byte 或 Short 數值寫成 Int 或字串),set 不接受無型別的純文字,而是要求傳入版本化的 nbtcli.typed-nbt JSON(透過 --value 或 --value-file)。
步驟 A:先用 get --types 取得目前的型別結構
Section titled “步驟 A:先用 get --types 取得目前的型別結構”.\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --types回傳結果中的 data.value 即為標準的 typed-nbt 結構:
{ "schemaFamily": "nbtcli.typed-nbt", "schemaVersion": 1, "data": { "name": "", "root": { "tag": "string", "value": "Original Map Name" } }}選擇節點定位方式
Section titled “選擇節點定位方式”指定要修改的節點時,請擇一使用以下定位旗標:
--pointer:標準 JSON Pointer 語法(以/分隔層級;若欄位名稱本身含~寫為~0,含/寫為~1),例如--pointer /Data/LevelName或--pointer /Data/Player/Inventory/0/id。--segments:最多 256 層的明確 JSON 陣列,適合欄位名稱含有句點或特殊符號時使用:--segments '[{"kind":"key","key":"Data"},{"kind":"key","key":"Custom.Key"}]'
若目標為區塊檔(.mca),請一併加上 --chunk <x,z>(全域區塊座標)。
3. 預覽編輯計畫(不修改世界檔案)
Section titled “3. 預覽編輯計畫(不修改世界檔案)”將準備替換的 typed-nbt 內容存為外部檔案(例如 D:\Plans\new-level-name.json),接著執行不加 --apply 的 set 指令以產生預覽計畫:
New-Item -ItemType Directory -Path 'D:\Plans' -Force | Out-Null$read = .\nbtcli.exe get 'D:\WorldCopy' --path level.dat --pointer /Data/LevelName --types | ConvertFrom-Jsonif (-not $read.success) { throw $read.error.message }$replacement = $read.data.value$replacement.data.root.value = 'Translated Map Name'$replacement | ConvertTo-Json -Depth 50 | Set-Content -Encoding utf8 'D:\Plans\new-level-name.json'
.\nbtcli.exe set 'D:\WorldCopy' ` --path level.dat ` --pointer /Data/LevelName ` --value-file 'D:\Plans\new-level-name.json' ` --output 'D:\Plans\level-name-plan.json'由於沒有加上 --apply,此時 D:\WorldCopy 完全不會被修改,工具只會在 D:\Plans\level-name-plan.json 輸出不可變的修補計畫(nbtcli.patch-plan),並回傳該計畫的 planHash。
[!NOTE] 若需一次預覽多筆修改,可準備一份包含 1 至 100,000 筆操作的
nbtcli.operationsJSON 檔案,交由nbtcli plan 'D:\WorldCopy' --request 'D:\Plans\ops.json' --output 'D:\Plans\batch-plan.json'或nbtcli batch 'D:\Plans\ops.json' --world 'D:\WorldCopy' --output 'D:\Plans\batch-plan.json'產生計畫。
4. 離線套用計畫(apply --world-offline)
Section titled “4. 離線套用計畫(apply --world-offline)”確認計畫內容正確且 Minecraft 已關閉後,執行 apply 並加上 --world-offline:
.\nbtcli.exe apply 'D:\WorldCopy' ` --plan 'D:\Plans\level-name-plan.json' ` --world-offline ` --output 'D:\Plans\level-name-receipt.json'在執行 apply 時,寫入引擎會依序完成四道安全保護:
- 前置雜湊核對:檢查目標檔案是否仍與建立計畫時的 SHA-256 雜湊完全一致。若期間檔案曾被其他程式改動,會直接以退出碼
3(Conflict)拒絕寫入,不破壞現有檔案。 - 寫前備份與暫存準備:將原始檔案備份至外部
objects/儲存庫,並在暫存檔完成新內容的驗證。 - 寫入日誌與原子替換:在外部
journals/記錄執行狀態後,才替換世界內的目標檔案。 - 寫後讀回校驗(Readback):重新讀取寫入後的檔案,確認雜湊值與計畫預期結果完全吻合,最後標記回執完成(
"receiptIsTerminal": true)。
認識回執中的九種操作結果狀態
Section titled “認識回執中的九種操作結果狀態”每份寫入回執(nbtcli.apply-receipt)都會將所有操作明確歸類為以下九種統計欄位之一:
| 狀態欄位 | 白話說明 |
|---|---|
applied |
修改已成功寫入世界並通過讀回校驗。 |
unchanged |
目標節點原本就已經是指定的值,經核對無需實際重寫檔案。 |
skipped |
在正式寫入前的驗證階段即被拒絕,未修改任何世界檔案。 |
failed |
操作在準備或執行階段發生錯誤。 |
conflict |
目標檔案自建立計畫後曾被外部修改,或存在衝突的操作。 |
unsupported |
目標格式或結構不支援此寫入操作。 |
cancelled |
操作被記錄為取消狀態(退出碼 130)。 |
recoveryRequired |
寫入途中發生中斷或 I/O 錯誤,需執行 status 與 recover(退出碼 7)。 |
rolledBack |
已透過復原機制安全退回修改前的原始狀態(退出碼 8)。 |
5. 寫入中斷後如何判斷與恢復(status 與 recover)
Section titled “5. 寫入中斷後如何判斷與恢復(status 與 recover)”若 CLI 回傳退出碼 7(RECOVERY_REQUIRED),請保持遊戲關閉,先查詢日誌再重試。程序遭強制結束時可能沒有回應。兩種情況都應使用預先保存的計畫雜湊及同一個 state root。已在 Windows NTFS 驗證程序終止後的復原,斷電後的復原尚待驗證。
以下為簡化的復原回應範例。
{ "schemaFamily": "nbtcli.cli", "schemaVersion": 1, "success": false, "command": "apply", "outcome": "RecoveryRequired", "data": { "planHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "recovery": { "world": "D:\\WorldCopy", "stateRoot": "C:\\Users\\Player\\AppData\\Local\\nbtcli\\worlds\\4a8b9c..." } }, "error": { "code": "RECOVERY_REQUIRED", "message": "World write requires recovery before further use." }}第一步:切勿在遊戲中開啟該世界
Section titled “第一步:切勿在遊戲中開啟該世界”在完成復原之前,請不要用 Minecraft 開啟該存檔,以免遊戲改寫區塊時間戳記而影響復原比對。
第二步:使用 status 查詢日誌狀態
Section titled “第二步:使用 status 查詢日誌狀態”帶入同一個世界路徑、同一個 --plan-hash(若有自訂 --state-root 也請一併帶入)執行唯讀查詢:
.\nbtcli.exe status 'D:\WorldCopy' ` --plan-hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08一併核對退出碼、日誌階段、回執和 repair 指引。journalMayBeAbsent: true 表示 CLI 無法確認日誌,receiptIsTerminal: false 表示結果仍未確定。請保持遊戲關閉,保留原計畫、備份與 state root。日誌遺失或無法讀取時,請先查明原因。確認原日誌與計畫身分後,再執行 recover。
第三步:執行 recover(繼續完成寫入,或完整退回原狀)
Section titled “第三步:執行 recover(繼續完成寫入,或完整退回原狀)”您可以根據需求選擇以下兩種復原方式之一:
-
繼續完成原本的修改計畫:
終端機視窗 .\nbtcli.exe recover 'D:\WorldCopy' `--plan-hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 `--world-offline -
放棄修改並退回修改前的原始存檔(
--rollback):終端機視窗 .\nbtcli.exe recover 'D:\WorldCopy' `--plan-hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 `--rollback `--world-offline
當執行 --rollback 成功將世界完整還原至修改前的位元組狀態時,CLI 會回傳退出碼 8(RolledBack),讓您或自動化腳本能清楚確認存檔已安全退回原狀。