📒 NbtCompound - 標籤類型

一個 NbtCompound 代表一個完整的標籤，裡面儲存了一系列鍵值對，類似於對象 / 表這樣的數據結構。
通過 NbtCompound 對象的接口，才可以進行 NBT 標籤所獨有的一些操作。

獲取一個 NBT 標籤對象

從現有的 NBT 對象中解析獲取

詳見 NbtList - 列表類型 和 NbtCompound - 標籤類型 文檔

創建新的 NBT 標籤對象

[JavaScript] new NbtCompound([data])
[Lua] NbtCompound([data])

• 參數：
• data：Object<string, NBT Object>（可選參數）
  傳入一個 NBT 對象構成的對象。對象中允許包含其他數組 / 對象結構， 但內容必須都為 NBT 對象。Null 會被視為 NBT.End
• 返回值：生成的 NBT 對象
• 返回值類型：NbtCompound
• 如果創建失敗，將拋出異常

[JavaScript]

var nbt = new NbtCompound({
        "name1": new NbtInt(3),
        "name2": new NbtString("test"),
        "name3": new NbtList([
            new NbtFloat(4.0),
            new NbtFloat(6.0)
        ]),
        "name4": new NbtLong(66666)
    });

[Lua]

local nbt = NbtCompound({
        "name1" = NbtInt(3),
        "name2" = NbtString("test"),
        "name3" = NbtList({
            NbtFloat(4.0),
            NbtFloat(6.0)
        }),
        "name4" = NbtLong(66666)
    });

從 SNBT 字符串生成 NBT 標籤對象

NBT.parseSNBT(snbt)

• 參數：
• snbt：String
  你要解析的 SNBT 字符串
• 返回值：生成的 NBT 對象
• 返回值類型：NBT Object
• 如返回值為 Null 則表示解析失敗

支持腳本層已暴露的 SNBT 值類型，包括普通值、List 和 Compound

從二進制 NBT 數據生成 NBT 標籤對象

NBT.parseBinaryNBT(nbt)

• 參數：
• nbt：ByteBuffer
  你要解析的二進制 NBT 數據
• 返回值：生成的 NBT 對象
• 返回值類型：NbtCompound
• 如返回值為 Null 則表示解析失敗

二進制 NBT 數據中必須包含一個完整的 Compound

對於某個一個 NbtCompound 類型的對象 comp，有如下這些接口

獲取所有的鍵

comp.getKeys()

• 返回值：Compound 中所有的鍵
• 返回值類型：Array<String,String,...>

獲取鍵對應的值的數據類型

comp.getTypeOf(key)

• 參數：
• key：String
  要查詢的鍵名
• 返回值：對應的值的數據類型
• 返回值類型：Enum
• 如果要讀取的NBT不存在，將返回Null

可能的返回值有：NBT.End NBT.Byte NBT.Short NBT.Int NBT.Long
NBT.Float NBT.Double NBT.ByteArray NBT.String
NBT.List NBT.Compound

設置鍵對應的 NBT 對象

comp.setTag(key,tag)

• 參數：
• key：String
  要操作的鍵名
• tag： NBT Object
  要寫入的 NBT 對象（它承載著具體的 NBT 數據）
  如果鍵已存在，會直接替換原有標籤；如果鍵不存在，則會新建這個鍵值對。 傳入 Null 時會寫入 NBT.End
• 返回值：CompoundTag 自身
• 返回值類型：NbtCompound

讀取鍵對應的 NBT 對象

comp.getTag(key)

• 參數：
• key：String
  要操作的鍵名
• 返回值：鍵對應的 NBT 對象
• 返回值類型： NBT Object
• 如果要讀取的 NBT 不存在，將返回Null

判斷鍵是否存在

comp.hasTag(key)

• 參數：
• key：String 要查詢的鍵名
• 返回值：該鍵是否存在於當前 Compound 中
• 返回值類型：Boolean

