文档中心

stop ​

停止小游戏脚本运行 ​

stop() 用于停止当前正在运行的小游戏脚本。调用此方法后，游戏将从 PLAYING 或 RUNNING 状态回退至 WAITING 状态。

与 pause() 不同的是，stop() 通常伴随着明确的业务意图（如玩家主动点击退出），它会触发小游戏内部的 onHide 生命周期函数，并允许你向 JS 层传递特定的退出或停止参数。

方法声明 ​

java
/**
 * 停止小游戏运行。
 * 操作成功后小游戏实例进入 `WAITING` 状态。
 *
 * @param onHideMsg 程序切后台或停止前，作为 js api `onHide` 回调的参数。
 * 通常传入一个 JSON 字符串，用于告知游戏停止的原因或保存当前状态。
 */
void stop(String onHideMsg);

运行行为与状态迁移 ​

1. 前提条件 ​

  • 当前状态必须为 GAME_STATE_RUNNING 或 GAME_STATE_PLAYING。
  • 游戏环境必须存在且尚未被销毁（UNAVAILABLE）。

2. 执行过程 ​

  • 触发回调：SDK 向 JS 引擎发送指令，触发游戏代码中的 App.onHide(onHideMsg)。
  • 逻辑终止：停止游戏逻辑更新、物理模拟和渲染提交。
  • 资源挂起：音频和输入监听被完全切断。

3. 结果 ​

  • 成功后，状态变为 GAME_STATE_WAITING。
  • 此时脚本处于非激活状态，但 JS 虚拟机内存并未释放，可以通过调用 start() 再次快速启动。

代码示例 ​

java
// 当用户点击原生“返回”或“关闭游戏”按钮时
public void handleUserExit() {
    // 构造告知游戏层的停止参数
    String onHideMsg = "{\"reason\": \"user_exit\", \"timestamp\": " + System.currentTimeMillis() + "}";
    
    // 停止运行
    gameHandle.stop(onHideMsg);
    
    // 如果确认不再需要该游戏实例，紧接着执行销毁
    // gameHandle.destroy();
}

注意事项 ​

  • onHideMsg 的重要性：小游戏可以在 onHide 回调中执行存档、上报埋点或清理本地临时数据的操作。请确保传入的 JSON 字符串符合你与游戏开发者之间的协议。
  • 与 pause 的区别：虽然两者最终都会进入 WAITING 状态，但 stop 强调的是“停止逻辑”，且带有 onHideMsg 参数；而 pause 更倾向于系统级的暂时挂起。
  • 异步确认：如果游戏在 onHide 中执行了复杂的 IO 操作，状态切换可能会有微小的延迟。建议通过 GameStateChangeListener 观察状态是否成功切回 WAITING。