NBT-API

NBT-API

Plugin

Add custom NBT tags to Items/Tiles/Entities without NMS

Server Library
77.0k downloads
103 followers
Created2 years ago
Updateda month ago
Follow Save
Host your Minecraft server on BisectHosting - get 25% off your first month with code MODRINTH.
Ad via Adrinth
Filter loader...
Filter versions...
Filter channels...

2.12.3

by tr7zw on Mar 24, 2024
Download

What's Changed

  • Add support for un-remapped Paper 1.20+

Other changes

New Contributors

Full Changelog: https://github.com/tr7zw/Item-NBT-API/compare/2.12.2...2.12.3

2.12.2

by tr7zw on Dec 10, 2023
Download

What's Changed

Full Changelog: https://github.com/tr7zw/Item-NBT-API/compare/2.12.1...2.12.2

2.12.1

by tr7zw on Nov 4, 2023
Download

What's Changed

Full Changelog: https://github.com/tr7zw/Item-NBT-API/compare/2.12.0...2.12.1

2.12.0

by tr7zw on Sep 21, 2023
Download

2.12.0

Hello everyone, this is the by far biggest NBTAPI update so far. This release contains 100 commits of the total 580 total commits(17% of all commits of the past 7 years?!?), so strap in for the changes.

(Also small reminder that supporting the dev behind this project would be really nice, especially when you use this API to make paid Plugins 😅)

Late changes between 2.12.0-RC1 and 2.12.0:

  • Add 1.20.2 support
  • Fix getKeys on empty ItemStacks
  • Fix modifyMeta on empty ItemStacks
  • Add support for ProxiedLists
  • Add support for using indices like [123] or [-1] in resolve methods
  • Hard prevent Jitpack. If you are using Jitpack for whatever reason, check the wiki to use the correct repo!

Major Changes

  • Add support for Mojang-Mapped servers(Paper-Mojmap/Paper dev mode)
  • Add support for Folia
  • HEAVY performance improvements for NBT.get and NBT.modify (see below)
  • Preview: Interface proxies to access NBT without writing code(see below)
  • Entity/BlockEntity modifications are now atomic and faster to prevent pitfalls
  • Entity/BlockEntity read-only is now a lot faster by only getting the tag once
  • Added resolveOrNull/resolveOrDefault/resolveCompound/resolveOrCreateCompound. They take . separated strings to keys like tag.othertag.key (see below for examples)

Noteworthy Changes

  • Updated bStats from version 1? to 3.0.2
  • Reduced logging for Gson
  • Added long[] support with setLongArray/getLongArray (1.16+)
  • Include NBTAPI version in errors
  • Removed the "functional-annotations" dependency shading users might have noticed
  • Fixed NBTFile.saveTo always saving the root instead of the passed tag
  • Added @Nullable in some key places
  • When the tag is empty at the end of NBT.modify, the tag gets removed from the item instead of saving an empty {} tag
  • Prevented some misuse of the NBT.get/NBT.modify methods
  • New set(String key, T value, NBTHandler<T> handler) method to set your custom data with the provided handler
  • New get(String key, NBTHandler<T> handler) method to get your custom data with the provided handler

Other Changes/Documentation

Performance

This release has a lot of performance optimizations under the hood, mainly for the NBT.get and NBT.modify methods for ItemStacks/Entities/BlockEntities. I highly encourage everyone to start updating their NBTItem/NBTEntity/NBTTileEntity code to use these new methods. All benchmarks are done on Paper-171 on my local PC with 2.11.3 vs 2.12.0-RC1. The numbers are how often the test case was able to run in one second(the JVM did have some warmup time before on these methods). But since it's just one run there is probably a +-5% margin of error on these values, they are just there to get a rough idea.

Itemstacks

Link to the code that runs. The legacy tests use new NBTItem, while the others use the NBT class. Both tests get/set the same data, just changing between the old and new syntax!

NMS-Backed Itemstacks:

  • LegacyGet: 880.620 -> 909.369 = ~3% faster
  • NBT.get: 884.326 -> 4.214.210 = ~376% faster
  • LegacySet: 762.453 -> 804.732 = ~5% faster
  • NBT.modify: 298.238 -> 1.781.667 = ~497% faster

