教學/NBT與JSON

本頁面不適合使用可視化編輯器編輯

本頁含有大量的樣式等技術性內容，可視化編輯器可能無法很好地處理。

本教學主要講述NBT以及JSON的語法和用法。

用途概覽[]

在指令中，NBT可用於（以Java版為例）：

實體資料：如/summon minecraft:creeper ~ ~ ~ {powered:1b}（召喚一隻閃電苦力怕）。
實體選擇器，透過NBT選擇實體：如/kill @e[type=creeper,nbt={powered:1b}]（殺死所有閃電苦力怕）。
方塊資料：例如/setblock ~ ~-1 ~ command_block{Command:"say 1"}。
物品資料：比如/give @s diamond_block{CanPlaceOn:["dirt"]}表示給予玩家一個即使在冒險模式也可以放置在泥土上的鑽石方塊。
世界儲存：用於/data data (get merge modify) storage ...。

JSON可以在指令和資料包中使用。在指令中的使用，如：

直接在指令中使用JSON文字：通常用於/tellraw和/title指令，如/tellraw @s {"text":"点击此处自杀","clickEvent":{"action":"run_command","value":"/kill @s"}}。在上述實例中，紅色文字表示的是JSON。
在指令的NBT中間接使用JSON文字：需要注意NBT中必須變成字串格式。而且，在Java版1.14之前，由於NBT不支持單引號字串，因此一般需要轉義。自Java版1.14之後，NBT字串允許使用單引號，因此通常不再需要轉義，節省了許多代碼。包括：
- 告示牌文字內容：如/setblock ~ ~ ~ minecraft:oak_sign{Text1:'"第一行文本"',Text2:'{"text":"第二行文本，我是红色的！","color":"red"}'}。
- 物品名稱和描述：如/give @s minecraft:diamond_sword{display:{Name:'{"text":"不普通的鑽石劍","color":"dark_red","italic":false}'}}
- 完成的書的內容。

JSON在資料包和資源包中也十分普遍。語言檔案（例如zh_cn.json）、方塊和物品的模型、進度、配方、戰利品表、標籤、自訂維度等等都是由JSON檔案定義的。

下面將會詳細介紹NBT和JSON的資料結構和語法。

NBT的語法[]

NBT本質上是按照一定的結構儲存的資料。通常NBT本身是一個複合標籤（compound），它類似於一個Lua的表（table）、JSON的對象（object）或Python的字典（dict）。一個複合標籤有多個標籤（tag，或者稱為字段），每個標籤都包含鍵（key，也成為標籤名稱）和值（value）。

如果你理解表或對象的概念，你應該很快就理解NBT複合標籤的含義，可以跳過這一段。如果不理解，我們可以我們做一個類比，以「石頭」為例，它的名稱是石頭，它的硬度為硬，它的透光性為不透光，其開採工具為鎬；以「玻璃」為例，其名稱是玻璃，硬度為軟，透光性為透光，開採工具為無。這裏的「硬度」「透光性」等，都是鍵；「硬」「不透光」則是其值。因此，我們可以編寫出下面的表格（僅以「石頭」為例）：

「石頭」的資料
鍵	值
名稱	石頭
硬度	硬
透光性	不透光
開採工具	鎬

這個表格的第一列的內容是鍵，第二列是值。我們也可以這樣簡單表示（只是一個類比以便理解）：{名稱:石頭,硬度:硬,透光性:不透光,開採工具:鎬}。不難看出。這裏面的冒號和逗號與我們平時使用的冒號和逗號都有類似的含義。

每一個字段的值除了是一個數值或字串之外，還可以是一個新的複合標籤，或者是另一個列表。後面的內容會詳細提到。

參考下面這些實例，有助於更好地了解NBT的寫法。

簡單的NBT[]

以下面的指令為例：/summon minecraft:zombie ~ ~ ~ {CustomName:'{"text":"快乐的小僵尸"}', CustomNameVisible: 1, IsBaby: 1}

該指令召喚出一隻小殭屍。上面的這個實例中，有三個字段：第一個字段的鍵為CustomName，值為'{"text":"快樂的小殭屍"}'；第二個字段的鍵為CustomNameVisible，值為1。讀者不難看出上面這個實例的第三個字段的鍵和值。

如果讀者會英文，那麼就不難看出，召喚出的這個殭屍的自訂名稱（custom name）為「快樂的小殭屍」，並且自訂名稱可見（custom name visible），而且是個小殭屍（is baby）。

鍵通常只包含英文字母或下劃線，而值可以有多種類型。

值的常見類型[]

下面列舉了可用的值的類型及表示方法：

