🎮 UnitySkills

基于 REST API 的 AI 驱动 Unity 编辑器自动化引擎
让 AI 通过 Skills 直接控制 Unity 场景

🎉 我们现已收录于 DeepWiki！
有问题？请查看 AI 生成的文档 →

当前官方维护基线为 Unity 2022.3+。代码库中可能仍保留部分 Unity 2021 的兼容逻辑，但未来的功能开发、回归测试及适配工作将聚焦于 2022.3+ / Unity 6。

🤝 致谢

本项目是在 unity-mcp 优秀理念基础上进行的深度重构与功能扩展。

---

🚀 核心特性

• 🛠️ 513 个 REST Skills 综合工具包：包含 14 个辅助设计模块，支持多对象批量操作。
• 🎛️ 双模式灵活性：可根据不同工作流程在半自动（代码优先）和全自动（直接操控）之间切换。
• 🤖 原生支持四大 IDE：Claude Code / Antigravity / Gemini CLI / Codex — 一键安装即用。
• 🛡️ 事务原子性：失败操作会自动回滚，确保场景干净安全。
• 🌍 多实例同时控制：自动端口发现与全局注册，可同时控制多个 Unity 项目。
• 🔗 超稳定长连接：可配置请求超时时间（默认 15 分钟），Domain Reload 后自动恢复，并在脚本编译或资源更新期间提供重试提示。
• 🛡️ 防幻觉护栏：每个 Skill 模块都包含禁止列表和路由规则，以防止调用不存在的命令或参数错误。

---

🎛️ 运行模式

模式	默认	可用技能	使用场景
半自动	✅	~80	AI 编写 C# 代码 + 轻量级 Skills 辅助（脚本、感知、场景、编辑器、资源、工作流、调试）
全自动	—	全部 513	AI 直接操控 Unity（创建对象、配置材质/灯光/UI、构建场景）

如何切换：

• → 全自动："full auto" / "full-auto mode" / "build the scene for me" / "directly manipulate Unity"
• → 半自动："semi-auto" / "code-first" — 每次新会话默认为半自动模式

14 个辅助设计模块（架构、性能、设计模式、可测试性等）在两种模式下均可使用，并按需加载。

---

🏗️ 支持快速安装的 IDE/终端

本项目已针对以下环境进行了深度优化，以确保持续稳定的开发体验（未列出的工具并不一定不支持——只是缺少快速安装程序；可使用 自定义安装 将其部署到相应目录）：

AI 终端	支持状态	特色功能
Antigravity	✅ 已支持	支持 /unity-skills 斜杠命令，与原生工作流无缝集成。
Claude Code	✅ 已支持	智能识别 Skill 意图，支持复杂的多步骤自动化。
Gemini CLI	✅ 已支持	实验性支持，适配最新的 experimental.skills 规范。
Codex	✅ 已支持	支持 $skill 显式调用及隐式意图识别。

---

🏁 快速入门

概览：安装 Unity 插件 → 启动 UnitySkills 服务器 → AI 使用 Skills

1. 安装 Unity 插件

通过 Unity 包管理器，使用 Git URL 添加：

稳定版（main）：

https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity

测试版（beta）：

https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#beta

指定版本（如 v1.6.0）：

https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.6.0

📦 所有版本包均可在 Releases 页面获取。

2. 启动服务器

在 Unity 中，点击菜单：Window > UnitySkills > Start Server

⏳ script_*、debug_force_recompile、debug_set_defines、部分资源重新导入以及包变更可能会触发编译或 Domain Reload。在此期间 REST 接口暂时不可用属正常现象，请稍候再试。

3. 一键配置 AI Skills

1. 打开 Window > UnitySkills > Skill Installer。
2. 选择对应终端图标（Claude / Antigravity / Gemini / Codex）。
3. 点击 "Install" 即完成环境配置，无需手动复制代码。

安装程序会将包中的 unity-skills~/ 模板目录复制到目标位置。

安装程序生成的文件（位于目标目录）：

