API 参考

com.seecmd.mod.api 全部接口的分类导航、稳定性策略与迁移对照（唯一权威签名见各类型页）

# Theseus 模组 API 参考（mod-api 3.2）

适用版本：mod-api 3.2（随游戏当前版本发布） 文档语言：中文 对应包：com.seecmd.mod.api 及其子包 registry / spi / event / render / resource / language / capability / context / scene / audio / text / judge / collect

文档定位：本页是 API 总览（版本策略、迁移对照、常见报错）；每个类型的详细参考（签名 / 行为 / 示例）各成一页，按分类挂在左侧目录的「API 参考」下。全部接口均已落地并接入宿主核心循环；文档签名与源码逐字一致，并经签名快照（verify/api-surface.txt）机械校验，出现分歧以源码与快照为准，文档随之修正。 上手路径与完整示例见 模组开发指南；从 0.7.x 旧 API 迁移的逐项对照表随源码仓库提供（1.0 迁移指南），未在文档站发布。

怎么读这份文档

• 只写模组：从「开发指南」的入门页开始，再按需要跳到「API 参考」的各分类。
• 查类型：左侧目录「API 参考」按包分类列出全部类型页；每页给「用途 / 方法速览 / 逐方法签名与行为 / 示例」。
• 查报错：见下文「常见报错与排查」。
• 稳定性：com.seecmd.mod.api.* 的公共签名在当前 major 线内只增不破，详见「稳定性与版本策略」。

分类导航

包结构与依赖边界

包布局

依赖边界（强制）

模组编译期只依赖 com.seecmd:mod-api 这一个构件（对应发布物 mod-api-3.2.jar，版本随宿主演进）。该构件的边界由 verify/ApiBoundaryCheck.java 在每次校验中强制：

• API 源码不得引用 javafx.* / org.lwjgl.* / org.joml.* / javax.imageio.* 等实现导向类型；
• java.awt 只放行纯值对象 java.awt.Color；
• com.seecmd 命名空间下只允许 API 自己（不允许把内核类型泄漏进对外 API）。

唯一的例外是 gson：NoteTypeDefinition#deserialize 等契约以 com.google.gson.JsonObject 暴露，模组侧以 provided 引入（运行期由宿主提供）。模板工程的 build.bat 会自动定位 gson-*.jar（同目录优先，其次本地 Maven 仓库）。

稳定性与版本策略

3.x 内的承诺

com.seecmd.mod.api.* 的公共签名自 3.0 起冻结：

• 只允许新增：新接口、新 default 方法、新注册表、新事件、新枚举常量；
• 禁止：删签名、改签名、改语义；
• 破坏性变更只在 major 版本发生，且必须提供迁移指南与至少一个大版本的弃用期（@Deprecated + 告警）。

因此 API 类型上不再有「实验性」标注：凡是出现在类型页里的签名，都是 3.x 内不会破坏的承诺面。少数语义上仍可能微调的成员会在其小节里单独指出。

历史沿革：1.x 的只增不破承诺已按约在 2.0 兑现终止（NoteTypeDefinition 的四个行为旗标方法删除、改为语义标记子接口）；2.x 的承诺在 3.0 兑现终止——3.0（3D-native 收口）删除 2D 几何残留参数（旋转 pivot 模式枚举、setLaneZ/setFakeTrackZ、createFakeTrack 的 z）；对照均见下文迁移对照。3.0 起进入新的 3.x 只增不破线。

1.x → 2.0 迁移对照（内置类型真实现化）

变化：行为分类从「NoteTypeDefinition 的四个 default 布尔旗标」改为「四个语义标记子接口」。内置五类型不再是空壳：判定/渲染/解析与模组类型走同一条分派管道（isBuiltinContent 命名空间门摘除，判据改为 BuiltinContent 身份标记——宿主内部概念，模组无感）。

旗标 → 子接口映射：

迁移前后对照：

// 1.x                                              // 2.0
public final class GripNote                         public final class GripNote
        implements NoteTypeDefinition {                     implements HoldNoteType {
    @Override public boolean isHold() {     →          // 语义由标记声明，删掉旗标方法
        return true;                                   // 其余（deserialize/render/...）不变
    }                                              }
}                                                   // 上下等价；标记子接口仍是 NoteTypeDefinition

