Skip to content

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:

PropertyTypeDescription
appIdNSStringMini-game unique identifier: Used to create an isolated storage sandbox.
versionNSStringVersion number: Used for version validation and incremental updates.
localPathNSStringLocal path: If the game package has been downloaded, specifies its absolute path on the device.
md5NSStringChecksum: Ensures the resource package has not been tampered with during transmission.

Runtime Behavior ​

  1. Integrity verification: Verifies whether the game package file is corrupted based on the MD5 value in paramModel.
  2. Sandbox extraction: Extracts the files inside the archive to the directory corresponding to SUDRT_KEY_RUNTIME_STORAGE_PATH_APP.
  3. Resource mapping: Establishes a virtual file system mapping, so that the JavaScript layer can access resources via relative paths (such as res/hero.png).
  4. Progress feedback: During IO-intensive operations, reports the extraction percentage in real time through the progress closure, 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.