模组插件数据包光影资源包整合包软件汉化地图
设置
NBT-API

NBT-API

在不使用 NMS 的情况下向物品/方块/实体添加自定义 NBT 标签

前置
93912 years ago

基本信息

我的世界Java版本

26.2
26.1.x
1.21.x
1.20.x
1.19.x
1.18.x
1.17.x
1.16.x
1.15.x
1.14.x
1.13.x
1.12.x
1.11.x
1.10.x
1.9.x
1.8.8–1.8.9
1.7.9–1.7.10

平台

Bukkit
Folia
\n \n \n \n \n Paper
\n \n \n \n \n \n \n \n \n \n \n Purpur
Spigot

运行环境

服务端

分类

前置
BBSMC 创作者激励广告

其他链接

反馈问题 查看源码
Modrinth

搬运团队

BBSMC 官方搬运(1)
BBSMC 官方搬运(1)团队

搬运资源声明

对于可进行 JAR 文件搬运的许可证，我们提供站内下载服务；其他资源会跳转到原帖下载。资源更新可能不及时，建议前往资源内提供的原帖链接下载最新版本。

详情信息

许可证 MIT
发布于 2024-11-29
更新于 2026-07-27
1
2
3

2.16.0

on 2026 Jul 27
下载

更新内容

开发者说明

  • 建议改用新的 NBT.readAndGetChunkPDC / NBT.readChunkPDC 等方法，以替代 NBTChunk / NBTBlock 类。新方法在读取时性能更优，且不会残留空标签。
  • 请注意：1.7.10 版本已不再获得官方支持，包括 Forge 混合版本。请自行承担使用风险；如遇问题，可通过提交 PR 来修复。
  • 在进行 Shade（依赖打包）时，MinecraftVersion 显示为 UNKNOWN 并不意味着 NBTAPI 无法正常工作，仅表示该 Minecraft 版本尚未经过测试。因此，请勿仅因该原因拒绝加载插件。

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.15.7...2.16.0

2.15.7

on 2026 Jul 17
下载

更新内容

  • 将所有 26.1.x 版本均列为受支持版本，前提是 Mojang/Spigot/Paper 在补丁版本中未引入破坏性变更
  • 新增对 Papers 26.1.1+ 版本新编号格式的支持

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.15.6...2.15.7

2.15.6

on 2026 Jul 17
下载

更新内容

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.15.5...2.15.6

2.15.5

on 2026 Jul 17
下载

更新内容

  • 修复了API报告其不支持1.21.11版本的问题

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.15.4...2.15.5

2.15.4

on 2026 Jul 17
下载

更新内容

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.15.3...2.15.4

2.15.3

on 2026 Jul 17
下载

更新内容

完整更新日志: https://github.com/tr7zw/Item-NBT-API/compare/2.15.2...2.15.3

2.15.2

on 2026 Jul 17
下载

更新内容

  • 将 1.21.8 版本标记为兼容（此前本就兼容，此次更新仅移除了日志中的警告）
  • 修复 Spigot 平台下 1.21.5 版本出现的 CODEC 错误
  • 修正 DataFixerUtil 中变量的使用方式，使其基于版本修订号进行处理
  • 将 org.apache.maven.plugins:maven-javadoc-plugin 从 3.11.2 升级至 3.11.3（由 @dependabot[bot] 提交，详见 https://github.com/tr7zw/Item-NBT-API/pull/333）

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.15.1...2.15.2

2.15.1

on 2026 Jul 17
下载

更新内容

新贡献者

完整变更日志：https://github.com/tr7zw/Item-NBT-API/compare/2.15.0...2.15.1

2.15.0

on 2026 Jul 17
下载

更新内容

新贡献者

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.14.1...2.15.0

2.14.1

on 2026 Jul 17
下载

更新内容

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.14.0...2.14.1

2.14.0

on 2026 Jul 17
下载

