Item-NBT-API Documentation

The experimental NBTInjector was removed in version 2.13.0 (released with Minecraft 1.21). It was deprecated because it was incompatible with server reloads and could cause instability.

If you need to access custom entity NBT data without NBTInjector, refer to the documentation on accessing custom data.

If you have shaded NBT-API into your plugin, it is best practice to call NBT.preloadApi() during your plugin's onEnable() method. This ensures the API is initialized early and allows you to verify that it loaded correctly before proceeding with your plugin's logic. If you do not call this, the API will initialize lazily upon its first usage.

@Override
public void onEnable() {
    if (!NBT.preloadApi()) {
        getLogger().warning("NBT-API wasn't initialized properly, disabling the plugin");
        getPluginLoader().disablePlugin(this);
        return;
    }
    // Load other things
}

To use NBT-API in your own plugin development, follow these steps:

1. Import the API: Add the dependency to your project using Maven or Gradle.
2. Learn the basics: Review the basic usage documentation.
3. Explore examples: Check out specific implementation guides, such as working with Skulls.
4. Reference the API: For full technical details, consult the official Javadoc.

Normal blocks do not have NBT. To store custom data for a block, use the Chunk's Persistent Data Container (PDC). This is available since Minecraft 1.16.4.

• Mechanism: Data is stored in the Chunk's PDC under a blocks compound. The key is the block's location in the format X_Y_Z.
• Methods:
  • NBT.readChunkPDC(chunk, ...)
  • NBT.readAndGetChunkPDC(chunk, ...)
  • NBT.modifyAndGetChunkPDC(block, ...)

Caveats:

1. Persistence: Data is linked to the location. If the block is broken or moved, the data remains at that location unless manually cleared.
2. Performance: Storing large amounts of data in chunks increases the chunk's disk size.

// Modify and retrieve data for a specific block
boolean bool = NBT.modifyAndGetChunkPDC(block, nbt -> {
    nbt.setString("owner_name", "Player123");
    return nbt.getOrDefault("key", false);
});

Use NBTFileHandle to manage NBT files on disk. This approach maintains a link to the file, allowing you to apply changes and save them later. Note that NBT.getFileHandle will automatically create the file if it does not exist.

To work with files without maintaining a persistent link, use NBT.readFile(File) and NBT.writeFile(File, ReadWriteNBT). Unlike the handle approach, readFile will return an empty compound if the file is missing rather than creating it.

// Using NBTFileHandle (automatically creates file if missing)
NBTFileHandle nbtFile = NBT.getFileHandle(new File("directory", "test.nbt"));
nbtFile.setString("foo", "bar");
nbtFile.save();

// Using direct read/write (does NOT automatically create file)
File file = new File("directory", "test.nbt");
ReadWriteNBT nbt = NBT.readFile(file);
NBT.writeFile(file, nbt);

Use DataFixerUtil to migrate NBT data from older Minecraft versions to newer ones. This is useful when loading data saved in legacy formats (e.g., 1.12.2) into modern versions (e.g., 1.20.6) where the NBT structure (like item components) has changed.

• Use DataFixerUtil.fixUpItemData(nbt, fromVersion, toVersion) for specific migrations.
• Use DataFixerUtil.getCurrentVersion() to target the version currently running on the server.

// Update 1.12.2 data to 1.20.6
DataFixerUtil.fixUpItemData(nbt, DataFixerUtil.VERSION1_12_2, DataFixerUtil.VERSION1_20_6);

// Update to the current server version
DataFixerUtil.fixUpItemData(nbt, DataFixerUtil.VERSION1_12_2, DataFixerUtil.getCurrentVersion());

Once the API is imported, you can begin adding custom NBT tags to Items, Tiles, or Entities without using NMS (net.minecraft.server).

Key capabilities include:

• Modifying NBT data directly.
• Storing NBT in files or other NBT structures.
• Storing NBT as Strings in formats like YAML, JSON, SQL, or Redis.

For implementation details, consult the basic usage documentation or specific code examples (e.g., working with Skulls).

Support for Minecraft 1.7.10 is available but is considered broken and is no longer officially supported. If you must use it, be aware of the following limitations:

• Use version 1.7.10 of the API.
• NBTLists may not function correctly.
• NBTTypes do not work because the 1.7.x Minecraft version lacks the necessary underlying features.

To use Item-NBT-API in your project, you must import it using a dependency manager. Detailed configuration instructions for both Maven and Gradle can be found in the project wiki.

• For Maven, refer to the Using Maven guide.
• For Gradle, refer to the Using Gradle guide.