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:
| Category | Constant Key (String) | Description |
|---|---|---|
| Storage path | KEY_RUNTIME_STORAGE_PATH_APP | The game's persistent private directory. |
KEY_RUNTIME_STORAGE_PATH_CACHE | The game's temporary cache directory. | |
| Core path | KEY_CORE_ROOT_PATH | The root directory where the Core engine resides. |
KEY_CORE_SHARED_LIBRARY_PATH | The physical path where the .so library files reside. | |
| JS entry | KEY_RUNTIME_GAME_PACKAGE_JS_ENTRY_PATH | The 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
loadCoresuccess callback and cannot be created on your own.
Runtime Behavior
- Environment isolation: Based on the paths in
options, the SDK allocates an independent sandbox space for the game instance. - Handle generation: On success,
onSuccessreturns anSUDRTGameHandleobject. This object is the sole entry point for all subsequent operations (such as start, sending instructions, and destroy). - Reuse logic: To restart the game with different parameters, it is officially recommended to first call
gameHandle.destroy()to release resources, then runcreateGameHandleagain, or update the Options and then callstart().
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
Activityusually corresponds to only one activeSUDRTGameHandleat a time. - Path validity: Before passing in the
Bundle, be sure the corresponding local directory has been created and has read/write permissions.
