文档中心

通过游戏包文件路径加载游戏 ​

本文档介绍如何通过本地游戏包文件路径启动游戏，并将游戏视图加载到应用页面中。

概述 ​

通过 SUDOP.startGameByPkgPath 接口，可以根据设备上的本地游戏包文件路径直接启动游戏。

该接口适用于以下场景：

  • 业务侧已自行完成游戏包下载
  • 需要离线启动游戏
  • 内部测试环境使用本地包验证
  • 需要由业务侧控制游戏资源的存储位置和生命周期

调用后，SDK 会自动完成以下流程：

  • 读取本地游戏包
  • 解压游戏资源
  • 初始化运行时环境
  • 创建游戏实例
  • 回调返回游戏视图

开发者只需要在成功回调中获取 gameView，并将其添加到页面容器中即可。

使用前提 ​

在通过本地文件路径启动游戏前，必须先完成以下步骤：

  1. 初始化 SDK
  2. 完成用户鉴权
  3. 准备好本地游戏包文件路径
  4. 构造 SUDOPGamePackageParams
  5. 调用 startGameByPkgPath

完整示例 ​

java
SUDOP.initSDK(context, "Your appId", "Your appKey", new SUDOPInitSDKListener() {
    @Override
    public void onSuccess() {
        SUDOP.auth("Your user signature", new SUDOPAuthListener() {
            @Override
            public void onSuccess() {
                String pkgPath = context.getFilesDir() + "/my_game_package.zip";

                SUDOPGamePackageParams params = new SUDOPGamePackageParams();
                params.version = "gamePkgVersion";
                params.fid = "2e7ca170f33629c7baf4dc430c541c43";
                params.fidType = FIDType.MD5;
                params.appGameID = "appGameID";
                params.appCPID = "Game Developer id";
                params.appGroupID = "Game developer group id";

                SUDOPGameTask gameTask = SUDOP.startGameByPkgPath(pkgPath, params, new SUDOPStartGameListener() {
                    @Override
                    public void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) {
                        // 如果游戏包有加密，请解密之后调用handle.success(String decryptedFilePath, boolean isDeleteFile);来返回新的文件路径
                    }

                    @Override
                    public void onCreated(SUDRTGameHandle gameHandle) {
                        // SUDRTGameHandle创建完成时的回调，一般可以在此处设置自定义的启动参数或注入和游戏交互java对象
                    }

                    @Override
                    public void onSuccess(String gameId, SUDRTGameHandle gameHandle) {
                        // 收到此回调时，表示游戏加载成功，app将游戏View add到自身所需要展示的页面当中即可
                        View gameView = gameHandle.getGameView();
                    }

                    @Override
                    public void onFailure(int retCode, String retMsg) {
                        // 加载游戏失败，通常请检查参数是否正确，以及网络原因
                    }
                });

                // 在业务需要销毁游戏时，调用此方法销毁
//              gameTask.destroy();
            }

            @Override
            public void onFailure(int retCode, String retMsg) {
                // auth接口失败，通常请检查user signature是否正确以及网络原因
            }
        });
    }

    @Override
    public void onFailure(int retCode, String retMsg) {
        // 初始化SDK失败，在appId和appKey正确的情况下，通常是网络原因引起
    }
});

核心接口 ​

startGameByPkgPath ​

java
public static SUDOPGameTask startGameByPkgPath(
    String pkgPath,
    SUDOPGamePackageParams params,
    SUDOPStartGameListener listener
);

该接口用于根据本地游戏包文件路径启动游戏，并返回一个 SUDOPGameTask 任务句柄，用于后续管理游戏生命周期。

参数说明 ​

参数类型描述
pkgPathString必填。本地游戏包文件的绝对路径，通常为 .zip 文件。
paramsSUDOPGamePackageParams必填。游戏包相关参数信息，用于标识游戏包版本、校验信息及业务侧附加信息。
listenerSUDOPStartGameListener必填。游戏启动过程监听器，用于接收启动过程中的状态回调。

SUDOPGamePackageParams 说明 ​

SUDOPGamePackageParams 用于描述当前本地游戏包的元数据信息。

示例中的参数含义如下：

字段类型描述
versionString游戏包版本号。
fidString游戏包文件标识，一般用于文件校验。
fidTypeFIDType文件标识类型，例如 MD5。
appGameIDString业务侧自定义游戏 ID。
appCPIDString游戏开发者 ID。
appGroupIDString游戏开发者分组 ID。

启动回调说明 ​

SUDOPStartGameListener ​

void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) ​

游戏包解密回调。

当本地游戏包存在加密逻辑时，可以在该回调中完成解密，并通过 handle 返回解密结果。

