文档中心

stop ​

停止并发送隐藏消息 ​

stop: 用于停止小游戏的运行。与无参数的 stop 不同，该方法允许在停止引擎逻辑的同时，向游戏脚本发送一条最后的“隐藏消息”（Hide Message）。这通常用于通知游戏当前的退出原因、保存最后的业务状态，或触发游戏内部的销毁清理逻辑。

方法声明 ​

objectivec
/**
 * 停止小游戏运行并发送消息。
 * @param onHideMsg 停止时透传给游戏的最后一条消息字符串（推荐 JSON 格式）。
 * 该消息会在游戏的 `onHide` 生命周期或销毁回调中被捕获。
 */
- (void)stop:(nullable NSString *)onHideMsg;

参数说明 ​

参数名类型必传描述
onHideMsgNSString否停止消息：包含如 reason (退出原因)、lastScore (最终得分) 等参数。如果不需传参，可传 nil 或 "{}"。

运行行为 ​

  1. 最后通牒：在引擎彻底关闭前，先将 onHideMsg 派发给 JavaScript 层。
  2. 生命周期触发：触发游戏内部的 onHide 回调，游戏可以根据传入的 JSON 字符串执行最后的存档或资源释放。
  3. 引擎挂起：完成消息派发后，立即停止 JavaScript 虚拟机的运行。
  4. 状态迁移：状态由 SUD_RT_GAME_STATE_PLAYING (3) 或 SUD_RT_GAME_STATE_RUNNING (2) 回退至 SUD_RT_GAME_STATE_WAITING (1)。

代码示例 ​

在用户因余额不足或被踢出房间时调用，告知游戏退出原因：

objectivec
// 1. 构造停止时的业务参数
NSDictionary *stopParams = @{
    @"reason": @"room_closed",
    @"save_state": @(YES)
};

// 2. 转换为 JSON 字符串
NSData *jsonData = [NSJSONSerialization dataWithJSONObject:stopParams options:0 error:nil];
NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];

// 3. 停止运行 (Selector: stop:)
[self.gameHandle stop:jsonString];

NSLog(@"[SUD] 游戏停止指令已下发，附带退出原因。");

注意事项 ​

  • 异步执行：调用此方法后，引擎会尽力确保消息送达 JavaScript 层，但如果脚本已崩溃或处于死循环，消息可能无法被处理。
  • 状态重置：调用 stop: 后，游戏的所有渲染和计时器都会停止。若要再次启动，必须重新调用 start:。
  • 资源保留：此方法不会销毁 gameHandle 实例，内存中仍保留引擎环境。
  • 命名匹配：请注意在 Objective-C 中，该方法的完整 Selector 是 stop:（带冒号），这与不带参数的 stop 是两个不同的入口。