常见问题 FAQ

认证与连接

游戏前端需要处理玩家账号或密码吗? 不需要,也接触不到。玩家凭证始终由大厅宿主持有,游戏前端只通过 postMessage 向宿主索取一次性 WebSocket 票据,票据单次有效、30 秒过期。前端 SDK 的 ticketProvider 已封装该流程。

平台有 App Secret 或接口签名吗? 没有。游戏逻辑运行在平台隔离运行时内,与平台钱包等能力是进程内调用,不存在网络签名。后台操作在浏览器内完成,登录态由后台页面自动维护。

WebSocket 握手失败,错误码 401005? 票据单次有效且 30 秒过期,重连必须重新索取。SDK 会自动处理;若自研客户端遇到该错误,检查是否复用了旧票据,或与建立连接的间隔是否超过 30 秒。

后台登录被限流(429001)? 登录每 IP 每分钟 30 次,连续失败 10 次锁定 10 分钟。检查用户名密码,稍后再试。

为什么我的 onAction 没有被调用? 玩法动作仅在会话进入 playing 状态后受理。quick 模式需玩家申报就绪且人数达到 minPlayer;room 模式需房主开局。检查前端是否调用了 client.ready() 或等待开局完成。

收到"游戏脚本执行超时"(500501)怎么办? 单次回调(含定时器回调)硬上限 2 秒,超时会话立即进入 error 终态。优化搜索与 AI 算法复杂度,采用节点预算加兜底策略,把重计算拆到多个动作或定时器切片中。

onSync 不实现会怎样? 断线重连、切换标签页回前台、错误恢复后的画面重建全部失效,提审也会被拒。onSync 是玩家对账的唯一通道,必须实现并用 sendTo 回应本人全量状态。

能用 Math.random 吗? 运行时中 Math.random 已被替换为密码学安全随机源,普通玩法可直接使用。涉及资金与奖励的随机结果必须使用公平随机接口,保证玩家可验证,否则拒审。

逻辑包里为什么不能用 fetch、DOM? 游戏逻辑运行在无网络、无 DOM 的隔离运行时中,这是安全模型的一部分。需要外部数据的玩法当前不支持,所有数据必须由玩家动作或前端带入。

钩子返回时回合没闭合会怎样? 本次回调中排队的全部钱包操作作废并产生会话错误。必须保证任何分支下 beginRound 之后都能执行到 endRound,用 try/finally 组织代码。

余额不足时会发生什么? 不会抛异常。扣款登记成功但 endRound 提交失败,返回 false;调用 lastRoundError() 读取原因(如 [400511] 余额不足),回滚本局状态并提示玩家。余额校验以平台结算时为准,禁止用 getBalance 预检。

玩家重复发送同一动作,会重复扣款吗? 不会。客户端消息按玩家与动作序号去重,同一动作不会重复进入 onAction;回合内的每笔操作也有平台生成的幂等键,重复提交整回合会返回已完成结果。

getBalance 为什么和玩家看到的余额不一致? getBalance 是引擎本地缓存,可能滞后。游戏内余额显示的唯一权威是 wallet:balance 版本化推送,按 version 单调守卫应用。

回合提交有时间限制吗? endRound 提交超时 15 秒,整组操作原子生效,任一失败全部回滚并逐操作下发 wallet:error。不要设计跨回合的半结算状态。

不调用 recordResult 会怎样? 玩家个人中心看不到该局的对局记录与胜负,影响体验与客服举证。建议每局结算时登记 win、lose 或 draw 与分数变化。

审核通过后还需要手动上架吗? 不需要,过审即发布:游戏转为 approved、立即出现在大厅。版本回滚才需要调用 switch 接口。

只更新前端,逻辑包可以不传吗? 可以,留空自动继承上一版本的逻辑包。反之亦然。但两侧都无变更的提交会被拒绝(400332)。

驳回原因在哪里看? 包记录的 reviewComment 字段,经 GET /api/admin/game/:id/package 或后台版本页查看。

怎么回滚到旧版本? POST /api/admin/game/:id/package/:pid/switch,目标包必须是已过审状态;归档状态的游戏不能切换。

rtpDeclared 填写错误会怎样? 平台每日比对实际运行数据,总投注 ≥ 10 万金币、回合 ≥ 100 且偏差超过 2 个百分点时触发风控核查。调整玩法参数后,记得在新版本同步更新申报值。

发版会影响进行中的对局吗? 不会。进行中的对局继续使用旧版本直至结束,新对局使用新版本。

平台有 Sandbox 测试环境吗? 当前没有独立 Sandbox。线上平台即为验证环境:金币为虚拟物品、支付为沙箱模拟,不会发生真实扣款。本地完成构建自检与逻辑自测后,直接在线上提审验证。

游戏前端本地单独打开为什么不能玩? 没有平台宿主时拿不到连接配置与票据,SDK 会停在等待宿主状态,这是安全设计。界面与纯前端交互可本地预览,完整链路必须经平台大厅进入。

怎么在本地测多人玩法? 同一浏览器的多个标签页共享登录态,是同一个玩家。测多人需要多个浏览器配置文件或无痕窗口,分别注册登录不同玩家账号后进入同一游戏:quick 模式等待匹配,room 模式用房间码互相加入。

如何排查线上对局问题? 平台保留每回合审计账与最多 500 条广播事件的回放记录,可通过客服工单请求平台调取;游戏逻辑内用 platform.log 打出的日志也在平台侧留存。