更新内容

  • 添加对 1.21.3 版本的支持（同时也支持 1.21.2，但不建议使用该版本）
  • 将 NBTFile/NBTContainer 完全隐藏于 NBT 之后（相关方法现已弃用，并指向对应的 NBT 替代方案）
  • 为 ReadWriteNBTCompoundList 补充缺失的 addCompound(ReadableNBT comp) 方法
  • 修复在无数据情况下序列化 Bukkit 物品时的边界情况问题
  • 尝试通过 “Count” 标签自动检测并更新早于 1.20.3 版本的物品 NBT 数据
  • 将 org.apache.maven.plugins:maven-javadoc-plugin 从 3.8.0 升级至 3.10.0（@dependabot，见 https://github.com/tr7zw/Item-NBT-API/pull/297）
  • 将 org.apache.maven.plugins:maven-javadoc-plugin 从 3.10.0 升级至 3.10.1（@dependabot，见 https://github.com/tr7zw/Item-NBT-API/pull/300）

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.13.2...2.14.0

2.13.2

on 2026 Jul 17
下载

更新内容

完整更新日志: https://github.com/tr7zw/Item-NBT-API/compare/2.13.1...2.13.2

2.13.1

on 2026 Jul 17
下载

更新内容

  • 修复 Paper 1.21 兼容性问题
  • 修复 ReadWriteNBT 中 resolveCompound 方法未返回 ReadWriteNBT 的问题
  • 为 resolveCompound 方法补充缺失的 @Nullable 注解
  • 移除新版中过时且错误的映射关系
  • 代码整体优化与清理
  • 修复数据修复器（datafixer）无法识别 1.21 版本 ID 的问题
  • 由 @SoSeDiK 更新 Wiki 文档：https://github.com/tr7zw/Item-NBT-API/pull/282

若您对如何将代码从 NBTItem 迁移至新方案，或如何使用新版 ItemStack 逻辑兼容 1.20.5+ 版本存在疑问，请查阅已更新的 Wiki！SoSeDiK 对 Wiki 进行了全面修订，新增了大量示例代码。此外，欢迎您将您的插件提交 PR 至 Wiki 中的插件列表。

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.13.0...2.13.1

2.13.0

on 2026 Jul 17
下载

更新内容

  • 升级至 1.21 版本
  • 废弃大量旧方法/构造函数，请迁移至 NBT 类，以使用更快速且抽象化的新替代方案
  • 新增适用于 1.20.5+ 版本的 NBT.modifyComponents API，用于修改原版组件
  • 移除了 nbt-injector（您本就不应使用它）和 nbt-data-api（从未完成），大幅精简了 JAR 文件体积
  • 由 @dependabot 将 org.apache.maven.plugins:maven-javadoc-plugin 从 3.6.3 升级至 3.7.0：https://github.com/tr7zw/Item-NBT-API/pull/279
  • 由 @dependabot 将 org.apache.maven.plugins:maven-shade-plugin 从 3.5.3 升级至 3.6.0：https://github.com/tr7zw/Item-NBT-API/pull/278

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.12.4...2.13.0

2.12.4

on 2026 Jul 17
下载

更新内容

  • 新增对 1.20.5 与 1.20.6 版本的支持
  • 新增 Datafixer 支持，用于将物品 NBT 数据升级至更新的版本
  • 在使用 NBT.itemStackFromNBT 及相关方法时，自动升级旧版 ItemStack：系统默认将传入的 NBT 视为 1.20.4 版本数据；若实际版本不同，请先自行通过 Datafixer 升级 NBT
  • 修复 Mojang 映射服务器上的方块实体（BlockEntity）漏洞
  • 将 org.apache.maven.plugins:maven-source-plugin 从 3.3.0 升级至 3.3.1（@dependabot，见 https://github.com/tr7zw/Item-NBT-API/pull/273）
  • 将 org.apache.maven.plugins:maven-shade-plugin 从 3.5.2 升级至 3.5.3（@dependabot，见 https://github.com/tr7zw/Item-NBT-API/pull/277）

注意事项

