文档中心

pause ​

暂停小游戏运行 ​

pause() 用于将小游戏从当前的活跃状态（PLAYING 或 RUNNING）切换到暂停状态。调用此方法后，游戏将进入 WAITING 状态。

在暂停期间，引擎会停止渲染循环、暂停音频播放，并切断所有的用户输入分发（如触摸事件和传感器数据）。这对于节省系统资源和电池电量至关重要。

方法声明 ​

java
/**
 * 暂停小游戏运行。
 * 操作成功后小游戏实例进入 `WAITING` 状态。
 * 通常在 App 切到后台或弹出原生全局对话框时调用。
 */
void pause();

运行行为与状态迁移 ​

1. 前提条件 ​

  • 当前状态通常应为 GAME_STATE_PLAYING 或 GAME_STATE_RUNNING。
  • 只有在环境已经创建且正在运行时，暂停指令才有效。

2. 执行过程 ​

  • 逻辑挂起：脚本引擎的定时器（如 requestAnimationFrame）会被挂起。
  • 资源静默：音频输出被静音或停止，渲染管线停止提交新帧。
  • 交互切断：不再响应任何屏幕触摸操作。

3. 结果 ​

  • 成功后，状态回退至 GAME_STATE_WAITING。
  • 此时游戏画面保持在暂停前的最后一帧（取决于具体的 Surface 回收策略）。

代码示例 ​

java
@Override
protected void onPause() {
    super.onPause();
    // 当 Activity 失去焦点或进入后台时，主动暂停游戏
    if (gameHandle != null) {
        gameHandle.pause();
    }
}

// 或者在弹出重要的原生 UI 模块时
public void showNativePayDialog() {
    gameHandle.pause();
    // 执行原生支付逻辑...
}

注意事项 ​

  • 必须配对使用：调用 pause() 后，当用户返回游戏时，必须通过 start() 或 play()（取决于你希望恢复到的具体阶段）来唤醒游戏。
  • 生命周期对齐：强烈建议将 pause() 放在 Activity 的 onPause() 中，将 start() 放在 onResume() 中，以确保小游戏与 App 的生命周期保持严格一致。
  • 音频处理：虽然 SDK 会尝试自动处理，但在某些极端机型上，建议在 pause() 之后显式检查是否有未关闭的系统级音频流，以防“人走了声音还在”。