mshumer/Claude-of-Duty · 上手攻略

是什么

Claude of Duty 是一款跑在浏览器里的第一人称射击游戏（FPS），用 Three.js r180 + WebGL2 实现，规模约 55k 行代码、拆成 11 个子系统。最反常识的一点是：完全没有美术资产——没有模型、没有 HDR、没有图片、没有音频文件，所有贴图、网格、动画、音效都在加载时由代码程序化生成，运行时唯一的 npm 依赖只有 three。

整个工程不是某个工程师手工写的，而是「由 AI agent 团队在编排下产出」。仓库里真正值得研究的不是游戏本身，而是那套把多 agent 协作推到 5 万行规模还能跑的工程约束——以 ARCHITECTURE.md 作为契约，约定子系统接口、目录归属、跨子系统事件词汇表和共享面类型。配套的截图/性能/像素对比工具链 (tools/*.mjs) 也是理解这套方法的关键入口。

解决什么问题

这个仓库瞄准的目标很直白：「用 AI agent 团队协作，写出一个对标《使命召唤》的浏览器 FPS」。核心要解三个工程问题：

  1. 55k 行的多 agent 协作不塌方。无规矩的多 agent 并行会快速陷入接口不一致、命名冲突、互相踩踏。ARCHITECTURE.md 把子系统边界、共享事件词汇、共享面类型写死，相当于多 agent 的宪法。
  2. 零美术资产也能撑起现代 3D 画面。19 种程序化材质、Sobel 高度转法线、视差遮挡贴图、三平面投影、curvature 驱动的边缘磨损；HDR 管线 + 级联阴影 + PCSS + GTAO + TAA + Karis Bloom + AgX 合成；体积雾、光柱、HRTF 空间化音效——全部从代码生成。
  3. AI 协作的「验证」怎么落地。FPS 这种强实时场景最容易出现「编译通过但画面崩了」「优化通过但效果变了」之类的伪进步。仓库给出答案：截图基线 (tools/baseline.mjs，每张图独立页 + 固定帧预算，跨运行 bit-identical) + 像素级门禁 (tools/imagediff.mjs，任何像素差异都非零退出) + 帧时分布分析 (tools/profile.mjs，p50/p95/p99 + hitch 归因)。

它没解决的问题是「真正像现代 COD」。仓库自家做了 11 张独立对抗性评审，5 分制里打了 3.59 → 4.14 → 4.05 → 5.05，盲测中每一轮评审都能挑出真 COD 而非本游戏——手部、材质丰富度、人物远观、间接光、帧率五项明确落后。

快速安装

环境：Node.js 18+、现代 Chromium 内核浏览器（需要 WebGL2、WebGPU 后备可选）、桌面级 GPU（移动端基本无意义）。

git clone https://github.com/mshumer/Claude-of-Duty.git
cd Claude-of-Duty
npm install
npm run dev          # 默认监听 http://127.0.0.1:5173

打开浏览器进入上述地址，点击画布锁定鼠标即可游玩。控制：WASD 移动、鼠标瞄准、左键开火、右键 ADS、R 换弹、Shift 冲刺、Ctrl 蹲伏、Space 跳跃、Q/E 侧身、Esc 释放鼠标。

不需要任何外部资产、模型、HDR 文件或音频文件——这套最小可跑命令就是全部。

核心用法

下面四类是「最值得复用的核心用法」，命令与脚本名都来自仓库自带的 package.json 和 tools/ 目录。

1) 跑工具链：截图、像素对比、帧分析、跑测

# 单张命名截图（GPU headless Chromium）
node tools/capture.mjs --shot aim-down-sights

# 一次跑 11 张官方评审镜头（快速看一整套状态）
node tools/shotset.mjs

# 可复现基线捕获：每张独立页 + 固定帧预算
node tools/baseline.mjs

# 像素级门禁：任何像素与基线不一致就非零退出（适合 CI）
node tools/imagediff.mjs baseline.png current.png

# 真实 DPR + 帧分布 + hitch 归因
node tools/profile.mjs

# 自动跑测：移动/开火烟雾测试
node tools/playtest.mjs

⚠️ shotset.mjs 复用一个页面跑 11 张截图，粒子 age/decal/曝光会跨图泄漏，作者实测两次运行 10/11 张不一样。要做像素门禁请用 baseline.mjs——这是仓库里两个反直觉但作者亲自写过结论的发现之一。

2) 复现 README 里的性能数字

官方基准：Apple Silicon 笔记本，1512×982，DPR 2（3.34 MP 内部分辨率），ultra preset，3 次取中位，游戏在动、敌人在场、玩家在开火。

指标 优化前 优化后
fps p50 12–17 28–30
fps p99 4–9 14–17
最差一帧 728–1236 ms 66–82 ms
游戏内 shader 编译 34–35 次 0 次
启动 ~9–12 s 3.7–4.6 s

复现方法：开 ultra 档、在战斗场景里保持移动和开火、跑 tools/profile.mjs，对比启用 src/core/prewarm.js 与不启用时的 p99 与 hitch 计数。

3) 接管一个子系统

如果你想基于这套架构写新内容，先看 ARCHITECTURE.md（子系统接口/目录归属/事件词汇/共享面类型都在里面），然后在 src/subsystems/<你的子系统>/ 下声明：

  • 入口文件
  • 该子系统向上抛出哪些事件（用跨子系统事件词汇表里的词）
  • 该子系统依赖哪些共享面类型
  • 该子系统拥有哪些目录、不能写哪些目录

多人共写一个子系统时，按 README 的「Process note」——单 owner 顺序写比 6 agent 并行写显著更好（分数 +1.00、缺陷 66→26）。

4) 跑「adversarial critic」评审

仓库的诚实评估部分提到 11 个独立评审对着画面打分。如果你也想做：用 tools/capture.mjs 抽 5–10 张代表性帧（包括但不限于：开火、ADS、室内、室外、近距离人物），把每张丢给独立评审代理（或真人），用 1–10 分打分，并要求「必须挑出哪张是 AI 程序化的、哪张是真 COD」——盲测是看穿方法论水分的最有效手段。

典型适用场景

  • 多 agent 协作的可参考架构：想做「N 个 agent 一起写一个有规模的项目」，这套「ARCHITECTURE.md 当宪法 + 工具链做验证」的范式可以原样移植到 WebGL/2D 游戏、可视化编辑器、仿真器。
  • 零资产生成画面：想做一个 demo/原型/技术验证但手头没有美术资源——19 种程序化材质、HRTF 合成音效、PMREM 环境生成这条路径几乎是现成的。
  • 像素级视觉回归测试：baseline.mjs + imagediff.mjs 拼出的「CI 友好渲染验证」可以拷到任何重 UI 项目里。
  • FPS 早期原型：要做「能在浏览器跑、有完整玩法循环、能塞给产品/设计 demo」的 FPS，这是少有的真能跑、且 README 写清楚「做到什么程度、还差什么」的参考实现。
  • 教学/课件：拿画面帧 + 工具链 + 评审打分当案例，可以讲清楚「多 agent 协作的耦合陷阱」「过度优化 diff 只看中位数」「自相矛盾的 brief 会让 agent 越改越糟」三件事。

坑与注意

  • README 里直接写了 5 个未解决的明显短板：手部像板砖、材质近距离读起来像噪声而非照片、远观人物像模特、间接光是近似不是真 GI、Retina 上只有 28–30 fps。引用这个仓库的「截图成果」做宣传前先读完这段。
  • 静态基准 = 骗自己。原作者给过一个反例：静态相机基准报 94 fps，实际游戏跑起来不可玩——任何只报平均 fps 的基准都不可信，必须 p99 + hitch 归因。
  • shader 不能懒编译。本作的 728–1236 ms 巨型 hitch 全部来自 34+ 个 WebGL program 在游戏中时段编译。改任何子系统前先确认 src/core/prewarm.js 在 prewarm 阶段把它冲好；任何一帧内的 gl.compileShader 都会引爆 p99。
  • performance.now() 当时钟 = 不一致。仓库原话：优化会让启动时间变化，把动画接到 performance.now() 而非引擎时钟就会改变最终画面，破坏像素稳定性。子系统动画请接引擎时钟。
  • viewmodel 光照是黑历史。render/index.js 的 viewmodel 光照给单位 albedo 多了约 20× 的辐照度，纯黑材质都能渲染到 L=110 vs 背景 91，所有武器 albedo 被砍到 1/3 物理值才能补偿——这是「与 brief 反向改」才修好的反模式。
  • 多 agent 并行写耦合子系统 = 互坑。3 轮 6 agent 并行（60→47→66 缺陷）反而比单 owner 顺序写（66→26 缺陷）差。只有真正解耦的子系统才适合并行。
  • README 里给的性能数字是「Apple Silicon + ultra + 真实战斗 + DPR 2」才成立的，挪到低端集成显卡/移动端需要重做 prewarm.js 与材质分辨率谱。

与同类对比

  • pmndrs/react-three-fiber + 资源商店模型：上手快、视觉上限高，但需要美术资产。本仓库差异点是「完全零资产 + 全程序化 + agent 协作架构」——属于完全不同的设计取向。
  • playcanvas/engine：成熟的浏览器 3D 引擎，强调易用、生产力。本仓库差异点是「不依赖任何引擎抽象，自己堆 11 个子系统 + 自写物理引擎」——研究价值大于生产力价值。
  • Babylon.js 的程序化材质/几何：更标准的现代浏览器 3D。本仓库差异点是「程序化 + agent + 像素门禁工具链」整套流程，可作方法论案例。
  • 开源 FPS 类项目（如 godotengine/godot 官方 FPS 演示、CSS 3D 实现的伪 3D）：广度/完整度普遍不如本仓库，但依赖更轻、跨设备兼容性更好。本仓库差异点是「追求画面密度而非跨平台」。
  • AI 协作产出的开源仓库（如各类 multi-agent 编程教程）：多 agent 协作模板很多，但撑到 5 万行规模的不多。本仓库值得当多 agent 协作产出的参考案例。

一句话推荐结论

如果你的目标是「用 AI agent 协作写出有规模的可玩项目」或「零资产做浏览器 3D 原型」，这是少有的把工程约束、工具链验证、诚实评估都写清楚的参考实现——不要把它当作游戏看，要当作多 agent 协作方法论的实物教材看。

原始 commit/PR/issue 参考链接：https://github.com/mshumer/Claude-of-Duty/blob/main/README.md（同页含 ARCHITECTURE.md 入口与 tools/ 脚本说明）。⚠️ 仓库未在 README 标注具体 commit SHA；如需可复现锚点请自行 git rev-parse HEAD 取当前 HEAD。