loadPackage:progress:completion:

加载游戏资源包

loadPackage:progress:completion: 是 SUDRT 协议中的核心实例方法。在创建游戏句柄之前或过程中，该方法负责将游戏的 游戏包 资源包（包含脚本、图片、音频等）解压并挂载到运行时的文件系统中。它是游戏从“静态文件”变为“可运行实例”的关键桥梁。

---

方法声明

/**
 * 加载并准备游戏资源包。
 * @param paramModel 包含包元数据的模型（如 AppID、版本号、下载地址或本地路径）。
 * @param progress 加载进度回调，返回 0-100 的整数。
 * @param completion 完成回调。若成功则 error 为 nil，否则包含具体的错误原因。
 */
- (void)loadPackage:(SUDRTLoadPackageParamModel *)paramModel
           progress:(nullable void(^)(NSInteger progress))progress
         completion:(nullable void(^)(NSError *_Nullable error))completion;

---

参数说明

该方法高度依赖 SUDRTLoadPackageParamModel 模型，其核心属性包括：

属性名	类型	描述
appId	NSString	小游戏唯一标识：用于创建隔离的存储沙盒。
version	NSString	版本号：用于版本校验和增量更新。
localPath	NSString	本地路径：如果 游戏包 已下载，指定其在手机中的绝对路径。
md5	NSString	校验值：确保资源包在传输过程中未被篡改。

---

运行行为

1. 完整性校验：根据 paramModel 中的 MD5 值验证 游戏包 文件是否损坏。
2. 沙盒解压：将压缩包内的文件提取到 SUDRT_KEY_RUNTIME_STORAGE_PATH_APP 对应的目录下。
3. 资源映射：建立虚拟文件系统映射，使得 JavaScript 层可以通过相对路径（如 res/hero.png）访问资源。
4. 进度反馈：在 IO 密集操作期间，通过 progress 闭包实时反馈解压百分比，方便 UI 展示进度条。

---

代码示例

// 1. 构造加载参数模型
SUDRTLoadPackageParamModel *model = [[SUDRTLoadPackageParamModel alloc] init];
model.appId = @"game_id_001";
model.version = @"1.0.2";
model.localPath = @"/var/mobile/Containers/Data/Documents/game.sp";

// 2. 执行加载任务
[self.sdkInstance loadPackage:model progress:^(NSInteger progress) {
    // 更新 UI 进度条
    NSLog(@"[SUD] 资源包加载进度: %ld%%", (long)progress);
} completion:^(NSError * _Nullable error) {
    if (error) {
        NSLog(@"[SUD] 加载失败: %@", error.localizedDescription);
    } else {
        NSLog(@"[SUD] 加载完成，可以调用 createGameHandleWithOptions 启动游戏了");
    }
}];

---

注意事项

• 缓存与覆盖逻辑：系统具备智能检测机制。若检测到相同 ID 且相同版本的资源已成功部署，引擎将跳过重复的解压与校验步骤，直接触发成功回调以加速启动。
• 磁盘空间预留：调用前请确保设备具备充足的剩余空间。

---