由于 Mojang 修改了 ItemStack 在运行时的工作机制，自 1.20.5 起，已加载的 ItemStack 中将不再显示原版 NBT 数据。因此，针对原版数据的修改方式将不再适用于 1.20.5 及更高版本（此前适用于 1.8 至 1.20.4），所有插件均需相应更新以适应该变化。如有疑问，欢迎在 Discord 上咨询。

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.12.3...2.12.4

2.12.3

on 2026 Jul 17
下载

更新内容

  • 新增对未重映射的 Paper 1.20+ 版本的支持

其他更改

新贡献者

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.12.2...2.12.3

2.12.1

on 2026 Jul 17
下载

更新内容

完整更新日志: https://github.com/tr7zw/Item-NBT-API/compare/2.12.0...2.12.1

2.12.0

on 2026 Jul 17
下载

2.12.0

大家好，这是迄今为止 NBTAPI 最重大的一次更新。本次发布共包含 580 次总提交中的 100 次（占过去 7 年全部提交数的 17%？！），请做好准备迎接这些变更。

（顺便温馨提醒：支持本项目的开发者将非常棒，尤其是当你使用此 API 开发付费插件时 😅）

2.12.0-RC1 与 2.12.0 之间的延迟变更：

  • 新增对 1.20.2 版本的支持
  • 修复空 ItemStack 上的 getKeys 方法
  • 修复空 ItemStack 上的 modifyMeta 方法
  • 新增对代理列表（ProxiedLists）的支持
  • 新增在 resolve 方法中使用类似 [123] 或 [-1] 索引的支持
  • 强制禁止使用 JitPack。若你因任何原因仍在使用 JitPack，请查阅 Wiki 以使用正确的仓库！

主要变更

  • 新增对 Mojang 映射服务器（Paper-Mojmap / Paper 开发模式）的支持
  • 新增对 Folia 的支持
  • 对 NBT.get 和 NBT.modify 方法进行了大幅性能优化（详见下文）
  • 预览功能：接口代理（Interface Proxies），无需编写代码即可访问 NBT（详见下文）
  • 实体（Entity）/ 区块实体（BlockEntity）的修改操作现为原子性且速度更快，可避免常见陷阱
  • 实体（Entity）/ 区块实体（BlockEntity）的只读访问速度大幅提升，仅需获取一次标签（Tag）
  • 新增 resolveOrNull / resolveOrDefault / resolveCompound / resolveOrCreateCompound 方法。这些方法接受以 . 分隔的字符串路径（如 tag.othertag.key）来定位键（详见下方示例）

值得关注的变更

  • 将 bStats 从 1.x 版本升级至 3.0.2
  • 减少 Gson 相关日志输出
  • 新增 long[] 支持（setLongArray / getLongArray，适用于 1.16+）
  • 在错误信息中包含 NBTAPI 版本号
  • 移除了 “functional-annotations” 依赖项（此前部分用户可能已注意到该依赖被遮蔽）
  • 修复 NBTFile.saveTo 始终保存根标签而非传入标签的问题
  • 在若干关键位置新增 @Nullable 注解
  • 当 NBT.modify 执行完毕后标签为空时，该标签将直接从物品中移除，而非保存一个空的 {} 标签
  • 防止对 NBT.get / NBT.modify 方法的误用
  • 新增 set(String key, T value, NBTHandler<T> handler) 方法，可通过指定处理器设置自定义数据
  • 新增 get(String key, NBTHandler<T> handler) 方法，可通过指定处理器获取自定义数据

其他变更 / 文档更新

性能优化

本次发布在底层进行了大量性能优化，主要针对 ItemStack / 实体（Entity）/ 区块实体（BlockEntity）的 NBT.get 和 NBT.modify 方法。我们强烈建议各位尽快将 NBTItem / NBTEntity / NBTTileEntity 的现有代码迁移至这些新方法。
所有基准测试均在本地 PC 上基于 Paper-171 运行，对比版本为 2.11.3 与 2.12.0-RC1。数值表示每秒可执行测试用例的次数（JVM 在测试前已进行预热）。但由于仅为单次运行，实际误差范围约为 ±5%，仅供参考。