Bukkit-only Itemstacks:

  • LegacyGet: 215.992 -> 202.413 = ~6% slower
  • NBT.get: 223.998 -> 649.626 = ~190% faster
  • LegacySet: 229.485 -> 239.910 = ~4% faster
  • NBT.modify: 166.048 -> 567.107 = 241% faster

Basically, switch to the new NBT.get/NBT.modify method and get at least 200% more performance compared to before.

Persistent Data Container

To get a better idea on the performance of using the NBTAPI to store data on items vs Spigots Persistent Data Container API I checked and compared these too. Again, Paper-171 on 2.12.0-RC1. On NMS-Backed Itemstacks normal PDC is about the same speed as NBT.get. Only when caching the NamespacedKey in a final class field PDC pulls ahead. Writing data, especially on Bukkit-only items is a lot slower, but still easily 500.000+ times per second, so doubt that it's much of an issue(especially for gaining a way more flexible API and pre-1.14 support).

Resolve methods

To simplify working with deeply nested NBT, resolve methods now allow directly getting or working with these tags. Compounds are separated by .. In case you need a . inside a key, it can be escaped with a \. Examples:

// sets foo/bar/baz/test to 42
nbt.resolveOrCreateCompound("foo.bar.baz").setInteger("test", 42);
// gets the value we just set or 0
nbt.resolveOrDefault("foo.bar.baz.test", 0);
// gets the value we just set or null
nbt.resolveOrNull("foo.bar.baz.test", int.class);
// example of a key with a . in it. Sets the key foo/some.key/baz/other
nbt.resolveOrCreateCompound("foo.some\\.key.baz").setInteger("other", 123)
// get a tag or null when it's not there
nbt.resolveCompound("some.nested.key");

Interface Proxies

This is a preview feature contained in this release, and the API might change depending on feedback/development. It allows defining an Interface with normal methods/default methods, and the NBTAPI wraps the NBT with an automatically generated implementation of this Interface.

Methods starting with has/get/set will be interpreted as their respective calls: public boolean hasKills(); runs return nbt.hasTag("kills"); public void setKills(int amount); runs nbt.setInteger("kills", amount); public int getKills(); runs return nbt.getInteger("kills"); Default methods like

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

inside the interface are supported. Also having a getter return another Interface that also extends NBTProxy is supported. To support other datatypes like ItemStacks, the init method can be overwritten with a default method, using the registerHandler method to add handlers. For example:

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

To now use your interface, just call NBT.modify or NBT.readNbt like this:

NBT.modify(item, TestInterface.class, ti -> {
ti.addKill();
//or any other method from your interface
});
// This instance can only run read-only methods. Calling any setter will cause an exception
TestInterface yourInterface = NBT.readNbt(item, TestInterface.class);
yourInterface .getKills();

For the complete example check the built-in startup test or the WIP NBT-ItemMeta proxy. Also feel free to ask on Discord.

New Contributors

Full Changelog: https://github.com/tr7zw/Item-NBT-API/compare/2.11.3...2.12.0-RC1

2.12.0 - Release Candidate 1

by tr7zw on Sep 10, 2023
Download

2.12.0 - Release Candidate 1

Hello everyone, this is the by far biggest NBTAPI update so far, that's why I decided to have a Minecraft-style Release Candidate before the full 2.12.0 release(best-case without any changes). This release contains 84 commits of the total 563 total commits(nearly 15% of all commits of the past 6-7 years?!?), so strap in for the changes.

(Also small reminder that supporting the dev behind this project would be really nice, especially when you use this API to make paid Plugins 😅)

Major Changes

  • Add support for Mojang-Mapped servers(Paper-Mojmap/Paper dev mode)
  • Add support for Folia
  • HEAVY performance improvements for NBT.get and NBT.modify (see below)
  • Preview: Interface proxies to access NBT without writing code(see below)
  • Entity/BlockEntity modifications are now atomic and faster to prevent pitfalls
  • Entity/BlockEntity read-only is now a lot faster by only getting the tag once
  • Added resolveOrNull/resolveOrDefault/resolveCompound/resolveOrCreateCompound. They take . separated strings to keys like tag.othertag.key (see below for examples)

