Using Maven

To start using NB-API, you either need to depend on its plugin version, or shade (include) it inside your plugin.

Important

Plugin and shaded versions have different artifactId. Make sure to correctly choose the one you need!

[!IMPORTANT] Alternative ways of loading the api like Libby are not supported on Discord/Github issues.

Option 1) NBT-API as a dependency (recommended)

Add the following entries to your pom at the correct locations:

<repositories>
...
<!-- CodeMC -->
<repository>
  <id>codemc-repo</id>
  <url>https://repo.codemc.io/repository/maven-public/</url>
  <layout>default</layout>
</repository>
...
</repositories>

<dependency>
  <groupId>de.tr7zw</groupId>
  <artifactId>item-nbt-api-plugin</artifactId>
  <version>VERSION</version>
  <scope>provided</scope>
</dependency>

(Get the current VERSION from here)

Add the API as dependency to your plugin.yml:

depend: [NBTAPI]

Or, if you are using paper-plugin.yml:

dependencies:
  server:
    NBTAPI:
      load: BEFORE
      required: true
      join-classpath: true

Option 2) Shading the NBT-API into your plugin (Not recommended)

Warning

Due to the increasing amount of pitfalls in modern Paper, shading is not recommended. Please test with the normal plugin dependency before reporting issues.

To include NBT-API directly in your plugin, you can use the maven shade plugin.

Create an empty .mojang-mapped file in the META-INF folder of your plugin for 1.20+ Paper support.

Warning

Not adding this flag will make the shaded api not work on the latest Paper. It might also break other reflections/nms logic!

Add the plugin to the build configuration, as shown here:

 <plugins>
   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-shade-plugin</artifactId>
     <version>3.6.0</version>
     <executions>
       <execution>
         <id>shade</id>
         <phase>package</phase>
         <goals>
           <goal>shade</goal>
         </goals>
       </execution>
     </executions>
     <configuration>
       <relocations>
         <relocation>
           <pattern>de.tr7zw.changeme.nbtapi</pattern>
           <shadedPattern>YOUR PACKAGE WHERE THE API SHOULD END UP</shadedPattern>
         </relocation>
       </relocations>
     </configuration>
   </plugin>
</plugins>

The latest version of the shade plugin can be found here.

Replace YOUR PACKAGE WHERE THE API SHOULD END UP with your own unique package. For example:

<relocation>
  <pattern>de.tr7zw.changeme.nbtapi</pattern>
  <shadedPattern>com.yourname.pluginname.nbtapi</shadedPattern>
</relocation>

Then, add NBT-API to your dependencies by including the following entries to your pom at the correct locations:

<repositories>
...
<!-- CodeMC -->
<repository>
  <id>codemc-repo</id>
  <url>https://repo.codemc.io/repository/maven-public/</url>
  <layout>default</layout>
</repository>
...
</repositories>

<dependency>
  <groupId>de.tr7zw</groupId>
  <artifactId>item-nbt-api</artifactId>
  <version>VERSION</version>
</dependency>

(Get the current VERSION from here)

Warning

Make sure you're using item-nbt-api as artifactId, never shade the -plugin artifact!

Initializing NBT-API early

If you are shading NBT-API, you may call NBT.preloadApi() during onEnable to initialize NBT-API early and check whether everything works. If you omit this step, NBT-API will be initialized on the first call to the API.

@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
}