loadCore

加载核心引擎模块

loadCore 是启动整个游戏环境的“破冰”接口。在 SUD Runtime 的架构中，所有的 JS 渲染、Native 绑定以及物理引擎逻辑都封装在 Runtime Core 模块中。在创建具体的游戏句柄（Handle）之前，必须先调用此方法完成核心引擎的静态资源映射与动态库加载。

---

方法声明

/**
 * 加载本地已存在的 Runtime Core 模块
 * * 一个进程中只能加载一个版本的 Runtime Core 且无法卸载。
 * 如果需要更换 Core 的版本，必须通过建立新的独立进程来实现。
 *
 * @param options  Runtime Core 加载参数（包含路径、密钥等配置的 Bundle）
 * @param listener Runtime Core 加载结果监听器
 */
void loadCore(Bundle options, @NonNull SUDRTGameRuntime.CoreLoadListener listener);

---

参数说明

1. Bundle options (核心配置项)

调用 loadCore 时，必须通过 Bundle 告知 SDK 核心文件的物理位置。以下是常用的 Key：

常量 Key	是否必填	描述
KEY_CORE_ROOT_PATH	是	Core 引擎资源的根目录路径。
KEY_CORE_ASSETS_PATH	是	Core 内部静态资源路径。
KEY_CORE_SHARED_LIBRARY_PATH	是	C++ 共享库（.so）所在的路径。
KEY_CORE_SECRET_KEY	否	用于核心资源解密的密钥（若资源已加密）。
KEY_CORE_HASH	否	核心文件的 Hash 校验值。

2. CoreLoadListener

• void onSuccess(SUDRTGameCoreHandle handle)：核心加载成功。返回的 handle 是后续调用 createGameHandle 的必需参数。
• void onFailure(Throwable throwable)：加载失败。常见原因包括 .so 文件缺失、路径无访问权限或 CPU 架构不匹配（ABI 错误）。

---

运行行为

1. 单例锁定：一旦 Core 加载成功，该进程将锁定当前版本的引擎。此后在该进程内再次调用 loadCore 通常会直接返回成功或报错，无法覆盖加载。
2. Native 链接：SDK 会执行 System.loadLibrary 操作，将底层的渲染与逻辑能力注入 JVM。
3. 环境准备：初始化内置的 JS 运行时（如 V8 或 Hermes），并准备好资源映射表。

---

代码示例

// 1. 准备核心配置路径
Bundle coreOptions = new Bundle();
coreOptions.putString(SUDRTGameRuntime.KEY_CORE_ROOT_PATH, "/data/user/0/com.app/files/sud_core");
coreOptions.putString(SUDRTGameRuntime.KEY_CORE_SHARED_LIBRARY_PATH, "/data/user/0/com.app/lib");

// 2. 发起加载
runtime.loadCore(coreOptions, new SUDRTGameRuntime.CoreLoadListener() {
    @Override
    public void onSuccess(SUDRTGameCoreHandle handle) {
        // 保存 handle，准备创建游戏实例
        mCoreHandle = handle;
        Log.i("SUDOP", "Runtime Core loaded successfully.");
    }

    @Override
    public void onFailure(Throwable throwable) {
        // 加载失败，检查路径和 ABI 架构
        Log.e("SUDOP", "Runtime Core load failed: " + throwable.getMessage());
    }
});

---

注意事项

• 进程隔离：如果你的应用需要在一个 Activity 中运行 A 版本游戏，在另一个 Activity 中运行版本差异巨大的 B 版本游戏，请确保它们运行在不同的 android:process 中。
• ABI 匹配：确保 KEY_CORE_SHARED_LIBRARY_PATH 下的 .so 文件与当前设备的 CPU 架构（arm64-v8a, armeabi-v7a 等）严格一致。
• 预加载建议：由于加载核心涉及磁盘 I/O 和 Native 链接，耗时约在百毫秒级，建议在应用冷启动或进入游戏大厅时提前执行。

---