Skip to content

startGameWithDerectoryPath:options:didGameViewCreated:didGameHandleCreated:progress:completion: ​

Start Game (by Local Directory Path) ​

This method starts a game via a local game resource directory. directoryPath should point to a game resource directory that is already prepared, and the SDK creates a game instance and starts the game based on the resources in that directory.

This approach is suitable for scenarios where game resources have been downloaded and decompressed to a local directory in advance, reducing online download and decompression time. Developers can obtain the game view through didGameViewCreated, obtain the game handle through didGameHandleCreated, monitor the start progress through progress, and receive the final start result in completion.

Note: The Derectory in the interface name is the original spelling of the SDK method name; call it as declared.


Method Declaration ​

objectivec
+ (id<SUDOPGameTask>)startGameWithDerectoryPath:(NSString *)directoryPath
                                        options:(SUDOPGamePackageOptions *)options
                             didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
                           didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
                                       progress:(nullable SUDOPProgressBlock)progress
                                     completion:(nullable SUDOPGameOperationCompletionBlock)completion;

Parameters ​

ParameterTypeRequiredDescription
directoryPathNSString *YesThe local game resource directory path, usually the game resource directory that has been downloaded and decompressed. It is recommended to pass an absolute path.
optionsSUDOPGamePackageOptions *YesThe game resource package configuration object, usually containing the game ID, version number, and other meta-information for resource identification and startup.
didGameViewCreatedSUDOPDidGameViewCreatedBlockNoCallback invoked after the game view is created. Developers typically obtain the game View in this callback and add it to the business page.
didGameHandleCreatedSUDOPDidGameHandleCreatedBlockNoCallback invoked after the game handle is created. Developers typically save the game handle, register the business delegate, or prepare for subsequent communication in this callback.
progressSUDOPProgressBlockNoProgress callback during the game start process, which can be used to display loading progress.
completionSUDOPGameOperationCompletionBlockNoCallback invoked after the game start flow finishes. Success indicates the game has completed startup; on failure, error information is returned.

Return Value ​

Return ValueTypeDescription
gameTaskid<SUDOPGameTask>The game start task object, which can be used to track or manage the current start flow.

Runtime Behavior ​

  1. Path Validation
    The SDK checks whether directoryPath is valid and confirms that it points to an accessible local directory. If the path does not exist, is not a directory, or lacks the necessary resource files, the start may fail.

  2. Read Configuration
    The SDK identifies the resource package based on the game ID, version number, and other meta-information in options, and reads the game configuration and entry files within the directory.

  3. Create Start Task
    The SDK creates a game start task and immediately returns an id<SUDOPGameTask> object.

  4. Resource Loading
    The SDK loads game resources directly from the local directory, usually without additional downloading; however, it may still perform resource verification, runtime initialization, script loading, or rendering environment preparation.

  5. Progress Callback
    During the start process, the SDK returns the current loading progress via the progress callback, which developers can use to update the loading UI.

  6. Game View Creation
    When the game View is created, the SDK triggers the didGameViewCreated callback. Developers should add the game view to their own page view hierarchy here.

  7. Game Handle Creation
    When the game Handle is created, the SDK triggers the didGameHandleCreated callback. This handle is typically used for communicating with the game, registering delegates, sending states, or controlling the game lifecycle.

  8. Start Completed
    After the game starts successfully or fails, the SDK triggers the completion callback. On success, the game enters a runnable state; on failure, you can handle it based on the error information.


Example Code ​

objectivec
NSString *directoryPath = @"/var/mobile/Containers/Data/Application/.../Library/Caches/Game_001_v2";

SUDOPGamePackageOptions *options = [[SUDOPGamePackageOptions alloc] init];
options.appGameID = @"game_001";
options.version = @"2.0.0";

id<SUDOPGameTask> gameTask = [SUDOP startGameWithDerectoryPath:directoryPath
                                                       options:options
                                            didGameViewCreated:^(UIView * _Nullable gameView) {
    if (!gameView) {
        return;
    }

    // Add the game view to the current page
    gameView.frame = self.view.bounds;
    [self.view addSubview:gameView];

    NSLog(@"Game view created");
} didGameHandleCreated:^(id _Nullable gameHandle) {
    if (!gameHandle) {
        return;
    }

    // Save the game handle for subsequent communication with the game or resource release
    // self.gameHandle = gameHandle;

    // If the business requires it, you can register the game delegate here
    // [SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];

    NSLog(@"Game handle created");
} progress:^(CGFloat progress) {
    NSLog(@"Game start progress: %.2f", progress);

    // You can update the loading progress UI here
    // self.progressView.progress = progress;
} completion:^(NSError * _Nullable error) {
    if (error) {
        NSLog(@"Failed to start game from local directory: %@", error);
        return;
    }

    NSLog(@"Started game from local directory successfully");
}];

self.gameTask = gameTask;

Note: For the Block parameter types in the example, refer to the actual definitions of the corresponding typedefs in the SDK.


Notes ​

  • Method Name Spelling: Use startGameWithDerectoryPath as declared in the SDK; do not change it to Directory on your own.
  • directoryPath Required: directoryPath cannot be empty and should point to a valid, accessible game resource directory.
  • options Required: options should contain the game ID, version number, and other information required to start local resources; the specific fields are subject to the actual definitions in the SDK.
  • Resource Directory Must Be Complete: The directory should contain the configuration files, scripts, assets, and other resources required to run the game; missing files will cause the start to fail.
  • Do Not Modify the Directory During Running: While the game is running, do not delete, move, rename, or overwrite the resource files under this directory.
  • Recommended to Call on Main Thread: This interface involves game View creation and UI operations, so it is recommended to call it on the main thread.
  • Add the Game View Promptly: After receiving the didGameViewCreated callback, add the game View to the page; otherwise, the user may not see the game screen.
  • Save the Game Handle Promptly: After receiving the didGameHandleCreated callback, it is recommended to save the game handle for subsequent communication, state synchronization, or resource release.
  • Clean Up Resources on Page Exit: When the user leaves the game page, stop the game or release related resources as required by the SDK to avoid leftover rendering, audio, or memory resources.