數字：一般，在數字後面加一個英文字母以表示其值與類型，比如1b就表示布林值的1。數字後面的字母表示其儲存類型，而且可以省略。系統可以自動將其轉化為對應的形式。也就是說，我們完全可以用我們日常生活中習慣的直接表示數字（整數或小數）的方法表示數字，如32、18.32。以下各種具體的數字儲存類型，供有經驗的人參考。
- 字節型（byte）：1個字節，值在[-128,127]（這是數學中區間集合的表示方法，便於讀者理解）之間的整數，用「數字 + b」表示。一般用於表示其某項功能是否開啟，常作為布林值使用，因此其值通常為0b或1b，如上述殭屍的標籤的CustomNameVisible（名稱是否可見），若其值為1b則可以看見其名字，若為0b則表示只有指向它時才能看見它的名字。此外，1b和0b還分別可以用true和false表示。
- 短整型（short）：2個字節，值在[-32768,32767]之間的整數，用「數值 + s」表示。如舊版本的Health（表示生命值），32767s是其最大值。附魔的級別也是短整型，因此，在舊版本中，能透過指令實現的最大的附魔級別是32767級。
- 整型（integer，簡稱int）：4位元組，值在[-2147483648,2147483647]之間的整數，直接用一個數值表示。
- 長整型（long）：8位元組，值在[-9223372036854775808,9223372036854775807]之間的整數，在NBT中極為罕見。它可以用來表示極大的數字。
- 單精度浮點型（float）：32位元單精度浮點數，用「數值 + f」表示。如實體的Health（生命值），就是浮點型。雖然我們在遊戲內看到的實體生命值通常是整數，半個心代表1，事實上，生命值在儲存時，是可以有小數的。座標、實體朝向等，也是浮點型。
- 倍精度浮點型（double）：64位元倍精度浮點數，用「數值 + d」表示。。
字串（string）：和大多數語言的字串一樣，表示文字。用英文雙引號""或單引號''括起來的字元表示，注意必須使用半形雙引號或半形單引號，如"这是一个字符串"和'这是一个字符串'都是有效的。你可以對字串內容進行轉義）。跳脫可以用來表示特殊字元，以及容易被理解為字串邊界的字元，後文會詳細提及。此外，如果字串沒有標點符號（可以含有下劃線_），引號可以省去，如標籤id:"netherite_sword"可以寫成id:netherite_sword，但是id:"minecraft:netherite_sword"不能寫成id:minecraft:netherite_sword，因為冒號:是標點符號。
列表（list）：參見#列表。
複合標籤（compound）：參見#複合標籤。

複合標籤[]

NBT複合標籤（compound）的基本語法是使用花括號括起來，裏面含有零個或更多個字段，每一個字段是「键:值」的格式。多個字段用逗號隔開。其中，鍵通常是字串（其引號通常可以省略），值可以有各種類型，可以是另一個複合標籤。

NBT的複合標籤整個可以看作值。比如，下面例子中的綠色文字就是整個複合標籤，這個複合標籤作為「display」的值。

/give @s minecraft:stick{display:{Name:"\"谎言之杖\""}}（仅限1.13后的版本）
/give @s minecraft:stick{display:{Name:'"谎言之杖"'}}（仅限1.14后的版本）

列表[]

列表（list），或者稱為序列（sequence）、陣列（array），可以包含零個、一個或多個值，它的每一個值對應的鍵都不表示，如：

/summon minecraft:spider ~ ~ ~ {Passengers:[{id:"minecraft:skeleton"}]}

該指令用於召喚蜘蛛騎士，即骷髏騎在蜘蛛身上。這個例子中的綠色文字就是一個列表，它的唯一一個值就是一個組合。

/summon minecraft:zombie ~ ~ ~ {ArmorItems:[{id:"minecraft:diamond_boots",Count:1b},{id:"minecraft:diamond_leggings",Count:1b},{id:"minecraft:diamond_chestplate",Count:1b},{id:"minecraft:diamond_helmet",Count:1b}]}

該指令用於召喚一個穿著全套鑽石盔甲的殭屍。綠色文字表示的列表含有4個值，每一個值都是一個組合。

列表的每項都有它的位置（或者成為鍵），注意這個位置是以0開始計數（就像Python、JavaScript那樣），而非像Lua那樣以1開始計數。例如：

/data get entity @s Inventory[1]

表示取得物品欄的第二個物品的資料，而非第一個。取得物品欄的第一個物品資料，應當使用：

/data get entity @s Inventory[0]

跳脫[]

在NBT中，字串可以跳脫，但是只支持引號和反斜槓的跳脫。比如：

/give @s minecraft:paper{display:{Name:"{\"text\":\"一张空纸\",\"color\":\"red\"}"}}

上面這個例子中，紅色的文字表示了一整個字串，其中綠色的文字表示跳脫的引號。字串的內容將會被解釋成如下內容：

{"text":"一张空纸","color":"red"}

（這是一個原始JSON文字。在NBT中，JSON文字被當做一個字串使用。）

在NBT的字串中，要表示一個雙引號應用\"表示，如果要表示一個反斜槓則應該使用\\。所以，如果在字串中要表示\"，則應該使用\\\"。

與JSON、Python、Lua等大多數程式語言不同，NBT只允許跳脫引號和反斜槓，因此不支持\n、\b、\u00a7等跳脫方式。\後面只有是\或"時才會被跳脫（此時，被跳脫的\和"不能再跳脫其他的字元，也不能夠作為字串的分界線），其他的情況統統不跳脫。

