API 参考 / 入口与生命周期

ModApiVersion

宿主支持的模组 API 版本，是版本语义的唯一真源。当前 CURRENT = "3.2"。版本声明位置：模组 jar 的 manifest 键 Seecmd-Api-Version（可选）。校验发生在创建模组类加载器之前，不合规的 jar 根本不会被加载。

方法速览

方法	用途
`CURRENT`	宿主当前 API 版本（`"3.2"`）
`DEPRECATED_UNTIL`	已弃用 API 的最后可用版本（`"1.0"`）
`currentMajor()`	`CURRENT` 的 major 号
`majorOf(String)`	解析 major 号；失败 `-1`
`minorOf(String)`	解析 minor 号；失败 `-1`
`check(String)`	判定声明版本是否可加载

完整签名

java

public final class ModApiVersion {

    public static final String CURRENT = "3.2";

    public static final String DEPRECATED_UNTIL = "1.0";

    public static int currentMajor();

    public static int majorOf(String version);

    public static int minorOf(String version);

    public static Compatibility check(String declaredVersion);
}

java

public final class Compatibility { // ModApiVersion 的静态嵌套类

    public final boolean allowed;

    public final boolean warn;

    public final String message;
}

currentMajor()

签名：

java

public static int currentMajor();

行为：返回 CURRENT 的 major 号（当前为 3）。等价于 majorOf(CURRENT)。

示例：

java

int major = ModApiVersion.currentMajor();   // 3

majorOf(String version)

签名：

java

public static int majorOf(String version);

行为：解析版本串的 major 号；无法解析返回 -1。容忍 "1.0.0" / "1.0" / ".0" / "V1.0" / "1.0-SNAPSHOT"：去掉前缀 v / V，截断首个 - 之后内容；"1" 视为 1.0。null 或非数字段返回 -1。

示例：

java

int major = ModApiVersion.majorOf(".2.1");   // 3

minorOf(String version)

签名：

java

public static int minorOf(String version);

行为：解析 minor 号；只有 major 段（如 "3"）时返回 0；无法解析（含 null、非数字）返回 -1。patch 段不参与。

示例：

java

int minor = ModApiVersion.minorOf("3.2.7");   // 2

check(String declaredVersion)

签名：

java

public static Compatibility check(String declaredVersion);

行为：判断模组声明的 API 版本是否可加载。null / 空白按 CURRENT 处理（允许，无告警）。

情形	判定
键缺失 / 为空白	按 `CURRENT` 处理（不拒绝）。这样「忘写版本」的老模组不会一律被拒之门外；而 1.0 之前编译的老模组会在链接期因找不到已删除的 API 类型而失败，报错文案由类加载器给出（比 `NoSuchMethodError` 崩溃可读得多）
版本串无法解析（major 或 minor 得到 `-1`）	拒绝加载，文案为「无法解析模组声明的 API 版本 "X"（期望形如 "3.2"）」
major 不等	拒绝加载（`LOAD_FAILED`），错误文案给出「此模组要求 API X，宿主支持 3.2（major 版本不匹配，宿主不保证兼容）」
minor 更高（major 相同）	记录告警但加载：宿主保证 minor 向后兼容（模组按更高的 minor 编写、宿主是更低 minor 时，模组可能引用了宿主没有的新接口）
patch 差异	不参与判定

Compatibility 字段语义：allowed 是否允许加载；warn 是否应记录告警（允许加载但存在风险，或版本更高）；message 为拒绝原因 / 告警文案，无则 null。其构造器为包内可见，模组只读字段。

拒绝发生在 jar 注册之前，因此该模组不会出现在 registered 中，但会以 manifest 的 Seecmd-Mod-Id（缺失时用 jar 文件名）记为 LOAD_FAILED，getLoadError 可读到原因。

示例：

java

ModApiVersion.Compatibility c = ModApiVersion.check("3.0");
if (!c.allowed) {
    ctx.notifier().error(c.message);
} else if (c.warn) {
    ctx.getLogger().warning(c.message);
}

DEPRECATED_UNTIL

签名：

java

public static final String DEPRECATED_UNTIL = "1.0";

行为：标注为 @Deprecated 的旧 API 的最后一个可用版本，仅用于文档与错误文案（「此 API 已在 1.1 弃用」）；当前无弃用项。

示例：

java

String until = ModApiVersion.DEPRECATED_UNTIL;   // "1.0"

CURRENT

签名：

java

public static final String CURRENT = "3.2";

行为：宿主当前支持的 API 版本。3.2 在 3.0（3D-native 收口）基础上加入预览会话身份 / 事件作用域 / PreviewSeekEvent 等增量能力。

示例：

java

ctx.getLogger().info("mod-api " + ModApiVersion.CURRENT);

1.x 内的承诺：com.seecmd.mod.api.* 的公共签名自 1.0 起承诺在 1.x 内只增不破——只允许新增（新接口、新 default 方法、新注册表、新事件），禁止删签名 / 改签名 / 改语义。该承诺已按约在 2.0 兑现终止（首个破坏性变更：NoteTypeDefinition 旗标 → 语义子接口，见「1.x → 2.0 迁移对照」）。

2.x → 3.0 迁移警告：3.0 删除了 2D 时代残留几何参数——GameStateAccess.setLaneRotation / ExtraContentApi.setLaneRotation 的 pivot 圆心参数与 LANE_ROTATE_PIVOT_* 常量（圆心固定判定线中点）、ExtraContentApi.setLaneZ 与 setFakeTrackZ（画家算法层级已删除）、createFakeTrack 的 z 参数。迁移对照见 API 参考「2.x → 3.0 迁移对照」。后续破坏性变更同样只随 major 版本发生，且须提供迁移指南。

线程：源码未声明额外线程约束（全部为静态纯函数与静态常量）。

稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名 / 改签名 / 改语义）；首个破坏性变更随 2.0 发生（NoteTypeDefinition 旗标 → 语义子接口，见「1.x → 2.0 迁移对照」），3.0 发生第二次（见上），后续破坏性变更只随 major 版本发生且须提供迁移指南；3.x 内继续只增不破。

上一页MissingDependencyException 下一页registry 包：注册表与资源标识