API 参考 / 事件系统

Event

想先跑起来？

这一页是签名与行为参考。所有事件的基类，注意结果与取消的边界。直接做一遍：教程 · 订阅游玩事件。

所有事件的公共基类。可取消性在构造期由子类经 protected Event(boolean cancellable) 声明，之后不可变；结果由总线在分发时读取。事件实例可能被宿主复用（每帧类事件曾如此设计，当前 tick 类事件已改为逐帧新建），因此监听器不得缓存事件对象，需要的数据当场读出。

方法速览

方法	用途
`isCancellable()`	本事件是否可取消（构造期定死）
`result()`	当前结果，默认 `DEFAULT`
`setResult(EventResult)`	设置结果；不可取消事件上是无操作
`isDenied()`	结果是否为 `DENY`
`isAllowed()`	结果是否为 `ALLOW`
`isDecided()`	结果是否非 `DEFAULT`（总线短路判据）

isCancellable()

java

public final boolean isCancellable();

行为：返回构造期声明的可取消性，不可变。true 表示宿主对该事件确实存在「可选默认动作」，setResult 有效且总线会按结果短路；false 表示纯通知。

示例：

java

if (!event.isCancellable()) {
    return;
}

result()

java

public final EventResult result();

行为：返回当前结果，初始为 EventResult.DEFAULT。宿主要在 post 返回后读回它来决定是否走非默认分支（实际实现多读 isDenied()）。

setResult(EventResult result)

java

public final void setResult(EventResult result);

行为：对可取消事件写入结果，参数 null 视为 DEFAULT；对不可取消事件是无操作（结果保持 DEFAULT），模组不可能靠它让宿主跳过出帧或跳过默认动作。宿主读取的是 isDenied()（有的投递点还读 isRedirected()），所以正常用法是 DENY 表示「跳过本次默认动作」，ALLOW 表示「提前下定论：放行」并阻止后续监听器再投 DENY。

示例：

java

ctx.eventBus().subscribe(PauseEvent.class, EventPriority.HIGH, event -> {
    if (isCutscenePlaying()) {
        event.setResult(EventResult.DENY);
    }
});

isDenied()

java

public final boolean isDenied();

行为：result() == EventResult.DENY。宿主用它决定是否跳过默认动作（例如暂停、切场、吞轨道输入）。

isAllowed()

java

public final boolean isAllowed();

行为：result() == EventResult.ALLOW。

isDecided()

java

public final boolean isDecided();

行为：result() != EventResult.DEFAULT，即已有监听器干预。这是总线短路判据：可取消事件在结果非 DEFAULT 后不再通知后续监听器。

完整签名

java

public abstract class Event {
    protected Event(boolean cancellable);
    public final boolean isCancellable();
    public final EventResult result();
    public final void setResult(EventResult result);
    public final boolean isDenied();
    public final boolean isAllowed();
    public final boolean isDecided();
}

线程：无额外线程约束；结果字段由宿主在投递线程写入与读取。

稳定性：2.0 起冻结，2.x 内只增不破。

上一页事件总表下一页EventResult