createGameHandle

创建游戏运行环境实例

createGameHandle 是从 Runtime 引擎层跨越到游戏业务层的关键接口。在通过 loadCore() 成功加载引擎核心后，调用此方法会初始化一个具体游戏的运行环境。

它不仅会建立 Activity 与游戏视图的绑定关系，还会根据传入的 options 参数配置游戏的存储空间、核心路径以及插件系统。

---

方法声明

/**
 * 创建游戏运行环境实例
 * * @param activity   当前宿主 Activity
 * @param options    包含路径配置、管理器配置等关键参数的 Bundle
 * @param coreHandle 通过 loadCore() onSuccess 回调获得的句柄
 * @param listener   创建结果监听器
 */
void createGameHandle(
    @NonNull Activity activity, 
    @NonNull Bundle options, 
    @NonNull SUDRTGameCoreHandle coreHandle, 
    @NonNull SUDRTGameRuntime.GameHandleCreateListener listener
);

---

参数说明

1. Activity

• 说明：游戏运行的上下文。SDK 需要此 Activity 来处理 UI 渲染、生命周期同步（如横竖屏切换）以及权限请求。

2. Bundle options (核心配置项)

此参数必须包含 SUDRTGameRuntime 接口中定义的关键路径。以下是必需填写的 Key 分类：

分类	常量 Key (String)	描述
存储路径	KEY_RUNTIME_STORAGE_PATH_APP	游戏的持久化私有目录。
	KEY_RUNTIME_STORAGE_PATH_CACHE	游戏的临时缓存目录。
Core 路径	KEY_CORE_ROOT_PATH	Core 引擎所在的根目录。
	KEY_CORE_SHARED_LIBRARY_PATH	.so 库文件所在的物理路径。
JS 入口	KEY_RUNTIME_GAME_PACKAGE_JS_ENTRY_PATH	游戏包内主 JS 文件的相对/绝对路径。

3. SUDRTGameCoreHandle

• 说明：它是引擎核心加载成功的“凭证”。必须在 loadCore 成功回调后获取，不可自行创建。

---

运行行为

1. 环境隔离：SDK 会根据 options 中的路径，为该游戏实例分配独立的沙盒空间。
2. 句柄生成：成功后，onSuccess 会返回一个 SUDRTGameHandle 对象。该对象是后续所有操作（如启动、发送指令、销毁）的唯一入口。
3. 重用逻辑：如需更换参数重开游戏，官方建议先调用 gameHandle.destroy() 释放资源，再重新执行 createGameHandle 或更新 Options 后 start()。

---

代码示例

// 1. 组装配置信息
Bundle options = new Bundle();
options.putString(SUDRTGameRuntime.KEY_CORE_ROOT_PATH, coreDir.getPath());
options.putString(SUDRTGameRuntime.KEY_RUNTIME_STORAGE_PATH_APP, gameDir.getPath());
options.putString(SUDRTGameRuntime.KEY_RUNTIME_GAME_PACKAGE_JS_ENTRY_PATH, "main.js");

// 2. 调用创建接口
runtime.createGameHandle(this, options, mCoreHandle, new SUDRTGameRuntime.GameHandleCreateListener() {
    @Override
    public void onSuccess(SUDRTGameHandle handle) {
        // 创建成功，保存句柄用于后续操作
        mGameHandle = handle;
        Log.i("SUDOP", "Game handle created successfully.");
        
        // 接下来可以调用 handle.start() 或配置 ViewMode
    }

    @Override
    public void onFailure(Throwable throwable) {
        // 创建失败，可能是路径无效或资源冲突
        Log.e("SUDOP", "Failed to create handle: " + throwable.getMessage());
    }
});

---

注意事项

• 线程安全：此方法应在主线程中调用，因为涉及到与 Activity 的 UI 绑定。
• 生命周期：一个 Activity 在同一时间通常只对应一个活动的 SUDRTGameHandle。
• 路径有效性：在传入 Bundle 之前，务必确保对应的本地目录已经创建且具有读写权限。

---