开发者文档 · v1

游戏接入平台

接入 HTML5 游戏、玩家身份、侧栏、防 Boss 与音频控制。

适用于 HTML、CSS、JavaScript 构成的静态 HTML5 游戏。平台分发已构建的文件，通过 iframe 外壳提供身份展示、侧栏和防 Boss。游戏自己的运行、音频和进度保存仍由游戏实现。

游戏构建环境由游戏项目自行决定，包括 Node.js 26.5.0 与 pnpm 11.17.0。平台只托管构建后的静态网页文件；需要常驻 Node 服务、服务端渲染或私有后端的项目，应先导出为静态资源或另行部署后端。上传可使用独立 MCP 客户端，无需平台源码。

文件与来源

将游戏适配器下载后复制到游戏发布目录，使用相对路径加载。平台不会替游戏运行构建命令；入口 HTML 及其引用的资源都需要包含在提交目录或 ZIP 中。

正式平台来源固定为 https://scalia.ltd。游戏文件来自 https://game-游戏UUID.scalia.ltd，候选预览来自 https://preview-候选UUID.scalia.ltd。同款游戏使用稳定独立来源，版本入口位于 /v/版本UUID/入口路径，以便更新后继续访问同源浏览器存档。各游戏和平台的存储彼此隔离。

详情链接为 /games/slug，游玩外壳为 /play/slug。分享详情或游玩外壳链接，不分享私有候选、凭据或带个人数据的链接。首页和详情不提前下载游戏包。

最小接入示例

下面的回调需要连接到游戏现有的身份、场景和音频系统。顶层单独打开游戏或私有文件预览时不建立父窗口连接，保留游戏原本的启动逻辑。

<script src="./youxi-game-v1.js"></script>
<script>
const platform = window.parent !== window ? YouxiGame.connect({
  platformOrigin: 'https://scalia.ltd',
  onIdentity(identity) {
    updatePlayerDisplay(identity);
  },
  onState({ sidebar, boss }) {
    setPlatformScene({ sidebar, boss });
  },
  setTemporaryMuted(muted) {
    setPlatformAudioMute(muted);
    return true; // 仅在实际同步覆盖全部音源后返回 true
  },
  isRunning() { return gameIsRunning(); }
}) : null;

// 在资源、场景与玩法均已准备好后调用，而不是刚加载脚本时。
// 放入你自己的游戏加载完成回调：
function onGameReady() {
  platform?.ready();
}

// 游戏中的平台入口按需调用：
// platform?.open('sidebar');
// platform?.open('login');
// platform?.open('instructions');
// platform?.open('settings');
// 游戏彻底结束时可 platform?.destroy()。
</script>

updatePlayerDisplay、setPlatformScene、setPlatformAudioMute 和 gameIsRunning 是示意函数，需要由游戏实现。不要从收到的消息、查询参数或不可信输入自动取 platformOrigin。本地开发时才改成对应本地平台来源，例如 http://127.0.0.1:53200。

玩家身份与存档

onIdentity 收到游客或成员身份。成员的 user 只含 id、nickname、avatarId、revision。登录、退出或资料变化可在游戏运行中更新，无需重新加载。

这些资料仅用于展示，不能作为游戏后端登录凭证。适配器不提供邮箱、管理员角色、网页 Cookie、CSRF 或 MCP 凭据；当前没有统一云存档和游戏后端身份令牌。各游戏自行保存进度，平台不调用游戏存档接口或回放旧快照。

真实可玩后调用 ready()，平台才会确认最近玩过。游客记录保存在该浏览器，登录后不会自动合并到账号记录。游戏加载失败或未完成 ready 不应产生一次成功游玩记录。

运行与音频

为手动暂停、游戏菜单、平台侧栏和防 Boss 分别维护暂停原因。恢复平台遮盖时只移除对应原因，保留玩家原有的暂停状态。增量游戏可以按自身玩法继续结算经过时间；浏览器可能限制后台计时，时间修正由游戏自行处理。

音频需要独立维护“用户音量/静音”和“平台临时静音”。Web Audio 应统一接入输出 GainNode，HTMLAudio、HTMLVideo 及第三方播放器也要接入中央音频控制。之后新创建的音源在播放前同样应用临时静音。

setTemporaryMuted 必须同步完成静音后返回 true。Promise 不算成功回执。平台能立即遮盖 iframe 画面，但实际静音依赖游戏适配，必须逐款验收。

消息协议 v1

适配器发送 game.hello，平台按来源、父子窗口和当前实例完成握手。iframe 每次加载产生新实例；旧实例消息不生效。常规业务消息信封如下：

{
  "protocol_version": 1,
  "instance_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "22222222-2222-4222-8222-222222222222",
  "type": "game.ready",
  "payload": {}
}

游戏侧业务消息上限 4 KiB，请求去重保留最近 1024 个 UUID。使用适配器即可完成来源、窗口、实例和结构校验；不要改成通配 postMessage('*')。游戏消息不能直接触发平台管理、上传或发布。

快捷键与预览

默认 Alt+M 展开或收起侧栏，Alt+Q 进入防 Boss，Alt+Shift+Q 恢复；macOS 对应 Option。玩家可在设置中修改，适配器会接收新偏好。进入是幂等操作，不通过同一组合键切回。输入框内不触发侧栏快捷键，但进入和恢复防 Boss 仍有效。

侧栏覆盖游戏，iframe 尺寸不变。全屏由平台外壳统一控制，游戏不能单独全屏、顶层跳转或弹窗。私有候选预览在独立顶层页面打开；它用于检查文件，不等同于完整外壳联调。正式发布后仍需验证游玩外壳里的身份、侧栏、快捷键和音频。

上架前检查

• 确认入口和相对资源完整；资源准备成功后才 ready，失败不记成功游玩。
• 登录、退出、更新身份、展开侧栏和防 Boss 均不重载游戏。
• 遮盖期间所有已有和新音源都静音，恢复后保留用户原音量与静音设置。
• 原有手动暂停不被恢复操作清空；增量游戏进度不回滚。
• 游戏有输入焦点、鼠标锁定和外壳全屏时，快捷键与恢复均正常。
• 在目标电脑浏览器和真实手机检查触控、系统快捷键及浏览器存档。

下一步见上传与发布。