文档中心

setGameStartOptions ​

设置游戏启动参数 ​

setGameStartOptions 是 SUDRTGameHandle 中最核心的配置接口。它允许开发者在正式创建游戏环境（调用 create()）之前，通过 Bundle 定义游戏的运行行为、渲染性能、网络超时以及调试开关。

方法声明 ​

java
/**
 * 设置游戏启动时所需的参数信息。
 * * @param id      必填。要启动的小游戏的唯一标识（Game ID）。
 * @param options 可选。包含各种配置 Key 的 Bundle 对象。
 * @return boolean 是否设置成功。
 */
boolean setGameStartOptions(@NonNull String id, final Bundle options);

常用配置项（Bundle Key） ​

这些常量定义在 SUDRTGameHandle 接口中，按功能分类如下：

1. 基础信息 ​

常量 Key类型描述
KEY_GAME_USER_IDString当前登录用户的唯一 ID，用于游戏内数据隔离。
KEY_GAME_START_OPTIONS_GAME_VERSIONString指定启动的游戏包版本。

2. 渲染与视图 ​

常量 Key类型描述
KEY_GAME_VIEW_TYPEint视图类型。1 为 SurfaceView（默认），2 为 TextureView。
KEY_GAME_START_OPTIONS_PIXEL_RATIOfloat逻辑像素与物理像素比（DPR）。
KEY_GAME_START_OPTIONS_RENDER_THREAD_MODEint渲染线程模式。建议使用 RENDER_THREAD_MODE_AUTO。

3. 调试配置 (Debug Options) ​

常量 Key类型描述
KEY_GAME_DEBUG_OPTION_ENABLE_FPSboolean是否在界面上显示帧率（FPS）监控面板。
KEY_GAME_DEBUG_OPTION_ENABLE_V_CONSOLEboolean是否开启 vConsole（JS 日志调试面板）。
KEY_GAME_DEBUG_OPTION_ENABLE_DEBUGGERboolean是否开启远程调试端口。

4. 网络超时设置 (Network) ​

  • KEY_GAME_START_OPTIONS_NETWORK_TIMEOUT_DOWNLOAD: 下载超时（ms）。
  • KEY_GAME_START_OPTIONS_NETWORK_TIMEOUT_XML_HTTP_REQUEST: AJAX 请求超时（ms）。
  • KEY_GAME_START_OPTIONS_NETWORK_TIMEOUT_WEB_SOCKET: WebSocket 连接超时（ms）。

运行行为 ​

  1. 调用时机：必须在调用 create() 之前执行。如果在游戏运行中调用，参数通常不会立即生效，除非重新启动实例。
  2. 默认值：如果 options 传 null 或未设置某个 Key，SDK 将使用内置的默认配置（例如默认开启多线程渲染）。
  3. 持久性：设置的参数将作用于该 SUDRTGameHandle 的整个生命周期，直到该句柄被 destroy()。

代码示例 ​

java
Bundle options = new Bundle();

// 1. 设置渲染视图为 TextureView (支持动画/层叠效果更好)
options.putInt(SUDRTGameHandle.KEY_GAME_VIEW_TYPE, SUDRTGameHandle.GAME_VIEW_TYPE_TEXTURE_VIEW);

// 2. 开启调试功能，方便开发阶段排查 JS 错误
options.putBoolean(SUDRTGameHandle.KEY_GAME_DEBUG_OPTION_ENABLE_V_CONSOLE, true);
options.putBoolean(SUDRTGameHandle.KEY_GAME_DEBUG_OPTION_ENABLE_FPS, true);

// 3. 设置网络超时为 10 秒
options.putInt(SUDRTGameHandle.KEY_GAME_START_OPTIONS_NETWORK_TIMEOUT_DOWNLOAD, 10000);

// 4. 应用配置
boolean success = gameHandle.setGameStartOptions("demo_game_001", options);

if (success) {
    // 参数设置成功，可以开始创建环境
    gameHandle.create();
}

注意事项 ​

  • View 类型选择：SurfaceView 性能最高，适合重度游戏；TextureView 兼容性更强，支持在 View 上做透明度动画或截图，但会有轻微性能损耗。
  • 渲染线程模式：除非有特殊需求（如需要与原生 UI 线程极度同步），否则请维持默认的 RENDER_THREAD_MODE_AUTO。
  • 权限与存储：如果设置了 KEY_GAME_START_OPTIONS_LIMIT_USER_STORAGE，当游戏存储超过该值时，JS 层的写入操作会报错。