• SKILL.md
• skills/
• references/
• scripts/unity_skills.py
• scripts/agent_config.json（包含 Agent 标识符）
• Antigravity 还会额外生成 workflows/unity-skills.md

Codex 注意事项：建议进行 全局安装。若在项目级别安装，则需在 AGENTS.md 中声明才能被识别；全局安装后，重启 Codex 即可使用。

📘 完整的安装与使用说明，请参阅：Setup Guide | 安装指南

4. 手动安装 Skills（可选）

若不支持或更倾向于手动安装，请按照以下 标准流程 进行部署（适用于所有支持 Skills 的工具）：

✅ 标准安装方法 A

1. 自定义安装：在安装界面中，选择“Custom Path”选项，将 Skills 安装到您指定的任意目录（如 Assets/MyTools/AI），以便于项目管理。

✅ 标准安装方法 B

1. 定位 Skills 源目录：UPM 包中的 SkillsForUnity/unity-skills~/ 目录是可分发的 Skills 模板（根目录包含 SKILL.md）。
2. 找到工具的 Skills 根目录：不同工具的路径可能不同，请先参考该工具的文档。
3. 完整复制：将 unity-skills~/ 的全部内容复制到工具的 Skills 根目录中（重命名为 unity-skills/）。
4. 创建 agent_config.json：在 unity-skills/scripts/ 目录下创建一个 agent_config.json 文件：

   {"agentId": "your-agent-name", "installedAt": "2026-02-11T00:00:00Z"}
   

   将 your-agent-name 替换为你的 AI 工具名称（例如 claude-code、antigravity、gemini-cli、codex）。
5. 目录结构要求：复制完成后，保持如下结构（示例）：
   • unity-skills/SKILL.md
   • unity-skills/skills/
   • unity-skills/references/
   • unity-skills/scripts/unity_skills.py
   • unity-skills/scripts/agent_config.json
6. 重启工具：让工具重新加载 Skills 列表。
7. 验证加载：在工具中触发 Skills 列表或命令（或执行一个简单的技能调用），以确认其可用性。

🔎 常见工具目录参考

以下是一些经过验证的默认目录（如果工具配置了自定义路径，则使用自定义路径）：

• Claude Code：~/.claude/skills/
• Antigravity：~/.agent/skills/
• Gemini CLI：~/.gemini/skills/
• OpenAI Codex：~/.codex/skills/

🧩 其他支持 Skills 的工具

如果你使用的是其他支持 Skills 的工具，请按照该工具文档中指定的 Skills 根目录进行安装。只要满足 标准安装规范（根目录包含 SKILL.md 并保持 skills/、references/ 和 scripts/ 结构），就能被正确识别。

---

📦 Skills 分类概览（513 个）

