API 参考 / 事件系统

GameplayEventScope

事件分发作用域。宿主在游玩更新、渲染与事件投递期间进入本作用域，模组在监听器或渲染回调中可读取「当前事件属于哪个会话」，无需给每个事件类增加字段。作用域是 ThreadLocal 的，可嵌套，关闭时恢复上一层。

方法速览

方法	用途
`enter(Supplier<GameplayContext>, String, boolean, String)`	进入作用域（宿主装配面）
`current()`	当前作用域的上下文；不在作用域内返回 `null`
`sessionId()`	当前会话 id；不在作用域内返回 `""`
`preview()`	当前是否预览；不在作用域内返回 `false`
`hostKind()`	当前宿主类型；不在作用域内返回 `"game"`
`context()`	本作用域上下文（每次调用构造新快照）
`close()`	关闭作用域，恢复上一层

enter(Supplier contextSupplier, String sessionId, boolean preview, String hostKind)

java

public static GameplayEventScope enter(java.util.function.Supplier<GameplayContext> contextSupplier,
                                       String sessionId, boolean preview, String hostKind);

行为：宿主装配面。压入一层新作用域并返回它；contextSupplier 是懒构造的上下文，只有调用 current() / context() 时才求值，避免无监听器时为每帧构造快照。sessionId 为 null 时存为 ""，hostKind 为 null 时存为 "game"。模组一般不需要调用它。

current()

java

public static GameplayContext current();

行为：返回当前作用域的上下文（由 supplier 现构造）；不在作用域内返回 null。

sessionId()

java

public static String sessionId();

行为：返回当前会话 id（实机可为空串，编辑器预览如 "viewport-3"）；不在作用域内返回 ""。

preview()

java

public static boolean preview();

行为：当前会话是否为编辑器 / 宿主内嵌预览；不在作用域内返回 false。

hostKind()

java

public static String hostKind();

行为：当前宿主类型（game / editor / cli）；不在作用域内返回 "game"。

context()

java

public GameplayContext context();

行为：返回本作用域的上下文，每次调用都构造新快照（反映调用瞬间的分数 / 连击）。同一监听器内多处使用请存到局部变量，避免重复构造。

close()

java

public void close();

行为：关闭本作用域并恢复上一层；重复调用无副作用（内部 closed 标志）。典型用法是宿主侧的 try-with-resources。

示例

java

ctx.eventBus().subscribe(GameplayTickEvent.Pre.class, event -> {
    // 预览会话不计入本模组的全局统计
    if (GameplayEventScope.preview()) {
        return;
    }
    String session = GameplayEventScope.sessionId();
    GameplayContext snapshot = GameplayEventScope.current();
    if (snapshot == null) {
        return;
    }
    recordTick(session, snapshot.musicTimeMs());
});

完整签名

源码声明为 public final class GameplayEventScope implements AutoCloseable：

java

public final class GameplayEventScope implements AutoCloseable {
    public static GameplayEventScope enter(java.util.function.Supplier<GameplayContext> contextSupplier,
                                           String sessionId, boolean preview, String hostKind);
    public static GameplayContext current();
    public static String sessionId();
    public static boolean preview();
    public static String hostKind();
    public GameplayContext context();
    public void close();
}

线程：ThreadLocal；事件总线与游玩更新都应在同一线程调用。

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

上一页Subscription 下一页TickEvent