参数说明：

参数类型描述
handleGamePkgDecryptHandle解密结果回调句柄。
filePathString当前待解密文件路径。

如果业务侧没有加密逻辑，通常可以不处理该回调。

void onCreated(SUDRTGameHandle gameHandle) ​

游戏实例创建完成回调。

当收到该回调时，说明 SUDRTGameHandle 已创建完成。通常可以在这里：

  • 设置自定义启动参数
  • 注入和游戏交互的 Java 对象
  • 做一些启动前的业务准备

参数说明：

参数类型描述
gameHandleSUDRTGameHandle游戏实例句柄。

void onSuccess(String gameId, SUDRTGameHandle gameHandle) ​

游戏启动成功回调。

当收到该回调时，表示游戏已经加载成功，开发者可以通过 gameHandle.getGameView() 获取游戏视图，并将其添加到自身页面的容器中进行展示。

参数说明：

参数类型描述
gameIdString当前启动成功的游戏 ID。
gameHandleSUDRTGameHandle游戏实例句柄。

示例：

java
View gameView = gameHandle.getGameView();
// container.addView(gameView);

void onFailure(int retCode, String retMsg) ​

游戏启动失败回调。

通常可以根据错误码和错误信息判断失败原因。

参数说明：

参数类型描述
retCodeint错误码。
retMsgString错误描述。

常见失败原因包括：

  • 本地文件路径错误
  • 游戏包文件不存在
  • 游戏包结构不合法
  • 参数不正确
  • 网络异常
  • 运行时初始化失败

解密句柄说明 ​

GamePkgDecryptHandle ​

void success(String decryptedFilePath, boolean isDeleteFile) ​

通知 SDK 解密成功。

参数说明：

参数类型描述
decryptedFilePathString解密后的文件路径。
isDeleteFileboolean游戏加载完成后是否删除解密后的文件。

void fail(int retCode, String retMsg) ​

通知 SDK 解密失败。

参数说明：

参数类型描述
retCodeint错误码。
retMsgString错误描述。

运行行为 ​

调用 startGameByPkgPath 后，SDK 会按以下流程执行：

  1. 读取指定路径下的本地游戏包文件
  2. 如有需要，进入解密流程
  3. 解压游戏资源到工作目录
  4. 初始化运行环境
  5. 创建游戏实例
  6. 回调返回游戏视图

与通过 gameId 启动游戏相比，该接口不会主动进行游戏包下载，而是直接使用业务侧提供的本地包。

页面集成方式 ​

建议在页面中提前准备好一个用于承载游戏视图的容器，例如 FrameLayout。

示例：

java
FrameLayout container;

在 onSuccess 回调中获取 gameView 后，将其添加到容器中：

java
View gameView = gameHandle.getGameView();
container.addView(gameView);

生命周期管理 ​

startGameByPkgPath 会返回一个 SUDOPGameTask 对象，业务侧需要持有该对象，并在不再需要游戏时主动销毁。

示例：

java
SUDOPGameTask gameTask = SUDOP.startGameByPkgPath(pkgPath, params, listener);

在页面销毁或业务结束时：

java
gameTask.destroy();

注意事项 ​

1. 本地文件路径必须有效 ​

pkgPath 必须是一个真实存在的本地文件绝对路径，且当前应用对该路径具有访问权限。

如果游戏包位于应用私有目录中，例如：

java
context.getFilesDir() + "/my_game_package.zip"

通常不需要额外存储权限。

2. 游戏包格式必须合法 ​

请确保本地游戏包是 SDK 可识别的标准包结构，否则会导致启动失败。

3. 本地包不会自动下载 ​

该接口不会进行网络下载逻辑，调用前必须确保本地包已经准备完成。

4. 原始游戏包文件生命周期由业务侧管理 ​

startGameByPkgPath 不会自动删除业务侧提供的原始 .zip 文件，业务侧需要自行决定是否保留或删除。

5. 建议同一时间只运行一个游戏实例 ​

为了避免资源竞争和页面管理复杂度增加，建议同一时间仅维护一个活跃的游戏实例。

总结 ​

通过本地游戏包路径加载游戏的核心流程如下：

  1. 调用 SUDOP.initSDK 初始化 SDK
  2. 调用 SUDOP.auth 完成鉴权
  3. 准备本地游戏包路径和 SUDOPGamePackageParams
  4. 调用 SUDOP.startGameByPkgPath
  5. 在 onSuccess 中获取 gameView
  6. 将 gameView 添加到页面容器中
  7. 在业务结束时调用 gameTask.destroy() 释放资源