分类	数量	核心功能
Cinemachine	23	2.x/3.x 双版本自动安装/MixingCamera/ClearShot/TargetGroup/Spline
工作流	22	持久化历史/任务快照/会话级撤销/回滚/书签
材质	21	批量修改材质属性/HDR/PBR/发光/关键词/渲染队列
GameObject	18	创建/查找/变换同步/批量操作/层级管理/重命名/复制
场景	10	多场景加载/卸载/激活/截图/上下文/依赖分析/报告导出
UI 系统	16	Canvas/按钮/文本/滑块/切换开关/锚点/布局/对齐/分布
UI Toolkit	15	UXML/USS 文件管理/UIDocument/PanelSettings 全属性读写/模板生成/结构检查/批量创建
资源	11	资源导入/删除/移动/复制/搜索/文件夹/批量操作/刷新
编辑器	12	播放模式/选择/撤销-重做/上下文获取/菜单执行
Timeline	12	轨道创建/删除/剪辑管理/播放控制/绑定/时长
物理	12	射线检测/球形检测/盒形检测/物理材质/层碰撞矩阵
音频	10	音频导入设置/AudioSource/AudioClip/AudioMixer/批量
纹理	10	纹理导入设置/平台设置/Sprite/类型/大小搜索/批量
模型	10	模型导入设置/网格信息/材质映射/动画/骨骼/批量
脚本	12	C# 脚本创建/读取/替换/列表/信息/重命名/移动/分析
包	11	包管理/安装/移除/搜索/版本/依赖关系/Cinemachine/Splines
AssetImport	11	纹理/模型/音频/Sprite 导入设置/标签管理/重新导入
项目	11	渲染管线/构建设置/包管理/层/标签/PlayerSettings/质量
着色器	11	着色器创建/URP 模板/编译检查/关键词/变体分析/全局关键词
相机	11	场景视图控制/游戏摄像机创建/属性/截图/正交切换/列表
地形	10	地形创建/高度图/珀林噪声/平滑/平整/纹理绘制
NavMesh	10	打包/路径计算/代理/障碍物/采样/区域成本
清理	10	未使用的资源/重复文件/空文件夹/缺失脚本修复/依赖树
ScriptableObject	10	创建/读写/批量设置/删除/查找/JSON 导入导出
控制台	10	日志捕获/清除/导出/统计/暂停控制/折叠/播放时清空
调试	10	错误日志/编译检查/堆栈跟踪/程序集/定义符号/内存信息
事件	10	UnityEvent 监听器管理/批量添加/复制/状态控制/列表
智能	10	场景 SQL 查询/空间查询/自动布局/吸附地面/网格吸附/随机化/替换
测试	10	测试运行/按名称运行/分类/模板创建/汇总统计
预制件	11	创建/实例化/覆盖应用与撤销/批量实例化/变体/查找实例/资源属性编辑
组件	10	添加/删除/属性配置/批量操作/复制/启用-禁用
优化	10	纹理压缩/网格压缩/音频压缩/场景分析/静态标志/LOD/重复材质/过度绘制
性能分析器	10	FPS/内存/纹理/网格/材质/音频/渲染统计/对象数量/AssetBundle
灯光	10	灯光创建/类型配置/强度-颜色/批量切换/探头组/反射探头/光照贴图
验证	10	项目验证/空文件夹清理/引用检测/网格碰撞器/着色器错误
Animator	10	动画控制器/参数/状态机/过渡/分配/播放
感知	11	场景摘要/层级树/脚本分析/空间查询/材质概览/场景快照/依赖分析/报告导出/性能提示/脚本依赖图
示例	8	基础示例：创建/删除/变换/场景信息

⚠️ 大多数模块都支持 *_batch 批量操作。在操作多个对象时，优先使用批量 Skills 以获得更好的性能。

🧠 unity-skills/skills/ 还包含 14 个设计建议模块，用于架构、脚本设计、性能、可维护性以及 Inspector 指导。

---

📂 项目结构

.
├── SkillsForUnity/                 # Unity 编辑器插件（UPM 包）
│   ├── package.json                # com.besty.unity-skills
│   ├── unity-skills~/              # 跨平台 AI 技能模板（带波浪号的隐藏目录，随包打包）
│   │   ├── SKILL.md                # 主要技能定义（AI 可读）
│   │   ├── scripts/
│   │   │   └── unity_skills.py     # Python 客户端库
│   │   ├── skills/                 # 模块化技能文档 + 13 个辅助模块
│   │   └── references/             # Unity 开发参考资料
│   └── Editor/Skills/              # 核心技能逻辑（40 个 Skills.cs 文件，共 513 个技能）
│       ├── SkillsHttpServer.cs     # HTTP 服务器核心（生产者-消费者模型）
│       ├── SkillRouter.cs          # 请求路由与基于反射的技能发现
│       ├── WorkflowManager.cs      # 持久化工作流（任务/会话/快照）
│       ├── RegistryService.cs      # 全局注册中心（多实例发现）
│       ├── GameObjectFinder.cs     # 统一的游戏对象查找器（按名称/实例ID/路径）
│       ├── BatchExecutor.cs        # 通用批处理框架
│       ├── GameObjectSkills.cs     # 游戏对象操作（18 个技能）
│       ├── MaterialSkills.cs       # 材质操作（21 个技能）
│       ├── CinemachineSkills.cs    # Cinemachine 2.x/3.x（23 个技能）
│       ├── WorkflowSkills.cs       # 工作流撤销/回滚（22 个技能）
│       ├── PerceptionSkills.cs     # 场景理解（11 个技能）
│       └── ...                     # 共 513 个技能的源代码
├── docs/
│   └── SETUP_GUIDE.md              # 完整的设置与使用指南
├── CHANGELOG.md                    # 版本更新日志
└── LICENSE                         # MIT 许可证

