Skip to content

preLoadGameWithDirectoryPath:options:completion: ​

Pre-load Game (by Local Directory Path) ​

This method allows developers to perform a pre-load by specifying a game resource directory (Directory Path) that has already been decompressed. Unlike loading from a file path, this interface is suitable for scenarios where the game resources already exist on the local file system as a decompressed folder (such as inside the app Bundle or the sandbox's Library directory). The SDK directly maps the resources under this directory, skips the decompression process, and achieves the fastest environment readiness.


Method Declaration ​

objc
/**
 Pre-load game using a local directory path.
 @param directoryPath the local directory path.
 @param options Configuration object containing  and metadata.
 @param completion Called when the pre-load operation finishes.
 @return An instance of id<SUDOPGameTask> to track the pre-load task.
 */
+ (id<SUDOPGameTask>)preLoadGameWithDirectoryPath:(NSString *)directoryPath
                                          options:(SUDOPGamePackageOptions *)options
                                       completion:(nullable SUDOPGameOperationCompletion)completion;

Parameters ​

ParameterTypeRequiredDescription
directoryPathNSString *YesThe absolute path path of the containing directory.
optionsSUDOPGamePackageOptions *YesConfiguration object containing information such as the version version and game identifier.
completionSUDOPGameOperationCompletionNoCallback invoked after the asynchronous pre-load finishes. On success, returns the provider from which the handle can be obtained.

Return Value ​

Returns an object conforming to the id<SUDOPGameTask> protocol, used to monitor or cancel the pre-load task.


Runtime Behavior ​

  1. Directory Structure Validation: The SDK checks whether the core entry files (such as index.json or main.js) exist under the directoryPath directory to confirm the directory's integrity.
  2. Direct Loading: Since the resources are already decompressed, the SDK directly initializes the script virtual machine and associates the directory, greatly reducing the time required for pre-loading.
  3. Persistent Association: In this mode, the SDK assumes by default that the developer is responsible for the lifecycle of this directory; it is recommended not to modify the directory contents while the game is running.

Example Code ​

objectivec
SUDOPGamePackageOptions *options = [[SUDOPGamePackageOptions alloc] init];
// Assume the resources are located in a built-in folder of the app's Main Bundle
NSString *resourcePath = [[NSBundle mainBundle] pathForResource:@"GameRes" ofType:nil];

options.appGameID = @"game_builtin_001";
options.version = @"1.0.0";

[SUDOP preLoadGameWithDirectoryPath:resourcePath options:options completion:nil];

Notes ​

  • Path Nature: directoryPath must point to a folder, not a compressed package. If it points to a compressed file, use preLoadGameWithFilePathOptions:.
  • Read-only Restriction: If the directory is located in the app Bundle (read-only), make sure the game logic itself does not depend on writing data to the resource directory.
  • Version Matching: Although this is direct loading, it is recommended that options.version be consistent with the configuration inside the directory, so that the SDK can perform correct version management and caching decisions.