NMS NBT Manipulation

目的

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

---

平台需求

• Paper 1.21.11 / 26.2（兩版皆經編譯驗證；版本差異以行尾 // @1.21.11: 標註）
• Paperweight userdev 2.0.0-beta.24+
• Mojang 官方名稱（Minecraft 26.1 起不再混淆）
• Java 21（1.21.11）／25（26.2）

---

產生的代碼

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 存取實體狀態，必須在主執行緒呼叫