setGameStateListener

设置游戏状态变更监听器

setGameStateListener 用于注册游戏引擎生命周期状态的监听接口。当小游戏在初始化、加载、运行及播放等各个阶段进行切换时，SDK 会通过该监听器实时通知宿主 App，是原生层控制 UI 展示（如显示加载动画、挂载 View、处理暂停/恢复）的核心依据。

---

方法声明

/**
 * 设置游戏状态监听。
 * @param listener 遵循 SUDRTGameStateChangeListener 协议的对象。
 */
- (void)setGameStateListener:(nullable id<SUDRTGameStateChangeListener>)listener;

---

参数说明

参数名	类型	必传	描述
listener	id<SUDRTGameStateChangeListener>	否	监听器实例。传入 nil 则取消监听。

---

运行行为

1. 自动触发：当执行 create、start、pause、play 或 destroy 操作导致引擎内部状态机发生变化时，回调立即触发。
2. 顺序保障：回调会明确告知转换前的状态（fromState）和当前的新状态（toState）。
3. 驱动业务：App 通常在监听到 WAITING 时挂载视图，在监听到 PLAYING 时隐藏原生 Loading 遮罩。

---

代码示例

通过监听状态流转，实现完整的游戏加载与显示逻辑：

// 1. 实现协议
@interface GameViewController () <SUDRTGameStateChangeListener>
@end

@implementation GameViewController

- (void)setupStateListener {
    // 2. 注册监听
    [self.gameHandle setGameStateListener:self];
}

#pragma mark - SUDRTGameStateChangeListener

- (void)onStateChangedFrom:(int)fromState to:(int)toState {
    NSLog(@"[SUD] 状态变更: %d -> %d", fromState, toState);
    
    // 3. 必须在主线程处理相关 UI
    dispatch_async(dispatch_get_main_queue(), ^{
        switch (toState) {
            case SUD_RT_GAME_STATE_WAITING:
                // 环境就绪，挂载游戏 View
                [self mountGameView];
                break;
                
            case SUD_RT_GAME_STATE_PLAYING:
                // 游戏正式开始播放，隐藏加载图
                self.loadingView.hidden = YES;
                break;
                
            case SUD_RT_GAME_STATE_UNAVAILABLE:
                // 引擎已销毁，清理资源
                [self.gameView removeFromSuperview];
                break;
                
            default:
                break;
        }
    });
}

@end

---

注意事项

• 早期绑定：建议在调用 create 之前就设置好监听器，以确保捕获从 UNAVAILABLE 到 WAITING 的第一个关键状态跳变。

• 状态值对应：

• 0: UNAVAILABLE (不可用)

• 1: WAITING (等待中/已暂停)

• 2: RUNNING (脚本运行中/后台加载)

• 3: PLAYING (交互播放中)

• 幂等性处理：如果多次执行同一指令导致状态未发生实际改变，此监听器不会重复触发。

• UI 线程：状态变更回调可能来自引擎的工作线程，所有操作 UI 的代码必须包裹在 dispatch_get_main_queue() 中。

---