Skip to content

loadCore ​

Load the Core Engine Module ​

loadCore is the "ice-breaking" interface that starts the entire game environment. In the SUD Runtime architecture, all JS rendering, native binding, and physics engine logic are encapsulated in the Runtime Core module. Before creating a specific game handle, you must call this method to complete the static resource mapping and dynamic library loading of the core engine.


Method Declaration ​

java
/**
 * Load an already-present local Runtime Core module
 * * Only one version of the Runtime Core can be loaded per process, and it cannot be unloaded.
 * To switch the Core version, you must do so by creating a new independent process.
 *
 * @param options  Runtime Core load parameters (a Bundle containing configuration such as paths and keys)
 * @param listener Runtime Core load result listener
 */
void loadCore(Bundle options, @NonNull SUDRT.CoreLoadListener listener);

Parameters ​

1. Bundle options (core configuration items) ​

When calling loadCore, you must use a Bundle to tell the SDK the physical location of the core files. The following are the commonly used Keys:

Constant KeyRequiredDescription
KEY_CORE_ROOT_PATHYesThe root directory path of the Core engine resources.
KEY_CORE_ASSETS_PATHYesThe path of the Core's internal static resources.
KEY_CORE_SHARED_LIBRARY_PATHYesThe path where the C++ shared libraries (.so) reside.
KEY_CORE_SECRET_KEYNoThe key used to decrypt core resources (if the resources are encrypted).
KEY_CORE_HASHNoThe hash checksum of the core files.

2. CoreLoadListener ​

  • void onSuccess(SUDRTGameCoreHandle handle): The core loaded successfully. The returned handle is a required parameter for the subsequent createGameHandle call.
  • void onFailure(Throwable throwable): Loading failed. Common causes include a missing .so file, a path with no access permission, or a CPU architecture mismatch (ABI error).

Runtime Behavior ​

  1. Singleton lock: Once the Core loads successfully, the process locks the current engine version. After that, calling loadCore again within the process usually returns success or an error directly, and cannot override the load.
  2. Native linking: The SDK performs a System.loadLibrary operation to inject the underlying rendering and logic capabilities into the JVM.
  3. Environment preparation: It initializes the built-in JS runtime (such as V8 or Hermes) and prepares the resource mapping table.

Example ​

java
// 1. Prepare the core configuration paths
Bundle coreOptions = new Bundle();
coreOptions.putString(SUDRT.KEY_CORE_ROOT_PATH, "/data/user/0/com.app/files/sud_core");
coreOptions.putString(SUDRT.KEY_CORE_SHARED_LIBRARY_PATH, "/data/user/0/com.app/lib");

// 2. Start loading
runtime.loadCore(coreOptions, new SUDRT.CoreLoadListener() {
    @Override
    public void onSuccess(SUDRTGameCoreHandle handle) {
        // Save the handle, ready to create a game instance
        mCoreHandle = handle;
        Log.i("SUDOP", "Runtime Core loaded successfully.");
    }

    @Override
    public void onFailure(Throwable throwable) {
        // Loading failed; check the path and ABI architecture
        Log.e("SUDOP", "Runtime Core load failed: " + throwable.getMessage());
    }
});

Notes ​

  • Process isolation: If your app needs to run game version A in one Activity and a substantially different game version B in another Activity, make sure they run in different android:process values.
  • ABI matching: Ensure that the .so files under KEY_CORE_SHARED_LIBRARY_PATH strictly match the current device's CPU architecture (arm64-v8a, armeabi-v7a, etc.).
  • Preloading recommendation: Because loading the core involves disk I/O and native linking and takes on the order of hundreds of milliseconds, it is recommended to run it in advance during the app's cold start or when entering the game lobby.