开发者快速开始

当前公共能力边界

第三方插件唯一受支持的入口是 sealitems-api 模块中的 SealItemsApi.openIdentification(UUID)。物品发放、迁移、词条改造、宝石事务、PDC codec、Plugin 单例和 Paper controller 都是内部实现，不是公共 API。

如果你的需求超出公开入口，不要反射私有类、复制 PDC 或依赖 cn.sealplugins.items.paper/plugin/core。先提出明确用例，再把最小稳定契约加入 sealitems-api。

1. 准备 API JAR

从同一 SealItems commit 构建：

./gradlew :sealitems-api:jar

产物通常位于：

sealitems-api/build/libs/sealitems-api-0.1.0-SNAPSHOT.jar

复制到你插件的 libs/。不要把完整 SealItems-*.jar 当 API 依赖，也不要 shade API 类进你的成品。

2. Gradle Kotlin DSL

plugins {
    java
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
}

dependencies {
    compileOnly(files("libs/sealitems-api-0.1.0-SNAPSHOT.jar"))
    compileOnly("io.papermc.paper:paper-api:1.21-R0.1-SNAPSHOT")
}

如果未来 SealItems API 发布到 Maven，改用项目公布的精确坐标和版本；当前不要编造不存在的仓库坐标。

3. plugin.yml

若没有 SealItems 也能运行：

name: MySealAddon
version: 1.0.0
main: com.example.mysealaddon.MySealAddon
api-version: '1.21'
softdepend: [SealItems]

若插件没有 SealItems 完全不能工作，才使用 depend: [SealItems]。

4. 获取服务

SealItemsApi api = getServer()
    .getServicesManager()
    .load(SealItemsApi.class);

if (api == null) {
    getLogger().warning("SealItems API 尚不可用");
    return;
}

API 通过 Bukkit ServicesManager 以 ServicePriority.Normal 注册。不要用 SealItemsPlugin.getInstance()。

5. 完整调用

UUID playerUuid = player.getUniqueId();
IdentificationOpenResponse response = api.openIdentification(playerUuid);

if (response.getOpened()) {
    player.sendMessage("已打开鉴定界面");
} else {
    String reason = response.getReason() == null
        ? "SealItems 未提供具体原因"
        : response.getReason();
    player.sendMessage("无法打开鉴定界面：" + reason);
}

opened=false 是正常业务拒绝，例如玩家离线、配置不可用、GUI 不可用或玩法未启用，不等于 Java 异常。

6. 生命周期

SealItems 禁用时会注销服务，进入只读状态时也可能没有可用 API。最简单安全模式是每次用户触发功能时重新 load，而不是把 provider 永久缓存。高频调用插件可监听 Bukkit 服务注册/注销事件并更新引用，但仍要处理调用时业务拒绝。

7. 线程约束

公开方法最终会操作玩家和 GUI，应在服务端主线程/插件正常 Bukkit 调度上下文调用。不要从数据库线程、异步 HTTP 回调直接调用；先切回主线程，并在执行时重新确认玩家在线。

8. 兼容策略

• 0.1.0-SNAPSHOT 是开发快照，固定你测试过的 commit/API JAR。
• 编译时只依赖 API 模块。
• 运行时通过 ServicesManager 探测能力。
• 对 null、opened=false、reason 为空和插件重载都有分支。
• 在真实 Paper/Leaf 测试，而不只使用 mock。

下一章给出 公开 API 完整参考。