setGameStateListener

设置小游戏状态变更监听器

setGameStateListener 用于监控小游戏在不同运行阶段之间的状态切换。由于小游戏的资源加载、脚本启动和环境销毁都是耗时的异步操作，宿主 App 必须通过此监听器来获取切换结果，以便同步更新 UI（如显示加载动画、隐藏封面图或处理异常报错）。

---

方法声明

/**
 * 设置小游戏状态变更监听器。
 * 若当前状态与目标状态一致，则监听器不会被触发。
 *
 * @param listener 状态变更监听器实例
 */
void setGameStateListener(SUDRTGameHandle.GameStateChangeListener listener);

内部接口定义

public interface GameStateChangeListener {
    /** 状态将要切换时的回调 */
    void preStateChange(int fromState, int toState);

    /** 状态切换成功后回调 */
    void onStateChanged(int fromState, int toState);

    /** 状态切换失败后回调（例如资源损坏、内存不足等） */
    void onFailure(int fromState, int toState, Throwable error);
}

---

状态机转换图

了解状态如何流转是使用此监听器的核心：

• UNAVAILABLE (0): 初始状态。
• WAITING (1): 环境就绪。调用 create() 后到达。
• RUNNING (2): 脚本运行。调用 start() 后到达。
• PLAYING (3): 交互开启。调用 play() 后到达。

---

代码示例

gameHandle.setGameStateListener(new SUDRTGameHandle.GameStateChangeListener() {
    @Override
    public void preStateChange(int fromState, int toState) {
        // 示例：当准备进入 RUNNING 状态时，显示 Loading 遮罩
        if (toState == SUDRTGameHandle.GAME_STATE_RUNNING) {
            showLoadingSpinner();
        }
    }

    @Override
    public void onStateChanged(int fromState, int toState) {
        Log.i("SUDOP", "State changed from " + fromState + " to " + toState);
        
        if (toState == SUDRTGameHandle.GAME_STATE_RUNNING) {
            // 脚本启动成功，关闭加载动画，正式让游戏进入输入态
            hideLoadingSpinner();
            gameHandle.play();
        }
    }

    @Override
    public void onFailure(int fromState, int toState, Throwable error) {
        // 关键：处理启动失败，例如弹窗提示用户
        Log.e("SUDOP", "Failed to switch state: " + error.getMessage());
        showErrorMessage("游戏启动失败，请稍后重试");
    }
});

---

注意事项

• 幂等性：如果你尝试切换到一个游戏已经处于的状态（例如游戏已经是 RUNNING，你又调用了 start()），此监听器不会被触发。
• 主线程操作：虽然 SDK 内部会处理状态切换，但 onStateChanged 回调通常在工作线程执行。若需操作 UI（如隐藏 View），请务必通过 Activity.runOnUiThread() 进行。
• 错误处理：onFailure 是捕获引擎级错误（如 JS 脚本崩溃、核心资源加载异常）的最直接途径，请务必在此处实现业务逻辑的闭环（如退出 Activity 或重试）。

---