内容
# Unity AI 游戏制作工具
用于 Unity 编辑器的安全本地 AI 游戏制作工具。
Unity AI 游戏制作工具是一个轻量级的 Unity 编辑器工具链，用于构建 Unity 游戏的 AI 编码代理：创建场景、预制体、游戏脚本、移动 UI、截图、验证器和面向生产的游戏对象，而无需将编辑器变成不安全的远程 shell。
它专为 Codex、Claude、Cursor 等支持 MCP 或 CLI 的 AI 代理设计，需要用于制作游戏的实用 Unity 自动化。
目标很简单：为 AI 代理快速创建 Unity 游戏，默认情况下保持输出面向生产，并通过明确的项目策略锁定危险功能。
## 为什么存在
当 AI 代理可以在 Unity 内执行实际的游戏制作工作时，它们非常有用：
- 查找和编辑场景对象
- 检查 UI Canvas 层次结构
- 安全地更新组件
- 管理预制体和资产
- 生成游戏脚本
- 创建生产级别的移动游戏 UI
- 捕获截图和日志
- 准备构建并运行测试
大多数现有的 Unity AI 桥梁证明了代理可以与 Unity 对话，但该项目旨在满足更具体的搜索需求：**用于制作游戏的 Unity AI**。它从一个小型受信任的本地核心开始，然后逐层添加游戏制作工作流。
## 安全第一
默认情况下，设置是故意保守的：
- 仅绑定到 `127.0.0.1`
- RPC 调用需要令牌
- 无云模式
- 无遥测
- 无静默自动更新
- 默认情况下不执行任意 C# 代码
- 默认情况下不调用私有反射
- 破坏性工具通过策略控制
有关完整的安全模型，请参见 [docs/SECURITY.md](docs/SECURITY.md)。
## 当前状态
该存储库是 AI 辅助 Unity 游戏创建的早期基础。它已经包括：
- 可安装的 Unity 编辑器包
- 本地令牌保护的 HTTP RPC 服务器
- 用于支持 MCP 的 AI 客户端的 MCP stdio 适配器
- 用于场景、GameObjects、组件、资产、预制体、相机和 Unity UI 的编辑器控制工具
- 用于脚本、物理、构建设置、播放模式、控制台日志、截图、灯光、音频和移动控件的游戏创建工具
- 用于游戏菜单、HUD、按钮、摇杆控件和验证的生产级 UI 样式预设
- 无依赖的 Node CLI
- 架构、路线图和安全文档
Unity 包 ID 为 `com.alday.unity-ai-game-maker`。
## 存储库布局
```text
.
|-- cli/ # 无依赖的本地 CLI 原型
|-- docs/ # 安全、架构、路线图
|-- examples/ # 示例策略和请求
|-- mcp/ # MCP stdio 适配器
|-- packages/
| `-- com.alday.unity-ai-game-maker/ # Unity 编辑器包
`-- server/ # MCP 适配器说明和未来服务器层
```
## 快速入门
将软件包安装到 Unity 项目中：
```bash
node cli/unity-ai.js /path/to/UnityProject install
```
打开 Unity。本地服务器在 `0.3.0+` 版本中默认自动启动。您也可以手动管理它：
```text
工具 > Unity AI 游戏制作工具 > 启动本地服务器
工具 > Unity AI 游戏制作工具 > 打印令牌
工具 > Unity AI 游戏制作工具 > 运行批处理文件...
工具 > Unity AI 游戏制作工具 > 捕获菜单截图
```
使用原型 CLI 调用 Unity AI 游戏制作工具：
```bash
node cli/unity-ai.js /path/to/UnityProject doctor
node cli/unity-ai.js /path/to/UnityProject health
node cli/unity-ai.js /path/to/UnityProject tools
node cli/unity-ai.js /path/to/UnityProject call scene.listOpen '{}'
node cli/unity-ai.js /path/to/UnityProject unity-batch ./examples/batch.menu-screenshots.json
node cli/unity-ai.js /path/to/UnityProject capture-scenes --output ../menu-screenshots --filter menu --source camera
node cli/unity-ai.js /path/to/UnityProject capture-scenes --output ../menu-screenshots --filter menusandgameplay --source playMode
```
CLI 从以下位置读取生成的令牌：
```text
UserSettings/UnityAiGameMaker.json
```
## MCP 适配器
构建 MCP stdio 适配器：
```bash
npm install --prefix mcp
npm --prefix mcp run build
```
在 Unity 项目中运行它，其中软件包已生成 `UserSettings/UnityAiGameMaker.json`:
```bash
node mcp/dist/src/server.js --project /path/to/UnityProject
```
示例 MCP 客户端配置：
```json
{
"mcpServers": {
"unity-ai-game-maker": {
"command": "node",
"args": [
"/path/to/Unity-AI-MCP-Game-Maker/mcp/dist/src/server.js",
"--project",
"/path/to/UnityProject"
]
}
}
}
```
适配器公开了诸如 `unity_scene_list_open`、`unity_game_object_find`、`unity_ui_button_create` 和 `unity_screenshot_capture` 等架构验证的 MCP 工具。参见 [mcp/README.md](mcp/README.md)。
## 示例游戏
在新的 Unity 6000.5 项目中创建一个完整的 3D 跑步游戏示例：
```bash
node cli/unity-ai.js /path/to/UnityProject sample-runner3d --unity /Applications/Unity/Hub/Editor/6000.5.1f1/Unity.app/Contents/MacOS/Unity
```
示例通过游戏制作批处理工具生成，包括：
- `MainMenu` 和 `Gameplay` 场景
- 相机、灯光、Canvas UI、EventSystem
- 玩家、硬币、障碍物和目标预制体
- 使用 Unity 原始对象仅生成的材质
- 移动、计分、碰撞、相机跟随和菜单流程的运行时脚本
## 首次工具界面
启动 Unity 软件包包括：
- `scene.listOpen`
- `scene.open`
- `scene.create`
- `scene.save`
- `scene.saveAs`
- `scene.hierarchy`
- `gameObject.find`
- `gameObject.create`
- `gameObject.delete`
- `gameObject.setTransform`
- `gameObject.setActive`
- `gameObject.setParent`
- `component.add`
- `component.list`
- `component.setField`
- `component.setProperty`
- `asset.find`
- `asset.material.create`
- `script.create`
- `physics.rigidbody.add`
- `physics.rigidbody.set`
- `physics.collider.add`
- `physics.collider.set`
- `scene.buildSettings.set`
- `playmode.start`
- `playmode.stop`
- `console.clear`
- `console.read`
- `screenshot.capture`
- `screenshots.captureScenes`
- `light.create`
- `light.set`
- `audio.source.add`
- `audio.source.set`
- `camera.create`
- `camera.set`
- `prefab.instantiate`
- `prefab.createFromGameObject`
- `prefab.child.create`
- `prefab.child.delete`
- `prefab.component.add`
- `prefab.component.setProperty`
- `ui.canvas.create`
- `ui.text.create`
- `ui.button.create`
- `ui.menu.create`
- `ui.hud.create`
- `ui.validate`
- `ui.virtualButton.create`
- `ui.joystick.create`
- `ui.mobileControls.create`
- `ui.rectTransform.set`
- `sample.runner3D.createScripts`
- `sample.runner3D.createContent`
协议是故意枯燥的 JSON：
```json
{
"tool": "gameObject.find",
"args": {
"name": "Canvas"
}
}
```
创建并定位 UI 按钮：
```bash
node cli/unity-ai.js /path/to/UnityProject call ui.button.create '{"parentPath":"Canvas","name":"Play Button","text":"PLAY","style":"soccer_mobile","variant":"primary","anchoredPosition":[0,-40]}'
```
UI 工具具有生产级别的默认值。按钮和文本使用游戏样式预设、生成的圆形切片精灵、阴影、轮廓、最佳文本拟合、移动友好型按钮大小和可读的颜色对比度。可用的预设包括 `arcade`、`casual`、`dark`、`premium` 和 `soccer_mobile`。
创建精致的菜单或 HUD：
```bash
node cli/unity-ai.js /path/to/UnityProject call ui.menu.create '{"parentPath":"Main Menu Canvas","style":"soccer_mobile","title":"SOCCER RUSH","subtitle":"Win the match","buttons":["PLAY","SHOP","SETTINGS"]}'
node cli/unity-ai.js /path/to/UnityProject call ui.hud.create '{"parentPath":"Gameplay Canvas","style":"soccer_mobile","scoreText":"LEVEL 1","coinsText":"COINS 0"}'
node cli/unity-ai.js /path/to/UnityProject call ui.validate '{"minButtonHeight":44}'
```
代理的推荐 UI 工作流程：
1. 使用样式预设创建 UI。
2. 运行 `ui.validate`。
3. 使用 `screenshot.capture` 或 `screenshots.captureScenes` 捕获截图。
4. 如果验证或截图审查显示重叠、对比度弱或比例不佳，请调整布局。
在没有运行 HTTP 服务器的情况下捕获所有菜单场景：
```bash
# 锐利的编辑器相机捕获（推荐用于菜单/UI）
node cli/unity-ai.js /path/to/UnityProject capture-scenes --output ../menu-screenshots --filter menu --source camera
# Play Mode 捕获（运行时引导/游戏）
node cli/unity-ai.js /path/to/UnityProject capture-scenes --output ../menu-screenshots --filter menusandgameplay --source playMode
```
截图模式：
- `camera` — 编辑器相机渲染，快速锐利（默认）
- `playMode` / `game` — 通过 `UnityAiScreenshotPlayModeBatch` 进入 Play Mode
- `gameView` — 读取 Game View，同时 Unity 编辑器打开
截图参数：
- `outputPath` — 首选 PNG 目标
- `path` — `outputPath` 的旧别名
- `source` — `camera`、`playMode`、`game` 或 `gameView`
- `cameraPath` — 相机层次结构路径，与输出路径分开
批处理模式入口点：
```bash
# 编辑器相机批处理
Unity -batchmode -quit \
-executeMethod Alday.UnityAiGameMaker.Editor.UnityAiGameMakerBatch.RunFromEnvironment
# Play Mode 批处理（Unity 完成后自动退出）
Unity -batchmode \
-executeMethod Alday.UnityAiGameMaker.Editor.UnityAiScreenshotPlayModeBatch.RunFromEnvironment
```
在编辑之前打开场景：
```bash
node cli/unity-ai.js /path/to/UnityProject call scene.open '{"path":"Assets/Scenes/MainMenu.unity"}'
```
实例化预制体：
```bash
node cli/unity-ai.js /path/to/UnityProject call prefab.instantiate '{"prefabPath":"Assets/Prefabs/Player.prefab","name":"Player","position":[0,1,0]}'
```
创建游戏脚本模板：
```bash
node cli/unity-ai.js /path/to/UnityProject call script.create '{"className":"PlayerController","path":"Assets/Scripts/PlayerController.cs","template":"PlayerController"}'
```
批处理模式会自动在 `script.create` 后创建编译阶段，因此使用新类型的命令可以保持在一个逻辑 JSON 请求中：
```json
{
"commands": [
{
"tool": "script.createAndAttach",
"args": {
"className": "EnemyAI",
"path": "Assets/Scripts/EnemyAI.cs",
"template": "MonoBehaviour",
"targetPath": "Enemy"
}
}
]
}
```
`script.createAndAttach` 是一个 CLI 批处理宏。它扩展到 `script.create`，等待 Unity 在下一个阶段编译/域重新加载，然后运行 `component.add` 和可选的 `component.setProperty` 命令。
添加物理和移动控件：
```bash
node cli/unity-ai.js /path/to/UnityProject call physics.rigidbody.add '{"path":"Player","mass":1,"useGravity":true}'
node cli/unity-ai.js /path/to/UnityProject call physics.collider.add '{"path":"Player","collider":"Capsule","height":1.8,"radius":0.45}'
node cli/unity-ai.js /path/to/UnityProject call ui.mobileControls.create '{"parentPath":"Gameplay Canvas"}'
```
## 下一步开发
下一步开发的重点是使该存储库成为一个实用的 **Unity AI 游戏制作工具**，用于代理编码工作流。MCP 作为一种标准协议很有用，但产品不应仅依赖 MCP。最强的方向是：
- **核心 Unity 软件包**，用于安全的编辑器端工具。
- **无依赖的 CLI**，适用于 Codex 和终端优先的代理。
- **MCP 适配器**，以便 Claude Desktop、Claude Code 等 MCP 客户端可以调用相同的工具。
- **适用于代理的游戏友好工作流**，可生成完整、验证的游戏功能，而不是原始编辑器对象。
计划的游戏制作功能：
1. `game.template.create`
游戏模板（跑步、足球、俯视、平台和简单射击游戏），包括场景结构、预制体、脚本、相机、UI 和构建设置。
2. 场景角色预设
诸如 `scene.createMenu`、`scene.createGameplay`、`scene.createLoading` 和 `scene.createGameOver` 之类的工具，以便代理可以快速创建完整的游戏流程。
3. 生产验证器
在 `ui.validate` 的基础上添加 `game.validate`、`camera.validate`、`mobile.validate` 和 `build.validate`，以便在游戏测试或构建之前检查生成的游戏。
4. Android 构建工作流
添加 `build.android.configure` 和 `build.android.run` 以配置包名、方向、版本、密钥库占位符、开发构建和输出路径。
5. 移动输入运行时工具
使用 `input.mobile.createController` 将视觉摇杆/按钮升级为运行时输入，包括触摸状态、移动向量、操作按钮和生成的玩家控制器绑定。
6. 游戏预制体套件
添加工具以创建具有网格、材质、碰撞器、刚体、脚本和预制体保存工作流的生产就绪玩家、敌人、可收集物、弹丸、目标、生成器、检查点和触发器预制体。
7. 截图审查工作流
添加 `game.reviewScreenshot` 以在 `screenshot.capture` 后捕获空白视图、不可见 UI、弱对比度、布局重叠、缺少主对象和相机框架问题。
### AI 代理定位
本项目应能被搜索以下内容的用户发现：
- Unity AI 游戏制作工具
- Unity AI MCP
- 用于游戏开发的 Unity MCP 服务器
- 用于 Codex 的 Unity 自动化
- Claude Unity 游戏开发工具
- AI 代理 Unity 游戏构建器
- 使用 AI 代理创建 Unity 游戏
技术定位应保持诚实：MCP 是一种集成层，而不是整个产品。可持续的价值是 Unity 游戏制作工具链：安全的编辑器控制、生产级默认值、验证、截图和可重复的游戏工作流，任何有能力的 AI 代理都可以使用。
## 路线图
近期：
- 策略文件强制执行
- 本地命令核心上的 MCP 适配器
长期：
- 软件包管理器工具
- 构建/测试编排
- 安全的脚本生成工作流与审查门
- 每工具审计日志
- 签名发布软件包
## 设计原则
权力只有在有责任时才有用。Unity AI MCP 游戏制作工具应该让 AI 代理更容易操作 Unity，同时使每个高风险操作可见、明确和可逆。
