API 参考 / 事件系统

BeatEvent

游玩帧内，宿主更新完音乐时间 τ 后检测拍序号（BeatGrid 纯函数）是否与上一帧不同，不同即投递一次。每帧至多一次：一帧内大步跨过多个拍点只报最终位置（倒带快退可能发生，监听器应按「直接对齐最终拍」处理，不要假设逐拍连续）。暂停 / 入场过渡期 τ 冻结，不投递。谱面无 BPM 段时按默认 120 BPM 产拍。

方法速览

方法	用途
`beatIndex()`	拍序号（自当前 BPM 段起点，可为负）
`phase()`	投递时刻拍相位 `[0,1)`
`bpm()`	当前 BPM 段的 BPM
`periodMs()`	拍长（毫秒）
`rewinding()`	是否处于倒带重演窗口

beatIndex()

java

public long beatIndex();

行为：返回自当前 BPM 段起点的整拍数，可为负（count-in）。精确定义见 com.seecmd.mod.api.context.BeatGrid#beatIndex(long, double, long)（τ 的纯函数；无节拍信息时返回 -1）。

phase()

java

public double phase();

行为：返回投递时刻的拍相位，范围 [0,1)；跨越后通常接近 0。可用于段内插值（缩放、透明度），不要把相邻两次投递的相位差当作固定步长。

bpm()

java

public double bpm();

行为：返回当前 BPM 段的 BPM。

periodMs()

java

public long periodMs();

行为：返回当前拍长（毫秒），等于 BeatGrid.periodMs(bpm)（round(60000 / bpm)；无节拍信息时返回 0）。

rewinding()

java

public boolean rewinding();

行为：true 表示处于倒带重演窗口，此时 τ 可能倒流并反向跨拍。应与 GameplayTickEvent.rewinding() 同一口径使用：据此重建跟拍演出状态，而不是假设时间只进不退。

示例

java

ctx.eventBus().subscribe(BeatEvent.class, event -> {
    double pulse = 1.0 - event.phase();
    if (event.rewinding()) {
        pulse = 0.0;
    }
    beatPulse = pulse;
});

完整签名

java

public class BeatEvent extends Event {
    public BeatEvent(long beatIndex, double phase, double bpm, long periodMs, boolean rewinding);
    public long beatIndex();
    public double phase();
    public double bpm();
    public long periodMs();
    public boolean rewinding();
}

性能：至多每帧一次，监听器保持轻量。

稳定性：新增，2.x 内只增不破。

上一页GameplayTickEvent 下一页NoteJudgedEvent