文档中心

通过游戏包目录加载游戏 ​

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

概述 ​

通过 SUDOP.startGameByDirectoryPath 接口，可以根据设备上的本地游戏资源目录直接启动游戏。

该接口适用于以下场景：

  • 业务侧已经完成游戏资源的下载和解压
  • 游戏资源已预置到应用私有目录中
  • 需要跳过下载和解压流程以提升启动速度
  • 业务侧需要自行管理游戏资源目录

调用后，SDK 会直接基于指定目录完成以下流程：

  • 校验游戏目录结构
  • 初始化运行时环境
  • 创建游戏实例
  • 回调返回游戏视图

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

使用前提 ​

在通过本地目录启动游戏前，必须先完成以下步骤：

  1. 初始化 SDK
  2. 完成用户鉴权
  3. 准备好本地游戏资源目录
  4. 构造 SUDOPGamePackageParams
  5. 调用 startGameByDirectoryPath

完整示例 ​

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 directoryPath = context.getFilesDir() + "/game_res/my_tetris_folder";

                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.startGameByDirectoryPath(directoryPath, params, new SUDOPStartGameListener() {
                    @Override
                    public void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) {
                        // 默认可以不实现此回调
                    }

                    @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正确的情况下，通常是网络原因引起
    }
});

核心接口 ​

startGameByDirectoryPath ​

java
public static SUDOPGameTask startGameByDirectoryPath(
    String directoryPath,
    SUDOPGamePackageParams params,
    SUDOPStartGameListener listener
);

该接口用于根据本地游戏资源目录启动游戏，并返回一个 SUDOPGameTask 任务句柄，用于后续管理游戏生命周期。

参数说明 ​

参数类型描述
directoryPathString必填。本地游戏资源目录的绝对路径。目录根部需包含游戏运行所需的入口文件，例如 app.json。
paramsSUDOPGamePackageParams必填。游戏包相关参数信息，用于标识版本、校验信息及业务侧附加信息。
listenerSUDOPStartGameListener必填。游戏启动过程监听器，用于接收启动过程中的状态回调。

SUDOPGamePackageParams 说明 ​

SUDOPGamePackageParams 用于描述当前游戏资源目录对应的元数据信息。

示例中的参数含义如下：

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

启动回调说明 ​

SUDOPStartGameListener ​

void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) ​

游戏包解密回调。

对于通过目录启动的场景，该回调通常不会成为主要流程，但接口仍保持一致。如果业务侧在目录资源准备阶段仍存在额外解密逻辑，可结合该回调进行处理。

参数说明：

参数类型描述
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错误描述。

运行行为 ​

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

  1. 校验指定目录下的资源结构是否合法
  2. 直接读取该目录中的游戏资源
  3. 初始化运行时环境
  4. 创建游戏实例
  5. 回调返回游戏视图

与通过 gameId 或本地压缩包启动游戏相比，该接口不会触发下载流程，也不会执行压缩包解压流程，而是直接基于现有目录启动。

页面集成方式 ​

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

示例：

java
FrameLayout container;

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

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

生命周期管理 ​

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

示例：

java
SUDOPGameTask gameTask = SUDOP.startGameByDirectoryPath(directoryPath, params, listener);

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

java
gameTask.destroy();

注意事项 ​

1. 必须传入目录路径而不是文件路径 ​

directoryPath 必须指向一个已经存在的游戏资源目录，而不是压缩包文件路径。

2. 目录结构必须完整 ​

请确保目录根部包含游戏运行所需的关键文件，例如 app.json。如果目录结构不完整，SDK 将无法正常启动游戏。

3. 目录生命周期由业务侧管理 ​

SDK 不会自动删除或清理该接口指定的资源目录。目录的更新、替换和删除需要由业务侧自行管理。

4. 推荐使用应用私有目录 ​

如果资源目录放在应用私有目录下，例如：

java
context.getFilesDir() + "/game_res/my_tetris_folder"

通常不需要额外存储权限，路径访问也更稳定。

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

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

6. 回调可直接操作 UI ​

启动相关回调在主线程执行，开发者可以直接在 onSuccess 中完成 addView 等 UI 操作。

总结 ​

通过本地游戏目录加载游戏的核心流程如下：

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