Skip to content

createGameHandleWithOptions:completion: ​

Create Game Handle ​

createGameHandleWithOptions:completion: is the most critical instance method of the SUDRT protocol. It plays the role of a "game factory", responsible for initializing an independent Game Handle with a complete runtime environment based on the configuration parameters you provide. Only after successfully obtaining this handle can you further control the game's lifecycle (such as starting, stopping, and listening for events).


Method Declaration ​

objectivec
/**
 * Initializes and creates a new game handle.
 * @param options A dictionary containing handle creation parameters (such as render mode, base library path, etc.).
 * @param completion Asynchronous callback. Returns handle on success, and error on failure.
 */
- (void)createGameHandleWithOptions:(NSDictionary *)options
                         completion:(nullable void (^)(id<SUDRTGameHandle> _Nullable handle,
                                                       NSError * _Nullable error))completion;

Parameters ​

The options dictionary determines the underlying behavior of the game instance. Common configurations are as follows:

KeyTypeDescription
"renderMode"NSNumberRender mode: 0 for auto, 1 for native Surface rendering, 2 for WebView-compatible rendering.
"baseLibPath"NSStringBase library path: Specifies the path to the runtime base JS library required for the mini-game to run.
"appId"NSStringMini-game ID: Identifies the business application to which the current instance belongs.
"maxMemory"NSNumber(Optional) Limits the maximum memory (MB) that the instance can occupy.

Runtime Behavior ​

  1. Resource allocation: The Runtime allocates an independent JavaScript virtual machine (JS VM) and rendering canvas for the instance.
  2. Environment validation: Checks whether the paths and parameters provided in options are valid and whether the base library is complete.
  3. Asynchronous instantiation: Since it involves initializing the underlying engine, this process is asynchronous and does not block the main thread.
  4. Handle delivery: After initialization completes, the id<SUDRTGameHandle> instance is delivered through the completion closure.

Code Example ​

objectivec
// 1. Prepare the creation parameters
NSDictionary *createOpts = @{
    @"appId": @"sud_test_game_001",
    @"renderMode": @(1), // Force enable native accelerated rendering
    @"baseLibPath": [[NSBundle mainBundle] pathForResource:@"sud_base_lib" ofType:@"js"]
};

// 2. Initiate the creation request
[self.sdkInstance createGameHandleWithOptions:createOpts
                                   completion:^(id<SUDRTGameHandle> _Nullable handle, NSError * _Nullable error) {
    if (error) {
        NSLog(@"[SUD] Failed to create handle: %@", error.localizedDescription);
        return;
    }
    
    // 3. Hold the handle; all subsequent game operations are performed through it
    self.currentGameHandle = handle;
    NSLog(@"[SUD] Game handle created successfully, ready to load the resource package...");
}];

Notes ​

  • Multi-instance support: In theory, creating multiple handles simultaneously is supported, but limited by device performance and memory, it is generally recommended to run only one active game handle at a time.
  • Memory release: Once the completion callback returns the handle, the App must hold it properly. When the game is no longer needed, be sure to call the handle's destroy method, otherwise it will cause serious memory leaks.
  • Thread safety: The callback closure is typically executed on the SDK's internal worker thread. If you need to update the UI in this callback (such as displaying the game screen), be sure to manually switch back to the main thread: dispatch_async(dispatch_get_main_queue(), ^{ ... });.