preLoadGameByPkgPath

预加载游戏（通过本地文件路径）

preLoadGameByPkgPath 方法允许开发者直接指定本地存储中的**游戏资源压缩包（.zip）**进行预加载。该接口会跳过所有网络下载环节，直接执行解压、资源校验、引擎初始化及首屏预渲染。

此方法常用于“离线包”场景，或者由业务侧自行实现下载逻辑并将文件存放在特定路径的情况。

---

方法声明

/**
 * 预加载游戏，根据游戏包本地文件路径
 *
 * @param pkgPath   pkgPath
 * @param params   包含游戏包信息的参数对象
 * @param listener 预加载状态监听器
 * @return SUDOPGameTask 任务句柄，可用于管理或销毁预加载任务
 */
public static SUDOPGameTask preLoadGameByPkgPath(String pkgPath, SUDOPGamePackageParams params, SUDOPPreLoadGameListener listener);

---

参数说明

用于指定本地资源包的位置：

属性	类型	描述
pkgPath	String	必填。游戏资源压缩包（.zip）在设备上的绝对路径。

1. SUDOPGamePackageParams

用于指定具体的资源下载链接：

属性	类型	描述
version	String	必填。游戏版本
fid	String	游戏包文件指纹
fidType	FIDType	游戏包文件指纹生成方式
appGameID	String	必填。指定gameID
appCPID	String	指定游戏开发者的CP ID
appGroupID	String	指定游戏开发者的Group ID

2. FIDType

用于指定游戏包文件指纹生成方式

属性	类型	描述
MD5	enum	MD5算法
CRC32	enum	CRC32算法
SHA1	enum	SHA1算法
SHA256	Strenuming	SHA256算法

3. SUDOPPreLoadGameListener

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

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

• gameId：从资源包配置中解析出的游戏唯一标识。

• handle：游戏实例句柄，可用于后续挂载视图。

• void onFailure(int retCode, String retMsg)：预加载失败。常见原因包括文件路径不存在、压缩包损坏、权限不足或内存溢出。

---

运行行为

1. 文件访问：SDK 尝试读取指定路径的文件。开发者需确保已获得相应的存储权限。
2. 解压与校验：将资源包解压至 SDK 的工作目录，并验证包内配置文件（如 app.json）的合法性。
3. 环境初始化：启动运行时环境，并预加载游戏首屏所需的底层素材。
4. 准备就绪：返回 SUDRTGameHandle，此时游戏逻辑已在后台启动并挂起。

---

代码示例

String pkgPath = getExternalFilesDir(null) + "/games/tetris_v1.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 preLoadTask = SUDOP.preLoadGameByPkgPath(pkgPath, params, new SUDOPPreLoadGameListener() {
    @Override
    public void onSuccess(String gameId, SUDRTGameHandleProvider provider) {
    }
    @Override
    public void onFailure(int retCode, String retMsg) {
    }
});

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

---

注意事项

• 存储权限：在 Android 6.0+ 系统上，请确保应用已获得读取存储（Read External Storage）的权限。
• 资源规范：传入的 .zip 包必须符合 SUD 平台标准的资源组织结构。
• 内存管理：由于此过程涉及解压和引擎加载，属于资源密集型操作。预加载成功后若不立即使用，请监控应用的内存占用。

---