API 参考 / 事件系统

SceneChangeEvent

场景切换事件的基类，两个时序：

SceneChangeEvent.Pre：切换的决议阶段（历史栈尚未改动），可取消，也可改道。
SceneChangeEvent.Post：切换完成之后（新场景已进入），纯通知。

方法速览

方法	用途
`from()` / `to()`	当前场景名 / 目标场景名（`Pre` 为 `String`，`Post` 为 `SceneInfo`）
`kind()`	切换种类 `PUSH` / `REPLACE` / `BACK`
`params()`	本次切换的参数表
`redirect(String)`	改道到目标场景，沿用原参数
`redirect(String, Map<String, Object>)`	改道并替换参数
`isRedirected()`	是否已改道
`redirectTarget()`	改道目标（未改道为 `null`）
`redirectParams()`	改道参数（`null` 表示沿用原参数）

from()

java

public String from();

行为：Pre 返回当前场景名；Post 返回切换前场景的 SceneInfo（见 SceneChangeEvent.Post 的完整签名）。

to()

java

public String to();

行为：Pre 返回原始目标场景名。改道后仍返回原始目标，改道目标请读 redirectTarget()。Post 返回切换后的 SceneInfo。

kind()

java

public Kind kind();

行为：返回切换动作种类。构造参数为 null 时按 Kind.REPLACE 处理。

params()

java

public Map<String, Object> params();

行为：返回本次切换的参数表；构造参数为 null 时是空表。改道后的新参数请读 redirectParams()。

redirect(String target)

java

public void redirect(String target);

行为：改道到 target 并沿用原参数，等价于 redirect(target, null)。target 为 null 或空白串时忽略（不产生改道）。宿主收到改道决策后直接切到目标场景，不再对改道目标二次征询（防环）。改道不会自动设置 EventResult，所以不会短路后续监听器。

示例：

java

ctx.eventBus().subscribe(SceneChangeEvent.Pre.class, EventPriority.HIGH, event -> {
    if ("gameplay".equals(event.to()) && isMaintenanceMode()) {
        event.redirect("main_menu");
    }
});

redirect(String target, Map params)

java

public void redirect(String target, Map<String, Object> params);

行为：改道并替换参数；params 为 null 表示沿用原参数。target 为 null 或空白串时忽略。

isRedirected()

java

public boolean isRedirected();

行为：redirectTarget() != null。

redirectTarget()

java

public String redirectTarget();

行为：返回改道目标；未改道返回 null。

redirectParams()

java

public Map<String, Object> redirectParams();

行为：返回改道参数；null 表示沿用原参数。

示例：否决与改道

java

ctx.eventBus().subscribe(SceneChangeEvent.Pre.class, EventPriority.HIGHEST, event -> {
    if (SceneChangeEvent.Kind.BACK.equals(event.kind()) && isModalOpen()) {
        // 否决返回：当前场景不退栈
        event.setResult(EventResult.DENY);
    }
});

完整签名

java

public abstract class SceneChangeEvent extends Event {
    protected SceneChangeEvent(boolean cancellable);

    public enum Kind {
        PUSH,
        REPLACE,
        BACK
    }

    public static final class Pre extends SceneChangeEvent {
        public Pre(String from, String to, Kind kind, Map<String, Object> params);
        public String from();
        public String to();
        public Kind kind();
        public Map<String, Object> params();
        public void redirect(String target);
        public void redirect(String target, Map<String, Object> params);
        public boolean isRedirected();
        public String redirectTarget();
        public Map<String, Object> redirectParams();
    }

    public static final class Post extends SceneChangeEvent {
        public Post(SceneInfo from, SceneInfo to);
        public SceneInfo from();
        public SceneInfo to();
    }
}

行为核验：宿主在历史栈变更之前投递 Pre；isDenied() 为真则放弃本次切换（BACK 时连出栈都不发生）；否则 isRedirected() 为真则按改道目标（及参数）执行。Post 由 SceneManager 的切换完成回调统一投递，宿主自身切换与模组触发的切换都会投递。

线程：场景栈所在线程（GL 侧为渲染线程）。

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

上一页TickEvent 下一页SoundPlayEvent