@1game/cli-1gameplay
v1.27.0
Published
1Game gameplay recording CLI
Readme
@1game/cli-1gameplay(1gameplay)
无头录制、步进和回放调试工具。日常使用 1gameplay 命令;包根同时导出供 @1game/test 使用的 JS API,其签名以发布类型为准,不依赖内部模块路径。
安装与最小流程
在已配置 1Game 的游戏项目中安装,与其它公开包保持同版本:
pnpm add -D @1game/cli-1gameplay
# npm install -D @1game/cli-1gameplay
pnpm exec 1gameplay --help
pnpm exec 1gameplay create --entry src/game.tsx --out out/demo.1gamerecord
pnpm exec 1gameplay step out/demo.1gamerecord --ms 16 --repeat 10
pnpm exec 1gameplay frame query out/demo.1gamerecord --at last --select store:state
pnpm exec 1gameplay bundle-player-html out/demo.1gamerecord --out out/replay.html下文省略 pnpm exec;npm 可用 npx。完整参数、默认值和命令语法以当前版本 1gameplay --help 为准,本文保留使用流程和容易误解的边界。
归档是单个 SQLite .1gamerecord 文件,包含构建产物、帧树与 journal。create 自动构建带 record 运行时的 Worker;手工 play-only Worker 不能直接用于回放。后续 step 不重新构建游戏源码,源码或引擎版本变化后需重新 create。
查询使用只读连接,同一查询复用读取会话,不复制全库。引擎、CLI 与归档按同版本配套使用;读写入口均拒绝不支持的旧 schema,不会原地升级或生成迁移副本。SQLite 日志需要恢复时,查询会报错并要求独立恢复。
完整读档、回放和截图直接读取数据库数据;需要完整归档字节或源摘要的导出使用独立备份,需保证系统临时目录可写且空间充足。包不再编译自有 SQLite 扩展,better-sqlite3 与 @napi-rs/canvas 仍按各自 npm 包的要求安装原生平台依赖。
帧坐标与分支
CLI 的 --at、--from-frame、--from-seq 等使用全局 frame_id,历史字段名中的 seq 不代表路径深度。last 是活动分支 HEAD,播放器的 currentSeq 则是路径 ordinal;从播放器回填 CLI 用 currentFrameId。
普通调试保持单分支:create → step 追加 → 导出。Step 默认在 HEAD 追加,不从途中播放位置追加;显式 --from-frame 截断后继续,只能删除本 ref 的独占后缀,CLI 不自动 fork。
需要保留两种试验时显式创建分支:
1gameplay branch create out/demo.1gamerecord --name 另一种打法 --at 12
1gameplay branch list out/demo.1gamerecord
1gameplay branch checkout out/demo.1gamerecord --name 另一种打法Checkout 到目标 HEAD;seek 不改变 HEAD。CHECKOUT_BROKEN 时先 branch list 查看诊断,再 branch repair-checkout。读路径的容错不是写路径授权。
branch list 的 result.sourceInfo 描述当前源格式与只读会话。diskActiveBranchId、isActive 反映原始存储,isResolvedActive 反映当前解析选择;诊断不会自动修复 checkout。输出仍使用 1gameplay.branch.list.v1。
删除 ref 会回收它的独占帧,无法撤销;先 checkout 到其它分支并预览计划。--plan-only 只回滚分支删除,此前显式格式升级仍可能保留:
1gameplay branch delete out/demo.1gamerecord --name 另一种打法 --plan-only.swp 试跑
step --dry-run 在缺失时从主档复制 sidecar;后续加 --dry-run 的命令使用 sidecar。主档读取不受影响,但 sidecar 存在时主档写入被阻止,包括同路径 create。其它命令不会自行创建 sidecar。
1gameplay step out/demo.1gamerecord --dry-run --ms 16 --repeat 2
1gameplay frame query out/demo.1gamerecord --dry-run --at last --select store:state
# 采纳试跑结果;丢弃则删除 .swp
mv out/demo.1gamerecord.swp out/demo.1gamerecord试跑会真实提交到 sidecar,不是进程内假 tick。没有独立 commit/abort 子命令。
输入与落稳
点击前用 hit 查询确认目标:
1gameplay frame query out/demo.1gamerecord --at last --select 'hit:point=100,100'
1gameplay step out/demo.1gamerecord --click 100,100
1gameplay step out/demo.1gamerecord --event '{"type":"keypress","data":{"code":"ArrowLeft","ms":180}}'
1gameplay step out/demo.1gamerecord --ms 16 --until store:state:anim.phase=idle --until-ms 800单 scene 可省略 sceneStableUid;多 scene 使用 create 返回的真实 UID 或 --scene-stable-uid,不能填名称或写死猜测值。动作宏的按住时长不是动画完成时长,也不采用普通空 tick 的 --ms。
Until 每次空 tick 后检查谓词,必须显式提供正的 --ms 与 --until-ms,不能同时使用 repeat;hit 谓词需要 display surface。STEP_UNTIL_NOT_MET 表示未达条件,已生成帧仍会提交;不要当作没有写入或 Worker 超时。
复杂输入用 --event-file;事件载荷与可复制配方见公开 @1game/skill 的 1game-api / 1game-debug。
状态、画面与性能
1gameplay frames list out/demo.1gamerecord
1gameplay frame diff out/demo.1gamerecord --from 0 --to last --select store:state
1gameplay frame screenshot out/demo.1gamerecord --at last --out out/frame.png
1gameplay step out/demo.1gamerecord --ms 16 --repeat 60 --perf summary
1gameplay obs report out/demo.1gamerecord --profile lab.workerStore state/frame/dump 从 journal 纯计算,不为此启动 Worker;render/hit 和截图需要运行时恢复。查询不会因缺数据而隐式猜测结果。--select 的完整语法在命令帮助;批处理使用 frame plan。
截图用 Node canvas,无需 Chromium,并叠加回放页右上角暂停按钮,便于检查游戏控件是否被遮挡。场景截图按宿主视口位置投影按钮;按钮落在场景外时不显示。不含底部回放控制条。浏览器字体、抗锯齿、远程资源和原生 DOM 编辑行为可能不同;原生交互要在浏览器验证。
step --perf 采集,obs report 只读。显式选择 profile:Worker lab、display lab、Node paint 和 device budget 具有不同来源;Main rAF、Worker 与 paint-lab 毫秒不能互相比快慢。Browser userplay 采集档使用 device profile,不能当作 Host Lab 数据。frame paint 是绘制快照,不是设备 FPS。
评论、裁剪与分享
1gameplay comments add out/demo.1gamerecord --at last --body '检查这个状态' --author-id ai
1gameplay record extract out/demo.1gamerecord --out out/clip.1gamerecord --from-seq 12 --to-seq 24
1gameplay bundle-player-html out/clip.1gamerecord --out out/replay.htmlExtract 在活动路径上开窗,保留输入档,输出独立线性档;已有输出可能被覆盖。--branch-meta 记录来源,--merge-diff 会合并历史并减少可 seek 时刻。frames delete --after / --last 则原地删除独占后缀,不能挖中间段或重排全局身份。
导出默认单 HTML;没有引擎 CDN 时嵌入引用的引擎字节,设置 ONEGAME_ENGINE_CDN_BASE 时依赖 CDN。需要旁挂产物用 --multi-file。Sql.js WASM 是独立网络资源,离线部署需配置可达地址。
打开 replay.html?mode=autoplay 自动播放,?mode=userplay 进入玩家采集;空回放未传 mode 时进入玩家面板。?userplay=0 隐藏玩家入口。暂停后长按游戏画面添加定位评论。Iframe 分享与部署选项见已发布 @1game/1gamerecord-player-html README。
诊断
命令通过 stdout JSON 回执报告结果,消费 ok、code 与结构化 details,不匹配提示文案。具体 schema、字段和退出码以当前版本帮助及发布类型为准。
引擎版本不兼容时对齐公开包并重新 create;step 不改写归档的引擎身份。better-sqlite3 缺少原生构建时,检查包管理器构建脚本限制,按项目策略允许并重装该依赖。
Node 运行 CDN 模式归档时,从同版本的本地 @1game/engine-bundle 安装读取引擎;包缺失、版本不符或引擎文件不可读时直接失败,不联网下载引擎。浏览器回放页仍可加载 CDN,Sql.js WASM 与游戏远程资源也仍可能需要联网。
JS API 查安装包的公开声明;CLI 完整语法用 1gameplay --help。不依赖内部模块路径。
严格坐标工具 API
import {
openArchiveCoordinates,
frameIdWindow,
pathOrdinal,
ordinalRange,
extractFrameRangeToPathCoordinates,
} from '@1game/cli-1gameplay/coordinates';
const archive = openArchiveCoordinates('input.1gamerecord');
try {
const last = archive.resolveFrameId('last');
const frame = archive.getRuntimeAt(last);
const rows = archive.getRuntimeAtMany([frame.frameId]);
// 身份数值窗口允许空洞,不将其解释为路径 ordinal。
archive.countRuntimeFramesInWindow(frameIdWindow(frame.frameId, last));
} finally {
archive.close();
}
await extractFrameRangeToPathCoordinates('input.1gamerecord', 'clip.1gamerecord', ordinalRange(pathOrdinal(0), pathOrdinal(2)));archiveCoordinates(reader) 只提供视图,reader 由原调用方关闭;openArchiveCoordinates 拥有并关闭自己的 reader。批量结果为带 FrameIdValue 的 entries,避免以对象引用作为 Map 键。Node 评论查询必须显式选择 current/all,两者都使用 FrameIdWindow;当前路径的兄弟帧端点仍拒绝。严格提取自动映射窗口端点并校验源帧身份。
此子路径的声明自包含,消费者无需安装私有 workspace 包。根入口与 CLI stdout 使用明确的 FrameId 地址字段;数字旗标仍按帧身份解释。
新 Node 集成默认使用此严格入口。CLI 内部在解析 token 后分别维护帧身份和路径深度,输出时才生成既有数字字段;两者数值相同也不互换。坐标值对象用于 API 交接,批量去重和缓存应按数值身份比较。
