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

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

重要事项

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

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

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

在合适的位置，在你的构建脚本 build.gradle(.kts) 里面添加以下内容:

repositories {
    ...
    maven {
        name = "CodeMC"
        url = uri("https://repo.codemc.io/repository/maven-public/")
    }
    ...
}

compileOnly("de.tr7zw:item-nbt-api-plugin:版本")

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

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

depend: [NBTAPI]

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

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

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

警告

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

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

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

警告

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

在构建脚本添加插件，就像这样:

plugins {
    id("com.gradleup.shadow") version "VERSION"
}

最新的 shadow 插件版本可以在 here (opens new window) 找到。

将 NBT-API 添加到你的项目依赖:

repositories {
    ...
    maven {
        name = "CodeMC"
        url = uri("https://repo.codemc.io/repository/maven-public/")
    }
    ...
}

implementation("de.tr7zw:item-nbt-api:VERSION")

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

警告

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

然后，你可以添加 shadowJar 配置，调动 (relocate) 依赖 API 的包:

译者注：如果使用 Kotlin DSL 构建脚本 (build.gradle.kts)，以下配置要写到 tasks {} 块里面。

shadowJar {
    relocate("de.tr7zw.changeme.nbtapi", "API将出现在哪个包")
}

如果你想在执行 build 任务的时候运行 shadowJar 任务，你可以像这样:

build {
    dependsOn(shadowJar)
}

早期初始化 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();
}