Skip to content

startGameWithDerectoryPath:options:didGameViewCreated:didGameHandleCreated:progress:completion: ​

启动游戏(通过本地目录路径) ​

该方法用于通过本地游戏资源目录启动游戏。directoryPath 应指向一个已经准备好的游戏资源目录,SDK 会基于该目录中的资源创建游戏实例并启动游戏。

该方式适用于游戏资源已经提前下载并解压到本地目录的场景,可减少在线下载和解压耗时。开发者可以通过 didGameViewCreated 获取游戏视图,通过 didGameHandleCreated 获取游戏句柄,通过 progress 监听启动进度,并在 completion 中接收最终启动结果。

注意:接口名中的 Derectory 为 SDK 方法名原始拼写,请按实际声明调用。


方法声明 ​

objectivec
+ (id<SUDOPGameTask>)startGameWithDerectoryPath:(NSString *)directoryPath
                                        options:(SUDOPGamePackageOptions *)options
                             didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
                           didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
                                       progress:(nullable SUDOPProgressBlock)progress
                                     completion:(nullable SUDOPGameOperationCompletionBlock)completion;

参数说明 ​

参数名类型必传描述
directoryPathNSString *是本地游戏资源目录路径,通常为已下载并解压完成的游戏资源目录。建议传入绝对路径。
optionsSUDOPGamePackageOptions *是游戏资源包配置对象,通常包含游戏 ID、版本号等用于资源识别和启动的元信息。
didGameViewCreatedSUDOPDidGameViewCreatedBlock否游戏视图创建完成后的回调。开发者通常在此回调中获取游戏 View,并将其添加到业务页面中。
didGameHandleCreatedSUDOPDidGameHandleCreatedBlock否游戏句柄创建完成后的回调。开发者通常在此回调中保存游戏句柄、注册业务代理或进行后续通信准备。
progressSUDOPProgressBlock否游戏启动过程中的进度回调,可用于展示加载进度。
completionSUDOPGameOperationCompletionBlock否游戏启动流程完成后的回调。成功时表示游戏已完成启动;失败时返回错误信息。

返回值说明 ​

返回值类型描述
gameTaskid<SUDOPGameTask>游戏启动任务对象,可用于跟踪或管理当前启动流程。

运行行为 ​

  1. 路径校验
    SDK 会检查 directoryPath 是否有效,并确认其指向可访问的本地目录。如果路径不存在、不是目录或缺少必要资源文件,启动可能失败。

  2. 读取配置
    SDK 会结合 options 中的游戏 ID、版本号等元信息识别资源包,并读取目录内的游戏配置和入口文件。

  3. 创建启动任务
    SDK 创建游戏启动任务,并立即返回 id<SUDOPGameTask> 对象。

  4. 资源加载
    SDK 直接从本地目录加载游戏资源,通常不需要额外下载;但仍可能进行资源校验、运行时初始化、脚本加载或渲染环境准备。

  5. 进度回调
    在启动过程中,SDK 会通过 progress 回调返回当前加载进度,开发者可用于更新加载 UI。

  6. 游戏视图创建
    当游戏 View 创建完成后,SDK 会触发 didGameViewCreated 回调。开发者应在此处将游戏视图添加到自己的页面视图层级中。

  7. 游戏句柄创建
    当游戏 Handle 创建完成后,SDK 会触发 didGameHandleCreated 回调。该句柄通常用于与游戏通信、注册代理、发送状态或控制游戏生命周期。

  8. 启动完成
    游戏启动成功或失败后,SDK 会触发 completion 回调。成功后游戏进入可运行状态;失败时可根据错误信息进行处理。


代码示例 ​

objectivec
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 要求停止游戏或释放相关资源,避免渲染、音频或内存资源残留。