Skip to content

createGameHandle ​

Create a Game Runtime Environment Instance ​

createGameHandle is the key interface that bridges from the Runtime engine layer to the game business layer. After the engine core has been successfully loaded via loadCore(), calling this method initializes the runtime environment for a specific game.

It not only establishes the binding between the Activity and the game view, but also configures the game's storage space, core path, and plugin system according to the passed-in options parameter.


Method Declaration ​

java
/**
 * Create a game runtime environment instance
 * * @param activity   The current host Activity
 * @param options    A Bundle containing key parameters such as path configuration and manager configuration
 * @param coreHandle The handle obtained from the loadCore() onSuccess callback
 * @param listener   Creation result listener
 */
void createGameHandle(
    @NonNull Activity activity, 
    @NonNull Bundle options, 
    @NonNull SUDRTGameCoreHandle coreHandle, 
    @NonNull SUDRT.GameHandleCreateListener listener
);

Parameters ​

1. Activity ​

  • Description: The context in which the game runs. The SDK needs this Activity to handle UI rendering, lifecycle synchronization (such as orientation changes), and permission requests.

2. Bundle options (core configuration items) ​

This parameter must contain the key paths defined in the SUDRT interface. The following are the categories of required Keys:

CategoryConstant Key (String)Description
Storage pathKEY_RUNTIME_STORAGE_PATH_APPThe game's persistent private directory.
KEY_RUNTIME_STORAGE_PATH_CACHEThe game's temporary cache directory.
Core pathKEY_CORE_ROOT_PATHThe root directory where the Core engine resides.
KEY_CORE_SHARED_LIBRARY_PATHThe physical path where the .so library files reside.
JS entryKEY_RUNTIME_GAME_PACKAGE_JS_ENTRY_PATHThe relative/absolute path of the main JS file inside the game package.

3. SUDRTGameCoreHandle ​

  • Description: It is the "credential" of a successful engine core load. It must be obtained in the loadCore success callback and cannot be created on your own.

Runtime Behavior ​

  1. Environment isolation: Based on the paths in options, the SDK allocates an independent sandbox space for the game instance.
  2. Handle generation: On success, onSuccess returns an SUDRTGameHandle object. This object is the sole entry point for all subsequent operations (such as start, sending instructions, and destroy).
  3. Reuse logic: To restart the game with different parameters, it is officially recommended to first call gameHandle.destroy() to release resources, then run createGameHandle again, or update the Options and then call start().

Example ​

java
// 1. Assemble the configuration information
Bundle options = new Bundle();
options.putString(SUDRT.KEY_CORE_ROOT_PATH, coreDir.getPath());
options.putString(SUDRT.KEY_RUNTIME_STORAGE_PATH_APP, gameDir.getPath());
options.putString(SUDRT.KEY_RUNTIME_GAME_PACKAGE_JS_ENTRY_PATH, "main.js");

// 2. Call the creation interface
runtime.createGameHandle(this, options, mCoreHandle, new SUDRT.GameHandleCreateListener() {
    @Override
    public void onSuccess(SUDRTGameHandle handle) {
        // Created successfully; save the handle for subsequent operations
        mGameHandle = handle;
        Log.i("SUDOP", "Game handle created successfully.");
        
        // Next you can call handle.start() or configure ViewMode
    }

    @Override
    public void onFailure(Throwable throwable) {
        // Creation failed, possibly due to an invalid path or resource conflict
        Log.e("SUDOP", "Failed to create handle: " + throwable.getMessage());
    }
});

Notes ​

  • Thread safety: This method should be called on the main thread, as it involves UI binding with the Activity.
  • Lifecycle: An Activity usually corresponds to only one active SUDRTGameHandle at a time.
  • Path validity: Before passing in the Bundle, be sure the corresponding local directory has been created and has read/write permissions.