事件订阅

模组与宿主之间的“发生了什么”全部经事件总线获得。当前版本把游玩事件与跨场景事件合并到同一条总线上，模组不再需要在多条总线之间做选择，也不需要任何 per-模组的订阅注册回调——在 onInit 里直接订阅即可。

4.1 一条总线

EventBus 是全进程唯一的事件总线，模组在 onInit 中经 ModContext#eventBus() 取得：

• 游玩事件（判定、连击中断、暂停/恢复、游玩帧、游玩输入、轨道渲染等）与跨场景事件（场景切换、启动/关闭、音效播放、设置变更、每帧 tick、资源重载等）都在这一条总线上，模组用事件类型区分自己关心哪一类。
• ctx.eventBus() 返回的实例带模组归属：模组经它建立的全部订阅，在模组停用/卸载时由宿主一次性自动退订，模组不需要自己记账。
• subscribe 返回 Subscription 令牌，需要提前退订时调用 unsubscribe()（幂等，重复调用无副作用）。

订阅与投递的接口声明：

<E extends Event> Subscription subscribe(Class<E> type, EventPriority priority, Consumer<E> listener);
<E extends Event> Subscription subscribe(Class<E> type, Consumer<E> listener);
<E extends Event> E post(E event);

单参数重载等价于使用 EventPriority.NORMAL。同一个监听器实例可以重复注册，每次注册各产生一个独立订阅，各自用返回的 Subscription 退订。

4.2 分发语义

以下契约来自 EventBus 的接口说明，是模组写监听器时必须遵守的前提：

1. 同步投递：post(Event) 在调用线程内当场完成全部分发并返回事件本身。没有异步队列，也没有延迟投递。
2. 匹配规则：按 订阅类型.isInstance(事件) 匹配。订阅 Event 可捕获全部事件；订阅父类可收到其子类（例如订阅 TickEvent 会同时收到 TickEvent.Pre 与 TickEvent.Post，订阅 GameplayTickEvent 同理）。
3. 顺序：先按 EventPriority 降序（HIGHEST 最先收到），同一优先级内按注册顺序（稳定序，可复现）。
4. 短路条件：仅当事件可取消、且已有结论（结果不是 DEFAULT）时，停止通知后续监听器。不可取消事件永远通知全部监听器。
5. 异常隔离：每个监听器独立 try/catch(Throwable)。单个监听器抛异常只记日志，不影响其它监听器，也绝不冒泡到宿主循环——一个模组崩不了游戏。
6. 零订阅零开销：完全无订阅时 post 立即返回（不分配、不遍历）。因此模组可以在需要时随时订阅，不必为“多加一个监听器”担心空闲成本。
7. 线程约定：subscribe / unsubscribe 任意线程可调用（内部加锁）；post 在调用线程同步分发，宿主在游戏线程 / 渲染线程投递，因此监听器回调就在该线程执行。监听器禁止在回调里做阻塞 IO（网络、磁盘、future.get() 等），需要耗时工作请交给自己的线程或宿主提供的线程池。

事件实例的生命周期不属于契约：当前宿主对 TickEvent / GameplayTickEvent 等每帧事件逐帧新建实例，但接口并不保证「每次收到的是新对象」。监听器不得把事件对象存起来跨帧使用——需要的数据请当场读出。

4.3 优先级与结果

EventPriority 的枚举声明顺序即执行顺序，同一优先级内按注册顺序：

EventResult 的取值与总线行为：

干预方式与边界：

• 可取消性由事件在构造期声明，之后不可变。事件基类为 Event，其子类经 protected Event(boolean cancellable) 声明；isCancellable() 的返回值构造时定死。CancellableEvent 是“等价于 extends Event + 构造传 true”的可取消事件基类，见到某个事件继承它，即知 setResult 有效且总线会按结果短路。
• 干预用 setResult(EventResult.DENY) 或 setResult(EventResult.ALLOW)；参数为 null 时视为 DEFAULT。
• 对不可取消事件调用 setResult 是无操作（结果保持 DEFAULT）——纯通知事件不可能靠它让宿主跳过出帧或跳过默认动作。
• 读回结果：result() 返回当前结果；isDenied() / isAllowed() / isDecided()（结果非 DEFAULT，即已有监听器干预）为只读判断。宿主实际按 isDenied()（部分投递点还看改道）决定是否走非默认分支，总线则以 isDecided() 作为短路判据。

注意访问器命名冲突：某些事件的业务结果访问器不叫 result()，例如 NoteJudgedEvent#judgeResult()——基类的 result() 是 final，承载总线结果语义，子类无法覆盖。

4.4 事件总表

补充几点使用要点：

