Skip to content

startGame:didGameViewCreated:didGameHandleCreated:progress:completion: ​

Start Game (by Game ID) ​

This method starts a game via the game's unique identifier (Game ID). The SDK creates a game task based on the passed gameID and completes game resource preparation, game view creation, game handle creation, and the final start flow.

This interface is one of the core methods for starting a game. Developers can obtain the game view through didGameViewCreated and add it to the business page, obtain the game handle through didGameHandleCreated and register the business delegate, monitor the start progress through progress, and handle the final start result in completion.


Method Declaration ​

objectivec
+ (id<SUDOPGameTask>)startGame:(NSString *)gameID
            didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
          didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
                      progress:(nullable SUDOPProgressBlock)progress
                    completion:(nullable SUDOPGameOperationCompletionBlock)completion;

+ (id<SUDOPGameTask>)startGame:(NSString *)gameID
                      language:(nullable NSString *)language
            didGameViewCreated:(nullable SUDOPDidGameViewCreatedBlock)didGameViewCreated
          didGameHandleCreated:(nullable SUDOPDidGameHandleCreatedBlock)didGameHandleCreated
                      progress:(nullable SUDOPProgressBlock)progress
                    completion:(nullable SUDOPGameOperationCompletionBlock)completion;

Parameters ​

ParameterTypeRequiredDescription
gameIDNSString *YesThe unique identifier of the game.
languageNSString *NoOptional language in the new overload, such as zh-CN. Used for the signature request and the loading name and cover. See the language rules below.
didGameViewCreatedSUDOPDidGameViewCreatedBlockNoCallback invoked after the game view is created. Developers typically obtain the game View in this callback and add it to their own page view hierarchy.
didGameHandleCreatedSUDOPDidGameHandleCreatedBlockNoCallback invoked after the game handle is created. Developers typically register the business delegate in this callback, or save the game handle for subsequent communication.
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 the current start flow. Developers can manage the task based on the capabilities provided by the SDK.

Runtime Behavior ​

  1. Create Start Task: The SDK creates a game start task based on the passed gameID and immediately returns an id<SUDOPGameTask> object.
  2. Resource Preparation: The SDK checks whether the game resources already exist. If the game resources are not ready, the SDK automatically performs the necessary download, load, or initialization flows.
  3. Progress Callback: During the game start process, the SDK returns the current loading progress via the progress callback, which developers can use to update the loading UI.
  4. Game View Creation: When the game View is created, the SDK triggers the didGameViewCreated callback. Developers should add the game view to the page here.
  5. Game Handle Creation: When the game Handle is created, the SDK triggers the didGameHandleCreated callback. This handle is typically used for subsequent communication with the game, registering delegates, or sending states.
  6. Start Completed: After the game starts successfully or fails, the SDK triggers the completion callback. On success, the game enters an interactive state; on failure, you can handle it based on the error information.

Language and Loading View ​

  • The original method remains available and is equivalent to passing language:nil.
  • A nonempty language is forwarded to /v1/game/signature and used to select the loading name from game_name and cover URL from icon.
  • With nil or an empty string, the signature request uses the server default. The loading view uses the first system preferred language (NSLocale.preferredLanguages.firstObject) to select both the name and cover.
  • Selection uses the existing language helper: exact language, parent language (for example, zh-Hans-CN → zh-Hans), language prefix, another entry with the same prefix, default, then any nonempty string. If no usable localized icon exists, the cover falls back to game_icon.
  • An existing task for the same game ID is reused. A later call does not overwrite an already started task's language.

Example Code ​

objectivec
NSString *gameID = @"game_999";

id<SUDOPGameTask> gameTask = [SUDOP startGame:gameID
                                     language:@"zh-CN"
                           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, or register the business delegate
    // self.gameHandle = gameHandle;
    // [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:^(id<SUDOPGameHandleProvider> _Nullable gameHandleProvider, NSError * _Nullable error) {
    if (error) {
        NSLog(@"Game start failed: %@", error);
        return;
    }

    NSLog(@"Game started 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 ​

  • gameID Required: gameID is the core parameter for starting the game and cannot be empty or invalid.
  • 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 business page; otherwise, the user may not see the game screen.
  • Register the Business Delegate Promptly: If the business needs to receive game events or send states to the game, it is recommended to complete delegate registration in the didGameHandleCreated callback.
  • Watch the Start Progress: progress can be used to display loading progress and improve the user experience during waiting.
  • Handle Start Failure: If completion returns an error, check the network status, game resource status, whether gameID is valid, and whether the SDK has completed initialization and authentication.
  • 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.