API 参考 / spi 包：音符与判定 SPI

JudgeContext

想先跑起来？

这一页是签名与行为参考。自主判定时本类型待判音符的快照。直接做一遍：教程 · 添加新音符类型。

判定上下文：onJudgeTick 收到的只读游玩状态视图，由宿主在回调前构造。模组据此查询本类型待判定音符并自主产出结果。

方法速览

签名：

java

long musicTimeMs();

行为：当前音乐时间（毫秒），与 onJudgeTick 的 timeMs 入参同源。

示例：

java

long now = ctx.musicTimeMs();

签名：

java

int laneCount();

行为：谱面轨道数（谱面未加载时为 1）。

示例：

java

int lanes = ctx.laneCount();

签名：

java

List<NoteView> notes();

行为：本类型待判定音符的只读快照——即注册为该定义对象、且「未整体判定、长按起点未判定、非幽灵」的音符，顺序与宿主待判定队列一致（正常游玩即时间升序）。

实现事实：宿主每帧为每个接管类型构造一次列表并用不可变包装固定，notes() 直接返回同一实例（不是每次调用新建）。因此应在回调开头取一次存局部变量，不要每帧反复调用；列表只在该帧回调内有效。

示例：

java

List<NoteView> notes = ctx.notes();   // 本帧只取一次
for (NoteView n : notes) {
    long delta = timeMs - n.time();
}

java

public interface JudgeContext {

    long musicTimeMs();

    int laneCount();

    List<NoteView> notes();
}

线程：源码未声明额外线程约束；宿主在游玩更新线程每帧构造并同步传入。

生命周期阶段：运行期每帧判定回调内使用。

稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名/改签名/改语义）。