• 迁移是机械替换：删掉旗标方法 override，把 implements NoteTypeDefinition 换成对应标记子接口（可再叠加其它接口）；编译器会逐个指出残留的 @Override isHold() 等错误。
• 只实现标记、不再有方法：本批四个子接口均为空标记（后续可加配置方法，只增不破）。
• model.NoteData（宿主侧）与 context.NoteView（模组侧只读视图）的 isHold()/isBarrier()/isExploit()/isPayload() 只读方法保留，语义不变——模组侧判断代码零改动。
• 内置 seecmd:hold/barrier/exploit/payload 即按此声明（normal 无任何标记）；解析期 deserialize 对内置类型返回 null（实现决策：内置主体由 Gson 直构，无 runtimeData 需求）。
• manifest 键 Seecmd-Api-Version: 1.0 需改为 2.0（major 不匹配会拒绝加载）；缺键的模组按当前版本处理，但只要引用了被删方法，就会在编译期暴露。

1.x → 2.0 迁移对照（内置模式真实现化）

变化：内置游戏模式（seecmd:normal/autoplay/disorder）从「注册表放无行为描述符 + 场景内部类换实例」的双轨结构，改为注册表即活实例——注册表持有的就是被宿主 activeMode 持有的运行对象，内置/模组模式走同一条模式回调管道（无序机制的引擎驱动、专用输入分支、终点/Barrier/Payload 判定全部归位到模式对象，宿主不再旁路直调）。同时删除幽灵扩展点 GameModeDefinition.overridesJudgment()。

模组侧影响：零迁移成本——本批破坏面只有一条全仓无调用的 @Deprecated 幽灵方法，行为分类与本接口的其余成员不变：

宿主侧语义锚点（模组可观测的等价性）：

• 注册表 gameModes().get(seecmd:autoplay) 取出的对象与宿主激活模式为同一实例（运行时绑定，e2e 有身份断言）。
• 内置模式的无序机制（谱面 disorderMarkers 驱动，与所选模式正交）在模组模式激活期间同样工作——引擎驱动作为常驻模式挂点分发，与 1.x 行为逐毫秒一致。
• mapLane / mirrorsPlayfield / onHandleInput 消费次序不变：先当前激活模式，后无序机制窗口，最后常规输入。

2.x → 3.0 迁移对照（三期 3D-native 收口：删除 2D 几何残留参数）

变化：三期把渲染管线统一到 3D-native 后，2D 时代的几何残留参数已无执行体，随 3.0 一次性删除（不保留兼容别名）。动机：画家算法 z 层级（P-3 DN3-1）与"旋转圆心模式枚举"（P-3 DN3-3）都已从渲染器删除，接口若继续保留则只剩"传了也不生效"的假参数，会误导模组作者。

仓内迁移样本：mods-aimtrack 的 3 处 setLaneRotation(..., LANE_ROTATE_PIVOT_JUDGE_LINE) 改为两参调用、2 处 setLaneOffset(x, y) 补 0；官方示例模组 的 setLaneOffset 补 0、setNoteTransform 按 rollDeg = toDegrees(NOTE_ROT) 改写。以上均为签名适配，行为零变化。

不变：getLaneRotation / laneRotationPivot / trackAreaGeometry / setLaneScale / setLaneSkew / setLaneArc / setTrackOffset / EntityPose / MatrixStack 的签名与语义均不变（laneRotationPivot 的坐标口径自 2026-10-17 起为世界坐标：含单轨 lane_pose 偏移、不含 setTrackOffset；真轨本地 (0,0,0) = 世界原点）。setLaneOffset 与 setNoteTransform 属于扩展（新增 z / 三轴旋转），旧调用补 0 即可。

API 版本协商（manifest 键 Seecmd-Api-Version）

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

校验发生在创建模组类加载器之前，因此不会出现"加载到一半才炸"的情况。校验逻辑与版本真源见 ModApiVersion。

类加载隔离

每个模组 jar 由宿主的独立类加载器加载，规则是：

• java.* / javax.* / jdk.* / sun.* / com.sun.* / com.seecmd.mod.api.* / com.google.gson.* 交给父加载器；
• 其余类优先在模组自己的 jar 内查找（因此模组可以用 com.seecmd.mod.<自己的 id> 这样的包名）；
• 未命中且属于 com.seecmd.* 的类（即宿主/内核实现）→ 抛「内核访问被拒绝」。

含义：模组看不到也拿不到内核实现类，只能通过本文的 API 交互。若你确实需要宿主做某件事，正确的做法是走能力接口提出需求，而不是尝试反射内核。

常见报错与排查

与 0.7.x 旧 API 的差异

0.7.x 的模组在 1.0 宿主下不会被兼容加载。逐项对照表、迁移顺序与常见报错见单独的迁移指南：

• 1.0 迁移指南（源码仓库内文档）—— 旧 → 新 逐项对照与迁移步骤

类型速览