preLoadGame

预加载游戏（通过游戏 ID）

preLoadGame 方法比预下载更进一步。它不仅会确保游戏资源已下载到本地，还会提前完成运行时环境的初始化、脚本引擎的加载以及首屏资源的解码。

该接口适用于用户处于“游戏准入”阶段（如点击了游戏入口但尚未点击正式“开始”）的场景，能够极大缩短用户点击“开始”到看到游戏画面的等待时间。

---

方法声明

/**
 * 预加载游戏，根据游戏 ID
 *
 * @param gameID   gameID
 * @param listener 预加载状态监听器
 * @return SUDOPGameTask 任务句柄，可用于管理或销毁预加载任务
 */
public static SUDOPGameTask preLoadGame(String gameID, SUDOPPreLoadGameListener listener);

---

参数说明

用于指定预加载的目标：

属性	类型	描述
gameId	String	必填。需要预加载的游戏唯一标识。

SUDOPPreLoadGameListener

用于接收预加载结果的回调：

• void onSuccess(String gameId, SUDRTGameHandle handle)：预加载完成。

• gameId：游戏标识。

• handle：游戏实例句柄，此时游戏已在后台完成初始化。

• void onFailure(int retCode, String retMsg)：预加载失败。可能原因包括内存不足、资源加载错误或环境冲突。

---

运行行为

1. 资源校验：首先检查本地资源是否完整，若缺失则自动触发静默下载。
2. 环境预热：启动游戏所需的 Runtime 容器，并预执行基础脚本。
3. 句柄生成：提前创建 SUDRTGameHandle。当用户真正启动游戏时，可直接通过此句柄快速挂载 View。
4. 状态锁定：预加载成功后，游戏实例将处于“待挂载”状态，等待正式的启动指令。

---

代码示例

// 执行预加载
SUDOPGameTask preLoadTask = SUDOP.preLoadGame("game_101", new SUDOPPreLoadGameListener() {
    @Override
    public void onSuccess(String gameId, SUDRTGameHandle handle) {
        // 预加载成功，可将 handle 缓存，待用户点击开始时直接使用
        Log.i("SUDOP", "Pre-load success. Game is ready to show.");
    }

    @Override
    public void onFailure(int retCode, String retMsg) {
        // 预加载失败
        Log.e("SUDOP", "Pre-load failed: " + retMsg);
    }
});

// 如果用户离开页面，取消预加载以释放内存
// preLoadTask.destroy();

---

注意事项

• 内存消耗：与“预下载”仅占用磁盘不同，“预加载”会占用一定的 CPU 和内存资源。请避免同时预加载多个游戏。
• 前置条件：调用前必须确保 initSDK 成功，且通常需要完成 auth 鉴权。
• 生命周期同步：如果预加载成功后长时间未启动游戏，建议通过 task.destroy() 释放资源，防止内存溢出。

---