构建、IDEA 与贡献

工具要求

• Git；
• JDK 21；
• 仓库自带 Gradle Wrapper；
• IntelliJ IDEA（可选）；
• 首次解析依赖所需网络。

项目固定 Kotlin 2.3.21、TabooLib Gradle 2.0.38，JVM target/toolchain 21，编译警告视为错误。

获取与构建

git clone https://github.com/Seal959/SealItems.git
Set-Location SealItems
./gradlew clean check --rerun-tasks

依赖已缓存且锁完整时可用：

./gradlew clean check --rerun-tasks --offline

不要第一次构建就加 --offline。

最终插件 JAR：

sealitems-plugin/build/libs/SealItems-0.1.0-SNAPSHOT.jar

API JAR：

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

版本改变时文件名随之改变。

check 做什么

除了六模块测试，还检查：

• 模块依赖只能沿批准方向；
• compileOnly SealAttributes API artifact 的固定哈希；
• 最终 JAR 有且只有一个 plugin.yml；
• 必需默认资源和 ArcartX 模板存在；
• 不打入 Bukkit、TabooLib、SealAttributes、Vault、PlayerPoints、MythicMobs、ArcartX 类；
• 明确 folia-supported: false；
• 五个 softdepend 存在；
• JAR 条目顺序/时间戳可复现。

只运行 compileKotlin 不能替代根 check。

IDEA 正确导入

1. 用 IDEA 打开仓库根目录，不是单独某个模块。
2. Gradle JVM 选择 JDK 21。
3. Gradle distribution 选择 Wrapper。
4. 等待 Gradle Sync 完成。
5. 在 Gradle 工具窗口运行根 check。

如果 CLI 通过但编辑器仍红：

1. 看 Gradle Sync 第一处错误。
2. 点击 Reload All Gradle Projects。
3. 检查项目 SDK、Gradle JVM 都是 21。
4. 确认 libs/sealattributes-api-1.0.9.jar 存在且未被替换。
5. 确认 dependency lock 和 verification-metadata.xml 未丢失。
6. 必要时再修复 IDEA 缓存/索引；不要先删锁文件绕过校验。

“命令行绿色”与“IDEA 模型恢复”是两项独立验收，二者都应通过。

依赖锁

正常开发不要随意重写锁。明确升级依赖时才运行类似：

./gradlew resolveAndLockAll --write-locks

依赖校验元数据也必须随真实升级更新并审查，不要为了让构建通过而关闭验证。

开发约定

• API 变更先定义兼容边界与失败模型。
• Core/Gameplay 优先纯 Kotlin 测试。
• Paper 写操作要测试冲突、回滚、背包满、玩家离线和 provider UNKNOWN。
• YAML 新字段要有严格 reader、默认资源、合法/非法边界测试和 Wiki 更新。
• 不把测试夹具或计划中的功能写成已发布能力。
• 不在 PR 中提交 build 产物、真实服务器世界或密钥。

提交前

./gradlew clean check --rerun-tasks
git diff --check
git status --short

然后在干净 Paper/Leaf 测试服验证启动、/si health、改动对应玩法和正常停服。自动测试、真实服验证和正式发布要分别报告，不能互相代替。