Unity3d MCP - 连接AI与Unity的桥梁，实现智能化游戏开发
Unity3d MCP (Model Context Protocol) 是一个创新的AI-Unity集成系统，它通过内置的MCP服务器将AI助手（如Cursor、Claude、Trae）与Unity编辑器无缝连接，实现AI驱动的Unity开发工作流。
- AI驱动开发：通过自然语言指令控制Unity编辑器
- 无缝集成：支持主流AI客户端，无需修改现有工作流
- 功能丰富：提供32+专业工具，覆盖Unity开发全流程
- 高性能：基于HTTP的高效通信机制
- 可扩展：模块化设计，易于添加新功能
- 零配置：Unity内置MCP服务器，无需外部依赖
- 内置MCP Server (C#)：Unity编辑器内置的MCP协议服务器
- Unity Package (C#)：完整的Unity编辑器插件
- 工具生态：32+专业Unity开发工具
- 通信协议：基于HTTP的JSON-RPC 2.0通信
系统采用分层架构设计，从上到下分为：
- AI客户端层：Cursor、Claude、Trae等AI助手
- MCP协议层：Unity内置MCP服务器
- 通信层：HTTP (可自定义端口，默认8000) + JSON-RPC 2.0
- Unity编辑器层：Unity Editor + Unity API
- 工具层：40+专业工具 + 消息队列执行引擎
图1：Unity3d MCP系统整体架构图，展示了从AI客户端到Unity编辑器的完整数据流和组件关系
图2：Unity3d MCP数据流图，详细展示了从AI指令到Unity执行的完整数据流转过程
AI客户端 → FacadeTools → MethodTools → Unity API
- FacadeTools：
async_call和batch_call两个门面工具 - MethodTools：40+专业功能方法，仅通过FacadeTools调用
- 基于状态模式的路由系统
- 支持参数验证和类型转换
- 提供统一的错误处理机制
- 可自定义端口配置 (默认8000)
- 消息队列处理机制
- 主线程安全执行保障
unity-package/Editor/Connect/
├── McpService.cs # 内置MCP服务器核心
├── McpServiceStatusWindow.cs # 服务状态监控窗口
└── McpServiceGUI.cs # 服务管理界面
1. 内置MCP服务器 (McpService.cs)
// HTTP监听器管理
public static void StartService()
{
// 创建HttpListener
// 配置可自定义端口
// 启动消息队列处理
}
// MCP协议处理
private async Task<string> ProcessMcpRequest(string requestBody)
{
// JSON-RPC 2.0协议解析
// 工具调用路由
// 响应格式化
}2. 消息队列系统
// 主线程安全执行
private void EnqueueTask(Action task)
{
// 添加任务到队列
// 注册EditorApplication.update回调
// 确保Unity API在主线程执行
}
private void ProcessMessageQueue()
{
// 处理队列中的任务
// 自动注册/注销update回调
// 线程安全的任务执行
}3. 工具发现系统
private void DiscoverTools()
{
// 反射发现IToolMethod实现
// 自动注册async_call和batch_call
// 构建工具信息和输入模式
}unity-package/
├── Runtime/ # 运行时核心（精简）
│ └── StateTreeContext.cs # 执行上下文
├── Editor/ # 编辑器扩展（完整实现）
│ ├── Connection/ # 连接管理
│ │ └── McpService.cs # TCP连接核心
│ ├── Executer/ # 执行器（核心执行层）
│ │ ├── SingleCall.cs # 单次调用
│ │ ├── BatchCall.cs # 批量调用
│ │ ├── ToolsCall.cs # 工具调用
│ │ ├── CoroutineRunner.cs # 协程运行器
│ │ ├── McpTool.cs # MCP工具基类
│ │ ├── StateMethodBase.cs # 状态方法基类
│ │ ├── DualStateMethodBase.cs # 双状态方法基类
│ │ ├── IToolMethod.cs # 工具方法接口
│ │ ├── MethodKey.cs # 方法键定义
│ │ └── ToolNameAttribute.cs # 工具名称属性
│ ├── StateTree/ # 状态树引擎
│ │ ├── StateTree.cs # 状态树核心
│ │ ├── StateTreeBuilder.cs # 状态树构建器
│ │ └── StateTreeContext.cs # 执行上下文
│ ├── Selector/ # 选择器系统
│ │ ├── HierarchySelector.cs # 层级选择器
│ │ ├── ProjectSelector.cs # 项目选择器
│ │ ├── ObjectSelector.cs # 对象选择器
│ │ └── IObjectSelector.cs # 选择器接口
│ ├── Model/ # 数据模型
│ │ ├── Command.cs # 命令模型
│ │ ├── Response.cs # 响应模型
│ │ ├── McpSettings.cs # MCP设置
│ │ ├── McpExecuteRecordObject.cs # 执行记录
│ │ └── UIDefineRuleObject.cs # UI规则定义
│ ├── GUI/ # 编辑器GUI
│ │ ├── McpServiceGUI.cs # 连接GUI
│ │ ├── McpDebugWindow.cs # 调试窗口
│ │ ├── UIDefineRuleObjectDrawer.cs # UI规则绘制器
│ │ └── UIDefineRuleObjectEditor.cs # UI规则编辑器
│ ├── Provider/ # 设置提供者
│ │ ├── McpSettingsProvider.cs # MCP设置提供者
│ │ ├── McpUISettingsProvider.cs # UI设置提供者
│ │ └── FigmaSettingsProvider.cs # Figma设置提供者
│ ├── Tools/ # 工具实现
│ │ ├── Hierarchy/ # 层级管理
│ │ │ ├── HierarchyCreate.cs
│ │ │ ├── HierarchySearch.cs
│ │ │ └── HierarchyApply.cs
│ │ ├── Projet/ # 项目管理
│ │ │ ├── ProjectSearch.cs
│ │ │ └── ProjectOperate.cs
│ │ ├── ResEdit/ # 资源编辑
│ │ │ ├── EditGameObject.cs
│ │ │ ├── EditComponent.cs
│ │ │ ├── EditMaterial.cs
│ │ │ └── ... (更多编辑工具)
│ │ ├── Console/ # 控制台工具
│ │ │ ├── ConsoleRead.cs
│ │ │ └── ConsoleWrite.cs
│ │ ├── RunCode/ # 代码运行
│ │ │ ├── CodeRunner.cs
│ │ │ └── PythonRunner.cs
│ │ ├── UI/ # UI工具
│ │ │ ├── UGUILayout.cs
│ │ │ ├── UIRuleManage.cs
│ │ │ ├── FigmaManage.cs
│ │ │ └── FigmaDataSimplifier.cs
│ │ ├── GameWindow/ # 游戏窗口
│ │ ├── Setting/ # 设置工具
│ │ ├── GamePlay.cs # 游戏玩法
│ │ ├── BaseEditor.cs # 编辑器管理
│ │ ├── ManagePackage.cs # 包管理
│ │ ├── ObjectDelete.cs # 对象删除
│ │ ├── RequestHttp.cs # HTTP请求
│ │ └── Storage/ # 存储管理
│ │ ├── Prefers.cs # 偏好设置
│ │ └── SourceLocation.cs # 资源定位
│ ├── Utils/ # 工具类库
│ │ ├── ConsoleUtils.cs # 控制台工具
│ │ ├── GameObjectUtils.cs # GameObject工具
│ │ ├── UGUIUtil.cs # UGUI工具
│ │ ├── MenuUtils.cs # 菜单工具
│ │ └── CursorChatIntegration.cs # Cursor集成
│ └── Unity.Mcp.Editors.asmdef # 程序集定义
└── package.json # 包配置
1. 状态树引擎 (Editor/StateTree/StateTree.cs)
public class StateTree
{
public string key; // 当前层变量
public Dictionary<object, StateTree> select = new(); // 选择分支
public Func<StateTreeContext, object> contextFunc; // 叶子函数
public object Run(StateTreeContext ctx)
{
// 状态树路由逻辑
// 参数验证和类型转换
// 方法执行和结果处理
}
}- 位置变化：从 Runtime 移动到 Editor/StateTree
- 配套工具：新增 StateTreeBuilder 构建器，简化状态树构建流程
2. HTTP服务器管理 (Editor/Connect/McpService.cs)
public partial class McpService
{
private HttpListener listener;
private readonly Queue<Action> messageQueue = new();
public void Start()
{
// 可自定义端口监听 (默认8000)
// HTTP请求处理
// 消息队列管理
}
private async Task<string> ProcessMcpRequest(string requestBody)
{
// JSON-RPC 2.0解析
// 工具调用路由
// 响应生成
}
}3. 门面工具 (Editor/Executer/AsyncCall.cs / BatchCall.cs)
public class AsyncCall : McpTool
{
public override void HandleCommand(JsonNode cmd, Action<JsonNode> callback)
{
string id = cmd["id"]?.Value;
string type = cmd["type"]?.Value;
// 异步调用管理
// 结果缓存和获取
HandleAsyncOperation(id, type, cmd, callback);
}
}4. 协程运行器 (Editor/Executer/CoroutineRunner.cs)
public class CoroutineRunner : MonoBehaviour
{
// 支持在编辑器模式下运行协程
// 用于异步操作（如HTTP请求、文件下载等）
}- 位置变化：从 Runtime 移动到 Editor/Executer
- 功能增强：支持编辑器模式下的协程执行
5. 选择器系统 (Editor/Selector/)
// 统一的对象选择接口
public interface IObjectSelector
{
Object[] SelectObjects(string[] paths);
}
// 层级选择器：用于选择场景中的GameObject
public class HierarchySelector : IObjectSelector { }
// 项目选择器：用于选择项目资源
public class ProjectSelector : IObjectSelector { }- 新增模块：提供统一的对象选择机制
- 应用场景：支持灵活的对象查询和批量操作
6. 工具方法基类 (Editor/Executer/)
- StateMethodBase：单状态树工具基类
- DualStateMethodBase：双状态树工具基类（支持更复杂的路由）
- IToolMethod：工具方法接口，定义工具标准
- ToolNameAttribute：工具名称属性，用于自动注册
7. GUI系统 (Editor/GUI/)
- McpServiceGUI：连接状态显示和控制
- McpDebugWindow：调试窗口，查看执行历史和日志
- UI规则编辑器：可视化UI规则定义工具
-
层级管理工具 (Tools/Hierarchy/)
hierarchy_create：创建GameObjecthierarchy_search：搜索和查询GameObjecthierarchy_apply：应用预制体
-
资源编辑工具 (Tools/ResEdit/)
edit_gameobject：编辑GameObject属性edit_component：编辑组件属性edit_material：编辑材质edit_texture：编辑纹理- 等多个编辑工具
-
项目管理工具 (Tools/Projet/)
project_search：搜索项目资源project_operate：项目操作
-
UI开发工具 (Tools/UI/)
ugui_layout：UGUI布局ui_rule_manage：UI规则管理figma_manage：Figma资源管理figma_data_simplifier：Figma数据简化
-
控制台工具 (Tools/Console/)
console_read：读取控制台日志console_write：写入控制台日志
-
代码运行工具 (Tools/RunCode/)
code_runner：运行C#代码python_runner：运行Python脚本
-
编辑器工具 (Tools/)
base_editor：编辑器管理manage_package：包管理gameplay：游戏玩法控制object_delete：对象删除
-
存储管理工具 (Tools/Storage/)
prefers：偏好设置管理（EditorPrefs/PlayerPrefs）source_location：资源定位（文件浏览器、项目定位）
-
网络工具 (Tools/)
request_http：HTTP请求
[ToolName("tool_name", "工具描述")]
public class ToolClass : StateMethodBase
{
protected override MethodKey[] CreateKeys()
{
return new[]
{
new MethodKey("param1", "参数描述", false),
new MethodKey("param2", "参数描述", true)
};
}
protected override StateTree CreateStateTree()
{
return StateTreeBuilder
.Create()
.Key("action")
.Leaf("action1", HandleAction1)
.Leaf("action2", HandleAction2)
.Build();
}
}- Unity 2020.3+ (推荐 2022.3.61f1c1)
- 支持MCP协议的AI客户端 (Cursor/Claude/Trae)
- Windows/macOS/Linux (跨平台支持)
# Unity Package
# 将unity-package导入Unity项目
# 无需额外的Python依赖在AI客户端的MCP配置文件中添加： Mcp客户端口配置
{
"mcpServers": {
"unity3d-mcp": {
"url": "http://localhost:8000"
}
}
}Cursor配置 (~/.cursor/mcp.json)：
Claude配置 (~/AppData/Roaming/Claude/claude_desktop_config.json)：
VS配置 (~/.vs/mcp.json)：
Trae配置 (~/.trae/mcp.json)：
#### Unity编辑器配置
在Unity编辑器中，可以通过以下窗口进行MCP配置和调试：
**1. MCP设置窗口** (`Edit → Project Settings → MCP`)
*图：MCP设置窗口 - 配置MCP连接开关、查看已注册的工具列表、管理工具分类等*
MCP设置窗口提供以下功能：
- **连接开关**：启用/禁用MCP服务器连接
- **工具列表**：查看所有已注册的MCP工具及其分类
- **端口配置**：配置HTTP监听端口（默认8000，可自定义）
- **日志级别**：设置调试日志的详细程度
- **UI设置**：配置UI类型（UGUI、UIToolkit等）和构建流程
- **Figma设置**：配置Figma访问令牌和下载选项
**2. MCP调试窗口** (`Window → MCP → Debug Window`)
*图：MCP调试窗口 - 记录和查看所有MCP调用历史，支持重新执行历史命令*
MCP调试窗口提供以下功能：
- **调用记录**：实时记录所有MCP工具调用及其参数
- **执行结果**：显示每次调用的成功/失败状态和返回数据
- **时间戳**：记录每次调用的准确时间
- **重新触发**：点击历史记录可以重新执行相同的命令
- **过滤搜索**：按工具名称、状态、时间等条件过滤记录
- **导出日志**：将调用记录导出为JSON格式，便于分析和调试
通过这两个窗口，开发者可以：
- 快速配置和管理MCP连接
- 实时监控AI与Unity的交互过程
- 调试和重现问题
- 学习和理解MCP工具的使用方式
### 3. 启动流程
#### 1. 启动Unity编辑器
```bash
# 打开Unity项目
# Unity Package会自动启动内置MCP服务器
在AI客户端中测试连接：
请帮我创建一个Cube对象
# 通过AI客户端发送指令
"创建一个名为Player的Cube对象"# 批量创建多个对象
"创建5个Enemy对象，位置分别为(0,0,0), (1,0,0), (2,0,0), (3,0,0), (4,0,0)"# 下载并应用图片
"下载一张随机图片并应用到Image组件"- 在
unity-package/Editor/Tools/目录创建新工具文件 - 继承
StateMethodBase或IToolMethod接口 - 使用
ToolNameAttribute标记工具名称 - Unity会自动发现和注册新工具
// 使用batch_call提高性能
{
"func": "batch_call",
"args": [
{"func": "hierarchy_create", "args": {...}},
{"func": "edit_gameobject", "args": {...}},
{"func": "edit_component", "args": {...}}
]
}通过 python_runner 集成AI图像生成库，自动创建游戏素材：
# Python脚本示例：AI生成游戏纹理
"""
用途：使用Stable Diffusion批量生成游戏纹理
提示词：帮我生成10张fantasy风格的地面纹理
"""
from diffusers import StableDiffusionPipeline
import torch
def generate_textures(prompt, count=10, save_path="Assets/Textures/Generated"):
# 加载模型
pipe = StableDiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1")
pipe = pipe.to("cuda")
# 批量生成
for i in range(count):
image = pipe(f"{prompt}, texture, seamless, 4k, #{i}").images[0]
image.save(f"{save_path}/texture_{i:03d}.png")
return f"生成了{count}张纹理到{save_path}"
# 然后通过code_runner自动应用到Material
"""
C#代码：自动创建Material并应用生成的纹理
"""
string[] texturePaths = Directory.GetFiles("Assets/Textures/Generated", "*.png");
foreach(var path in texturePaths)
{
AssetDatabase.ImportAsset(path);
Texture2D texture = AssetDatabase.LoadAssetAtPath<Texture2D>(path);
Material mat = new Material(Shader.Find("Standard"));
mat.mainTexture = texture;
AssetDatabase.CreateAsset(mat, path.Replace(".png", ".mat"));
}
AssetDatabase.Refresh();应用价值：
- 快速原型制作，无需等待美术资源
- 根据游戏风格批量生成一致性素材
- 实验不同艺术风格，提高创意迭代速度
通过 python_runner 从开源资源站批量下载并整理资源：
# Python脚本示例：批量爬取Poly Haven资源
"""
用途：从Poly Haven批量下载高质量PBR材质
提示词：帮我下载所有metal类别的PBR材质到项目中
"""
import requests
import os
from concurrent.futures import ThreadPoolExecutor
def download_polyhaven_assets(category, asset_type="textures", resolution="2k"):
# 获取资源列表
api_url = f"https://api.polyhaven.com/assets?t={asset_type}&c={category}"
assets = requests.get(api_url).json()
save_dir = f"Assets/Materials/{category}"
os.makedirs(save_dir, exist_ok=True)
def download_asset(asset_id):
# 获取下载链接
files_url = f"https://api.polyhaven.com/files/{asset_id}"
files = requests.get(files_url).json()
# 下载PBR贴图（Diffuse, Normal, Roughness等）
for map_type in ["Diffuse", "Normal", "Rough", "Displacement"]:
if map_type in files[resolution]:
url = files[resolution][map_type]["url"]
filename = f"{save_dir}/{asset_id}_{map_type}.jpg"
response = requests.get(url)
with open(filename, 'wb') as f:
f.write(response.content)
return asset_id
# 并发下载
with ThreadPoolExecutor(max_workers=5) as executor:
results = list(executor.map(download_asset, assets.keys()))
return f"下载了{len(results)}个{category}材质到{save_dir}"
# 配合code_runner自动创建PBR材质
"""
C#代码：根据下载的贴图自动创建PBR Material
"""
string materialDir = "Assets/Materials/metal";
var assetGroups = Directory.GetFiles(materialDir, "*_Diffuse.jpg")
.Select(path => Path.GetFileNameWithoutExtension(path).Replace("_Diffuse", ""));
foreach(var assetName in assetGroups)
{
Material mat = new Material(Shader.Find("Standard"));
// 设置PBR贴图
mat.mainTexture = LoadTexture($"{materialDir}/{assetName}_Diffuse.jpg");
mat.SetTexture("_BumpMap", LoadTexture($"{materialDir}/{assetName}_Normal.jpg"));
mat.SetTexture("_MetallicGlossMap", LoadTexture($"{materialDir}/{assetName}_Rough.jpg"));
AssetDatabase.CreateAsset(mat, $"{materialDir}/{assetName}.mat");
}应用价值：
- 快速充实资源库，节省采购成本
- 自动化资源导入和配置流程
- 支持定制化资源筛选和分类
通过 python_runner 分析Unity项目，生成可视化架构图：
# Python脚本示例：生成项目架构图
"""
用途：分析Unity项目结构，生成交互式架构图
提示词：帮我生成当前Unity项目的架构图，包括脚本依赖关系
"""
import os
import re
from graphviz import Digraph
import json
def generate_project_architecture(project_path="Assets/Scripts"):
# 解析C#脚本，提取类和依赖关系
classes = {}
dependencies = []
for root, dirs, files in os.walk(project_path):
for file in files:
if file.endswith('.cs'):
filepath = os.path.join(root, file)
with open(filepath, 'r', encoding='utf-8') as f:
content = f.read()
# 提取类名
class_match = re.search(r'class\s+(\w+)', content)
if class_match:
class_name = class_match.group(1)
classes[class_name] = {
'file': filepath,
'namespace': re.search(r'namespace\s+([\w.]+)', content),
'inherits': re.search(r':\s*(\w+)', content)
}
# 提取依赖
using_matches = re.findall(r'using\s+([\w.]+);', content)
for using in using_matches:
if using in classes:
dependencies.append((class_name, using))
# 生成GraphViz图
dot = Digraph(comment='Unity Project Architecture')
dot.attr(rankdir='TB', size='20,20')
# 按命名空间分组
namespaces = {}
for class_name, info in classes.items():
ns = info['namespace'].group(1) if info['namespace'] else 'Global'
if ns not in namespaces:
namespaces[ns] = []
namespaces[ns].append(class_name)
# 添加节点和子图
for ns, class_list in namespaces.items():
with dot.subgraph(name=f'cluster_{ns}') as c:
c.attr(label=ns, style='filled', color='lightgrey')
for class_name in class_list:
c.node(class_name, shape='box')
# 添加依赖边
for src, dst in dependencies:
dot.edge(src, dst)
# 保存图
output_path = 'docs/unity_architecture'
dot.render(output_path, format='png', cleanup=True)
# 生成JSON报告
report = {
'total_classes': len(classes),
'namespaces': {ns: len(cls) for ns, cls in namespaces.items()},
'dependencies_count': len(dependencies)
}
with open(f'{output_path}.json', 'w') as f:
json.dump(report, f, indent=2)
return f"架构图已生成: {output_path}.png"应用价值：
- 快速了解项目结构，新成员快速上手
- 识别循环依赖和架构问题
- 文档自动化，保持与代码同步
通过 code_runner 分析场景性能瓶颈：
// C#代码：场景性能分析工具
using System.Linq;
using UnityEngine;
using UnityEngine.SceneManagement;
using UnityEditor;
public class PerformanceAnalyzer
{
public static string AnalyzeCurrentScene()
{
var report = new System.Text.StringBuilder();
report.AppendLine("=== 场景性能分析报告 ===\n");
// 统计GameObject数量
var allObjects = Object.FindObjectsOfType<GameObject>();
report.AppendLine($"总GameObject数量: {allObjects.Length}");
// 检查Draw Call问题
var renderers = Object.FindObjectsOfType<Renderer>();
var materials = renderers.SelectMany(r => r.sharedMaterials).Distinct().ToList();
report.AppendLine($"Renderer数量: {renderers.Length}");
report.AppendLine($"不同材质数量: {materials.Count}");
// 检查大型Mesh
var meshFilters = Object.FindObjectsOfType<MeshFilter>();
var largeMeshes = meshFilters
.Where(mf => mf.sharedMesh != null && mf.sharedMesh.vertexCount > 10000)
.Select(mf => new { mf.gameObject.name, mf.sharedMesh.vertexCount })
.OrderByDescending(m => m.vertexCount)
.ToList();
if (largeMeshes.Any())
{
report.AppendLine("\n⚠️ 高多边形模型:");
foreach (var mesh in largeMeshes)
report.AppendLine($" - {mesh.name}: {mesh.vertexCount:N0} 顶点");
}
// 检查缺失脚本
var missingScripts = allObjects
.Where(go => go.GetComponents<Component>().Any(c => c == null))
.ToList();
if (missingScripts.Any())
{
report.AppendLine($"\n⚠️ 发现{missingScripts.Count}个对象包含缺失脚本");
}
// 检查灯光设置
var lights = Object.FindObjectsOfType<Light>();
var realtimeLights = lights.Where(l => l.type != LightType.Directional && l.lightmapBakeType == LightmapBakeType.Realtime).ToList();
if (realtimeLights.Count > 4)
{
report.AppendLine($"\n⚠️ 实时光源过多({realtimeLights.Count}个)，建议烘焙");
}
// 优化建议
report.AppendLine("\n=== 优化建议 ===");
if (materials.Count > 50)
report.AppendLine("• 考虑合并材质球以减少Draw Call");
if (largeMeshes.Count > 10)
report.AppendLine("• 对高多边形模型启用LOD系统");
if (realtimeLights.Count > 4)
report.AppendLine("• 将静态光源改为Baked模式");
return report.ToString();
}
}
// 调用示例
Debug.Log(PerformanceAnalyzer.AnalyzeCurrentScene());应用价值：
- 自动发现性能瓶颈
- 提供可执行的优化建议
- 定期性能审计，防止性能退化
通过 python_runner 生成测试用游戏数据：
# Python脚本示例：生成游戏测试数据
"""
用途：批量生成游戏配置数据，用于压力测试
提示词：帮我生成1000个随机的敌人配置数据
"""
import random
import json
import faker
fake = faker.Faker('zh_CN')
def generate_game_data(data_type, count=1000):
if data_type == "enemies":
enemies = []
for i in range(count):
enemy = {
"id": f"enemy_{i:04d}",
"name": fake.name(),
"level": random.randint(1, 100),
"health": random.randint(100, 10000),
"attack": random.randint(10, 500),
"defense": random.randint(5, 300),
"speed": round(random.uniform(1.0, 10.0), 2),
"skills": random.sample([
"火球术", "冰冻", "闪电链", "治疗", "护盾",
"狂暴", "隐身", "召唤", "毒雾", "眩晕"
], k=random.randint(2, 5)),
"drop_items": [
{"item_id": f"item_{random.randint(1,100)}",
"drop_rate": round(random.uniform(0.01, 0.5), 3)}
for _ in range(random.randint(1, 5))
]
}
enemies.append(enemy)
# 保存为JSON
output_path = "Assets/Resources/Data/Enemies.json"
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with open(output_path, 'w', encoding='utf-8') as f:
json.dump(enemies, f, ensure_ascii=False, indent=2)
return f"生成了{count}个敌人配置到{output_path}"
elif data_type == "items":
# 类似的物品数据生成...
pass
elif data_type == "quests":
# 任务数据生成...
pass
# 然后用code_runner加载并验证数据
"""
C#代码：验证生成的游戏数据
"""
string json = File.ReadAllText("Assets/Resources/Data/Enemies.json");
var enemies = JsonUtility.FromJson<EnemyData[]>(json);
Debug.Log($"成功加载{enemies.Length}个敌人配置");
Debug.Log($"平均等级: {enemies.Average(e => e.level):F1}");
Debug.Log($"最强敌人: {enemies.OrderByDescending(e => e.attack).First().name}");应用价值：
- 快速生成大量测试数据
- 压力测试和性能测试
- 验证系统承载能力
通过 python_runner 集成翻译API，批量翻译游戏文本：
# Python脚本示例：批量翻译游戏文本
"""
用途：使用AI批量翻译游戏本地化文本
提示词：把所有UI文本翻译成英文、日文、韩文
"""
from openai import OpenAI
import json
def batch_translate_localization(source_file, target_langs=["en", "ja", "ko"]):
client = OpenAI()
# 读取源语言文本
with open(source_file, 'r', encoding='utf-8') as f:
source_texts = json.load(f)
translations = {lang: {} for lang in target_langs}
# 批量翻译
for key, text in source_texts.items():
for lang in target_langs:
prompt = f"Translate this game UI text to {lang}, keep game terminology: {text}"
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": prompt}]
)
translations[lang][key] = response.choices[0].message.content
# 保存翻译结果
for lang, texts in translations.items():
output_path = f"Assets/Localization/{lang}/ui_texts.json"
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with open(output_path, 'w', encoding='utf-8') as f:
json.dump(texts, f, ensure_ascii=False, indent=2)
return f"翻译完成，生成了{len(target_langs)}个语言版本"应用价值：
- 快速实现多语言支持
- 保持术语一致性
- 降低本地化成本
通过这些扩展场景，python_runner 和 code_runner 成为强大的自动化工具，覆盖从资源生成、数据采集、性能分析到质量保证的完整开发流程。
创新描述：设计了FacadeTools + MethodTools的双层架构
- FacadeTools：
async_call和batch_call两个门面工具 - MethodTools：32+专业功能方法，仅通过门面工具调用
技术优势：
- 统一的调用接口，简化AI客户端使用
- 批量操作支持，提高执行效率
- 参数验证和错误处理集中化
创新描述：基于状态模式的路由系统
StateTreeBuilder
.Create()
.Key("action")
.Leaf("create", HandleCreate)
.Leaf("edit", HandleEdit)
.Leaf("delete", HandleDelete)
.Build();技术优势：
- 灵活的参数路由和验证
- 支持可选参数和默认值
- 统一的错误处理机制
创新描述：基于EditorApplication.update的消息队列机制
- 可自定义端口配置（默认8000）
- 主线程安全执行保障
- 自动注册/注销update回调
技术优势：
- 确保Unity API在主线程执行
- 即使Unity失去焦点也能处理请求
- 智能的资源管理和清理
创新描述：支持Unity协程的异步操作
IEnumerator DownloadFileAsync(string url, string savePath, ...)
{
// 异步下载逻辑
yield return null;
}技术优势：
- 不阻塞主线程
- 支持长时间运行的操作
- 提供进度回调
创新描述：自动识别文件类型，优化响应数据
- 自动检测图片、视频、音频等文件类型
- 大型内容不返回实际数据，只返回元数据
- 提供文件路径和基本信息
技术优势：
- 减少内存使用
- 提高网络传输效率
- 保持响应格式一致性
- HTTP协议：标准化、易于调试
- JSON-RPC 2.0：标准化协议，完整的错误处理
- 消息队列：异步处理，不阻塞主线程
- 批量操作：支持批量调用，提高效率
- 可配置端口：支持自定义端口（默认8000）
- 主线程安全：确保Unity API正确执行
- 错误处理：完善的异常处理机制
- 超时控制：防止长时间阻塞
- 模块化架构：工具独立，易于扩展
- 反射调用：动态方法调用
- 插件化：支持自定义工具开发
- 配置化：灵活的参数配置
- 自然语言：通过AI助手自然交互
- 实时反馈：即时执行结果反馈
- 调试支持：详细的日志和错误信息
- 文档完善：完整的API文档和示例
单次函数调用工具
{
"func": "async_call",
"args": {
"func": "hierarchy_create",
"args": {
"name": "Player",
"primitive_type": "Cube",
"source": "primitive"
}
}
}批量函数调用工具
{
"func": "batch_call",
"args": [
{
"func": "hierarchy_create",
"args": {"name": "Player", "primitive_type": "Cube"}
},
{
"func": "edit_gameobject",
"args": {"path": "Player", "position": [0, 1, 0]}
}
]
}hierarchy_create：创建GameObjecthierarchy_search：搜索GameObjecthierarchy_apply：应用预制体
edit_gameobject：编辑GameObject属性edit_component：编辑组件属性edit_material：编辑材质edit_texture：编辑纹理
project_search：搜索项目资源project_operate：项目操作
request_http：HTTP请求figma_manage：Figma资源管理
{
"success": true,
"message": "操作成功",
"data": {
"result": "具体结果数据"
}
}{
"success": false,
"message": "错误描述",
"error": "详细错误信息"
}可能原因：
- Unity编辑器未启动
- 端口被占用
- 防火墙阻止连接
解决方案：
- 确认Unity编辑器已启动
- 检查端口8100-8110是否可用
- 检查防火墙设置
- 查看Unity控制台错误信息
可能原因：
- 网络不稳定
- Unity编辑器卡顿
- 超时设置过短
解决方案：
- 检查网络连接
- 优化Unity项目性能
- 调整超时设置
可能原因：
- 参数格式错误
- 目标对象不存在
- 权限不足
解决方案：
- 检查参数格式和类型
- 确认目标对象存在
- 检查Unity编辑器权限
可能原因：
- 某些操作依赖其他操作
- 资源冲突
- 内存不足
解决方案：
- 调整操作顺序
- 检查资源冲突
- 分批执行操作
可能原因：
- 网络延迟
- Unity编辑器性能
- 操作复杂度高
解决方案：
- 优化网络环境
- 关闭不必要的Unity功能
- 简化操作逻辑
可能原因：
- 大量对象创建
- 资源未释放
- 协程泄漏
解决方案：
- 及时销毁不需要的对象
- 释放未使用的资源
- 检查协程生命周期
# 在config.py中设置
log_level: str = "DEBUG"// 在Unity中启用详细日志
McpLogger.EnableLog = true;使用Wireshark等工具分析TCP通信数据
Unity3d MCP系统是一个创新的AI-Unity集成解决方案，通过内置MCP服务器实现了AI助手与Unity编辑器的无缝连接。系统采用双层调用架构、消息队列执行引擎、主线程安全机制等创新技术，提供了32+专业工具，覆盖Unity开发全流程。
- AI驱动：通过自然语言控制Unity编辑器
- 功能丰富：32+专业工具，覆盖开发全流程
- 高性能：基于HTTP的高效通信，内置消息队列
- 可扩展：模块化设计，易于扩展
- 易用性：支持主流AI客户端，无需修改工作流
- 零配置：Unity内置MCP服务器，无需外部依赖
- AI辅助游戏开发
- 自动化资源管理
- 批量操作优化
- 开发流程自动化
- 教育和培训
- 更多Unity工具支持
- 可视化工具开发
- 性能优化和监控
- 多平台兼容性
- 增强的调试和监控功能
- Runtime精简：将状态树和协程运行器移至Editor，优化运行时性能
- 模块化重组：新增Selector、GUI、Provider等专业模块，提升代码组织性
- 工具分类优化：按功能领域划分工具目录，提高可维护性
- 基类体系完善：引入DualStateMethodBase、IToolMethod等，增强扩展性
- 内置MCP服务器：移除Python依赖，Unity内置完整MCP协议支持
- 消息队列系统：基于EditorApplication.update的主线程安全执行机制
通过Unity3d MCP系统，开发者可以享受AI驱动的Unity开发体验，提高开发效率，降低学习成本，实现更智能的游戏开发工作流。
文档版本：v2.0
最后更新：2025年09月
维护团队：Unity3d MCP Development Team