setup-engine

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 发现你想构建什么 — 它还会推荐引擎。或者告诉我你的游戏想法，我可以帮你选择。"

如果用户想在无概念的情况下选择，询问：

1. 什么类型的游戏？（2D、3D，或两者兼具？）
2. 什么平台？（PC、移动端、主机、网页？）
3. 团队规模和经验？（单人新手、单人经验丰富、小团队？）
4. 有强烈的语言偏好吗？（GDScript、C#、C++、可视化脚本？）
5. 引擎授权预算？（仅免费，还是可接受商业授权？）

给出推荐

使用以下决策矩阵：

因素	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，填入引擎对应的默认值。先阅读现有模板，然后填入：

引擎和语言部分

• 根据第 4 步的引擎选择填入

命名约定（引擎默认值）

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 等文件 — 它们会增加上下文成本但价值有限。

如果超出训练数据（中风险或高风险）：

通过搜索网络创建完整的参考文档集：

1. 搜索官方迁移/升级指南：

   • "[engine] [旧版本] 到 [新版本] 迁移指南"
   • "[engine] [版本] breaking changes"
   • "[engine] [版本] changelog"
   • "[engine] [版本] deprecated API"

2. 从官方文档获取并提取：

   • 从知识截止到当前版本之间的每个版本的 breaking changes
   • 已废弃的 API 及其替代方案
   • 新功能和最佳实践

3. 创建完整的参考目录：

   docs/engine-reference/<engine>/
   ├── VERSION.md              # 版本锁定 + 知识缺口分析
   ├── breaking-changes.md     # 逐版本的 breaking changes
   ├── deprecated-apis.md      # "不要用 X → 用 Y" 对照表
   ├── current-best-practices.md  # 知识截止后的新实践
   └── modules/                # 各子系统参考（按需创建）
   

4. 使用网络搜索的真实数据填充每个文件，遵循现有参考文档的格式。每个文件必须有"最后验证：[日期]"标题。

5. 对于模块文件：仅对发生了重大变化的子系统创建模块。不要创建空白或内容稀少的模块文件。

---

8. 更新 CLAUDE.md 导入

更新"引擎版本参考"下的 @ 导入，指向正确的引擎：

## 引擎版本参考

@docs/engine-reference/<engine>/VERSION.md

如果之前的导入指向不同引擎（例如从 Godot 切换到 Unity），请更新。

---

9. 更新 Agent 指令

对于所选引擎的专家代理，验证它们是否有"版本感知"部分。如果没有，按照现有 Godot 专家代理的模式添加。

该部分应指示代理：

1. 读取 docs/engine-reference/<engine>/VERSION.md
2. 建议代码前检查已废弃的 API
3. 检查相关版本过渡的 breaking changes
4. 使用 WebSearch 验证不确定的 API

---

10. Refresh 子命令

如果以 /setup-engine refresh 调用：

1. 读取现有的 docs/engine-reference/<engine>/VERSION.md 获取当前引擎和版本
2. 使用 WebSearch 检查：
   • 自上次验证以来的新引擎发布
   • 更新的迁移指南
   • 新废弃的 API
3. 用新发现更新所有参考文档
4. 更新所有修改文件的"最后验证"日期
5. 报告变更内容

---

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 返回模糊结果，展示给用户并让其决定