游戏生命周期管理

本文档介绍如何通过 SUDRTGameHandle 管理小游戏的生命周期，包括状态监听与状态切换控制。

游戏生命周期管理主要包含两个核心部分：

1. 游戏状态监听（GameStateChangeListener）
2. 游戏状态控制（状态切换接口）

---

概述

SUDRTGameHandle 是游戏运行时的核心控制对象，开发者可以通过该对象：

• 监听游戏状态变化
• 控制游戏运行状态
• 管理游戏资源生命周期

游戏的所有生命周期控制均围绕该对象进行。

---

游戏状态定义

游戏内部定义了以下状态常量：

// SUDRTGameHandle中定义
int GAME_STATE_UNAVAILABLE = 0;
int GAME_STATE_WAITING = 1;
int GAME_STATE_RUNNING = 2;
int GAME_STATE_PLAYING = 3;

状态说明：

状态值	状态名称	描述
0	UNAVAILABLE	游戏运行环境未就绪。GameHandle 刚创建时处于该状态，应在此状态设置启动参数。
1	WAITING	游戏环境已就绪但未运行。通常用于游戏不可见状态。
2	RUNNING	游戏正在运行，但用户不可交互。通常用于界面可见但无焦点。
3	PLAYING	游戏正在运行，用户可交互。正常游戏状态。

---

游戏状态监听

注册监听器

gameHandle.setGameStateListener(listener);

方法说明：

/**
 * 设置小游戏状态变更监听器。
 * 若调用小游戏操作接口时的当前小游戏状态与目标小游戏状态一样，则不会触发回调
 */
void setGameStateListener(SUDRTGameHandle.GameStateChangeListener listener);

---

GameStateChangeListener 定义

public interface GameStateChangeListener {
    /**
     * 状态将要切换时的回调
     * @param fromState 之前状态
     * @param state     当前状态
     */
    void preStateChange(int fromState, int state);

    /**
     * 状态切换成功后回调
     * @param fromState 之前状态
     * @param state     当前状态
     */
    void onStateChanged(int fromState, int state);

    /**
     * 状态切换失败后回调
     * @param fromState 之前状态
     * @param toState   小游戏下个状态
     * @param error     错误信息
     */
    void onFailure(int fromState, int toState, Throwable error);
}

---

游戏状态控制

状态流转关系

UNAVAILABLE → WAITING → RUNNING → PLAYING
                           ↑       ↓
                        WAITING ← RUNNING

---

状态控制接口说明

1. 设置启动参数

gameHandle.setGameStartOptions(gameId, bundle);

说明：

• 应在 GAME_STATE_UNAVAILABLE 状态下调用
• 用于设置游戏启动参数

---

2. 创建游戏实例

gameHandle.create();

状态变化：

UNAVAILABLE → WAITING

说明：

• 初始化游戏运行环境
• 创建游戏实例但不开始运行

---

3. 启动游戏运行

gameHandle.start(null);

状态变化：

WAITING → RUNNING

说明：

• 游戏开始运行
• 用户暂不可交互

---

4. 进入可交互状态

gameHandle.play();

状态变化：

RUNNING → PLAYING

说明：

• 游戏进入正常交互状态
• 用户可以进行操作

---

5. 暂停游戏交互

gameHandle.pause();

状态变化：

PLAYING → RUNNING

说明：

• 游戏仍运行，但暂停用户交互

---

6. 停止游戏运行

gameHandle.stop(null);

状态变化：

RUNNING → WAITING

说明：

• 游戏停止运行
• 保留运行环境

---

7. 销毁游戏

gameHandle.destroy();

状态变化：

ANY → UNAVAILABLE

说明：

• 释放游戏占用的所有资源
• 销毁运行环境

---

关于 SUDOPGameTask.destroy

在通过 SUDOP.startGame 等接口启动游戏时，会返回 SUDOPGameTask。

gameTask.destroy();

说明：

• 本质内部调用的是：

gameHandle.destroy();

• 用于统一管理生命周期
• 推荐优先使用 gameTask.destroy()

---

推荐使用流程

标准生命周期流程

UNAVAILABLE
    ↓ create()
WAITING
    ↓ start()
RUNNING
    ↓ play()
PLAYING

退出流程：

PLAYING
    ↓ pause()
RUNNING
    ↓ stop()
WAITING
    ↓ destroy()
UNAVAILABLE

---

示例代码

gameHandle.setGameStateListener(new SUDRTGameHandle.GameStateChangeListener() {
    @Override
    public void preStateChange(int fromState, int state) {
    }

    @Override
    public void onStateChanged(int fromState, int state) {
    }

    @Override
    public void onFailure(int fromState, int toState, Throwable error) {
    }
});

// 初始化参数
gameHandle.setGameStartOptions(gameId, bundle);

// 创建
gameHandle.create();

// 启动
gameHandle.start(null);

// 可交互
gameHandle.play();

// 暂停
gameHandle.pause();

// 停止
gameHandle.stop(null);

// 销毁
gameHandle.destroy();

---

注意事项

1. 重复状态不会触发回调

如果当前状态与目标状态一致：

不会触发 GameStateChangeListener

---

2. destroy 必须调用

在以下场景必须调用：

• Activity 销毁
• 页面退出
• 游戏切换

否则可能导致：

• 内存泄漏
• 资源未释放
• 后台仍在运行

---

3. UI 生命周期建议

场景	建议操作
页面显示	start()
页面获取焦点	play()
页面失去焦点	pause()
页面隐藏	stop()
页面销毁	destroy()

---

总结

游戏生命周期管理的核心要点如下：

1. 使用 SUDRTGameHandle 作为唯一控制入口
2. 通过 setGameStateListener 监听状态变化
3. 按顺序调用生命周期接口控制游戏状态
4. 在合适时机调用 destroy 释放资源

完整流程：

setGameStartOptions → create → start → play → pause → stop → destroy