API 参考 / 事件系统

PreviewSeekEvent

预览会话完成一次确定性跳转（重置 + 正推）之后、下一次正常 Tick 之前投递一次。跳转期间的 GameplayTickEvent.rewinding() 仍为 true；本事件给出明确的起点 / 终点 / 原因 / 代次，状态型模组应在此清空或重建累计状态（粒子、轨迹、缓存）。EventPolicy.SILENT 的会话不投递本事件。

方法速览

方法	用途
`fromMs()` / `toMs()`	跳转起点 / 终点（毫秒）
`reason()`	跳转原因
`generation()`	同一会话内单调递增的代次
`context()`	跳转完成后的上下文
`durationMs()`	跳转跨度（可为负）

fromMs()

java

public long fromMs();

行为：返回跳转起点（毫秒）。首次跳转时取 0。

toMs()

java

public long toMs();

行为：返回跳转终点（毫秒），已被钳为非负。

reason()

java

public Reason reason();

行为：返回跳转原因（OPEN / SCRUB / LOOP / CHART_EDIT / RESUME / RELOAD）。构造参数为 null 时按 SCRUB 处理。

generation()

java

public long generation();

行为：返回同一会话内单调递增的代次；模组可据此丢弃旧代次的异步结果。

context()

java

public GameplayContext context();

行为：返回跳转完成后的上下文（sessionId() / preview() 与当前会话一致）。

durationMs()

java

long durationMs();

行为：返回 toMs - fromMs，可为负（向后拖动播放头）。

示例

java

ctx.eventBus().subscribe(PreviewSeekEvent.class, event -> {
    long gen = event.generation();
    if (gen < lastHandledGeneration) {
        return;
    }
    lastHandledGeneration = gen;
    clearTransientParticles();
});

完整签名

java

public class PreviewSeekEvent extends Event {
    public enum Reason {
        OPEN,
        SCRUB,
        LOOP,
        CHART_EDIT,
        RESUME,
        RELOAD
    }

    public PreviewSeekEvent(long fromMs, long toMs, Reason reason, long generation,
                            GameplayContext context);
    public long fromMs();
    public long toMs();
    public Reason reason();
    public long generation();
    public GameplayContext context();
    public long durationMs();
}

行为核验：仅预览会话投递；宿主在重置运行时、正推到目标时刻之后，先补发一对 rewinding = true 的 Pre / Post tick，再投递本事件，最后恢复正常 Tick。

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

上一页HitEffectLifecycleEvent 下一页KeyEvent