Noteworthy Changes

  • Updated bStats from version 1? to 3.0.2
  • Reduced logging for Gson
  • Added long[] support with setLongArray/getLongArray (1.16+)
  • Include NBTAPI version in errors
  • Removed the "functional-annotations" dependency shading users might have noticed
  • Fixed NBTFile.saveTo always saving the root instead of the passed tag
  • Added @Nullable in some key places
  • When the tag is empty at the end of NBT.modify, the tag gets removed from the item instead of saving an empty {} tag
  • Prevented some misuse of the NBT.get/NBT.modify methods
  • New set(String key, T value, NBTHandler<T> handler) method to set your custom data with the provided handler
  • New get(String key, NBTHandler<T> handler) method to get your custom data with the provided handler

Other Changes/Documentation

Performance

This release has a lot of performance optimizations under the hood, mainly for the NBT.get and NBT.modify methods for ItemStacks/Entities/BlockEntities. I highly encourage everyone to start updating their NBTItem/NBTEntity/NBTTileEntity code to use these new methods. All benchmarks are done on Paper-171 on my local PC with 2.11.3 vs 2.12.0-RC1. The numbers are how often the test case was able to run in one second(the JVM did have some warmup time before on these methods). But since it's just one run there is probably a +-5% margin of error on these values, they are just there to get a rough idea.

Itemstacks

Link to the code that runs. The legacy tests use new NBTItem, while the others use the NBT class. Both tests get/set the same data, just changing between the old and new syntax!

NMS-Backed Itemstacks:

  • LegacyGet: 880.620 -> 909.369 = ~3% faster
  • NBT.get: 884.326 -> 4.214.210 = ~376% faster
  • LegacySet: 762.453 -> 804.732 = ~5% faster
  • NBT.modify: 298.238 -> 1.781.667 = ~497% faster

Bukkit-only Itemstacks:

  • LegacyGet: 215.992 -> 202.413 = ~6% slower
  • NBT.get: 223.998 -> 649.626 = ~190% faster
  • LegacySet: 229.485 -> 239.910 = ~4% faster
  • NBT.modify: 166.048 -> 567.107 = 241% faster

Basically, switch to the new NBT.get/NBT.modify method and get at least 200% more performance compared to before.

Persistent Data Container

To get a better idea on the performance of using the NBTAPI to store data on items vs Spigots Persistent Data Container API I checked and compared these too. Again, Paper-171 on 2.12.0-RC1. On NMS-Backed Itemstacks normal PDC is about the same speed as NBT.get. Only when caching the NamespacedKey in a final class field PDC pulls ahead. Writing data, especially on Bukkit-only items is a lot slower, but still easily 500.000+ times per second, so doubt that it's much of an issue(especially for gaining a way more flexible API and pre-1.14 support).

Resolve methods

To simplify working with deeply nested NBT, resolve methods now allow directly getting or working with these tags. Compounds are separated by .. In case you need a . inside a key, it can be escaped with a \. Examples:

// sets foo/bar/baz/test to 42
nbt.resolveOrCreateCompound("foo.bar.baz").setInteger("test", 42);
// gets the value we just set or 0
nbt.resolveOrDefault("foo.bar.baz.test", 0);
// gets the value we just set or null
nbt.resolveOrNull("foo.bar.baz.test", int.class);
// example of a key with a . in it. Sets the key foo/some.key/baz/other
nbt.resolveOrCreateCompound("foo.some\\.key.baz").setInteger("other", 123)
// get a tag or null when it's not there
nbt.resolveCompound("some.nested.key");

Interface Proxies

This is a preview feature contained in this release, and the API might change depending on feedback/development. It allows defining an Interface with normal methods/default methods, and the NBTAPI wraps the NBT with an automatically generated implementation of this Interface.

