文档中心

preLoadGameWithPkgPath:options:completion: ​

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

该方法允许开发者通过指定本地文件系统中的游戏包路径（Path）来执行预加载操作。此接口适用于游戏包已由宿主应用自行下载完成、或存放在 App Bundle/自定义沙盒目录中的场景。SDK 将直接从指定路径读取资源，跳过网络下载阶段，快速完成运行环境的初始化。

方法声明 ​

objectivec
/**
 Pre-load game using a local file path.
 @param pkgPath the local path.
 @param options Configuration object containing verification metadata.
 @param completion Called when the pre-load operation finishes.
 @return An instance of id<SUDOPGameTask> to track the pre-load task.
 */
+ (id<SUDOPGameTask>)preLoadGameWithPkgPath:(NSString *)pkgPath
                                    options:(SUDOPGamePackageOptions *)options
                                 completion:(nullable SUDOPGameOperationCompletion)completion;

参数说明 ​

参数名类型必传描述
pkgPathNSString *是本地绝对路径 path
optionsSUDOPGamePackageOptions *是包含版本 version 及完整性校验 fid 等信息的对象。
completionSUDOPGameOperationCompletion否异步预加载完成后的回调。成功时 gameHandleProvider 将提供初步生成的句柄信息。

返回值 ​

返回一个遵循 id<SUDOPGameTask> 协议的对象，用于监控预加载任务进度或执行取消操作。

运行行为 ​

  1. 路径合法性检查：SDK 首先确认 pkgPath 指向的文件是否存在且具有读取权限。
  2. 强制校验：根据 options.fid 对本地文件进行哈希校验。如果校验失败（如文件损坏或版本不匹配），将通过 completion 返回错误。
  3. 就绪状态：一旦校验通过，SDK 会解压必要资源并初始化脚本引擎，使游戏处于“待启动”的高温状态。

代码示例 ​

objectivec
SUDOPGamePackageOptions *options = [[SUDOPGamePackageOptions alloc] init];
NSString * pkgPath = @"/var/mobile/Containers/Data/Application/.../Documents/game_v2.zip";
options.appGameID = @"game_456";
options.version = @"2.0.0";
options.fid = @"e99a18c428cb38d5f260853678922e03";
options.fidType = SUDOPFIDTypeMD5;

[SUDOP preLoadGameWithPkgPath:pkgPath options:pathOptions completion:nil];

注意事项 ​

  • 绝对路径：必须确保 pkgPath 是完整的本地文件绝对路径，且应用进程有权限访问。
  • 资源独占：在预加载期间，请勿移动或删除 pkgPath 指向的文件，否则可能导致解压或加载中断。
  • 内存占用：虽然是从本地路径加载，但 preLoad 依然会占用一定的内存用于环境初始化。