Game SDK v1 快速开始

使用范围

SDK 脚本路径为 /games/sdk/v1.js。站内游戏通过播放器连接宿主；独立页面自动退回本地存档。外部投稿仅作为链接打开，不会因为引用 SDK 就获得本站账号权限。

开发者本地调试时可下载此脚本随自己的页面运行。下面的 my-game 是示例 ID；上线前必须由维护者注册实际游戏 ID。

最小接入示例

<script src="/games/sdk/v1.js"></script>
<script>
(async () => {
  const gg = await GeekGravity.init({ game: 'my-game', version: '1.0.0' });
  let state = { schemaVersion: 1, level: 1 };
  function restore(data) {
    // 实际游戏应校验格式、迁移旧版本，并重新渲染运行中的状态。
    if (data && data.schemaVersion === 1) state = data;
  }
  gg.on('save', ({ data }) => restore(data));
  const saved = await gg.save.load();
  restore(saved.data);
  gg.ready();

  // 在关卡结束等稳定节点调用；不要每帧保存。
  async function checkpoint() {
    const result = await gg.save.write(state, { summary: { level: state.level } });
    if (!result.saved) console.warn('保存失败，请不要关闭页面');
    else if (result.source !== 'cloud') console.info('已本地保存，尚未确认云端同步');
  }
  // 将 checkpoint 绑定到游戏中的保存节点。
})();
</script>

常用接口

接口	用途
gg.host	当前连接：web、app 或 standalone
gg.ready()	通知宿主游戏已准备好
gg.user()	读取 { signedIn, name }，不暴露账号令牌
await gg.requestLogin()	请求宿主登录；返回后检查 signedIn，不能假定用户完成登录
gg.on('pause', fn) / gg.on('resume', fn)	挂接自己的暂停、恢复逻辑
gg.on('user', fn)	接收用户状态变化
gg.on('save', ({ data, rev }) => ...)	用户选择其他存档后，替换运行中的状态
await gg.save.load()	返回 { data, rev, source }，无存档时 data 可为空
await gg.save.write(data, { summary })	先写本地，再尝试宿主同步；检查 saved 和 source
gg.off(event, fn)	移除监听；on 也会返回取消监听函数

数据必须可以 JSON 序列化。账号存档正文上限 64 KiB，摘要上限 1 KiB。不要把图片或大型资源放入存档。

冲突与合并

默认由宿主让玩家选择保留哪份存档。需要自动合并时，可以向 init 传入同步 merge(local, cloud) 函数，返回可序列化数据。只对能安全合并的数据启用，例如已解锁关卡的集合；金币、消耗品和进行中的战局不能简单取最大值或相加。

更多说明见存档、同步与常见问题。App 需要实现相同宿主协议；脚本检测到 App 环境不代表某个客户端版本已经具备所有能力，发布前须在目标版本验证。