setGameLoadSubpackageListener

设置分包加载监听器

setGameLoadSubpackageListener 用于注册小游戏分包（Subpackage）加载过程的监听接口。当小游戏由于业务逻辑需要加载额外的资源分包时，SDK 会通过该监听器实时反馈下载进度、加载成功或失败的状态，以便宿主 App 展示原生加载进度条或处理网络异常。

---

方法声明

/**
 * 设置小游戏分包加载监听。
 * @param listener 遵循 SUDRTGameLoadSubpackageListener 协议的对象。
 */
- (void)setGameLoadSubpackageListener:(nullable id<SUDRTGameLoadSubpackageListener>)listener;

---

参数说明

参数名	类型	必传	描述
listener	id<SUDRTGameLoadSubpackageListener>	否	监听器实例。传入 nil 则取消监听。

---

运行行为

1. 触发机制：当小游戏代码调用 loadSubpackage 接口时，SDK 启动异步下载任务并触发监听。
2. 进度反馈：在下载大体积分包时，会多次触发 onProgress 回调，返回当前已完成的百分比。
3. 结果通知：下载并解压完成后，触发 onSuccess；若网络超时或校验失败，则触发 onFailure。
4. 自动流转：分包加载成功后，游戏引擎会自动将该包内的脚本和资源合并到运行环境。

---

代码示例

通过监听分包进度，可以提升用户在等待大型关卡加载时的体验：

// 1. 实现协议
@interface GameViewController () <SUDRTGameLoadSubpackageListener>
@end

@implementation GameViewController

- (void)setupSubpackageListener {
    // 2. 注册监听
    [self.gameHandle setGameLoadSubpackageListener:self];
}

#pragma mark - SUDRTGameLoadSubpackageListener

- (void)onGameLoadSubpackageProgress:(NSString *)packageName progress:(float)progress {
    // 3. 更新原生进度条（注意回到主线程）
    dispatch_async(dispatch_get_main_queue(), ^{
        [self.loadingBar setProgress:progress animated:YES];
        NSLog(@"分包 [%@] 加载进度: %.2f%%", packageName, progress * 100);
    });
}

- (void)onGameLoadSubpackageSuccess:(NSString *)packageName {
    NSLog(@"分包 [%@] 加载成功", packageName);
}

- (void)onGameLoadSubpackageFailure:(NSString *)packageName error:(int)error {
    NSLog(@"分包 [%@] 加载失败，错误码: %d", packageName, error);
}

@end

---

注意事项

• 包名匹配：回调中的 packageName 与小游戏配置文件（game.json）中定义的分包名称一致。
• 网络依赖：分包加载高度依赖网络环境，建议在 onFailure 中引导用户检查网络或提供重试逻辑。
• 时效性：分包通常会被 SDK 缓存。如果该分包已存在于本地且未更新，onSuccess 可能会被立即触发，而跳过中间的进度回调。
• 资源释放：建议在 destroy 游戏句柄前保持该监听器有效，以监控可能的未完成下载任务。

---