@1game/1gamerecord-player-html

@1game/1gamerecord-player-html 提供 .1gamerecord 浏览器回放壳，发布内容包含：

• dist/player.html
• dist/player.bundle.js（含 Solid UI controller，ESM 薄壳）
• dist/engine/runtime-main.mjs（local 模式旁挂的主线程引擎；与 1game build --target web 同源）

主线程渲染不再打进 player.bundle.js，而是外置 @1game/engine-bundle/runtime/main（CDN 或 ./engine/）。契约见 docs/engine-cdn-resolution.md。

安装

pnpm add @1game/1gamerecord-player-html

归档 worker 要求

回放页加载的 .1gamerecord 内嵌 game.worker.js 必须已安装录制/回放运行时（含 sql.js）。用 1gameplay create 生成的归档会自动带上；若手工 1game build --target worker，需加 --with-record（或入口显式 import '@1game/engine-bundle/runtime/record'），否则 worker 侧 replay.* 会返回 method-not-found。

使用方式

将 dist/player.html、dist/player.bundle.js 与 dist/engine/runtime-main.mjs 一并部署到静态站点（需支持 type=module），通过 URL 查询参数传入回放档案：

player.html?record=<.1gamerecord 文件 URL>

可选参数：

• title：页面标题
• wasm：覆盖 sql.js wasm 地址（URL query 优先于 gr-config.wasm；未传 query 时用导出/构建固化值）
• startSeq：起始帧序号
• shareButtonText：评论区分享按钮文案（默认 分享）
• exportBranchRecord：更多菜单导出按钮文案（默认 导出回放记录）
• shareActionMessage：当页面运行在 iframe 且该值非空时，点击分享后向父窗口 postMessage
• mode=autoplay：进页后自动 replay.play()（若已在尾帧则先回到起点）；可用 overlay 暂停 / 再播。与 mode=userplay 互斥。
• mode=userplay：打开「玩家游戏」面板；点「进入游戏」后按最近 3 分钟游戏时环形采集 Worker runtime_perf / console.warn+，导出时写入 record_meta.captureSession。官方 1game build 游玩页忽略此参数。
• userplay=0：隐藏更多菜单里的「进入玩家游戏模式」，并忽略 mode=userplay（论坛帖子详情看回放用）。userplay=1 显式打开该入口。缺省与现网一致（入口可见）。
• perf=off|budget|trace：仅当 mode=userplay 时生效（默认 budget）。控制 Worker PhaseId 捕获深度；Main rAF 卡顿只进 captureSession.main，不会写成 runtime_perf。

sql.js WASM CDN（构建时固化）

player.bundle.js 在 pnpm build 时写入绝对 wasm URL：

{ONEGAME_ENGINE_CDN_BASE|https://cdn.jsdelivr.net/npm}/sql.js@{installedVersion}/dist/sql-wasm.wasm

• 复用与引擎 externalization 相同的 env ONEGAME_ENGINE_CDN_BASE（trim、去尾 /）
• 未设时默认 https://cdn.jsdelivr.net/npm（仅回放壳 sql.js；不改变 1game build 未设 env 时的 ./engine/ local 模式）
• {installedVersion} 来自构建进程已安装的 sql.js 包 version（resolve 主入口后上溯 package.json）

1gameplay bundle-player-html 会再次按导出进程的 env 计算并把结果写入 gr-config.wasm（覆盖包内烘焙默认）。运行时若 URL 带非空 ?wasm=，仍优先于该固化值。

补充：也可由导出工具注入 gr-config 的 recordBase64（避免额外归档请求）。字段约定：

• recordBase64：内嵌归档字节的 base64
• recordEncoding：可选；"gzip" 表示 base64 解码后还需 gunzip。1gameplay bundle-player-html 默认单文件导出会写入 gzip + recordEncoding: "gzip"。省略该字段时按未压缩原始归档处理（兼容旧产物）
• 播放器解压依赖浏览器原生 DecompressionStream('gzip')

配置合并优先级：record/recordBase64 始终以 gr-config 内嵌值优先（URL query 仅作兜底），保证单文件回放页内嵌的归档数据不会被 URL 参数意外覆盖；而 wasm/shareButtonText/shareActionMessage/exportBranchRecord/userplay 则相反，URL query（若提供非空值）优先于 gr-config 内嵌值，gr-config 仅在 query 未提供时作为兜底——这允许 iframe 嵌入方通过在 src 上追加 query 参数来临时覆盖已固化在产物里的 wasm 地址、分享/导出按钮文案/消息类型、或 userplay=0，而无需重新生成整个回放 HTML。

shareActionMessage 触发时发送的数据结构：

• type：shareActionMessage 的值
• fileBuffer：当前回放归档 ArrayBuffer
• commentsJson：当前评论数组
• filename：建议文件名（.1gamerecord）

示例：

/player.html?record=/records/demo.1gamerecord&title=Demo%20Replay&startSeq=120
/player.html?record=/records/demo.1gamerecord&mode=autoplay

本地开发

pnpm run build

（工作目录：packages-public/1gamerecord-player-html）