| name | setup-engine |
| description | 配置项目的游戏引擎和版本。将引擎锁定到 CLAUDE.md 中，检测知识缺口，当版本超出 LLM 训练数据时通过 WebSearch 填充引擎参考文档。 |
| argument-hint | [engine version] or no args for guided selection |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Write, Edit, WebSearch, WebFetch, Task |
当此技能被调用时：
1. 解析参数
三种模式：
- 完整规格：
/setup-engine godot 4.6 — 已提供引擎和版本
- 仅引擎：
/setup-engine unity — 已提供引擎，版本将自动查找
- 无参数：
/setup-engine — 完全引导模式（引擎推荐 + 版本选择）
2. 引导模式（无参数）
如果未指定引擎，运行交互式引擎选择流程：
检查现有游戏概念
- 如果存在，读取
design/gdd/game-concept.md — 提取游戏类型、范围、目标平台、美术风格、团队规模，以及 /brainstorm 给出的引擎推荐
- 如果概念不存在，告知用户：
"未找到游戏概念。建议先运行 /brainstorm 发现你想构建什么 — 它还会推荐引擎。或者告诉我你的游戏想法，我可以帮你选择。"
如果用户想在无概念的情况下选择，询问：
- 什么类型的游戏？（2D、3D，或两者兼具？）
- 什么平台？（PC、移动端、主机、网页？）
- 团队规模和经验？（单人新手、单人经验丰富、小团队？）
- 有强烈的语言偏好吗？（GDScript、C#、C++、可视化脚本？）
- 引擎授权预算？（仅免费，还是可接受商业授权？）
给出推荐
使用以下决策矩阵：
| 因素 | Godot 4 | Unity | Unreal Engine 5 |
|---|
| 最适用于 | 2D 游戏、小型 3D、单人/小团队 | 移动端、中等规模 3D、跨平台 | 3A 级 3D、照片级写实、大型团队 |
| 语言 | GDScript（+ C#，通过扩展支持 C++） | C# | C++ / Blueprint |
| 费用 | 免费，MIT 许可证 | 收入门槛以下免费 | 收入门槛以下免费，5% 版税 |
| 学习曲线 | 平缓 | 中等 | 陡峭 |
| 2D 支持 | 优秀（原生） | 良好（但以 3D 为优先） | 可行但非理想选择 |
| 3D 质量上限 | 良好（快速提升中） | 非常好 | 业界领先 |
| Web 导出 | 支持（原生） | 支持（有限制） | 不支持 |
| 主机导出 | 通过第三方 | 支持（需要授权） | 支持 |
| 开源 | 是 | 否 | 源码可用 |
给出排名前 1-2 的推荐及其与用户回答相关联的理由。
让用户自行选择 — 永远不要强制推荐。
3. 查找当前版本
引擎确定后：
- 如果提供了版本，直接使用
- 如果未提供版本，使用 WebSearch 查找最新稳定版：
- 搜索：
"[engine] latest stable version [当前年份]"
- 与用户确认："最新稳定版 [引擎] 是 [版本]。使用这个吗？"
4. 更新 CLAUDE.md 技术栈
读取 CLAUDE.md 并更新技术栈部分。将 [CHOOSE] 占位符替换为实际值：
Godot:
- **引擎**：Godot [版本]
- **语言**：GDScript（主要），通过 GDExtension 支持 C++（性能关键场景）
- **构建系统**：SCons（引擎），Godot 导出模板
- **资产管线**：Godot 导入系统 + 自定义资源管线
Unity:
- **引擎**：Unity [版本]
- **语言**：C#
- **构建系统**：Unity Build Pipeline
- **资产管线**：Unity Asset Import Pipeline + Addressables
Unreal:
- **引擎**：Unreal Engine [版本]
- **语言**：C++（主要），Blueprint（游戏玩法原型开发）
- **构建系统**：Unreal Build Tool (UBT)
- **资产管线**：Unreal Content Pipeline
5. 填充技术偏好
更新 CLAUDE.md 后，创建或更新 .claude/docs/technical-preferences.md，填入引擎对应的默认值。先阅读现有模板，然后填入：
引擎和语言部分
命名约定（引擎默认值）
Godot (GDScript):
- 类名：PascalCase（如
PlayerController）
- 变量/函数：snake_case（如
move_speed）
- 信号：snake_case 过去时（如
health_changed）
- 文件名：snake_case 与类名匹配（如
player_controller.gd）
- 场景：PascalCase 与根节点匹配（如
PlayerController.tscn）
- 常量：UPPER_SNAKE_CASE（如
MAX_HEALTH）
Unity (C#):
- 类名：PascalCase（如
PlayerController）
- 公共字段/属性：PascalCase（如
MoveSpeed）
- 私有字段：_camelCase（如
_moveSpeed）
- 方法：PascalCase（如
TakeDamage()）
- 文件名：PascalCase 与类名匹配（如
PlayerController.cs）
- 常量：PascalCase 或 UPPER_SNAKE_CASE
Unreal (C++):
- 类名：带前缀的 PascalCase（
A 表示 Actor，U 表示 UObject，F 表示结构体）
- 变量：PascalCase（如
MoveSpeed）
- 函数：PascalCase（如
TakeDamage()）
- 布尔值：
b 前缀（如 bIsAlive）
- 文件名：与类名匹配但不带前缀（如
PlayerController.h）
其余部分
- 性能预算：保留为
[TO BE CONFIGURED] 并附带建议：
"典型目标：60fps / 16.6ms 帧预算。现在设置这些吗？"
- 测试：建议引擎对应的框架（Godot 用 GUT，Unity 用 NUnit 等）
- 禁止模式/允许的库：保留为占位符
协作步骤
向用户展示填好的偏好设置：
"这是 [引擎] 的默认技术偏好。要自定义其中任何一项，还是直接保存默认值？"
等待用户批准后再写入文件。
6. 确定知识缺口
检查引擎版本是否可能超出 LLM 的训练数据。
已知的大致覆盖范围（随着模型更新调整）：
- LLM 知识截止日期：2025 年 5 月
- Godot：训练数据可能覆盖到 ~4.3
- Unity：训练数据可能覆盖到 ~2023.x / 6000.x 早期版本
- Unreal：训练数据可能覆盖到 ~5.3 / 5.4 早期版本
将用户选择的版本与这些基线进行比较：
- 在训练数据范围内 →
低风险 — 参考文档可选但推荐
- 接近边界 →
中风险 — 推荐参考文档
- 超出训练数据 →
高风险 — 必须有参考文档
告知用户所属的类别及原因。
7. 填充引擎参考文档
如果在训练数据范围内（低风险）：
创建一个精简的 docs/engine-reference/<engine>/VERSION.md：
# [Engine] — 版本参考
| 字段 | 值 |
|------|-----|
| **引擎版本** | [版本] |
| **项目锁定日期** | [今天的日期] |
| **LLM 知识截止** | 2025 年 5 月 |
| **风险等级** | 低 — 版本在 LLM 训练数据范围内 |
## 说明
此引擎版本在 LLM 的训练数据范围内。引擎参考文档为可选项，
但如果代理建议了错误的 API，可稍后添加。
随时运行 `/setup-engine refresh` 来填充完整参考文档。
不要创建 breaking-changes.md、deprecated-apis.md 等文件 — 它们会增加上下文成本但价值有限。
如果超出训练数据（中风险或高风险）：
通过搜索网络创建完整的参考文档集：
-
搜索官方迁移/升级指南：
"[engine] [旧版本] 到 [新版本] 迁移指南""[engine] [版本] breaking changes""[engine] [版本] changelog""[engine] [版本] deprecated API"
-
从官方文档获取并提取：
- 从知识截止到当前版本之间的每个版本的 breaking changes
- 已废弃的 API 及其替代方案
- 新功能和最佳实践
-
创建完整的参考目录：
docs/engine-reference/<engine>/
├── VERSION.md # 版本锁定 + 知识缺口分析
├── breaking-changes.md # 逐版本的 breaking changes
├── deprecated-apis.md # "不要用 X → 用 Y" 对照表
├── current-best-practices.md # 知识截止后的新实践
└── modules/ # 各子系统参考（按需创建）
-
使用网络搜索的真实数据填充每个文件，遵循现有参考文档的格式。每个文件必须有"最后验证：[日期]"标题。
-
对于模块文件：仅对发生了重大变化的子系统创建模块。不要创建空白或内容稀少的模块文件。
8. 更新 CLAUDE.md 导入
更新"引擎版本参考"下的 @ 导入，指向正确的引擎：
## 引擎版本参考
@docs/engine-reference/<engine>/VERSION.md
如果之前的导入指向不同引擎（例如从 Godot 切换到 Unity），请更新。
9. 更新 Agent 指令
对于所选引擎的专家代理，验证它们是否有"版本感知"部分。如果没有，按照现有 Godot 专家代理的模式添加。
该部分应指示代理：
- 读取
docs/engine-reference/<engine>/VERSION.md
- 建议代码前检查已废弃的 API
- 检查相关版本过渡的 breaking changes
- 使用 WebSearch 验证不确定的 API
10. Refresh 子命令
如果以 /setup-engine refresh 调用：
- 读取现有的
docs/engine-reference/<engine>/VERSION.md 获取当前引擎和版本
- 使用 WebSearch 检查：
- 自上次验证以来的新引擎发布
- 更新的迁移指南
- 新废弃的 API
- 用新发现更新所有参考文档
- 更新所有修改文件的"最后验证"日期
- 报告变更内容
11. 输出摘要
设置完成后，输出：
引擎设置完成
=====================
引擎： [名称] [版本]
知识风险： [低/中/高]
参考文档： [已创建/已跳过]
CLAUDE.md： [已更新]
技术偏好： [已创建/已更新]
代理配置： [已验证]
后续步骤：
1. 查看 docs/engine-reference/<engine>/VERSION.md
2. [如果来自 /brainstorm] 运行 /map-systems 将概念分解为独立系统
3. [如果来自 /brainstorm] 运行 /design-system 逐系统编写 GDD（引导式，按章节）
4. [如果来自 /brainstorm] 运行 /prototype [核心机制] 测试核心循环
5. [如果是全新开始] 运行 /brainstorm 发现游戏概念
6. 创建第一个里程碑：/sprint-plan new
护栏
- 绝对不要猜测引擎版本 — 始终通过 WebSearch 或用户确认来验证
- 没有询问前绝不要覆盖现有参考文档 — 应追加或更新
- 如果已有不同引擎的参考文档，替换前先询问
- 始终在编辑 CLAUDE.md 之前向用户展示将要修改的内容
- 如果 WebSearch 返回模糊结果，展示给用户并让其决定