Methods starting with has/get/set will be interpreted as their respective calls: public boolean hasKills(); runs return nbt.hasTag("kills"); public void setKills(int amount); runs nbt.setInteger("kills", amount); public int getKills(); runs return nbt.getInteger("kills"); Default methods like

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

inside the interface are supported. Also having a getter return another Interface that also extends NBTProxy is supported. To support other datatypes like ItemStacks, the init method can be overwritten with a default method, using the registerHandler method to add handlers. For example:

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

To now use your interface, just call NBT.modify or NBT.readNbt like this:

NBT.modify(item, TestInterface.class, ti -> {
ti.addKill();
//or any other method from your interface
});
// This instance can only run read-only methods. Calling any setter will cause an exception
TestInterface yourInterface = NBT.readNbt(item, TestInterface.class);
yourInterface .getKills();

For the complete example check the built-in startup test or the WIP NBT-ItemMeta proxy. Also feel free to ask on Discord.

New Contributors

Full Changelog: https://github.com/tr7zw/Item-NBT-API/compare/2.11.3...2.12.0-RC1

2.11.3

by tr7zw on Jun 7, 2023
Download

What's Changed

A heads-up

More features like Mojang mapped jars/Folia support and a cleaner way to access data using interfaces are on the way. You should consider joining the discord to join the discussion.

New Contributors

Full Changelog: https://github.com/tr7zw/Item-NBT-API/compare/2.11.2...2.11.3

2.11.2

by tr7zw on Mar 16, 2023
Download
  • Add 1.19.4 as officially supported(2.11.1 will work fine on 1.19.4, but show a warning that it doesn't know about this version)
  • Fixed the return type of getOrCreateCompound/getCompound in ReadWriteNBT to be ReadWriteNBT too

2.11.1

by tr7zw on Dec 14, 2022
Download

What's Changed

New Contributors

Full Changelog: https://github.com/tr7zw/Item-NBT-API/compare/2.11.0...2.11.1

2.11.0

by tr7zw on Dec 11, 2022
Download

New major NBTAPI release, adding 1.19.3 support and a new way to interact with the API.

Changes:

  • 1.19.3 support
  • Added interfaces to most nbt logic, including read-only versions
  • Added a new utility class NBT, which provides clean lambda access to read and write NBT. https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API has updated examples on how to use this class.
  • Utility readFrom/saveTo methods to NBTFile
  • hasTag as alternative for hasKey, returning boolean instead of Boolean
  • Added getOrDefault method
  • Added getOrNull method
  • Deprecated setObject/getObject, please do the serialization yourself using your preferred lib/settings
  • getUUID/setUUID now will handle pre-1.16 and post-1.16 formats correctly on their own
  • getItemStack will now return null if the tag is not found
  • getKeys is now a copy of the Set, and no longer linked to NMS internal objects
  • Added setItemStackArray/getItemStackArray methods
  • Added modifyMeta methods to ItemStacks. Do not modify the NBT while inside the modifyMeta scope
  • The wiki is now inside the Github repository, so anyone can make pull requests to add examples, clarifications etc.
  • NBTItem now will correctly reject ItemStacks of size 0
  • Updated a lot of Javadoc
  • The full API Javadoc is now available under https://tr7zw.github.io/Item-NBT-API/v2-api/
  • Pulling the NBTAPI plugin via Maven/Gradle will now also correctly contain the API Javadoc(only had the plugin Javadoc before)
  • Fixed small NPE error during error reporting(ironic)
  • NBTCompoundList now extend NBTList<ReadWriteNBT> instead of NBTList<NBTListCompound>. This is a compile-time breaking change, and code needs to be updated accordingly. Already published plugins should not be affected by this.

2.10.0

by tr7zw on Aug 21, 2022
Download

Added:

  • 1.19 support

  • 1.7.10 Crucible support(use the latest build). Thanks, EverNife

External resources

IssuesSourceWikiDiscordKo-fi

Featured versions

See all
2.12.3
Bukkit, Folia, Paper, Purpur, Spigot 1.8.8–1.20.4
Release

Project members

tr7zw

Owner

Technical information

License
MIT
Project ID