startGameWithDerectoryPath:options:didGameViewCreated:didGameHandleCreated:progress:completion:
启动游戏(通过本地目录路径)
该方法用于通过本地游戏资源目录启动游戏。directoryPath 应指向一个已经准备好的游戏资源目录,SDK 会基于该目录中的资源创建游戏实例并启动游戏。
该方式适用于游戏资源已经提前下载并解压到本地目录的场景,可减少在线下载和解压耗时。开发者可以通过 didGameViewCreated 获取游戏视图,通过 didGameHandleCreated 获取游戏句柄,通过 progress 监听启动进度,并在 completion 中接收最终启动结果。
注意:接口名中的
Derectory为 SDK 方法名原始拼写,请按实际声明调用。
方法声明
+ (id<SUDOPGameTask>)startGameWithDerectoryPath:(NSString *)directoryPath
options:(SUDOPGamePackageOptions *)options
didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
progress:(nullable SUDOPProgressBlock)progress
completion:(nullable SUDOPGameOperationCompletionBlock)completion;参数说明
| 参数名 | 类型 | 必传 | 描述 |
|---|---|---|---|
| directoryPath | NSString * | 是 | 本地游戏资源目录路径,通常为已下载并解压完成的游戏资源目录。建议传入绝对路径。 |
| options | SUDOPGamePackageOptions * | 是 | 游戏资源包配置对象,通常包含游戏 ID、版本号等用于资源识别和启动的元信息。 |
| didGameViewCreated | SUDOPDidGameViewCreatedBlock | 否 | 游戏视图创建完成后的回调。开发者通常在此回调中获取游戏 View,并将其添加到业务页面中。 |
| didGameHandleCreated | SUDOPDidGameHandleCreatedBlock | 否 | 游戏句柄创建完成后的回调。开发者通常在此回调中保存游戏句柄、注册业务代理或进行后续通信准备。 |
| progress | SUDOPProgressBlock | 否 | 游戏启动过程中的进度回调,可用于展示加载进度。 |
| completion | SUDOPGameOperationCompletionBlock | 否 | 游戏启动流程完成后的回调。成功时表示游戏已完成启动;失败时返回错误信息。 |
返回值说明
| 返回值 | 类型 | 描述 |
|---|---|---|
| gameTask | id<SUDOPGameTask> | 游戏启动任务对象,可用于跟踪或管理当前启动流程。 |
运行行为
路径校验
SDK 会检查directoryPath是否有效,并确认其指向可访问的本地目录。如果路径不存在、不是目录或缺少必要资源文件,启动可能失败。读取配置
SDK 会结合options中的游戏 ID、版本号等元信息识别资源包,并读取目录内的游戏配置和入口文件。创建启动任务
SDK 创建游戏启动任务,并立即返回id<SUDOPGameTask>对象。资源加载
SDK 直接从本地目录加载游戏资源,通常不需要额外下载;但仍可能进行资源校验、运行时初始化、脚本加载或渲染环境准备。进度回调
在启动过程中,SDK 会通过progress回调返回当前加载进度,开发者可用于更新加载 UI。游戏视图创建
当游戏 View 创建完成后,SDK 会触发didGameViewCreated回调。开发者应在此处将游戏视图添加到自己的页面视图层级中。游戏句柄创建
当游戏 Handle 创建完成后,SDK 会触发didGameHandleCreated回调。该句柄通常用于与游戏通信、注册代理、发送状态或控制游戏生命周期。启动完成
游戏启动成功或失败后,SDK 会触发completion回调。成功后游戏进入可运行状态;失败时可根据错误信息进行处理。
代码示例
NSString *directoryPath = @"/var/mobile/Containers/Data/Application/.../Library/Caches/Game_001_v2";
SUDOPGamePackageOptions *options = [[SUDOPGamePackageOptions alloc] init];
options.appGameID = @"game_001";
options.version = @"2.0.0";
id<SUDOPGameTask> gameTask = [SUDOP startGameWithDerectoryPath:directoryPath
options:options
didGameViewCreated:^(UIView * _Nullable gameView) {
if (!gameView) {
return;
}
// 将游戏视图添加到当前页面
gameView.frame = self.view.bounds;
[self.view addSubview:gameView];
NSLog(@"游戏视图已创建");
} didGameHandleCreated:^(id _Nullable gameHandle) {
if (!gameHandle) {
return;
}
// 保存游戏句柄,便于后续与游戏通信或释放资源
// self.gameHandle = gameHandle;
// 如业务需要,可在此注册游戏代理
// [SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];
NSLog(@"游戏句柄已创建");
} progress:^(CGFloat progress) {
NSLog(@"游戏启动进度: %.2f", progress);
// 可在此更新加载进度 UI
// self.progressView.progress = progress;
} completion:^(NSError * _Nullable error) {
if (error) {
NSLog(@"通过本地目录启动游戏失败: %@", error);
return;
}
NSLog(@"通过本地目录启动游戏成功");
}];
self.gameTask = gameTask;说明:示例中的 Block 参数类型请以 SDK 中对应 typedef 的实际定义为准。
注意事项
- 方法名拼写:请按照 SDK 声明使用
startGameWithDerectoryPath,不要自行改为Directory。 - directoryPath 必传:
directoryPath不能为空,且应指向一个有效、可访问的游戏资源目录。 - options 必传:
options应包含启动本地资源所需的游戏 ID、版本号等信息,具体字段以 SDK 实际定义为准。 - 资源目录需完整:目录内应包含游戏运行所需的配置文件、脚本、素材等资源,缺失文件会导致启动失败。
- 运行期间不要修改目录:游戏运行过程中,请勿删除、移动、重命名或覆盖该目录下的资源文件。
- 建议在主线程调用:该接口涉及游戏 View 创建和 UI 操作,建议在主线程调用。
- 及时添加游戏视图:收到
didGameViewCreated回调后,应将游戏 View 添加到页面中,否则用户可能无法看到游戏画面。 - 及时保存游戏句柄:收到
didGameHandleCreated回调后,建议保存游戏句柄,用于后续通信、状态同步或资源释放。 - 页面退出需清理资源:用户离开游戏页面时,应按照 SDK 要求停止游戏或释放相关资源,避免渲染、音频或内存资源残留。
