Content
# Unity3d MCP System Documentation
## Contents
1. [System Overview](#系统概述)
2. [Design Architecture](#设计架构)
3. [Source Code Analysis](#源码解析)
4. [Usage](#使用方法)
5. [Innovation Points](#创新点)
6. [Technical Features](#技术特性)
7. [API Reference](#api参考)
8. [Troubleshooting](#故障排除)
---
## System Overview
*Unity3d MCP - A bridge connecting AI and Unity, enabling intelligent game development*
Unity3d MCP (Model Context Protocol) is an innovative AI-Unity integration system that seamlessly connects AI assistants (such as Cursor, Claude, Trae) with the Unity editor through a built-in MCP server, enabling AI-driven Unity development workflows.
### Core Value
- **AI-Driven Development**: Control the Unity editor through natural language commands
- **Seamless Integration**: Supports mainstream AI clients without modifying existing workflows
- **Rich Functionality**: Provides 32+ professional tools covering the entire Unity development process
- **High Performance**: Efficient HTTP-based communication mechanism
- **Extensible**: Modular design, easy to add new features
- **Zero Configuration**: Unity built-in MCP server, no external dependencies required
### System Components
- **Built-in MCP Server** (C#): MCP protocol server built into the Unity editor
- **Unity Package** (C#): Complete Unity editor plugin
- **Tool Ecosystem**: 32+ professional Unity development tools
- **Communication Protocol**: HTTP-based JSON-RPC 2.0 communication
---
## Design Architecture
### Overall Architecture
The system adopts a layered architecture design, divided into the following layers from top to bottom:
1. **AI Client Layer**: AI assistants such as Cursor, Claude, and Trae
2. **MCP Protocol Layer**: Unity built-in MCP server
3. **Communication Layer**: HTTP (customizable port, default 8000) + JSON-RPC 2.0
4. **Unity Editor Layer**: Unity Editor + Unity API
5. **Tool Layer**: 40+ professional tools + message queue execution engine
#### System Architecture Diagram
*Figure 1: Overall architecture diagram of the Unity3d MCP system, showing the complete data flow and component relationships from the AI client to the Unity editor*
#### Data Flow Diagram
*Figure 2: Unity3d MCP data flow diagram, detailing the complete data flow process from AI instructions to Unity execution*
### Core Design Principles
#### 1. Two-Layer Call Architecture
```
AI客户端 → FacadeTools → MethodTools → Unity API
```
- **FacadeTools**: `async_call` and `batch_call` two facade tools
- **MethodTools**: 40+ professional function methods, only called through FacadeTools
#### 2. State Tree Execution Engine
- State-based routing system
- Supports parameter validation and type conversion
- Provides a unified error handling mechanism
#### 3. Intelligent Connection Management
- Customizable port configuration (default 8000)
- Message queue processing mechanism
- Main thread safe execution guarantee
---
## Source Code Analysis
### 1. Unity Built-in MCP Server Architecture (C#)
#### Core File Structure
```
unity-package/Editor/Connect/
├── McpService.cs # Core of the built-in MCP server
├── McpServiceStatusWindow.cs # Service status monitoring window
└── McpServiceGUI.cs # Service management interface
```
#### Key Component Analysis
**1. Built-in MCP Server (McpService.cs)**
```csharp
// HTTP listener management
public static void StartService()
{
// Create HttpListener
// Configure customizable port
// Start message queue processing
}
// MCP protocol processing
private async Task<string> ProcessMcpRequest(string requestBody)
{
// JSON-RPC 2.0 protocol parsing
// Tool call routing
// Response formatting
}
```
**2. Message Queue System**
```csharp
// Main thread safe execution
private void EnqueueTask(Action task)
{
// Add task to the queue
// Register EditorApplication.update callback
// Ensure Unity API is executed on the main thread
}
private void ProcessMessageQueue()
{
// Process tasks in the queue
// Automatically register/unregister update callback
// Thread-safe task execution
}
```
**3. Tool Discovery System**
```csharp
private void DiscoverTools()
{
// Reflection discovers IToolMethod implementations
// Automatically register async_call and batch_call
// Build tool information and input patterns
}
```
### 2. Unity Tool Ecosystem Architecture (C#)
#### Core File Structure
```
unity-package/
├── Runtime/ # Runtime core (simplified)
│ └── StateTreeContext.cs # Execution context
├── Editor/ # Editor extension (complete implementation)
│ ├── Connection/ # Connection management
│ │ └── McpService.cs # TCP connection core
│ ├── Executer/ # Executor (core execution layer)
│ │ ├── SingleCall.cs # Single call
│ │ ├── BatchCall.cs # Batch call
│ │ ├── ToolsCall.cs # Tool call
│ │ ├── CoroutineRunner.cs # Coroutine runner
│ │ ├── McpTool.cs # MCP tool base class
│ │ ├── StateMethodBase.cs # State method base class
│ │ ├── DualStateMethodBase.cs # Dual state method base class
│ │ ├── IToolMethod.cs # Tool method interface
│ │ ├── MethodKey.cs # Method key definition
│ │ └── ToolNameAttribute.cs # Tool name attribute
│ ├── StateTree/ # State tree engine
│ │ ├── StateTree.cs # State tree core
│ │ ├── StateTreeBuilder.cs # State tree builder
│ │ └── StateTreeContext.cs # Execution context
│ ├── Selector/ # Selector system
│ │ ├── HierarchySelector.cs # Hierarchy selector
│ │ ├── ProjectSelector.cs # Project selector
│ │ ├── ObjectSelector.cs # Object selector
│ │ └── IObjectSelector.cs # Selector interface
│ ├── Model/ # Data model
│ │ ├── Command.cs # Command model
│ │ ├── Response.cs # Response model
│ │ ├── McpSettings.cs # MCP settings
│ │ ├── McpExecuteRecordObject.cs # Execution record
│ │ └── UIDefineRuleObject.cs # UI rule definition
│ ├── GUI/ # Editor GUI
│ │ ├── McpServiceGUI.cs # Connection GUI
│ │ ├── McpDebugWindow.cs # Debug window
│ │ ├── UIDefineRuleObjectDrawer.cs # UI rule drawer
│ │ └── UIDefineRuleObjectEditor.cs # UI rule editor
│ ├── Provider/ # Settings provider
│ │ ├── McpSettingsProvider.cs # MCP settings provider
│ │ ├── McpUISettingsProvider.cs # UI settings provider
│ │ └── FigmaSettingsProvider.cs # Figma settings provider
│ ├── Tools/ # Tool implementation
│ │ ├── Hierarchy/ # Hierarchy management
│ │ │ ├── HierarchyCreate.cs
│ │ │ ├── HierarchySearch.cs
│ │ │ └── HierarchyApply.cs
│ │ ├── Projet/ # Project management
│ │ │ ├── ProjectSearch.cs
│ │ │ └── ProjectOperate.cs
│ │ ├── ResEdit/ # Resource editing
│ │ │ ├── EditGameObject.cs
│ │ │ ├── EditComponent.cs
│ │ │ ├── EditMaterial.cs
│ │ │ └── ... (more editing tools)
│ │ ├── Console/ # Console tools
│ │ │ ├── ConsoleRead.cs
│ │ │ └── ConsoleWrite.cs
│ │ ├── RunCode/ # Code running
│ │ │ ├── CodeRunner.cs
│ │ │ └── PythonRunner.cs
│ │ ├── UI/ # UI tools
│ │ │ ├── UGUILayout.cs
│ │ │ ├── UIRuleManage.cs
│ │ │ ├── FigmaManage.cs
│ │ │ └── FigmaDataSimplifier.cs
│ │ ├── GameWindow/ # Game window
│ │ ├── Setting/ # Setting tools
│ │ ├── GamePlay.cs # Gameplay
│ │ ├── BaseEditor.cs # Editor management
│ │ ├── ManagePackage.cs # Package management
│ │ ├── ObjectDelete.cs # Object deletion
│ │ ├── RequestHttp.cs # HTTP request
│ │ └── Storage/ # Storage management
│ │ ├── Prefers.cs # Preferences
│ │ └── SourceLocation.cs # Resource location
│ ├── Utils/ # Utility library
│ │ ├── ConsoleUtils.cs # Console tools
│ │ ├── GameObjectUtils.cs # GameObject tools
│ │ ├── UGUIUtil.cs # UGUI tools
│ │ ├── MenuUtils.cs # Menu tools
│ │ └── CursorChatIntegration.cs # Cursor integration
│ └── UniMcp.Editors.asmdef # Assembly definition
└── package.json # Package configuration
```
#### Key Component Analysis
**1. State Tree Engine (Editor/StateTree/StateTree.cs)**
```csharp
public class StateTree
{
public string key; // Current layer variable
public Dictionary<object, StateTree> select = new(); // Selection branch
public Func<StateTreeContext, object> contextFunc; // Leaf function
public object Run(StateTreeContext ctx)
{
// State tree routing logic
// Parameter validation and type conversion
// Method execution and result processing
}
}
```
- **Location Change**: Moved from Runtime to Editor/StateTree
- **Supporting Tools**: Added StateTreeBuilder to simplify the state tree construction process
**2. HTTP Server Management (Editor/Connect/McpService.cs)**
```csharp
public partial class McpService
{
private HttpListener listener;
private readonly Queue<Action> messageQueue = new();
public void Start()
{
// Customizable port listening (default 8000)
// HTTP request processing
// Message queue management
}
private async Task<string> ProcessMcpRequest(string requestBody)
{
// JSON-RPC 2.0 parsing
// Tool call routing
// Response generation
}
}
```
**3. Facade Tools (Editor/Executer/AsyncCall.cs / BatchCall.cs)**
```csharp
public class AsyncCall : McpTool
{
public override void HandleCommand(JsonNode cmd, Action<JsonNode> callback)
{
string id = cmd["id"]?.Value;
string type = cmd["type"]?.Value;
// Asynchronous call management
// Result caching and retrieval
HandleAsyncOperation(id, type, cmd, callback);
}
}
```
**4. Coroutine Runner (Editor/Executer/CoroutineRunner.cs)**
```csharp
public class CoroutineRunner : MonoBehaviour
{
// Supports running coroutines in editor mode
// Used for asynchronous operations (such as HTTP requests, file downloads, etc.)
}
```
- **Location Change**: Moved from Runtime to Editor/Executer
- **Feature Enhancement**: Supports coroutine execution in editor mode
**5. Selector System (Editor/Selector/)**
```csharp
// Unified object selection interface
public interface IObjectSelector
{
Object[] SelectObjects(string[] paths);
}
// Hierarchy selector: used to select GameObjects in the scene
public class HierarchySelector : IObjectSelector { }
// Project selector: used to select project resources
public class ProjectSelector : IObjectSelector { }
```
- **New Module**: Provides a unified object selection mechanism
- **Application Scenarios**: Supports flexible object querying and batch operations
**6. Tool Method Base Class (Editor/Executer/)**
- **StateMethodBase**: Single state tree tool base class
- **DualStateMethodBase**: Dual state tree tool base class (supports more complex routing)
- **IToolMethod**: Tool method interface, defines tool standards
- **ToolNameAttribute**: Tool name attribute, used for automatic registration
**7. GUI System (Editor/GUI/)**
- **McpServiceGUI**: Connection status display and control
- **McpDebugWindow**: Debug window, view execution history and logs
- **UI Rule Editor**: Visual UI rule definition tool
### 3. Tool Ecosystem Architecture
#### Tool Classification System
1. **Hierarchy Management Tools** (Tools/Hierarchy/)
- `hierarchy_create`: Create GameObject
- `hierarchy_search`: Search and query GameObject
- `hierarchy_apply`: Apply prefab
2. **Resource Editing Tools** (Tools/ResEdit/)
- `edit_gameobject`: Edit GameObject properties
- `edit_component`: Edit component properties
- `edit_material`: Edit material
- `edit_texture`: Edit texture
- and more editing tools
3. **Project Management Tools** (Tools/Projet/)
- `project_search`: Search project resources
- `project_operate`: Project operation
4. **UI Development Tools** (Tools/UI/)
- `ugui_layout`: UGUI layout
- `ui_rule_manage`: UI rule management
- `figma_manage`: Figma resource management
- `figma_data_simplifier`: Figma data simplification
5. **Console Tools** (Tools/Console/)
- `console_read`: Read console logs
- `console_write`: Write console logs
6. **Code Running Tools** (Tools/RunCode/)
- `code_runner`: Run C# code
- `python_runner`: Run Python script
7. **Editor Tools** (Tools/)
- `base_editor`: Editor management
- `manage_package`: Package management
- `gameplay`: Gameplay control
- `object_delete`: Object deletion
8. **Storage Management Tools** (Tools/Storage/)
- `prefers`: Preference settings management (EditorPrefs/PlayerPrefs)
- `source_location`: Resource location (file browser, project location)
9. **Network Tools** (Tools/)
- `request_http`: HTTP request
#### Tool Implementation Pattern
```csharp
[ToolName("tool_name", "Tool Description")]
public class ToolClass : StateMethodBase
{
protected override MethodKey[] CreateKeys()
{
return new[]
{
new MethodKey("param1", "Parameter Description", false),
new MethodKey("param2", "Parameter Description", true)
};
}
protected override StateTree CreateStateTree()
{
return StateTreeBuilder
.Create()
.Key("action")
.Leaf("action1", HandleAction1)
.Leaf("action2", HandleAction2)
.Build();
}
}
```
---
## Usage
### 1. Environment Preparation
#### System Requirements
- Unity 2020.3+ (Recommended 2022.3.61f1c1)
- AI Client supporting MCP protocol (Cursor/Claude/Trae)
- Windows/macOS/Linux (Cross-platform support)
#### Dependency Installation
```bash
# Unity Package
# Import the unity-package into the Unity project
# No additional Python dependencies required
```
### 2. Configuration Settings
#### MCP Client Configuration
Add the following to the MCP configuration file of the AI client:
**MCP Client Port Configuration**
```json
{
"mcpServers": {
"unity3d-mcp": {
"url": "http://localhost:8000"
}
}
}
```
**Cursor Configuration** (`~/.cursor/mcp.json`):
**Claude Configuration** (`~/AppData/Roaming/Claude/claude_desktop_config.json`):
**VS Configuration** (`~/.vs/mcp.json`):
**Trae Configuration** (`~/.trae/mcp.json`)
#### Unity Editor Configuration
In the Unity editor, MCP configuration and debugging can be done through the following windows:
**1. MCP Settings Window** (`Edit → Project Settings → MCP`)
<img src="docs/mcp_settings.png">
*Figure: MCP Settings Window - Configure MCP connection switch, view registered tool list, manage tool categories, etc.*
The MCP settings window provides the following functions:
- **Connection Switch**: Enable/disable MCP server connection
- **Tool List**: View all registered MCP tools and their categories
- **Port Configuration**: Configure HTTP listening port (default 8000, customizable)
- **Log Level**: Set the detail level of debug logs
- **UI Settings**: Configure UI type (UGUI, UIToolkit, etc.) and build process
- **Figma Settings**: Configure Figma access token and download options
**2. MCP Debug Window** (`Window → MCP → Debug Window`)
<img src="docs/mcp_debug.png">
*Figure: MCP Debug Window - Record and view all MCP call history, support re-executing historical commands*
The MCP debug window provides the following functions:
- **Call Records**: Real-time recording of all MCP tool calls and their parameters
- **Execution Results**: Display the success/failure status and return data of each call
- **Timestamp**: Record the exact time of each call
- **Re-trigger**: Clicking on a historical record can re-execute the same command
- **Filter Search**: Filter records by tool name, status, time, etc.
- **Export Logs**: Export call records to JSON format for easy analysis and debugging
Through these two windows, developers can:
- Quickly configure and manage MCP connections
- Monitor the interaction between AI and Unity in real-time
- Debug and reproduce problems
- Learn and understand how to use MCP tools
### 3. Startup Process
#### 1. Start Unity Editor
```bash
# Open Unity project
# Unity Package will automatically start the built-in MCP server
```
#### 2. Verify Connection
Test the connection in the AI client:
```
Please help me create a Cube object
```
### 4. Basic Usage Examples
#### Create GameObject
```python
# Send command through AI client
"Create a Cube object named Player"
```
#### Batch Operations
```python
# Create multiple objects in batch
"Create 5 Enemy objects, located at (0,0,0), (1,0,0), (2,0,0), (3,0,0), (4,0,0)"
```
#### Resource Management
```python
# Download and apply image
"Download a random image and apply it to the Image component"
```
### 5. Advanced Usage
#### Custom Tool Development
1. Create a new tool file in the `unity-package/Editor/Tools/` directory
2. Inherit the `StateMethodBase` or `IToolMethod` interface
3. Use the `ToolNameAttribute` to mark the tool name
4. Unity will automatically discover and register new tools
#### Batch Operation Optimization
```json
// Use batch_call to improve performance
{
"func": "batch_call",
"args": [
{"func": "hierarchy_create", "args": {...}},
{"func": "edit_gameobject", "args": {...}},
{"func": "edit_component", "args": {...}}
]
}
```
### 6. Extensibility Application Scenarios
#### Scenario 1: AI Image Generation and Automatic Application
Integrate AI image generation library through `python_runner` to automatically create game assets:
```python
# Python script example: AI generates game textures
"""
Purpose: Use Stable Diffusion to generate game textures in batches
Prompt: Help me generate 10 fantasy-style ground textures
"""
from diffusers import StableDiffusionPipeline
import torch
def generate_textures(prompt, count=10, save_path="Assets/Textures/Generated"):
# Load model
pipe = StableDiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1")
pipe = pipe.to("cuda")
# Generate in batches
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"Generated {count} textures to {save_path}"
# Then automatically apply it to Material through code_runner
"""
C# code: Automatically create Material and apply generated textures
"""
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();
```
**Application Value**:
- Rapid prototyping without waiting for art resources
- Generate consistent assets in batches according to the game style
- Experiment with different art styles to improve creative iteration speed
#### Scenario 2: Batch Crawling of Game Resources
Batch download and organize resources from open source resource sites through `python_runner`:
```python
# Python script example: Batch crawl Poly Haven resources
"""
Purpose: Batch download high-quality PBR materials from Poly Haven
Prompt: Help me download all metal category PBR materials to the project
"""
import requests
import os
from concurrent.futures import ThreadPoolExecutor
def download_polyhaven_assets(category, asset_type="textures", resolution="2k"):
# Get resource list
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):
# Get download link
files_url = f"https://api.polyhaven.com/files/{asset_id}"
files = requests.get(files_url).json()
# Download PBR textures (Diffuse, Normal, Roughness, etc.)
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
# Concurrent download
with ThreadPoolExecutor(max_workers=5) as executor:
results = list(executor.map(download_asset, assets.keys()))
return f"Downloaded {len(results)} {category} materials to {save_dir}"
# Automatically create PBR materials in conjunction with code_runner
"""
C# code: Automatically create PBR Material based on downloaded textures
"""
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"));
// Set PBR textures
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");
}
```
**Application Value**:
- Quickly enrich the resource library and save procurement costs
- Automate resource import and configuration process
- Support customized resource filtering and classification
#### Scenario 3: Automatic Generation of Project Architecture Diagram
Analyze the Unity project through `python_runner` to generate a visual architecture diagram:
```python
# Python script example: Generate project architecture diagram
"""
Purpose: Analyze the Unity project structure and generate an interactive architecture diagram
Prompt: Help me generate an architecture diagram of the current Unity project, including script dependencies
"""
import os
import re
from graphviz import Digraph
import json
def generate_project_architecture(project_path="Assets/Scripts"):
# Parse C# scripts, extract classes and dependencies
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()
# Extract class name
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)
}
# Extract dependencies
using_matches = re.findall(r'using\s+([\w.]+);', content)
for using in using_matches:
if using in classes:
dependencies.append((class_name, using))
# Generate GraphViz graph
dot = Digraph(comment='Unity Project Architecture')
dot.attr(rankdir='TB', size='20,20')
# Group by namespace
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)
# Add nodes and subgraphs
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')
# Add dependency edges
for src, dst in dependencies:
dot.edge(src, dst)
# Save graph
output_path = 'docs/unity_architecture'
dot.render(output_path, format='png', cleanup=True)
# Generate JSON report
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"Architecture diagram generated: {output_path}.png"
```
**Application Value**:
- Quickly understand the project structure, new members can get started quickly
- Identify circular dependencies and architectural issues
- Document automation, keep in sync with code
#### Scenario 4: Performance Analysis and Optimization Suggestions
Analyze scene performance bottlenecks through `code_runner`:
```csharp
// C# code: Scene performance analysis tool
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("=== Scene Performance Analysis Report ===\n");
// Count the number of GameObjects
var allObjects = Object.FindObjectsOfType<GameObject>();
report.AppendLine($"Total number of GameObjects: {allObjects.Length}");
// Check Draw Call issues
var renderers = Object.FindObjectsOfType<Renderer>();
var materials = renderers.SelectMany(r => r.sharedMaterials).Distinct().ToList();
report.AppendLine($"Number of Renderers: {renderers.Length}");
report.AppendLine($"Number of different materials: {materials.Count}");
// Check large Meshes
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⚠️ High-polygon models:");
foreach (var mesh in largeMeshes)
report.AppendLine($" - {mesh.name}: {mesh.vertexCount:N0} vertices");
}
// Check for missing scripts
var missingScripts = allObjects
.Where(go => go.GetComponents<Component>().Any(c => c == null))
.ToList();
if (missingScripts.Any())
{
report.AppendLine($"\n⚠️ Found {missingScripts.Count} objects containing missing scripts");
}
// Check lighting settings
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⚠️ Too many real-time lights ({realtimeLights.Count}), baking is recommended");
}
// Optimization suggestions
report.AppendLine("\n=== Optimization Suggestions ===");
if (materials.Count > 50)
report.AppendLine("• Consider merging materials to reduce Draw Calls");
if (largeMeshes.Count > 10)
report.AppendLine("• Enable LOD system for high-polygon models");
if (realtimeLights.Count > 4)
report.AppendLine("• Change static lights to Baked mode");
return report.ToString();
}
}
// Example call
Debug.Log(PerformanceAnalyzer.AnalyzeCurrentScene());
```
**Application Value**:
- Automatically discover performance bottlenecks
- Provide actionable optimization suggestions
- Regular performance audits to prevent performance degradation
#### Scenario 5: Automated Test Data Generation
Generate test game data through `python_runner`:
```python
# Python script example: Generate game test data
"""
Purpose: Batch generate game configuration data for stress testing
Prompt: Help me generate 1000 random enemy configuration data
"""
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)
# Save as 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"Generated {count} enemy configurations to {output_path}"
elif data_type == "items":
# Similar item data generation...
pass
elif data_type == "quests":
# Quest data generation...
pass
# Then load and verify the data with code_runner
"""
C# code: Verify the generated game data
"""
string json = File.ReadAllText("Assets/Resources/Data/Enemies.json");
var enemies = JsonUtility.FromJson<EnemyData[]>(json);
Debug.Log($"Successfully loaded {enemies.Length} enemy configurations");
Debug.Log($"Average level: {enemies.Average(e => e.level):F1}");
Debug.Log($"Strongest enemy: {enemies.OrderByDescending(e => e.attack).First().name}");
```
**Application Value**:
- Quickly generate large amounts of test data
- Stress testing and performance testing
- Verify system carrying capacity
#### Scenario 6: Automated Localization Translation
Integrate translation API through `python_runner` to batch translate game text:
```python
# Python script example: Batch translate game text
"""
Purpose: Use AI to batch translate game localization text
Prompt: Translate all UI text into English, Japanese, and Korean
"""
from openai import OpenAI
import json
def batch_translate_localization(source_file, target_langs=["en", "ja", "ko"]):
client = OpenAI()
# Read source language text
with open(source_file, 'r', encoding='utf-8') as f:
source_texts = json.load(f)
translations = {lang: {} for lang in target_langs}
# Batch translate
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
# Save translation results
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"Translation completed, generated {len(target_langs)} language versions"
```
**Application Value**:
- Quickly implement multi-language support
- Maintain terminology consistency
- Reduce localization costs
---
Through these extended scenarios, `python_runner` and `code_runner` become powerful automation tools, covering the entire development process from resource generation, data collection, performance analysis to quality assurance.
---
## Innovations
### 1. Two-Layer Call Architecture
**Innovation Description**: Designed a two-layer architecture of FacadeTools + MethodTools
- **FacadeTools**: `async_call` and `batch_call` two facade tools
- **MethodTools**: 32+ professional function methods, only called through facade tools
**Technical Advantages**:
- Unified calling interface, simplifying AI client usage
- Batch operation support, improving execution efficiency
- Centralized parameter validation and error handling
### 2. State Tree Execution Engine
**Innovation Description**: Routing system based on state pattern
```csharp
StateTreeBuilder
.Create()
.Key("action")
.Leaf("create", HandleCreate)
.Leaf("edit", HandleEdit)
.Leaf("delete", HandleDelete)
.Build();
```
**Technical Advantages**:
- Flexible parameter routing and validation
- Support for optional parameters and default values
- Unified error handling mechanism
### 3. Message Queue Execution System
**Innovation Description**: Message queue mechanism based on EditorApplication.update
- Customizable port configuration (default 8000)
- Main thread safe execution guarantee
- Automatic registration/deregistration of update callbacks
**Technical Advantages**:
- Ensure Unity API is executed on the main thread
- Handles requests even when Unity loses focus
- Intelligent resource management and cleanup
### 4. Coroutine Support
**Innovation Description**: Supports asynchronous operations of Unity coroutines
```csharp
IEnumerator DownloadFileAsync(string url, string savePath, ...)
{
// Asynchronous download logic
yield return null;
}
```
**Technical Advantages**:
- Does not block the main thread
- Supports long-running operations
- Provides progress callbacks
### 5. Intelligent File Data Processing
**Innovation Description**: Automatically identifies file types, optimizing response data
- Automatically detects file types such as images, videos, and audio
- Large content does not return actual data, only metadata
- Provides file paths and basic information
**Technical Advantages**:
- Reduces memory usage
- Improves network transmission efficiency
- Maintains consistent response format
---
## Technical Features
### 1. High-Performance Communication
- **HTTP Protocol**: Standardized, easy to debug
- **JSON-RPC 2.0**: Standardized protocol, complete error handling
- **Message Queue**: Asynchronous processing, does not block the main thread
- **Batch Operations**: Supports batch calls, improving efficiency
### 2. Reliability Assurance
- **Configurable Port**: Supports custom ports (default 8000)
- **Main Thread Safety**: Ensures correct execution of Unity API
- **Error Handling**: Comprehensive exception handling mechanism
- **Timeout Control**: Prevents long-term blocking
### 3. Extensibility Design
- **Modular Architecture**: Tools are independent and easy to extend
- **Reflection Call**: Dynamic method calling
- **Plug-in**: Supports custom tool development
- **Configuration**: Flexible parameter configuration
### 4. Development Experience
- **Natural Language**: Natural interaction through AI assistant
- **Real-time Feedback**: Instant execution result feedback
- **Debugging Support**: Detailed logs and error information
- **Complete Documentation**: Complete API documentation and examples
---
## API Reference
### 1. Facade Tool API
#### async_call
Single function call tool
```json
{
"func": "async_call",
"args": {
"func": "hierarchy_create",
"args": {
"name": "Player",
"primitive_type": "Cube",
"source": "primitive"
}
}
}
```
#### batch_call
Batch function call tool
```json
{
"func": "batch_call",
"args": [
{
"func": "hierarchy_create",
"args": {"name": "Player", "primitive_type": "Cube"}
},
{
"func": "edit_gameobject",
"args": {"path": "Player", "position": [0, 1, 0]}
}
]
}
```
### 2. Core Tool API
#### Hierarchy Management Tool
- `hierarchy_create`: Create GameObject
- `hierarchy_search`: Search GameObject
- `hierarchy_apply`: Apply Prefab
#### Resource Editing Tool
- `edit_gameobject`: Edit GameObject properties
- `edit_component`: Edit component properties
- `edit_material`: Edit material
- `edit_texture`: Edit texture
#### Project Management Tool
- `project_search`: Search project resources
- `project_operate`: Project operation
#### Network Tool
- `request_http`: HTTP request
- `figma_manage`: Figma resource management
### 3. Response Format
#### Successful Response
```json
{
"success": true,
"message": "Operation successful",
"data": {
"result": "Specific result data"
}
}
```
#### Error Response
```json
{
"success": false,
"message": "Error description",
"error": "Detailed error information"
}
```
---
## Troubleshooting
### 1. Connection Issues
#### Problem: Unable to connect to Unity
**Possible Causes**:
- Unity editor is not started
- Port is occupied
- Firewall blocking connection
**Solutions**:
1. Confirm that the Unity editor is started
2. Check if ports 8100-8110 are available
3. Check firewall settings
4. View Unity console error messages
#### Problem: Connection is frequently disconnected
**Possible Causes**:
- Unstable network
- Unity editor is stuck
- Timeout setting is too short
**Solutions**:
1. Check network connection
2. Optimize Unity project performance
3. Adjust timeout settings
### 2. Tool Execution Issues
#### Problem: Tool call failed
**Possible Causes**:
- Parameter format error
- Target object does not exist
- Insufficient permissions
**Solutions**:
1. Check parameter format and type
2. Confirm that the target object exists
3. Check Unity editor permissions
#### Problem: Batch operations fail
**Possible reasons**:
- Some operations depend on other operations
- Resource conflicts
- Insufficient memory
**Solutions**:
1. Adjust the order of operations
2. Check for resource conflicts
3. Execute operations in batches
### 3. Performance Issues
#### Problem: Slow response speed
**Possible reasons**:
- Network latency
- Unity editor performance
- High operation complexity
**Solutions**:
1. Optimize the network environment
2. Close unnecessary Unity features
3. Simplify operation logic
#### Problem: Excessive memory usage
**Possible reasons**:
- Creation of a large number of objects
- Resources not released
- Coroutine leaks
**Solutions**:
1. Destroy unnecessary objects in a timely manner
2. Release unused resources
3. Check coroutine lifecycle
### 4. Debugging Tips
#### Enable detailed logging
```python
# Set in config.py
log_level: str = "DEBUG"
```
#### Unity Console Debugging
```csharp
// Enable detailed logging in Unity
McpLogger.EnableLog = true;
```
#### Network Packet Capture Analysis
Use tools such as Wireshark to analyze TCP communication data
---
## Summary
Unity3d MCP system is an innovative AI-Unity integration solution that realizes seamless connection between AI assistant and Unity editor through built-in MCP Server. The system adopts innovative technologies such as two-layer call architecture, message queue execution engine, and main thread security mechanism, and provides 32+ professional tools, covering the entire Unity development process.
### Core advantages
1. **AI-driven**: Control Unity editor through natural language
2. **Feature-rich**: 32+ professional tools, covering the entire development process
3. **High performance**: Efficient communication based on HTTP, built-in message queue
4. **Scalable**: Modular design, easy to expand
5. **Ease of use**: Supports mainstream AI clients without modifying the workflow
6. **Zero configuration**: Unity built-in MCP Server, no external dependencies
### Application scenarios
- AI-assisted game development
- Automated resource management
- Batch operation optimization
- Development process automation
- Education and training
### Future development direction
1. More Unity tool support
2. Visual tool development
3. Performance optimization and monitoring
4. Multi-platform compatibility
5. Enhanced debugging and monitoring functions
### Architecture optimization history
- **Runtime Simplification**: Move the state tree and coroutine runner to Editor to optimize runtime performance
- **Modular Reorganization**: Added professional modules such as Selector, GUI, and Provider to improve code organization
- **Tool Classification Optimization**: Divide the tool directory according to functional areas to improve maintainability
- **Base Class System Improvement**: Introduce DualStateMethodBase, IToolMethod, etc. to enhance scalability
- **Built-in MCP Server**: Remove Python dependencies, Unity built-in complete MCP protocol support
- **Message Queue System**: Main thread safe execution mechanism based on EditorApplication.update
Through the Unity3d MCP system, developers can enjoy the AI-driven Unity development experience, improve development efficiency, reduce learning costs, and achieve a more intelligent game development workflow.
---
*Document version: v2.0*
*Last updated: 2025年09月*
*Maintenance team: Unity3d MCP Development Team*
