Minecraft plugin NBTAPI

🔌 About the NBTAPI plugin

NBTAPI — is a Minecraft plugin/library that lets server owners and developers read, write and persist NBT on Items, Entities and Block‑Entities without using NMS.

🎯 Purpose

NBTAPI exists to provide a stable, version‑tolerant API for working with Minecraft NBT data. It solves the problem of directly using NMS (which breaks across Minecraft versions) by exposing safe helpers and abstractions for: reading and writing item NBT, entity & tile data, and storing NBT payloads in files or plain strings usable in configs or databases.

NBTAPI is intended primarily as a developer library for Spigot/Paper plugins, but a server JAR is provided so server owners can simply drop it into plugins/ to allow other plugins (that use NBTAPI) to work at runtime.

⚙ Main features

• Read and write custom NBT on ItemStacks, Entities and Block‑Entities without NMS.
• Store NBT as files, YAML/JSON strings, SQL fields or Redis values (API supports multiple persistence strategies). ()
• Works across many Minecraft versions (supports Spigot/Paper starting from 1.8; some compatibility for older 1.7.10 is indicated). ()
• Maven/Gradle artifacts for developers (use as a dependency) and a plugin JAR for server owners.
• bStats metrics integrated (project uses bStats). ()

🧩 Who should use NBTAPI

• Plugin developers who need to attach or read custom NBT without maintaining NMS code.
• Server owners who run plugins that depend on NBTAPI.
• Teams that require stable cross‑version NBT handling for items, custom skulls, attributes or block‑entities.

🏗 Usage examples

• A plugin stores custom data (cooldown timestamps, custom IDs) on an ItemStack via NBTAPI so it survives saves and restarts.
• Persisting block‑entity custom fields into a dedicated JSON/YAML column in a database using the NBTAPI persistence helpers.
• Reading entity NBT to adjust attributes or read custom tags added by other plugins that use NBTAPI.

⌨️ Commands

The plugin does not add new player commands by default. It is primarily a library used by other plugins. ()

🔐 Permissions

NBTAPI itself does not define plugin permissions for server users; it exposes an API for developers. Any permissions are implemented by plugins that use NBTAPI.

⚙ Installation

📥 Install

• Download the NBTAPI plugin JAR (or add the library as a Maven/Gradle dependency for development).
• Place the JAR in your server's plugins/ folder if you want runtime support for other plugins.
• Restart the server (do not use /reload) and verify the plugin loads.

(Official guidance: simply drop the jar in plugins/ — see project wiki/readme). ()

📦 Dependencies

• No external dependencies are required for the core API to function. It is built for Spigot/Paper runtime. If a plugin using NBTAPI requires Vault/PlaceholderAPI/etc., that is declared by that plugin (not NBTAPI itself). ()

🧾 Configuration

• Information about automatic config generation or a config.yml for the core NBTAPI plugin is not explicitly documented in the official sources; server owners should consult the repository wiki or the specific plugin that depends on NBTAPI for configuration details. (Information absent in official sources.) ()

🗄 Database / Persistence

• The API supports storing NBT content as files or as strings usable in YAML/JSON/SQL/Redis (documented in the project README). Use the persistence helpers provided by the API when implementing storage. ()

🧠 Additional information

⚠ Known constraints & notes

• NBTAPI is a developer library first — it exposes functionality for other plugins. Treat it as a dependency rather than a standalone gameplay plugin.
• Because it operates on NBT, behaviour can overlap with other plugins that also modify the same NBT tags; coordination between plugins is recommended.
• Compatibility: documented to support Spigot/Paper from 1.8 and has notes regarding older 1.7.10 behaviour. Always test on a staging server when upgrading Minecraft versions. ()

FAQ

Q: Is NBTAPI a runtime plugin or a developer library? A: Both — the project provides Maven/Gradle artifacts for developers and a plugin JAR server owners can drop into plugins/ for runtime compatibility. ()

Q: Does NBTAPI add commands or permissions I must configure? A: No. NBTAPI itself does not add user-facing commands or permissions; any commands/permissions come from plugins that use NBTAPI. ()

Q: Does NBTAPI collect analytics? A: The project includes bStats integration (project pages indicate bStats usage). ()

Q: Is there a support/Discord channel? A: The project references a community/Discord from its repository (check the GitHub repo/wiki for the current invite). ()

When NBTAPI is useful

If you develop plugins or run servers that need stable, cross‑version NBT handling without writing fragile NMS code, NBTAPI is a focused solution that many Spigot/Paper projects rely on. Use NBTAPI as a library dependency for plugin development or drop the provided plugin JAR into plugins/ to enable runtime support for dependent plugins. ()