Claude-of-Duty像素级回归测试指南：用baseline与imagediff打造位图一致的确定性截图门

Claude-of-Duty像素级回归测试指南用baseline与imagediff打造位图一致的确定性截图门【免费下载链接】Claude-of-DutyA Call of Duty-quality FPS in Three.js, built from a single prompt.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-of-DutyClaude-of-Duty 是一个用 Three.js 从零构建的《使命召唤》级浏览器 FPS它附带一套专业的像素级回归测试体系baseline.mjs负责可复现地拍摄 11 张固定镜头截图imagediff.mjs则逐像素比对两组截图任何一像素变动都会让测试门失败非零退出码。这套工具曾在一次性能优化中被用来强制执行零视觉变化——优化后的构建与优化前参考图在所有镜头上逐位一致bit-identical。本指南带你快速上手这套截图门。1. 为什么需要像素级的回归门这个项目最有意思的部分不是游戏本身而是围绕它的测试框架harness。项目 README 明确记录了两个关键教训中位数帧时间会掩盖真实问题静态相机基准测出 94 fps但实际游玩只有 12–17 fps根因是 34 个 WebGL 着色器在帧中途惰性编译导致 728–1236 ms 的卡顿。截图曾经不可复现shotset.mjs在同一个页面里连拍 11 个镜头粒子年龄、贴花缓冲、曝光状态会泄漏到后续镜头——两次完全相同的运行有 10/11 张截图不一致。也就是说如果截图本身不稳定视觉回归就无从谈起。于是有了 tools/baseline.mjs 与 tools/imagediff.mjs 这对组合。2. 回归工具链一览工具用途是否用于回归门tools/capture.mjsGPU 驱动的无头 Chromium 拍摄单个命名镜头快速验证用tools/shotset.mjs单会话拍全部 11 个镜头供人工/评审快速浏览❌ 不可复现tools/baseline.mjs可复现采集每个镜头独立页面 固定帧预算✅ 生成基线tools/imagediff.mjs逐像素比对有像素变动则退出码非零✅ 回归门11 个镜头全部定义在 src/dev/shots.js 中涵盖环境光照hero/interior/detail/sunset/night、武器视角weapon/ads/muzzle与战斗特效combat/impacts/hud三大类每个镜头都是冻结输入后的固定相机位姿 固定时刻保证每次评审看到的构图完全一致。3. baseline.mjs确定性截图的三根支柱打开 tools/baseline.mjs 的文件头注释作者把可复现性拆解为三条设计理解它们就能理解整套截图门隔离ISOLATION——每个镜头开一个全新页面。避免粒子年龄、贴花缓冲、动画相位、自动曝光状态在镜头之间泄漏固定帧预算FIXED FRAME BUDGET——镜头在已知的帧索引处应用随后精确推进settle默认 90帧使 TAA 抖动相位、曝光自适应等时间累积器总从同一相位收敛时间重置TEMPORAL RESET——开拍前请求渲染器丢弃 TAA 历史并重置曝光从已知相位开始累积。更深层的确定性来自lockstep 模式。引擎自身的 rAF 循环会在测试框架做各种等待往返时继续推进帧数导致快门按下时的帧索引每次漂移 10–20 帧所有与帧索引锁相的效果TAA 抖动、噪声旋转frame % 64、曝光自适应都会解算出不同结果。修复方案写在 src/dev/shots.js 的注释里lockstep 下引擎从不自己调度帧帧只发生在测试框架显式调用的__PUMP__(n)内——精确推进 n 帧快门时刻的帧索引成为常量截图期间仿真完全静止。配套的还有固定步长时钟capture 模式下每帧 dt 被强制为精确的 1000/60 毫秒与启动路径无关见 src/dev/shots.js。再加上 ARCHITECTURE.md 的硬性规则——游戏逻辑与视觉中禁止使用Math.random()必须用确定性随机源 src/core/rng.js——采集可复现性在代码层面被制度性地兜住。4. imagediff.mjs逐像素的回归门tools/imagediff.mjs 用 pngjs 逐字节读取两组 PNG按通道取最大差值统计tol默认 0每通道 0–255 差值容差低于它的像素视为未变化输出指标每张截图的changedPct变化像素百分比、maxDelta最大通道差、meanDelta平均通道差退出码即门禁tools/imagediff.mjs 中只要所有镜头changedPct为 0或整体在明确论证过的 epsilon 内变化 0.05% 且maxDelta ≤ max(2, tol)才返回 0否则退出码为 1——可直接接入 CI 流水线--write-diff把发生变化的像素以亮品红色高亮、原图压暗输出.diff.png方便肉眼定位差异区域。项目 README 记录了它的实战价值一次大规模优化被约束为零视觉变化且这一约束由imagediff.mjs强制执行而非口头声明——交付构建在全部 11 张镜头上与优化前参考位图一致。5. 快速上手三步建立你自己的截图门环境要求Node.js 依赖中的playwright、pngjs、vite见 package.json。第一步安装依赖git clone https://gitcode.com/gh_mirrors/cl/Claude-of-Duty cd Claude-of-Duty npm install npx playwright install chromium第二步采集基线node tools/baseline.mjs --outshots/base --port8080工具会自动拉起 vite若端口未占用、以 1920×1080 视口、deviceScaleFactor1、sRGB 色彩配置启动无头 Chromium逐一采集 11 张 PNG 并写出report.json。常用参数--shotshero,detail只拍子集迭代更快--settle90调整收敛帧数--queryprewarm0向所有镜头 URL 追加查询参数可做 A/B 对照例如对比预热的开/关。第三步改动代码后做像素比对# 重新拍一组例如优化后的构建 node tools/baseline.mjs --outshots/opt --port8080 # 逐像素回归门 node tools/imagediff.mjs --ashots/base --bshots/opt [--tol1] [--write-diff]退出码为 0 即视觉无变化通过门禁为 1 时终端 JSON 会指出worst最差镜头与每张镜头的统计行加--write-diff后还能直接看高亮差异图。6. 实践要点与常见陷阱 不要拿shotset.mjs的结果做回归比对。它快但同页连拍导致时间状态泄漏两次运行 10/11 张不同。它只适合人工评审。锁相帧索引是复现性的核心。TAA 抖动相位、GTAO/SSR/接触阴影噪声旋转都按frame % 64走帧索引差 1 帧输出就差一截。这正是 src/dev/shots.js 中 lockstep 模式存在的原因。预热pre-warm也会看起来改变画面它消耗约 1.4 s 墙钟时间若系统动画依赖performance.now()而非引擎时钟启动时长变化就会平移一切输出。项目修复方法是让相关子系统改用引擎时钟配合 src/core/prewarm.js 的着色器预热实现可证明的像素中性。跨机器位图一致有前提同一 GPU 后端与驱动下可 bit-identical换显卡驱动后可能出现系统性微小差异此时应重新采集基线并用--tol明确论证 epsilon。报告即诊断tools/baseline.mjs 会把页面pageerror与 console error 收进report.json并影响退出码——截图失败不会静默通过。7. 延伸阅读回归门背景与设计权衡README.md 中 Tooling 与 Performance 章节引擎契约与确定性硬规则禁用Math.random()ARCHITECTURE.md镜头定义与 lockstep 实现src/dev/shots.js单镜头快速截图tools/capture.mjs确定性随机源src/core/rng.js着色器预热的像素中性约束src/core/prewarm.js一句话总结先让截图可复现baseline 的隔离 锁相 固定帧预算再谈逐像素比对imagediff 的门禁语义——这就是 Claude-of-Duty 把优化不许改画面从口号变成可执行退出码的完整方法。【免费下载链接】Claude-of-DutyA Call of Duty-quality FPS in Three.js, built from a single prompt.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-of-Duty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考