npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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.worker

Store 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.html

Extract 在活动路径上开窗,保留输入档,输出独立线性档;已有输出可能被覆盖。--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 交接,批量去重和缓存应按数值身份比较。