Godot、Unity、UE5 三选一:同一套代理流水线在三引擎上的落地差距
Godot、Unity、UE5 三选一:同一套代理流水线在三引擎上的落地差距
Claude Code Game Studios(CCGS)在 README 里给出了一张很整齐的表:49 个 agent、74 个 skill、12 个 hook、13 条路径规则,Godot 4 / Unity / Unreal Engine 5 三套引擎专家"任选其一"。社区里流传的介绍也大多停在这一层——"支持三大引擎"。
但"支持"不是一个布尔值。把仓库的引擎适配层逐文件读下来会发现:三层组织架构、协作协议、七阶段流水线这三块是真正跨引擎共享的;而一旦落到"代码写在哪、命令怎么发、文档查什么、跑起来怎么截一张图",三条路径的成熟度差出了一个量级。这篇文章不谈引擎本身谁更强,只谈一件事:同一套代理流水线,压到三个引擎上时,哪些地方是等效的,哪些地方会打滑,打滑的代价是谁在付。
一、先划清边界:哪些东西真的三引擎通用
在讨论差异之前必须先确认共性的部分,否则容易把工程问题误判成引擎问题。以下内容在仓库里与引擎无关,/setup-engine 选什么都不改:
- 三层代理层级(directors → leads → specialists)与"问 → 选项 → 你决策 → 草稿 → 审批"的协作协议,写在 README.md 与各 agent 的 frontmatter 里;
- 74 个 skill 的工作流骨架。
/create-stories、/sprint-plan、/gate-check、/bug-triage这些流程节点不关心你用什么引擎; - hook 的事件位(SessionStart / PreToolUse / PostToolUse / PreCompact / SessionStop)与权限白黑名单,见 .claude/settings.json;
modes.rigor这一套流程重量开关。默认minimal,四步到可运行代码:/setup-engine→ 写一页 brief →/create-stories→/dev-story。
真正因引擎而变的,是下面四层:代码根、参考文档、命令与脚手架、验证手段。差异几乎全部集中在这里。
二、代码根:一条被写进规则里的 Godot 假设
这是三引擎落地差距中最硬、也最容易被忽视的一处。
仓库里有一份专门的裁决文档 .claude/docs/code-root-resolution.md,把结论写得很直白:
engine.name |
代码根 | 为什么不能是 src/ |
|---|---|---|
| Godot | src/ |
Godot 从 res:// 加载,位置无约束 |
| Unity | Assets/ |
Unity 只编译 Assets/ 与 Packages/ |
| Unreal | Source/<Module>/ |
UBT 只在 Source/ 下发现模块,内容在 Content/ |
问题在于,这个结论是后来补上的,而规则文件是早期写的。13 条路径规则里有 5 条的前置元数据仍然硬编码 src/:
# .claude/rules/gameplay-code.md
paths:
- "src/gameplay/**"
ai-code.md(src/ai/**)、engine-code.md(src/core/**)、network-code.md(src/networking/**)、ui-code.md(src/ui/**)同理。也就是说,在 Unity 项目里,你的代码在 Assets/Scripts/,这 5 条"数据驱动、零热路径分配、服务器权威、UI 不持有游戏状态"的约束一条都不会触发——它们不是报错,是安静地不存在。
仓库自己承认了这个残留。.claude/docs/directory-structure.md 末尾写着:".claude/ 下大约 30 个文件仍然字面写着 src/,因为它们是在 Godot 是唯一被端到端走通的引擎时写的。对 Godot 正确,对另外两个错误。" 实际用 grep 统计,.claude/ 下提到 src/ 的文件是 36 个。
比规则失效更危险的是失效不会被发现。同一份文档对这个失效模式有一段准确的描述:一次锚定到错误根的扫描匹配不到任何东西,而"什么都没找到"和"检查通过"在输出上无法区分——本地化检查找不到硬编码字符串、安全扫描找不到密钥、内容审计数出零个已实现内容、阶段探测把完成的项目判成绿地,每一条读起来都像通过。
这个坑在 1.1.0 版本被修过一次,但只修在 hook 层。CHANGELOG.md 记录:负责检查硬编码数值、无主 TODO、未记录玩法系统、缺失架构文档的三个 hook 过去都搜 src/,在 Unity/Unreal 上"匹配不到任何东西,每个检查静默地什么也没做,结果与干净通过无法区分"。修复方式是让 hook 从引擎解析代码根——实现就在 .claude/hooks/yaml-helper.sh 的 resolve_code_root() 里,按 project.local.yaml → project.yaml → 遗留镜像 → 目录树推断(且仅在唯一时才推断)→ 否则"未解析"的顺序走,并且明确规定:未解析不得回落为 src/。
/dev-story 也同步改了口径(.claude/skills/dev-story/SKILL.md 第 359 行):写文件前必须解析代码根,"解析不出来就不要写,报告并停止"。
结论:代码根这一层,Godot 是原生路径,Unity 与 Unreal 是移植路径。移植是对的,但规则层还留着一半旧假设。如果你用 Unity/Unreal 起项目,第一件该做的事不是跑 /dev-story,而是把 5 条规则里的 paths 改成 Assets/Scripts/** 或 Source/<Module>/**——否则你得到的是一套看起来在治理、实际上没接上的规范。
三、参考文档:621 行 vs 2493 行 vs 2549 行
CCGS 解决"模型不知道新版本 API"的方式不是让模型猜,而是让每个引擎目录自带一份版本钉死的参考快照,agent 在写代码前先查这里。/setup-engine 的第 6 节给出了知识缺口判断依据:训练截止 2026 年 5 月,Godot 约覆盖到 4.6、Unity 约到 6000.x、UE 约到 5.5。
这层设计的成本极不对称。按仓库实际文件统计:
| 引擎 | 参考目录体积 | modules/ 总行数 |
额外插件文档 |
|---|---|---|---|
| Godot 4.6 | 64 KB | 621 | 无 |
| Unity 6.3 LTS | 144 KB | 2493 | Addressables / Cinemachine / DOTS 三份,另有 PLUGINS.md |
| UE 5.7 | 160 KB | 2549 | CommonUI / GAS / GameplayCamera / PCG 四份,另有 PLUGINS.md |
Godot 的 8 个模块文件平均不到 80 行,风格是"变更点 + 少量 API 片段"。例如 docs/engine-reference/godot/modules/audio.md 的第一句结论是 "No major breaking changes to the audio API in 4.4–4.6"——它敢这么写,是因为 Godot 4.5 到 4.6 的音频层确实没动。而 docs/engine-reference/godot/modules/rendering.md 只用几十行就交代完了 D3D12 成为 Windows 默认后端、Glow 改为在 tonemapping 之前处理、AgX 新白点、SSR 重写这几件事。
Unity 与 UE 的模块文档是另一个量级:单是 ui.md,Unity 377 行、Unreal 353 行,Godot 只有 82 行。这不是作者厚此薄彼,而是三个引擎 API 表面积与破坏性变更密度本身的差异——Unity 6 从 2022 LTS 跨过来,Entities 1.0 重写 ECS、Input System 取代旧 Input Manager、UI Toolkit 取代 UGUI,每一条都是整层替换;UE 5.3 到 5.7 则叠了 Substrate 材质、PCG 转生产可用、Megalights、动画授权工具重做。
顺带一个对代理很实际的观察:Unreal 的 docs/engine-reference/unreal/VERSION.md 直接把 5.7 的"高风险"定在 PCG 与 Substrate 转生产可用上。对 agent 而言,这意味着凡是碰到材质与程序化生成的 story,参考文档的命中率远高于 Godot 的同类 story——不是模型更强,是要查的东西更多、更集中。
四、工程侧:脚手架、命令、命名,三处不对称
4.1 谁能替你建出工程
/setup-engine 第 7.5 节是整份 skill 里最诚实的一段,标题就叫 "Scaffold the Engine Project",开头一句:没有这一步,框架产出的源文件没有任何引擎能打开。
- Godot:直接写
project.godot,字段从已有决策推导,config/name取 brief 标题或仓库目录名,config/features只取major.minor,渲染方法由rendering决定(Compatibility →gl_compatibility,Forward+ →forward_plus)。写完若有引擎二进制,跑godot --headless --path . --import验证;找不到就写project.godot NOT VERIFIED — <reason>,不假装验过。 - Unity / Unreal:不生成,只指导。理由写得很清楚——这两类工程由编辑器生成、包含大量二进制与机器相关文件,手写脚手架正是第 7 节"宁可写 NOT SOURCEABLE 也不填一个看起来对的值"所禁止的失败模式。所以流程变成:先去 Hub / Epic Launcher 建工程,再回来重跑
/setup-engine。
这一条直接决定了三引擎的"首次可用时间":Godot 是分钟级,Unity/Unreal 先要装编辑器、建工程、等首次导入。对"单人 + jam"的场景,这个差距比任何性能差异都更影响体验。
4.2 命令成熟度
写进 project.yaml 的四条命令(build / test / run / smoke)在三个引擎上的确定性完全不同:
| 引擎 | build | test | smoke |
|---|---|---|---|
| Godot | godot --headless --export-debug '<PRESET>',preset 名必须问 |
godot --headless --script tests/gdunit4_runner.gd |
godot --headless --quit-after 5 |
| Unity | Unity -batchmode -quit -projectPath . -buildTarget <TARGET>,目标必须问 |
Unity -runTests -projectPath . -testPlatform PlayMode |
Unity -batchmode -quit -projectPath . -executeMethod SmokeCheck.Run |
| Unreal | RunUAT.bat BuildCookRun ...,skill 自己标注 # TODO: confirm these |
UnrealEditor-Cmd.exe ... -ExecCmds="Automation RunTests ...; Quit" |
需 -game 才会真的退出 |
Godot 的四条里只有 preset 名需要问,其余是可直接执行的确定值。Unity 的 build 被 skill 明确禁止给默认值——理由写得极其具体:硬编码 -buildTarget StandaloneLinux64 会让每个 Unity 工程都产出一个 Linux 构建,"一条会运行、会成功、但构建错产物的命令"比显式提问更糟。Unreal 则整块标注 TODO,因为 UBT / UAT 的参数随版本和工程结构漂移。
还有两个藏在细节里的坑,值得单独点出,因为它们只有在 UE 上才会踩:
smoke必须带-game。不带的话UnrealEditor-Cmd会启动编辑器,而裸Quit控制台命令只能结束 PIE 会话,进程驻留、命令永不返回。test的Automation字符串里必须含; Quit,由自动化 runner 自己处理,否则同样挂住。
以及一个与引擎无关、却专门咬 UE 命令的约束:仓库的 YAML 解析器 yaml-helper.sh 不解码任何转义,双引号内的 \" 会被截断在反斜杠处。所以 UE 的 test/smoke(内嵌双引号)必须用单引号标量;而"同时包含两种引号的值"在这个解析器里无法表示,只能改命令。Godot 的 build 含单引号,所以走双引号标量。这属于"用错引号,命令静默变成半截"的隐蔽故障。
4.3 命名与文件类型路由
/setup-engine 第 4 节有一个只有 Godot 才有的分支:选引擎之后还要再问一次语言(GDScript / C# / Both),因为它同时决定 CLAUDE.md 模板、命名约定、专家路由与 .gd/.cs 的归属。Unity 和 Unreal 没有这一步——Unity 就是 C#,Unreal 就是 C++ 加蓝图。
Unreal 的命名表是这份 skill 里罕见的"反通用形状"案例。通用表会推出 variables: camelCase、signals: on_event_name,而实际写进 UE 的是 variables: PascalCase、signals: PascalCase On<Event>。理由被记录下来:对照 docs/engine-reference/unreal/ 全目录,"signal" 这个词一次都没出现过——那是 Godot 的词汇,UE 用的是 delegate 和 event。同时保留了两条不粉饰的告示:classes: PascalCase 对 UE 是不完整的(缺 U/A/F/E/I/T 类型前缀,枚举表达不了),scenes 这个键对 UE 是类别错配(UE 是 Level 与 Map,不是 Scene);constants: SCREAMING_SNAKE 在 Unity 与 UE 上均标注 UNVERIFIED,要求写进 project.yaml 时带行尾注释。
五、验证手段:从"零脚手架"到"先构建一次播放器"
这是我认为三引擎差距最大、也最少被讨论的一层。
CCGS 有一条贯穿全流程的硬规矩,写在 .claude/docs/coding-standards.md 里:A parse check is not a run——凡是改变玩家可见内容的故事,关闭前必须启动、观察,并把截图留在 production/qa/evidence/。编译证明代码能加载,测试证明逻辑对,两者都不能证明文字没有溢出方框。而且这条规矩在 qa.level: minimal 下不豁免:测试可以豁免,看一眼不行。
具体怎么"看一眼",由 .claude/docs/run-and-observe.md 按引擎分派:
| 引擎 | 启动 | 截图 | 需要额外脚手架 |
|---|---|---|---|
| Godot 4 | godot --path . --windowed --resolution 1280x720 <scene>.tscn |
--write-movie shots/x.png --quit-after 60 |
无 |
| Unity 6 | 已构建的 player .exe -screen-width ... --scene Shop |
bootstrap 脚本调 ScreenCapture.CaptureScreenshot |
一个 MonoBehaviour |
| UE 5 | UnrealEditor.exe Game.uproject /Game/Maps/Shop -game -windowed |
HighResShot filename=... 控制台命令 |
一个 actor,或用 -ExecCmds |
Godot 那行是真正的零成本:--write-movie 指向 .png 时输出帧序列,--quit-after 定帧数,文件名 8 位补零(shop00000000.png 到 shop00000059.png),取最后一张即可;场景路径是位置参数,任意 .tscn 都能直接拉起——这顺带满足了"必须直达故事触及的场景,而不是从主菜单点三下进去"的要求。
Unity 那行的真实代价写在括号里:-batchmode 什么都不显示,所以只能跑构建好的 player,"先构建 player,小工程也要 1–3 分钟;这是看着你实际发布的东西、而不是看着编辑器所付的价"。而且 --scene / --screenshot / --after 这三个参数是你自己定的,需要写一个 ScreenshotOnArg 解析 Environment.GetCommandLineArgs()、加载场景、等帧、调 CaptureScreenshot、再等一帧、Application.Quit();路径必须传绝对路径,因为编辑器和 player 的相对基准不同。
UE 那行埋了一个只在 Windows + Git Bash 下出现的坑:MSYS_NO_PATHCONV=1 前缀是必需的,否则 /Game/Maps/Shop 会被 Git Bash 当成 Windows 路径改写成 C:/Program Files/Git/Game/Maps/Shop,然后游戏停在一个没人看得见的"地图未找到"对话框上。截图侧还有时序要求:HighResShot 写盘延迟,不能在同一帧 Quit,至少留一秒;蓝图节点 Take High Res Screenshot 是编辑器专属,在 -game 启动下无效。
把它换算成工程语言:同一句"看一眼",Godot 的成本是一次命令行调用,Unity 是一次分钟级构建加一段自写 C# 引导代码,UE 是一次带平台特判的启动加一次有时序风险的截图。而这条验证恰恰是 CCGS 认定"不豁免"的那一条。对用代理跑独立游戏的人来说,这几乎就是日更循环的节拍器。
六、仓库自己承认的三处漂移
写到这里应该把证据链收严一点。CCGS 在 CHANGELOG.md 的 Known limitations 里列了两条与本文直接相关的自述:
- Windows is the verified platform. Everything was checked on Windows. macOS and Linux should work but haven't been confirmed.
- No Unity or Unreal project was compiled. Configuration, routing and documentation were verified for both engines, but nothing here builds or launches a real project in either.
也就是说,Unity 与 UE 两条路径的"已验证"范围是配置、路由、文档,不含编译与启动。这与本文第三节的文档体量、第四节的 TODO 命令、第五节的脚手架成本正好互为印证:这两条路径是精心移植、但未经端到端实跑的。
第二处漂移在文档内部。三份 VERSION.md 分别把版本钉在 Godot 4.6(2026-01)、Unity 6.3 LTS(2025-12)、UE 5.7(2025-11);而 .claude/docs/run-and-observe.md 的落款写的是"commands and APIs above verified against the official Godot 4.7, Unity 6.3 LTS and Unreal 5.8 references on 2026-09-14"。Godot 差了一个小版本,UE 差了一个小版本。这份文档自己还留了一句提醒:"docs/engine-reference/<engine>/ 才是项目的钉死权威,别信这里的版本限定陈述。"
第三处是 Unity 的 docs/engine-reference/unity/VERSION.md 里一段自我否决的告示:标题写着 Post-Cutoff,抬头声明的截止是 2025 年 5 月,而表里四行有三行日期是 2024 年 10/11/12 月——都在截止之前。文件给出的处理方式是不修,因为真实发布日期无法从这个仓库溯源,而"用训练数据填一个看起来合理的日期"正是整个参考目录存在的意义所反对的事。结论是:在重新核实之前,"把 docs/engine-reference/unity/ 里所有带版本限定的断言视为未确认,优先使用不依赖版本边界的 API"。
值得注意的是,仓库为这类漂移准备了一个专用检查:.claude/scripts/project-coherence.sh。/setup-engine 第 8.5 节的标题是 "Read Back What You Just Wrote",因为"再多的文字说明也挡不住照样写错"——这个脚本比对 project.yaml、VERSION.md、project.godot 与 PATH 上真实的引擎二进制,并检查 commands.build / commands.test 点名的文件是否存在。规则同样是两条:每条 [DIFFERS] 必须回报并解决;[NOT CHECKED] 不算通过,因为"没能跑的比对,不等于比对一致"。
七、选择建议:先用轻引擎把流程跑通,再决定要不要背迁移成本
把上面五层差异合起来看,结论并不复杂,但需要说得比"先 Godot 后 Unity"更具体一些。
第一步,用 Godot 验证"流程"而不是"引擎"。 理由不是 Godot 更好,而是它在这套框架里的代理阻力最小:project.godot 自动生成、四条命令三条可直接执行、--write-movie 零脚手架出图、参考文档只有 621 行、命名与语言分支虽然多问一次但都有确定答案。你可以在一天内把 /setup-engine → brief → /create-stories → /dev-story → 截图验证这条闭环跑完,从而判断"这套代理流水线到底适不适合我"——这是一个与被测引擎无关的问题。
第二步,把"迁移"当成一次真实的改造工程来估。 换引擎不是改一行 engine.name,按本文的证据,至少要做四件事:
- 改 5 条路径规则的
paths,从src/**改成Assets/Scripts/**或Source/<Module>/**,否则这些约束在目标引擎上永不触发; - 在目标引擎编辑器里建工程(CCGS 不会替你造),再重跑
/setup-engine,让它做project.yaml与technical-preferences.md的双写; - 重写
commands四行。Unity 要给出-buildTarget,UE 要按你的版本确认 UAT 参数、并保住-game与; Quit这两个"不写就挂死"的细节; - 补验证脚手架:Unity 一个
ScreenshotOnArg,UE 一个 dev actor 或-ExecCmds行,并把MSYS_NO_PATHCONV=1与截图延迟写进团队约定。
这四件里,第 1 件和第 4 件是没有工具会提醒你的——前者静默失效,后者只在你第一次跑验证时才暴露。
第三步,只在"引擎能力确实构成瓶颈"时才换。 /setup-engine 的引导模式给了一张相当克制的取舍表,值得直接当决策依据用:2D 任意规模、风格化/氛围向 3D、有限世界 3D → Godot;移动端、中等规模 3D、主机认证、需要庞大资产商店、2–5 人团队 → Unity;3A 级写实、大型无缝开放世界、高端 PC/主机且视觉保真度是核心卖点 → UE5。表里同时写了两条常被忽略的限制:Godot 的大型开放世界 3D " largely untested "、主机导出需要第三方发行商或大量额外工作;UE5 对风格化/2D/小规模项目是 overkill,且编辑器最重、编译最慢。
一句话的选型口径:CCGS 的三引擎支持是真实的,但它是"Godot 原生 + Unity/Unreal 精心移植"的结构,而不是三条等宽的路径。合理的用法是反过来——把 Godot 当作这套流水线的对照组,先用它把流程跑顺、把你的 brief 和 story 写法磨出来;等你确认瓶颈真的在引擎侧,再带着这份已经验证过的流程去付那四笔迁移成本。 反过来做,你会同时承担"流程没跑通"和"引擎没编译过"两个未知数,而仓库自己的 Known limitations 已经告诉你,后一个未知数在 Unity 与 UE 上从没被消除过。