刪除鍵對應的 NBT 對象

comp.removeTag(key)

• 參數：
• key：String
  要操作的鍵名。鍵名必須已經存在
• 返回值：處理完畢的 NBT 對象（便於連鎖進行其他操作）
• 返回值類型：NbtCompound

一些協助 NBT 對象操作的方便函數

很明顯，在修改 NBT 的某些值的時候，純粹使用 NBT 對象會顯得麻煩而語法複雜。
因此，這裡還提供了一些簡化對象操作的方便函數，通過直接操作指定位置的數據，而避免通過 NBT 對象中轉，可以一定程度上降低代碼量

設置鍵對應的值的具體數據

comp.setEnd(key)
comp.setByte(key,data)
comp.setShort(key,data)
comp.setInt(key,data)
comp.setLong(key,data)
comp.setFloat(key,data)
comp.setDouble(key,data)
comp.setByteArray(key,data)
comp.setString(key,data)

• 參數：
• key：String
  要操作的鍵名
• data：上述类型
  要寫入的具體數據
  如果鍵不存在，會自動創建對應的鍵值
• 返回值：寫入完畢的 NBT 對象（便於連鎖進行其他操作）
• 返回值類型：NbtCompound

讀取鍵對應的值的具體數據

comp.getData(key)

• 參數：
• key：String
  要操作的鍵名
• 返回值：鍵對應的值的具體數據
• 返回值類型：任意类型，以儲存的數據類型為準
• 如果目標位置儲存的是 List 類型 NBT，將返回一個 NbtList 對象；如果目標位置儲存的是 Compound 類型 NBT，將返回一個 NbtCompound 對象
• 如果要讀取的 NBT 不存在，將返回 Null

將 NBT 標籤對象轉換為 Object

comp.toObject()

• 返回值：對應的對象 / 表
• 返回值類型：Object

將 Compound 的內容轉換為腳本引擎對象，把數據項都轉換為腳本引擎數據類型儲存於對象的對應 key 中，方便讀取和處理
如果 Compound 某一項儲存的是 List 或者 Compound 類型的 NBT，將在對應位置遞歸展開為 Array 或 Object

將 NBT 標籤對象序列化為 SNBT

comp.toSNBT([space[,format]])

• 參數
• space : Integer
  （可選參數）如果要格式化輸出的字符串，則傳入此參數
  代表每個縮進的空格數量，這樣生成的字符串更適合人閱讀
  此參數默認為 -1，即不對輸出字符串進行格式化
• format : Enum （可選參數）SNBT 輸出格式，使用 SnbtFormat 枚舉中的值
• 返回值：對應的 SNBT 字符串
• 返回值類型：String

調用 comp.toSNBT() 時，默認使用 SnbtFormat.ForceQuote。
調用 comp.toSNBT(space) 且 space >= 0 時，默認使用 SnbtFormat.PartialLineFeed。
如果需要顯式指定其他 SNBT 格式，請使用 comp.toSNBT(space, format)。

除了普通的二進制 NBT 之外，另一種玩家更熟悉的 NBT 是純文本形式的，通常在命令裡使用。這種格式常被稱為SNBT（字符串化的二進制命名標籤，Stringified NBT）

--- Minecraft Wiki

將 NBT 標籤對象 序列化為二進制 NBT

comp.toBinaryNBT()

• 返回值：對應的二進制 NBT 數據
• 返回值類型：ByteBuffer

只有完整的頂層Compound標籤可以被轉換為二進制 NBT

銷燬此 NBT 標籤對象

comp.destroy()

• 返回值：是否成功清理
• 返回值類型：Boolean

注意，只有根 Compound 標籤可以被銷燬，而且，請謹慎使用此函數，不當的使用將會造成服務器崩潰
合適的銷燬有助於解決內存佔用問題。在銷燬完後，請千萬不要再使用此 NBT 對象和他的所有子對象