---

⭐ 星标历史

---

📄 许可证

本项目采用 MIT 许可证。

Unity-Skills 快速上手指南

Unity-Skills 是一个基于 REST API 的 AI 驱动 Unity 编辑器自动化引擎，允许 AI 通过技能（Skills）直接控制 Unity 场景。支持半自动（代码优先）和全自动（直接操作）两种模式，内置 513+ 个原子化技能。

🛠️ 环境准备

• Unity 版本：官方维护基准为 Unity 2022.3+ 或 Unity 6。
  • 注：虽然部分代码兼容 Unity 2021，但新功能与测试均针对 2022.3+ 优化。
• AI 终端工具（任选其一）：
  • Claude Code
  • Antigravity
  • Gemini CLI
  • OpenAI Codex
• 网络环境：需确保能访问 GitHub 以拉取插件包。

📦 安装步骤

1. 在 Unity 中安装插件

打开 Unity 项目，进入 Window > Package Manager：

1. 点击左上角 + 号，选择 Add package from git URL...。

2. 输入以下地址并点击 Add：

   稳定版 (推荐):

   https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity
   

   测试版 (Beta):

   https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#beta
   

   指定版本 (例如 v1.6.0):

   https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.6.0
   

2. 启动 UnitySkills 服务

在 Unity 编辑器顶部菜单栏点击： Window > UnitySkills > Start Server

⚠️ 注意：首次启动或涉及脚本编译、资源导入时，可能会触发 Domain Reload，导致 REST 服务暂时不可用，请稍等片刻后重试。

3. 配置 AI 终端 (一键安装)

在 Unity 中点击菜单： Window > UnitySkills > Skill Installer

1. 在弹出的窗口中，选择你正在使用的 AI 终端图标（Claude / Antigravity / Gemini / Codex）。
2. 点击 Install 按钮。
3. 系统将自动把技能模板复制到对应终端的技能目录，并生成配置文件 agent_config.json。

Codex 用户特别提示：建议进行全局安装。若选择项目级安装，需在项目根目录的 AGENTS.md 中声明才能被识别。安装完成后请重启 Codex 终端。

(若一键安装失败，可参考原文档中的“手动安装”部分，将 unity-skills~/ 目录内容手动复制到对应终端的 skills 根目录，如 ~/.claude/skills/)

🚀 基本使用

切换运行模式

Unity-Skills 默认启动为 半自动模式 (Semi-Auto)，AI 主要编写 C# 代码辅助操作。如需让 AI 直接操控编辑器，可在对话中发送指令切换：

• 切换至全自动模式 (直接使用 513+ 技能)：

  "full auto" 或 "build the scene for me"

• 切换回半自动模式 (代码优先)：

  "semi-auto" 或 "code-first"

使用示例

假设你已启动服务器并完成配置，在 AI 终端中输入以下自然语言指令：

示例 1：创建场景物体 (全自动模式)

请在场景中心创建一个红色的立方体，并添加一个旋转动画。

AI 将直接调用 GameObject 和 Timeline 相关技能执行操作，无需你写代码。

示例 2：批量修改材质 (全自动模式)

选中场景中所有使用 Standard Shader 的材质，将它们的金属度 (Metallic) 统一调整为 0.8。

AI 将调用 Material 批处理技能完成修改。

示例 3：查询与清理 (通用)

检查项目中是否有未使用的资源文件，并列出列表。

AI 将调用 Cleaner 模块进行分析。

---

更多详细技能列表与高级配置，请参阅项目文档中的 Setup Guide。