loadPackage:progress:completion:
Load Game Resource Package
loadPackage:progress:completion: is a core instance method of the SUDRT protocol. Before or during the creation of a game handle, this method is responsible for extracting the game's game-package resource bundle (containing scripts, images, audio, etc.) and mounting it into the runtime file system. It is the key bridge that turns a game from "static files" into a "runnable instance".
Method Declaration
objectivec
/**
* Loads and prepares the game resource package.
* @param paramModel A model containing the package metadata (such as AppID, version number, download URL, or local path).
* @param progress Loading progress callback, returning an integer from 0 to 100.
* @param completion Completion callback. On success, error is nil; otherwise, it contains the specific error reason.
*/
- (void)loadPackage:(SUDRTLoadPackageParamModel *)paramModel
progress:(nullable void(^)(NSInteger progress))progress
completion:(nullable void(^)(NSError *_Nullable error))completion;Parameters
This method relies heavily on the SUDRTLoadPackageParamModel model, whose core properties include:
| Property | Type | Description |
|---|---|---|
| appId | NSString | Mini-game unique identifier: Used to create an isolated storage sandbox. |
| version | NSString | Version number: Used for version validation and incremental updates. |
| localPath | NSString | Local path: If the game package has been downloaded, specifies its absolute path on the device. |
| md5 | NSString | Checksum: Ensures the resource package has not been tampered with during transmission. |
Runtime Behavior
- Integrity verification: Verifies whether the game package file is corrupted based on the MD5 value in
paramModel. - Sandbox extraction: Extracts the files inside the archive to the directory corresponding to
SUDRT_KEY_RUNTIME_STORAGE_PATH_APP. - Resource mapping: Establishes a virtual file system mapping, so that the JavaScript layer can access resources via relative paths (such as
res/hero.png). - Progress feedback: During IO-intensive operations, reports the extraction percentage in real time through the
progressclosure, making it easy to display a progress bar in the UI.
Code Example
objectivec
// 1. Construct the load parameter model
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. Execute the load task
[self.sdkInstance loadPackage:model progress:^(NSInteger progress) {
// Update the UI progress bar
NSLog(@"[SUD] Resource package loading progress: %ld%%", (long)progress);
} completion:^(NSError * _Nullable error) {
if (error) {
NSLog(@"[SUD] Load failed: %@", error.localizedDescription);
} else {
NSLog(@"[SUD] Load complete, you can now call createGameHandleWithOptions to start the game");
}
}];Notes
- Cache and overwrite logic: The system has an intelligent detection mechanism. If it detects that resources with the same ID and same version have already been successfully deployed, the engine skips the redundant extraction and verification steps and triggers the success callback directly to speed up startup.
- Disk space reservation: Before calling, ensure the device has sufficient free space.