ItemStack

运行代码链接。旧版测试使用 new NBTItem，其余测试则使用 NBT 类。两种测试均对相同数据进行读写，仅语法不同！

基于 NMS 的 ItemStack：

  • LegacyGet：880.620 → 909.369，提升约 3%
  • NBT.get：884.326 → 4.214.210，提升约 376%
  • LegacySet：762.453 → 804.732，提升约 5%
  • NBT.modify：298.238 → 1.781.667，提升约 497%

纯 Bukkit 的 ItemStack：

  • LegacyGet：215.992 → 202.413，下降约 6%
  • NBT.get：223.998 → 649.626，提升约 190%
  • LegacySet：229.485 → 239.910，提升约 4%
  • NBT.modify：166.048 → 567.107，提升 241%

简而言之：切换至新的 NBT.get / NBT.modify 方法，性能相比之前至少提升 200%。

持久化数据容器（Persistent Data Container）

为更清晰地了解使用 NBTAPI 在物品上存储数据与 Spigot 的持久化数据容器（PDC）API 的性能差异，我也对此进行了测试与对比。同样基于 Paper-171 与 2.12.0-RC1。在基于 NMS 的 ItemStack 上，常规 PDC 与 NBT.get 性能基本相当；仅当将 NamespacedKey 缓存于 final 类字段中时，PDC 才略占优势。而写入数据（尤其在纯 Bukkit 物品上）则慢得多，但即便如此仍可达每秒 50 万次以上，因此实际影响极小（尤其考虑到 NBTAPI 提供了更灵活的 API 以及对 1.14 之前版本的支持）。

resolve 方法

为简化对深层嵌套 NBT 的操作，resolve 方法现支持直接获取或操作这些标签。
复合标签（Compound）之间以 . 分隔。若键名本身需包含 .，可用 \ 进行转义。
示例：

// 将 foo/bar/baz/test 设为 42
nbt.resolveOrCreateCompound("foo.bar.baz").setInteger("test", 42);
// 获取刚刚设置的值，若不存在则返回 0
nbt.resolveOrDefault("foo.bar.baz.test", 0);
// 获取刚刚设置的值，若不存在则返回 null
nbt.resolveOrNull("foo.bar.baz.test", int.class);
// 键名含 . 的示例：设置键 foo/some.key/baz/other
nbt.resolveOrCreateCompound("foo.some\\.key.baz").setInteger("other", 123)
// 获取标签，若不存在则返回 null
nbt.resolveCompound("some.nested.key");

接口代理（Interface Proxies）

这是本版本中的一项预览功能，其 API 可能会根据反馈或开发进展而调整。它允许你定义一个普通接口（含常规方法或默认方法），NBTAPI 将自动为该接口生成实现类，并将其包装在 NBT 对象之上。

方法名以 has / get / set 开头的方法将被自动解析为对应操作：
public boolean hasKills(); → return nbt.hasTag("kills");
public void setKills(int amount); → nbt.setInteger("kills", amount);
public int getKills(); → return nbt.getInteger("kills");
接口内的默认方法（如以下示例）也受支持：

        public default void addKill() {
            setKills(getKills() + 1);
        }

此外，getter 方法还可返回另一个同样继承 NBTProxy 的接口。
为支持 ItemStack 等其他数据类型，可通过覆盖 init 方法并使用 registerHandler 方法注册处理器。例如：

        @Override
        default void init() {
            registerHandler(ItemStack.class, NBTHandlers.ITEM_STACK);
        }

要使用你的接口，只需如下调用 NBT.modify 或 NBT.readNbt：

NBT.modify(item, TestInterface.class, ti -> {
ti.addKill();
// 或调用你接口中的任意其他方法
});
// 此实例仅支持只读方法。调用任何 setter 方法将抛出异常
TestInterface yourInterface = NBT.readNbt(item, TestInterface.class);
yourInterface .getKills();

