NMS NBT Manipulation

目的

透過 NMS CompoundTag 直接讀寫物品、實體、方塊實體的 NBT 資料，繞過 Bukkit PersistentDataContainer API 的限制，實現底層持久化與資料操作。

---

平台需求

• Paper 1.21 – 1.21.3
• Paperweight userdev 1.7.2+
• Mojang mappings（Paper 1.20.5+ 原生支援）
• Java 21

---

產生的代碼

ItemNbtHelper.java

// 讀取字串 NBT
Optional<String> getString(ItemStack item, String key)

// 寫入字串 NBT（回傳不可變副本）
ItemStack setString(ItemStack item, String key, String value)

// 讀取整數 NBT
int getInt(ItemStack item, String key, int def)

// 寫入整數 NBT
ItemStack setInt(ItemStack item, String key, int value)

EntityNbtHelper.java

// 讀取實體完整 CompoundTag
CompoundTag getTag(Entity entity)

// 合併 patch 到實體 NBT
void mergeTag(Entity entity, CompoundTag patch)

---

執行緒安全

• ItemNbtHelper 操作 NMS Copy，可在任意執行緒呼叫
• EntityNbtHelper 存取實體狀態，必須在主執行緒呼叫