NBT路徑的表示方法[]

/data (get|modify|remove) (block|entity|storage) ... <路徑>中「路徑」就是用於一系列鍵來定位到這個標籤的。

比如，閃電苦力怕擁有{powered:1b}的資料，powered路徑，就是索引到標籤名稱為powered的標籤。例如，/data get entity @e[type=creeper,limit=1] powered即可查詢這隻苦力怕是否為閃電苦力怕。

表示多層複合標籤中的鍵時，使用.（點）隔開。比如，{a:{b:{c:"某某文字"}}}，索引a.b.c就可以得到「"某某文字"」。

表示列表中的特定位置的元素時，使用[n]（n為自然數，表示該列表中的第n+1個值）。

例如，/data get entity @e[type=zombie,limit=1] ArmorItems[0].id表示，取得殭屍的腳上穿的物品的id（可能不存在）。這是因為，殭屍擁有名為ArmorItems的標籤，其值為列表，列表的第一個元素（表示腳上的物品）是一個複合標籤，這個複合標籤的id字段表示該物品的id。在本wiki，我們用樹狀圖表示它的標籤結構，如（部分內容已省略）：

：根標籤。
- ArmorItems：實體的盔甲物品。
  - ：腳上的物品。
    - id：物品的命名空間ID。
    - Count：物品的數量。
    - tag：物品擁有的NBT標籤。
      - Enchantments：物品的附魔。
        ：一個附魔。
        id：附魔的命名空間ID。
        
        lvl：附魔的等級。
  - ：腿上的物品，用法同上。
  - ：身上的物品，用法同上。
  - ：頭上的物品，用法同上。

從上面的列表不難看出，如果要取得殭屍頭顱上的物品有哪些附魔，可以用/data get entity @e[type=zombie,limit=1] ArmorItems[3].tag.Enchantments表示。

又比如，/data get entity @s Inventory[3]表示取得自己的物品欄的第4個物品的資訊。

JSON的語法[]

JSON的語法與NBT比較相似，但有以下區別：

JSON的數字不分為整型等類型，因此不支持1b、2s這樣的表達，直接使用1、2即可。
在JSON中，標籤、標籤名稱、標籤值常稱為域、鍵、值（就像Python的字典和Lua的表一樣）。在JSON中，表示鍵也必須用引號括起來，就像表示字串一樣。
JSON有布林值true與false。
JSON的字串只允許雙引號，單引號字串不接受，支持\n、\u00a7等跳脫，未知的跳脫（如\a）仍將報錯。JSON的字串無論是鍵還是值在任何時候下都不可以省略雙引號（NBT可以）。
JSON的語法很嚴格，比如，對象或列表的最後一項之後不能有逗號。

習慣上，JSON的表達應該經常換行，並且適當縮進（通常將2個或4個空格作為一個縮進），例如以下是一個資料包的pack.mcmeta：

{
  "pack": {
    "pack_format": 1,
    "description": "一个简单的数据包"
  }
}

在/tellraw、/title等指令中的JSON不支持換行（一般情況下，複製一段帶有縮進符號和換行符的文字，然後在遊戲內按Ctrl + V粘貼，換行符和縮進符號會被自動過濾），但是其JSON文字支持用\n跳脫換行。

編造比較複雜的JSON文字時，可以進入bejson.cn等具有解析、糾錯、跳脫、反跳脫、標準格式（更加美觀）、壓縮（去除多餘空格、換行、縮進）等功能的網站，或使用支持類似功能的軟件。

JSON的用途[]

JSON在資料包、資源包和JSON文字中有極大作用。參見教學/製作資源包、教學/製作資料包和教學/JSON文字。

JSON用於基岩版指令[]

此段落需要更新。

理由：部分過時，需要更多的物品組件

在攜帶版1.1.0後（包括）擁有了物品組件。適用於/give和/replaceitem，並且只有2個：can_place_on（該物品可放置在哪些方塊旁）和can_destroy（該物品可以破壞哪些方塊）。它們也只有在無法破壞和放置方塊的冒險模式生效，其語法如下：

{"minecraft:can_place_on":{"blocks":["方块1","方块2"…]}}
{"minecraft:can_destroy":{"blocks":["方块1","方块2"…]}}

注意方塊用英文（如"air"）而並非數字id（如0）。

例如：/give @s minecraft:diamond_pickaxe 1 0 {"minecraft:can_destroy":{"blocks":["stone"]}}可以獲得一個允許冒險模式玩家僅能破壞石頭的鑽石鎬。冒險模式的玩家如果沒有拿著這樣的鎬就無法破壞任何方塊，拿著這把鎬也只能破壞石頭，不能破壞其他方塊。該指令相當於Java版的/give @s minecraft:diamond_pickaxe{CanDestroy:["minecraft:stone"]}。

另一個實例：/give @s minecraft:tnt 1 0 {"minecraft:can_place_on":{"blocks":["sand","tnt"]},"minecraft:can_place_on":{"blocks":["redstone_block"]}}

Minecraft Wiki