完整示例请参阅 内置启动测试 或 正在开发中的 NBT-ItemMeta 代理。欢迎随时在 Discord 中提问。

新贡献者

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.11.3...2.12.0-RC1

2.12.0 - Release Candidate 1

on 2026 Jul 17
下载

2.12.0 - 发布候选版 1

大家好！这是迄今为止 NBTAPI 最重大的一次更新，因此我决定在正式发布 2.12.0 版本前，先推出一个 Minecraft 风格的发布候选版（理想情况下无需任何改动即可正式发布）。本次版本共包含 84 次提交，占过去 6–7 年全部 563 次提交的近 15%（竟达 15%？！），请系好安全带，迎接这些变更。

（顺便温馨提醒：支持本项目的开发者将不胜感激，尤其当你使用此 API 开发付费插件时 😅）

主要变更

  • 新增对 Mojang 映射服务器（Paper-Mojmap / Paper 开发模式）的支持
  • 新增对 Folia 的支持
  • 对 NBT.get 和 NBT.modify 方法进行了大幅性能优化（详见下文）
  • 预览功能：接口代理（Interface Proxies），无需编写代码即可访问 NBT（详见下文）
  • 实体（Entity）与方块实体（BlockEntity）的修改操作现已改为原子性操作，速度更快，避免常见陷阱
  • 实体与方块实体的只读访问大幅提速，仅需获取一次标签（tag）即可
  • 新增 resolveOrNull / resolveOrDefault / resolveCompound / resolveOrCreateCompound 方法。这些方法接受以英文句点 . 分隔的路径字符串（如 tag.othertag.key）（示例见下文）

值得关注的变更

  • 将 bStats 从 1.x 版本升级至 3.0.2
  • 减少 Gson 相关日志输出
  • 新增 long[] 类型支持（含 setLongArray / getLongArray 方法，适用于 1.16+）
  • 在错误信息中包含 NBTAPI 版本号
  • 移除了 functional-annotations 依赖项（此前部分用户可能注意到该依赖被遮蔽）
  • 修复 NBTFile.saveTo 总是保存根标签而非传入标签的问题
  • 在若干关键位置添加了 @Nullable 注解
  • 当 NBT.modify 执行完毕后标签为空时，该标签将从物品中彻底移除，而非保存空标签 {}
  • 防止对 NBT.get / NBT.modify 方法的误用
  • 新增 set(String key, T value, NBTHandler<T> handler) 方法，可通过指定处理器写入自定义数据
  • 新增 get(String key, NBTHandler<T> handler) 方法，可通过指定处理器读取自定义数据

其他变更 / 文档更新

性能表现

本次发布在底层进行了大量性能优化，主要针对 NBT.get 和 NBT.modify 方法在物品栈（ItemStack）、实体（Entity）及方块实体（BlockEntity）上的表现。强烈建议各位尽快将现有 NBTItem / NBTEntity / NBTTileEntity 代码迁移至这些新方法。

所有基准测试均在本地 PC 的 Paper-171 上运行，对比版本为 2.11.3 与 2.12.0-RC1。数值表示每秒可完成的测试用例执行次数（JVM 在测试前已进行充分预热）。由于仅执行单次测试，实际误差范围约为 ±5%，数值仅供粗略参考。

物品栈（ItemStack）

运行代码链接。旧版测试使用 new NBTItem，新版测试则使用 NBT 类。两组测试均读写相同数据，仅语法不同！

基于 NMS 的物品栈：

  • LegacyGet：880.620 → 909.369（提升约 3%）
  • NBT.get：884.326 → 4,214,210（提升约 376%）
  • LegacySet：762.453 → 804.732（提升约 5%）
  • NBT.modify：298.238 → 1,781,667（提升约 497%）

