翻译自 Item-NBT-API wiki (opens new window)

要使用 NBT-API，你需要依赖它的插件版本，或者通过 shade 将其包含到你的插件里。

重要事项

插件版本与 shaded 版本使用不同的 artifactId。请确保正确选择你需要的那个！

像是 Libby 之类的另类加载方式不受支持，不要在 Discord/Github issues 讨论。

选项 1) 将 NBT-API 作为依赖插件 (推荐)

在合适的位置，在你的 pom 里面添加以下内容:

<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>
  <scope>provided</scope>
</dependency>

(到 这里 (opens new window) 获取当前的 版本)

将依赖声明添加到你的 plugin.yml:

depend: [NBTAPI]

或者如果你使用 paper-plugin.yml 的话可以这样:

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

选项 2) 通过 shade 将 NBT-API 包含到你的插件 (不推荐)

警告

由于现代 Paper 的暗病越来越多，shade 操作是不推荐的。请在报告问题之前使用普通的插件依赖先测试一遍。

要直接包含 NBT-API 到你的插件，你可以使用 maven 的 shade 插件来操作。

在你的 META-INF 文件夹中创建一个空的 .mojang-mapped 文件，以支持 1.20+ 的 Paper 服务端。

警告

不添加这个标志文件，会使得打包的 api 无法在最新版本的 Paper 工作。也有可能会破坏其它的反射/NMS逻辑！

在构建配置添加插件，就像这样:

 <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>API将出现在哪个包</shadedPattern>
         </relocation>
       </relocations>
     </configuration>
   </plugin>
</plugins>

最新的 shade 插件版本可以在 这里 (opens new window) 找到。

替换 API将出现在哪个包 为你自己的包名，例如:

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

然后，在合适的位置，在你的 pom 里面添加 NBT-API 到你的项目依赖，以下示例:

<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>
</dependency>

(到 这里 (opens new window) 获取当前的 版本)

警告

请确保你使用的依赖是以 item-nbt-api 作为 artifactId，永远不要将 -plugin 打包到你的插件里!

早期初始化 NBT-API

如果你在使用 shade 打包 NBT-API，你可能需要在 onEnable 调用 NBT.preloadApi() 以进行早期初始化 NBT-API 以及检查功能是否正常工作。如果你省略了这一步，NBT-API 将会在你第一次调用 API 时初始化。

@Override
public void onEnable() {
    if (!NBT.preloadApi()) {
        getLogger().warning("NBT-API 未正确初始化，正在卸载插件");
        getPluginLoader().disablePlugin(this);
        return;
    }
    // 加载其他东西
}

译者注：我更喜欢在 onLoad 时初始化 API，并替换 Logger 以及关闭网络访问。

@Override
public void onLoad() {
    MinecraftVersion.replaceLogger(getLogger());
    MinecraftVersion.disableUpdateCheck();
    MinecraftVersion.disableBStats();
    // getVersion() 也算是“调用API”，这就可以对 NBT-API 进行初始化
    // 但这不会对整个依赖的完整性进行自检，如果你需要自检，那么请把这句换成 NBT.preloadApi()
    MinecraftVersion.getVersion();
}