开发指南

兼容性与版本

12.1 `Seecmd-Api-Version` 的协商规则

模组在 jar 的 manifest 里声明自己期望的 API 主版本：

声明情况	宿主行为
键缺失 / 为空白	按宿主当前版本处理（不拒绝），老 jar 不因缺键被一刀切
版本串无法解析	拒绝加载，文案为「无法解析模组声明的 API 版本 "X"（期望形如 "3.2"）」
major 不同	拒绝加载（状态 `LOAD_FAILED`），文案为「此模组要求 API X，宿主支持 Y（major 版本不匹配，宿主不保证兼容）」
minor 更高（major 相同）	告警放行：宿主保证 minor 向后兼容，但模组可能引用了宿主没有的新接口
patch 不同	不参与判定

两点补充：

校验发生在创建模组类加载器之前，因此不会出现「加载到一半才炸」的情况；
版本解析容忍 "1.0.0" / "1.0" / ".0" / "1.0-SNAPSHOT" 等写法（去掉前缀 v / V，截断 - 之后的内容）；"1" 视为 1.0；无法解析返回 -1。版本真源与判定逻辑见 ModApiVersion（当前 ModApiVersion.CURRENT = "3.2"）。

com.seecmd.mod.api.* 的公共签名在 2.x / 3.x 内只增不破（1.x 的冻结承诺已在 2.0 兑现过一次破坏性变更：NoteTypeDefinition 的四个布尔旗标改为语义标记子接口；3.0 又删除了每轨旋转圆心参数与常量）：

只允许新增：新接口、新 default 方法、新注册表、新事件、新枚举常量；
禁止：删签名、改签名、改语义；
因此声明 Seecmd-Api-Version 与宿主支持的模组 API 主版本一致的模组始终能加载（当前宿主为 3.2，声明 3.0 / 3.2 均可）；主版本不一致会被按 12.1 拒绝，需按 12.3 迁移后重新声明（3.0 迁移见 API 参考的「2.x → 3.0 迁移对照」）；
少数语义上仍可能微调的成员会在 API 参考里单独标注「实验性」（例如 GameStateAccess 的「轨道几何」区块）——签名稳定，但语义有微调可能。

破坏性变更只在 major 版本发生（已发生 2.0、3.0 两次），且必须同时满足：

换言之，你会先在大版本内看到弃用告警，下一个 major 版本才真正移除；major 变化时旧模组会被宿主按 12.1 的规则明确拒绝加载并给出提示，而不是在中途抛 NoSuchMethodError。

0.7.x 的模组在 1.0 宿主下不会被兼容加载（旧的裸字符串 id、裸路径资源、registerXxx 钩子、双总线等机制都已下线或归一）。逐项对照表、迁移顺序与常见报错见单独的迁移指南：

迁移前的三条速记：注册统一收敛到 onPreInit + ctx.registries()；资源与语言统一走 assets/<模组id>/...；能力与事件分别改走 ctx.capabilities() / ctx.eventBus()。