纯 Bukkit 物品栈：

  • LegacyGet：215.992 → 202.413（下降约 6%）
  • NBT.get：223.998 → 649.626（提升约 190%）
  • LegacySet：229.485 → 239.910（提升约 4%）
  • NBT.modify：166.048 → 567.107（提升 241%）

简而言之：切换至新的 NBT.get / NBT.modify 方法后，性能至少提升 200%。

持久化数据容器（Persistent Data Container）

为更清晰地对比 NBTAPI 与 Spigot 原生持久化数据容器（PDC）在物品数据存储方面的性能，我也一并进行了测试与对比。测试环境仍为 Paper-171 下的 2.12.0-RC1。在基于 NMS 的物品栈上，常规 PDC 的读取速度与 NBT.get 基本持平；仅当将 NamespacedKey 缓存于 final 类字段时，PDC 才略微领先。而数据写入（尤其在纯 Bukkit 物品上）则慢得多——但即便如此，仍可轻松达到每秒 50 万次以上，因此实际影响微乎其微（更何况 NBTAPI 提供了更灵活的 API 及对 1.14 之前版本的支持）。

解析方法（Resolve Methods）

为简化对深层嵌套 NBT 的操作，新增解析方法，可直接获取或操作对应标签。
复合标签（Compound）路径以英文句点 . 分隔。若键名本身需包含句点 .，可用反斜杠 \ 进行转义。
示例：

// 将 foo/bar/baz/test 设为 42
nbt.resolveOrCreateCompound("foo.bar.baz").setInteger("test", 42);
// 获取刚刚设置的值，若不存在则返回 0
nbt.resolveOrDefault("foo.bar.baz.test", 0);
// 获取刚刚设置的值，若不存在则返回 null
nbt.resolveOrNull("foo.bar.baz.test", int.class);
// 键名含句点的示例：设置键 foo/some.key/baz/other
nbt.resolveOrCreateCompound("foo.some\\.key.baz").setInteger("other", 123);
// 获取标签，若不存在则返回 null
nbt.resolveCompound("some.nested.key");

接口代理（Interface Proxies）

本功能为预览性质，API 可能随反馈与开发进展而调整。它允许你定义一个普通接口（含常规方法与默认方法），NBTAPI 将自动为该接口生成实现类，并将 NBT 标签封装其中。

以 has / get / set 开头的方法将被自动映射为对应操作：
public boolean hasKills(); → return nbt.hasTag("kills");
public void setKills(int amount); → nbt.setInteger("kills", amount);
public int getKills(); → return nbt.getInteger("kills");
接口内定义的默认方法（如以下示例）同样受支持：

        public default void addKill() {
            setKills(getKills() + 1);
        }

此外，getter 方法也可返回另一个同样继承 NBTProxy 的接口。
如需支持 ItemStack 等其他数据类型，可通过覆盖 init 方法（设为默认方法），调用 registerHandler 注册处理器。例如：

        @Override
        default void init() {
            registerHandler(ItemStack.class, NBTHandlers.ITEM_STACK);
        }

要使用你的接口，只需如下调用 NBT.modify 或 NBT.readNbt：

NBT.modify(item, TestInterface.class, ti -> {
    ti.addKill();
    // 或调用你接口中的任意其他方法
});
// 此实例仅支持只读方法。调用任何 setter 方法将抛出异常
TestInterface yourInterface = NBT.readNbt(item, TestInterface.class);
yourInterface.getKills();

完整示例请参阅 内置启动测试 或 正在开发中的 NBT-ItemMeta 代理。欢迎随时在 Discord 中提问交流。

新贡献者

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.11.3...2.12.0-RC1

2.11.3

on 2026 Jul 17
下载

更新内容

温馨提示

更多功能正在开发中，例如 Mojang 映射的 JAR 包支持、Folia 支持，以及通过接口更简洁地访问数据的方式。欢迎加入 Discord 参与讨论！

新贡献者

完整更新日志：https://github.com/tr7zw/Item-NBT-API/compare/2.11.2...2.11.3

1
2
3