Item-NBT-API: custom NBT on Minecraft items without touching internals

The problem it solves is narrower than it sounds

The pitch is a single line: add custom NBT tags to Items, Tiles and Entities without NMS.

NMS is the server implementation, the obfuscated and versioned internals that a plugin has to reach into to touch the actual game object. A plugin that uses NMS is bound to one Minecraft version and breaks on the next one, because the internal class names and signatures change with every release. The whole point of this library is to give plugin authors a way to attach their own data to game objects without that dependency.

The second half of the description is where it gets interesting: modify NBT and store it in Files, other NBT, or as String in yaml, json, SQL or Redis.

That list is the real design decision. Once you can write custom NBT, the obvious question is where the data goes, and each of those answers serves a different use. Keeping it in a file next to the plugin means the data is simple and local. Keeping it inside other NBT means the data travels with the object, so a custom item keeps its metadata wherever the player carries it. Storing it as a string in yaml, JSON, SQL or Redis means the data is a value in a system you already run, which is what you want for anything you need to query, index or share between servers.

Storing a value as a string rather than as structured NBT is what makes the SQL and Redis options work at all, since a relational table column is a string and a Redis value is a string. The trade is that the structure has to be encoded in that string, and the library is what handles the round trip.

The licence is MIT, the language is Java, and the recent releases are 2.16.1 from 2026-09-17, 2.16.0 from 2026-07-27 and 2.15.7 from 2026-04-06, with the last push on 2026-09-17.

A multi module repository, not one jar

The top level of the repository is where the interesting structure is, and it explains what the project actually is.

There are five directories that hold code. item-nbt-api is the library itself, the module you would depend on. item-nbt-plugin is a plugin, which is how the library gets into a server and provides the runtime the library needs. nbt-data-api is the data layer, the part that knows how to read and write those yaml, JSON, SQL and Redis backends. nbt-injector is the piece that gets the NBT capability into the running server, which is where the NMS avoidance is implemented. mappings-parser is separate again, and its name suggests it deals with the obfuscated mapping problem that NMS normally forces on you.

A pom.xml sits at the root, so the build is Maven, and the project is published to Maven, Gradle and Spigot or Modrinth as a plugin, with the readme pointing to wiki pages for using Maven and using Gradle separately, which tells you the two build systems are genuinely supported rather than one being an afterthought.

The wiki directory at the repository root holds the documentation source, and the readme points readers at two specific pages: the basic usage page and an example usages page with a worked example for setting a skull skin. The wiki is the real documentation, and the readme is a pointer to it.

There is also a curseforge.md file, which is the metadata used when the plugin is listed on CurseForge, a formatter.xml, and an spigot.bb file, which is the plugin descriptor for the Spigot platform. Those two files together tell you the plugin targets the Spigot and Paper ecosystem, and the repository topics list bukkit, paper and spigot, with nbt, nms, api and library alongside them.

Getting started is a dependency and a wiki page

The readme's getting started section is three sentences long, and that is deliberate, because the instructions live in the wiki.

The first step is importing the API, using either Maven or Gradle, with the wiki pages for each. Then you check out the basic usage page, or an example such as working with skulls. There is a separate server owner and developer wiki linked from the top of the readme, which implies two audiences, the plugin author using the API and the server operator deploying the plugin.

That division of responsibility is worth understanding before you install anything. If you are a plugin developer, the library is a dependency and the plugin is what carries it onto the server. If you are a server owner, the plugin is what you need, and the fact that the readme describes the plugin's Modrinth download badge and the SpigotMC resource listing suggests the operator journey is the more common one.

The server operator also gets a bStats panel, with server and player counts for the plugin, which is the standard mechanism plugins use to report anonymised usage statistics, and the readme links the bStats signature page alongside the Modrinth downloads badge and a Discord invite.

The project also carries a CI setup on CodeMC with a build status badge and a set of SonarCloud measures, including lines of code, duplicated lines density and a quality gate rating, plus a GitHub stargazers chart and a YourKit sponsorship mention. The duplication measure is the interesting one for a library of this shape, because the price of supporting multiple Minecraft versions is usually a lot of near-duplicate code, and tracking that density is how you would notice the problem growing.

Who maintains it, and what the release history shows

The project is a long-lived one, and the details in the readme describe the shape of that.

The version line is in the 2.x series with three recent releases, 2.16.1 on 2026-09-17, 2.16.0 on 2026-07-27 and 2.15.7 on 2026-04-06, and the last push was on the same day as the 2.16.1 tag. The SpigotMC listing badge tracks the current published version, and the Spiget badges track the resource rating and download count, which is the usual way a Spigot resource shows its standing.

The contributor surface is the usual open source scaffolding. There is an all contributors badge, a Discord invite, a code of conduct implied by the standard layout, and the repository topics carry hacktoberfest and hacktoberfest2022, which means the project takes outside contributions through that programme, and the formatter.xml file at the root is a style configuration for the codebase.

The community around it is worth noting for an adopter. The Discord server, the bStats panel, the Modrinth download badge, the Spigot resource page and a wiki that is written for both server owners and plugin developers together are the markers of a project with an audience beyond its author. For a Minecraft server plugin, that matters more than it would in a general purpose library, because the audience is a community of people writing plugins for the same platform and often facing the same version breakages.

One dependency of the ecosystem is worth flagging. The readme thanks YourKit for supporting open source projects, and specifically mentions the YourKit Java Profiler, the .NET profiler and YouMonitor, which is a profiling tool vendor sponsoring the project. That is normal for a Java project and it does not affect the library's behaviour, but it is the kind of thing to know about if your organisation has a policy about tooling vendors in an open source dependency chain.

What the project is for, and where it stops

The scope is best understood by what it is not. It is not a plugin that adds gameplay features, it is an enabling layer, and the readme describes it as a library whose job is to make custom metadata possible on the three kinds of object a server deals with: items, tiles and entities.

The data storage options in the description are the practical boundary of the whole project. If your plugin needs to store a per-player statistic, a custom item attribute, or a shard of state on an entity, and you need that data to be queryable or shared, this is the mechanism. If your plugin needs the vanilla NBT that Minecraft already writes, you do not need this library, because the server's own API covers that, and the whole point of the project is the custom layer on top.

The other limit is version coupling, and it is not entirely removed. The project avoids NMS, but it is still built against a Minecraft version, and the release history shows it tracking the game: 2.15.7 in April 2026, 2.16.0 in July, 2.16.1 in September. A plugin using this library inherits that cadence, so its own release cycle is tied to the game's unless the author pins a version and accepts the older Minecraft target.

That is a much smaller problem than raw NMS, because the library is the thing that absorbs the internal churn rather than your plugin, but it is not zero, and it is why the version numbers move the way they do.

The licence is MIT, which matters for a library that other plugin authors redistribute inside their own jars, and the repository also carries a LICENSE file at the root alongside the wiki, the CI configuration and the code modules.

Editorial conclusion

Adopt Item-NBT-API if you are writing Minecraft server plugins that need to attach your own data to items, tiles or entities and you want that data to survive restarts, or to live in a database rather than in the item stack. Do not adopt it if you only need to read standard vanilla tags, since the built-in API already covers that, and note that the version line moves with Minecraft releases, so pinning to a Minecraft version is part of your upgrade planning. Before you commit, check which module you actually need, read the basic usage and the example pages in the wiki, and confirm that the persistence backend you want, SQL or Redis among them, is one you can run in the same environment as the server.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tr7zw/Item-NBT-API on GitHub