AllayMC插件开发Skill allaymc-plugin-dev

---

name: allaymc-plugin-dev description: 使用Java或其他JVM语言构建、更新和排查AllayMC插件。适用于创建新的AllayMC插件、将现有插件迁移到新的Allay API版本、配置命令/事件/任务/配置，或设置Gradle和插件元数据（plugin.json或AllayGradle插件块）。 license: LGPL-2.1 metadata: author: AllayMC

AllayMC插件开发

概述

使用官方的Java模板和Allay API创建AllayMC插件。保持工作流程与最新的Allay API和捆绑的参考资料中的文档一致，除非用户另有要求，否则默认使用模板的Java 21工具链。

空值安全策略

AllayMC目前不使用诸如JSpecify的@Nullable/@NonNull等注解。除非方法的Javadoc明确说明参数或返回值可能为空，否则将其视为非空。

工作流程

1) 选择起点

• 对于新插件，优先使用references/JavaPluginTemplate中的官方模板。
• 如果更新现有插件，请将其build.gradle.kts和插件主类与模板进行差异比较。

2) 对齐Gradle和插件元数据

• 在build.gradle.kts中更新group、description和version。
• 保持group与插件主类的包名一致。
• 除非用户需要不同的版本，否则保持Java工具链与模板一致。
• 在allay {}块中：
  • 将api设置为目标Allay API版本。
  • 将plugin.entrance设置为完全限定的主类名（或模板中使用的短后缀）。
  • 更新authors和website。
• 如果项目不使用AllayGradle插件，请根据references/Allay/docs/tutorials/create-your-first-plugin.md中的文档创建或更新plugin.json。

3) 实现插件入口类

• 继承org.allaymc.api.plugin.Plugin。
• 根据需要重写生命周期方法：
  • onLoad用于轻量级设置。
  • onEnable用于注册和运行时连接。
  • onDisable用于清理。
• 保持类名与plugin.entrance/plugin.json中的入口一致。
• 如果需要可重载行为，请重写isReloadable并实现reload。
• 参考references/Allay/api/src/main/java/org/allaymc/api/plugin/Plugin.java中的基类。

4) 添加核心功能（仅选择需要的部分）

• 命令：遵循references/Allay/docs/tutorials/register-commands.md。
• 事件：遵循references/Allay/docs/tutorials/register-event-listeners.md。
• 任务：遵循references/Allay/docs/tutorials/schedule-tasks.md。
• 配置：遵循references/Allay/docs/tutorials/use-config.md。
• 权限：遵循references/Allay/docs/tutorials/use-permission.md。
• 国际化（i18n）：遵循references/Allay/docs/tutorials/use-i18n.md。
• 表单/UI：遵循references/Allay/docs/tutorials/use-forms.md。
• 数据：遵循references/Allay/docs/tutorials/persistent-data-container.md。
• 方块/物品：遵循references/Allay/docs/tutorials/block-api.md和references/Allay/docs/tutorials/item-api.md。

5) 构建和运行

• 当配置了AllayGradle插件时，使用./gradlew runServer进行本地测试。
• 使用./gradlew shadowJar构建阴影化jar包。
• 将build/libs/*-shaded.jar中的jar包复制到Allay服务器的plugins目录中。

6) 故障排除（仅在询问时进行）

• 插件未加载：验证plugin.entrance（或plugin.json入口）、api/api_version以及jar包位置。
• API不匹配：将Gradle中的allay.api版本更新为有效的Allay API发布版本。
• 类未找到：确认包名与group匹配，并且编译后的类名正确。

参考映射（按需加载）

• 模板项目：references/JavaPluginTemplate
  • build.gradle.kts用于Gradle + AllayGradle约定
  • README.md用于模板初始化步骤
  • src/main/java/.../JavaPluginTemplate.java用于生命周期结构
• AllayGradle：references/AllayGradle
  • Gradle插件源代码和配置模式
• Allay源代码和API：references/Allay
  • API入口点：api/src/main/java/org/allaymc/api
  • 教程：docs/tutorials/*.md

输出期望

• 保持Gradle配置、插件元数据和主类同步。
• 针对请求的Allay API版本，并在Gradle元数据中反映出来。
• 除非用户明确需要自定义结构，否则优先使用模板约定。