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
Derectoryin the interface name is the original spelling of the SDK method name; call it as declared.
Method Declaration
+ (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
| Parameter | Type | Required | Description |
|---|---|---|---|
| directoryPath | NSString * | Yes | The local game resource directory path, usually the game resource directory that has been downloaded and decompressed. It is recommended to pass an absolute path. |
| options | SUDOPGamePackageOptions * | Yes | The game resource package configuration object, usually containing the game ID, version number, and other meta-information for resource identification and startup. |
| didGameViewCreated | SUDOPDidGameViewCreatedBlock | No | Callback invoked after the game view is created. Developers typically obtain the game View in this callback and add it to the business page. |
| didGameHandleCreated | SUDOPDidGameHandleCreatedBlock | No | Callback 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. |
| progress | SUDOPProgressBlock | No | Progress callback during the game start process, which can be used to display loading progress. |
| completion | SUDOPGameOperationCompletionBlock | No | Callback invoked after the game start flow finishes. Success indicates the game has completed startup; on failure, error information is returned. |
Return Value
| Return Value | Type | Description |
|---|---|---|
| gameTask | id<SUDOPGameTask> | The game start task object, which can be used to track or manage the current start flow. |
Runtime Behavior
Path Validation
The SDK checks whetherdirectoryPathis 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.Read Configuration
The SDK identifies the resource package based on the game ID, version number, and other meta-information inoptions, and reads the game configuration and entry files within the directory.Create Start Task
The SDK creates a game start task and immediately returns anid<SUDOPGameTask>object.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.Progress Callback
During the start process, the SDK returns the current loading progress via theprogresscallback, which developers can use to update the loading UI.Game View Creation
When the game View is created, the SDK triggers thedidGameViewCreatedcallback. Developers should add the game view to their own page view hierarchy here.Game Handle Creation
When the game Handle is created, the SDK triggers thedidGameHandleCreatedcallback. This handle is typically used for communicating with the game, registering delegates, sending states, or controlling the game lifecycle.Start Completed
After the game starts successfully or fails, the SDK triggers thecompletioncallback. On success, the game enters a runnable state; on failure, you can handle it based on the error information.
Example Code
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
startGameWithDerectoryPathas declared in the SDK; do not change it toDirectoryon your own. - directoryPath Required:
directoryPathcannot be empty and should point to a valid, accessible game resource directory. - options Required:
optionsshould 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
didGameViewCreatedcallback, add the game View to the page; otherwise, the user may not see the game screen. - Save the Game Handle Promptly: After receiving the
didGameHandleCreatedcallback, 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.