• 可取消事件上干预的“默认动作”具体包含什么由宿主实现定义：例如 PauseEvent 置 DENY 表示跳过本次暂停的默认动作，LaneInputEvent.Pre 置 DENY 表示宿主吞掉该轨道上的这次输入（同一按键映射到的其它轨道不受影响）。注意 KeyEvent 的转播桥只转译、不读取结果，DENY 目前不会改变按键分发；MouseEvent 当前根本未投递——需要拦截按键请用 LaneInputEvent.Pre 或全局快捷键能力。SceneChangeEvent.Pre 还提供 redirect(target) 改道能力（改道后的目标不再二次征询）；只观察请订阅 SceneChangeEvent.Post。
• 想干预判定结果，不要指望 NoteJudgedEvent（它投递时判定已经落地），应改用判定策略 / 判定调整器或自定义判定等级。
• 玩家可见、需要改键的全局快捷键应经 ctx.hotkeys() 注册，不要用 KeyEvent 实现玩家无法改键的隐性快捷键。
• TickEvent / GameplayTickEvent / RenderEvent 都是高频事件，监听器必须保持极轻：禁止分配大对象、禁止阻塞 IO、禁止在渲染回调里做文件或网络访问。
• 上表只列常用事件； / 3.x 另有 BeatEvent、RewindEvent、GhostHitEvent、HitEffectLifecycleEvent、PreviewSeekEvent、SceneUnregisteredEvent（根包）与 host 包的 HostCommandEvent / HostGameResultEvent / HostAudioSpeedEvent，完整时机与访问器见 API 参考。

4.5 订阅与退订

• 幂等：unsubscribe() 重复调用无副作用；调用后该监听器不再收到事件。
• 强引用语义：总线对监听器持有强引用（不依赖 GC 回收）。因此模组必须在 onUnload 释放自己显式建立的长生命周期订阅，否则监听器会持续被调用。
• 模组停用由宿主统一退订：经 ModContext#eventBus() 建立的订阅带模组归属，模组停用 / 卸载时宿主会一次性清理该模组的全部订阅，模组无需自己记账。
• 模组自建的临时订阅应自己退订：只为某一段流程建立的订阅（例如“只在下一局开始前收集一次信息”），应在不再需要时立即 unsubscribe()。

4.6 完整示例：订阅开局与判定事件

下面的模组订阅 2 个游玩事件，在回调里读取 GameplayContext 只读快照，并在 onUnload 显式退订自建订阅。

package com.example.eventmod;

import com.seecmd.mod.api.Mod;
import com.seecmd.mod.api.ModContext;
import com.seecmd.mod.api.ModInfo;
import com.seecmd.mod.api.context.GameplayContext;
import com.seecmd.mod.api.event.EventBus;
import com.seecmd.mod.api.event.EventPriority;
import com.seecmd.mod.api.event.Subscription;
import com.seecmd.mod.api.event.gameplay.GameStartEvent;
import com.seecmd.mod.api.event.gameplay.NoteJudgedEvent;

import java.util.List;

/**
 * 事件订阅示例：一条总线，按事件类型区分。
 *
 * <p>注意所有监听器都在游戏线程被同步调用（事件由宿主投递），
 * 因此回调里只做轻量累加与读取，不做阻塞 IO。
 */
public final class EventExampleMod implements Mod {

    private static final String MOD_ID = "example_events";

    /** 自建的长生命周期订阅：onUnload 时显式退订。 */
    private Subscription judgedSubscription;

    /** 本局已判定音符数。 */
    private int judgedInThisRun;

    /** 本局峰值连击。 */
    private int peakCombo;

    @Override
    public ModInfo info() {
        return ModInfo.of(MOD_ID, "Event Example", "1.0.0", List.of("YourName"),
                "演示在同一总线上订阅游玩事件、读取 GameplayContext 快照与退订");
    }

    @Override
    public void onInit(ModContext ctx) {
        EventBus bus = ctx.eventBus();

        // 订阅 1：开局（记下本局基准信息）。
        // 单参数重载 = EventPriority.NORMAL；返回的 Subscription 不需要时可暂存。
        bus.subscribe(GameStartEvent.class, event -> {
            judgedInThisRun = 0;
            peakCombo = 0;

            // 事件负载是只读快照，读它不会改变游戏状态。
            GameplayContext snapshot = event.context();
            ctx.getLogger().info("本局开始：" + snapshot.chartTitle()
                    + "（难度 " + snapshot.chartDifficulty()
                    + "，总音符 " + snapshot.totalNoteCount() + "）");
        });

        // 订阅 2：音符判定完成（观察型，放 LOW，让干预型监听器先表态）。
        judgedSubscription = bus.subscribe(NoteJudgedEvent.class, EventPriority.LOW, event -> {
            judgedInThisRun++;
            GameplayContext snapshot = event.context();
            peakCombo = Math.max(peakCombo, snapshot.maxCombo());
            if (judgedInThisRun % 25 == 0) {
                ctx.getLogger().info("已判定 " + judgedInThisRun
                        + "，combo=" + snapshot.combo()
                        + "，峰值=" + peakCombo
                        + "，accuracy=" + snapshot.accuracy());
            }
        });
    }

    @Override
    public void onUnload() {
        // 显式释放自建的长生命周期订阅（幂等，重复调用无副作用）。
        // 模组经 ctx.eventBus() 建立的订阅也会由宿主在停用时统一清理，
        // 这里主动退订是为了让释放时机可控、不依赖停用流程。
        if (judgedSubscription != null) {
            judgedSubscription.unsubscribe();
            judgedSubscription = null;
        }
    }
}