Unity-MCP skills (#659)
* Initial Upload for Skills * Update unity-mcp-skill/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Refine language in Unity-MCP Operator Guide Updated wording for clarity and consistency in the guide. --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>beta
Shutong Wu
GitHub
parent
74236b6f66
commit
20e822b60f
|
|
@ -0,0 +1,214 @@
|
||||||
|
---
|
||||||
|
name: unity-mcp-orchestrator
|
||||||
|
description: Orchestrate Unity Editor via MCP (Model Context Protocol) tools and resources. Use when working with Unity projects through MCP for Unity - creating/modifying GameObjects, editing scripts, managing scenes, running tests, or any Unity Editor automation. Provides best practices, tool schemas, and workflow patterns for effective Unity-MCP integration.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Unity-MCP Operator Guide
|
||||||
|
|
||||||
|
This skill helps you effectively use the Unity Editor with MCP tools and resources.
|
||||||
|
|
||||||
|
## Quick Start: Resource-First Workflow
|
||||||
|
|
||||||
|
**Always read relevant resources before using tools.** This prevents errors and provides the necessary context.
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Check editor state → mcpforunity://editor/state
|
||||||
|
2. Understand the scene → mcpforunity://scene/gameobject-api
|
||||||
|
3. Find what you need → find_gameobjects or resources
|
||||||
|
4. Take action → tools (manage_gameobject, create_script, script_apply_edits, apply_text_edits, validate_script, delete_script, get_sha, etc.)
|
||||||
|
5. Verify results → read_console, capture_screenshot (in manage_scene), resources
|
||||||
|
```
|
||||||
|
|
||||||
|
## Critical Best Practices
|
||||||
|
|
||||||
|
### 1. After Writing/Editing Scripts: Always Refresh and Check Console
|
||||||
|
|
||||||
|
```python
|
||||||
|
# After create_script or script_apply_edits:
|
||||||
|
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
|
||||||
|
read_console(types=["error"], count=10, include_stacktrace=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why:** Unity must compile scripts before they're usable. Compilation errors block all tool execution.
|
||||||
|
|
||||||
|
### 2. Use `batch_execute` for Multiple Operations
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 10-100x faster than sequential calls
|
||||||
|
batch_execute(
|
||||||
|
commands=[
|
||||||
|
{"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube1", "primitive_type": "Cube"}},
|
||||||
|
{"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube2", "primitive_type": "Cube"}},
|
||||||
|
{"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube3", "primitive_type": "Cube"}}
|
||||||
|
],
|
||||||
|
parallel=True # Read-only operations can run in parallel
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Max 25 commands per batch.** Use `fail_fast=True` for dependent operations.
|
||||||
|
|
||||||
|
### 3. Use `screenshot` in manage_scene to Verify Visual Results
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Via manage_scene
|
||||||
|
manage_scene(action="screenshot") # Returns base64 image
|
||||||
|
|
||||||
|
# After creating/modifying objects, verify visually:
|
||||||
|
# 1. Create objects
|
||||||
|
# 2. capture screenshot
|
||||||
|
# 3. Analyze if result matches intent
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Check Console After Major Changes
|
||||||
|
|
||||||
|
```python
|
||||||
|
read_console(
|
||||||
|
action="get",
|
||||||
|
types=["error", "warning"], # Focus on problems
|
||||||
|
count=10,
|
||||||
|
format="detailed"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Always Check `editor_state` Before Complex Operations
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Read mcpforunity://editor/state to check:
|
||||||
|
# - is_compiling: Wait if true
|
||||||
|
# - is_domain_reload_pending: Wait if true
|
||||||
|
# - ready_for_tools: Only proceed if true
|
||||||
|
# - blocking_reasons: Why tools might fail
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parameter Type Conventions
|
||||||
|
|
||||||
|
### Vectors (position, rotation, scale, color)
|
||||||
|
```python
|
||||||
|
# Both forms accepted:
|
||||||
|
position=[1.0, 2.0, 3.0] # List
|
||||||
|
position="[1.0, 2.0, 3.0]" # JSON string
|
||||||
|
```
|
||||||
|
|
||||||
|
### Booleans
|
||||||
|
```python
|
||||||
|
# Both forms accepted:
|
||||||
|
include_inactive=True # Boolean
|
||||||
|
include_inactive="true" # String
|
||||||
|
```
|
||||||
|
|
||||||
|
### Colors
|
||||||
|
```python
|
||||||
|
# Auto-detected format:
|
||||||
|
color=[255, 0, 0, 255] # 0-255 range
|
||||||
|
color=[1.0, 0.0, 0.0, 1.0] # 0.0-1.0 normalized (auto-converted)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Paths
|
||||||
|
```python
|
||||||
|
# Assets-relative (default):
|
||||||
|
path="Assets/Scripts/MyScript.cs"
|
||||||
|
|
||||||
|
# URI forms:
|
||||||
|
uri="mcpforunity://path/Assets/Scripts/MyScript.cs"
|
||||||
|
uri="file:///full/path/to/file.cs"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Core Tool Categories
|
||||||
|
|
||||||
|
| Category | Key Tools | Use For |
|
||||||
|
|----------|-----------|---------|
|
||||||
|
| **Scene** | `manage_scene`, `find_gameobjects` | Scene operations, finding objects |
|
||||||
|
| **Objects** | `manage_gameobject`, `manage_components` | Creating/modifying GameObjects |
|
||||||
|
| **Scripts** | `create_script`, `script_apply_edits`, `refresh_unity` | C# code management |
|
||||||
|
| **Assets** | `manage_asset`, `manage_prefabs` | Asset operations |
|
||||||
|
| **Editor** | `manage_editor`, `execute_menu_item`, `read_console` | Editor control |
|
||||||
|
| **Testing** | `run_tests`, `get_test_job` | Unity Test Framework |
|
||||||
|
| **Batch** | `batch_execute` | Parallel/bulk operations |
|
||||||
|
|
||||||
|
## Common Workflows
|
||||||
|
|
||||||
|
### Creating a New Script and Using It
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Create the script
|
||||||
|
create_script(
|
||||||
|
path="Assets/Scripts/PlayerController.cs",
|
||||||
|
contents="using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n void Update() { }\n}"
|
||||||
|
)
|
||||||
|
|
||||||
|
# 2. CRITICAL: Refresh and wait for compilation
|
||||||
|
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
|
||||||
|
|
||||||
|
# 3. Check for compilation errors
|
||||||
|
read_console(types=["error"], count=10)
|
||||||
|
|
||||||
|
# 4. Only then attach to GameObject
|
||||||
|
manage_gameobject(action="modify", target="Player", components_to_add=["PlayerController"])
|
||||||
|
```
|
||||||
|
|
||||||
|
### Finding and Modifying GameObjects
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Find by name/tag/component (returns IDs only)
|
||||||
|
result = find_gameobjects(search_term="Enemy", search_method="by_tag", page_size=50)
|
||||||
|
|
||||||
|
# 2. Get full data via resource
|
||||||
|
# mcpforunity://scene/gameobject/{instance_id}
|
||||||
|
|
||||||
|
# 3. Modify using the ID
|
||||||
|
manage_gameobject(action="modify", target=instance_id, position=[10, 0, 0])
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running and Monitoring Tests
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Start test run (async)
|
||||||
|
result = run_tests(mode="EditMode", test_names=["MyTests.TestSomething"])
|
||||||
|
job_id = result["job_id"]
|
||||||
|
|
||||||
|
# 2. Poll for completion
|
||||||
|
result = get_test_job(job_id=job_id, wait_timeout=60, include_failed_tests=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pagination Pattern
|
||||||
|
|
||||||
|
Large queries return paginated results. Always follow `next_cursor`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
cursor = 0
|
||||||
|
all_items = []
|
||||||
|
while True:
|
||||||
|
result = manage_scene(action="get_hierarchy", page_size=50, cursor=cursor)
|
||||||
|
all_items.extend(result["data"]["items"])
|
||||||
|
if not result["data"].get("next_cursor"):
|
||||||
|
break
|
||||||
|
cursor = result["data"]["next_cursor"]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Multi-Instance Workflow
|
||||||
|
|
||||||
|
When multiple Unity Editors are running:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. List instances via resource: mcpforunity://instances
|
||||||
|
# 2. Set active instance
|
||||||
|
set_active_instance(instance="MyProject@abc123")
|
||||||
|
# 3. All subsequent calls route to that instance
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Recovery
|
||||||
|
|
||||||
|
| Symptom | Cause | Solution |
|
||||||
|
|---------|-------|----------|
|
||||||
|
| Tools return "busy" | Compilation in progress | Wait, check `editor_state` |
|
||||||
|
| "stale_file" error | File changed since SHA | Re-fetch SHA with `get_sha`, retry |
|
||||||
|
| Connection lost | Domain reload | Wait ~5s, reconnect |
|
||||||
|
| Commands fail silently | Wrong instance | Check `set_active_instance` |
|
||||||
|
|
||||||
|
## Reference Files
|
||||||
|
|
||||||
|
For detailed schemas and examples:
|
||||||
|
|
||||||
|
- **[tools-reference.md](references/tools-reference.md)**: Complete tool documentation with all parameters
|
||||||
|
- **[resources-reference.md](references/resources-reference.md)**: All available resources and their data
|
||||||
|
- **[workflows.md](references/workflows.md)**: Extended workflow examples and patterns
|
||||||
|
|
@ -0,0 +1,493 @@
|
||||||
|
# Unity-MCP Resources Reference
|
||||||
|
|
||||||
|
Resources provide read-only access to Unity state. Use resources to inspect before using tools to modify.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Editor State Resources](#editor-state-resources)
|
||||||
|
- [Scene & GameObject Resources](#scene--gameobject-resources)
|
||||||
|
- [Prefab Resources](#prefab-resources)
|
||||||
|
- [Project Resources](#project-resources)
|
||||||
|
- [Instance Resources](#instance-resources)
|
||||||
|
- [Test Resources](#test-resources)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## URI Scheme
|
||||||
|
|
||||||
|
All resources use `mcpforunity://` scheme:
|
||||||
|
|
||||||
|
```
|
||||||
|
mcpforunity://{category}/{resource_path}[?query_params]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Categories:** `editor`, `scene`, `prefab`, `project`, `menu-items`, `custom-tools`, `tests`, `instances`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Editor State Resources
|
||||||
|
|
||||||
|
### mcpforunity://editor/state
|
||||||
|
|
||||||
|
**Purpose:** Editor readiness snapshot - check before tool operations.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"unity_version": "2022.3.10f1",
|
||||||
|
"is_compiling": false,
|
||||||
|
"is_domain_reload_pending": false,
|
||||||
|
"play_mode": {
|
||||||
|
"is_playing": false,
|
||||||
|
"is_paused": false
|
||||||
|
},
|
||||||
|
"active_scene": {
|
||||||
|
"path": "Assets/Scenes/Main.unity",
|
||||||
|
"name": "Main"
|
||||||
|
},
|
||||||
|
"ready_for_tools": true,
|
||||||
|
"blocking_reasons": [],
|
||||||
|
"recommended_retry_after_ms": null,
|
||||||
|
"staleness": {
|
||||||
|
"age_ms": 150,
|
||||||
|
"is_stale": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Fields:**
|
||||||
|
- `ready_for_tools`: Only proceed if `true`
|
||||||
|
- `is_compiling`: Wait if `true`
|
||||||
|
- `blocking_reasons`: Array explaining why tools might fail
|
||||||
|
- `recommended_retry_after_ms`: Suggested wait time
|
||||||
|
|
||||||
|
### mcpforunity://editor/selection
|
||||||
|
|
||||||
|
**Purpose:** Currently selected objects.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"activeObject": "Player",
|
||||||
|
"activeGameObject": "Player",
|
||||||
|
"activeInstanceID": 12345,
|
||||||
|
"count": 3,
|
||||||
|
"gameObjects": ["Player", "Enemy", "Wall"],
|
||||||
|
"assetGUIDs": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://editor/active-tool
|
||||||
|
|
||||||
|
**Purpose:** Current editor tool state.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"activeTool": "Move",
|
||||||
|
"isCustom": false,
|
||||||
|
"pivotMode": "Center",
|
||||||
|
"pivotRotation": "Global"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://editor/windows
|
||||||
|
|
||||||
|
**Purpose:** All open editor windows.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"windows": [
|
||||||
|
{
|
||||||
|
"title": "Scene",
|
||||||
|
"typeName": "UnityEditor.SceneView",
|
||||||
|
"isFocused": true,
|
||||||
|
"position": {"x": 0, "y": 0, "width": 800, "height": 600}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://editor/prefab-stage
|
||||||
|
|
||||||
|
**Purpose:** Current prefab editing context.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"isOpen": true,
|
||||||
|
"assetPath": "Assets/Prefabs/Player.prefab",
|
||||||
|
"prefabRootName": "Player",
|
||||||
|
"isDirty": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scene & GameObject Resources
|
||||||
|
|
||||||
|
### mcpforunity://scene/gameobject-api
|
||||||
|
|
||||||
|
**Purpose:** Documentation for GameObject resources (read this first).
|
||||||
|
|
||||||
|
### mcpforunity://scene/gameobject/{instance_id}
|
||||||
|
|
||||||
|
**Purpose:** Basic GameObject data (metadata, no component properties).
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `instance_id` (int): GameObject instance ID from `find_gameobjects`
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"instanceID": 12345,
|
||||||
|
"name": "Player",
|
||||||
|
"tag": "Player",
|
||||||
|
"layer": 8,
|
||||||
|
"layerName": "Player",
|
||||||
|
"active": true,
|
||||||
|
"activeInHierarchy": true,
|
||||||
|
"isStatic": false,
|
||||||
|
"transform": {
|
||||||
|
"position": [0, 1, 0],
|
||||||
|
"rotation": [0, 0, 0],
|
||||||
|
"scale": [1, 1, 1]
|
||||||
|
},
|
||||||
|
"parent": {"instanceID": 0},
|
||||||
|
"children": [{"instanceID": 67890}],
|
||||||
|
"componentTypes": ["Transform", "Rigidbody", "PlayerController"],
|
||||||
|
"path": "/Player"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://scene/gameobject/{instance_id}/components
|
||||||
|
|
||||||
|
**Purpose:** All components with full property serialization (paginated).
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `instance_id` (int): GameObject instance ID
|
||||||
|
- `page_size` (int): Default 25, max 100
|
||||||
|
- `cursor` (int): Pagination cursor
|
||||||
|
- `include_properties` (bool): Default true, set false for just types
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"gameObjectID": 12345,
|
||||||
|
"gameObjectName": "Player",
|
||||||
|
"components": [
|
||||||
|
{
|
||||||
|
"type": "Transform",
|
||||||
|
"properties": {
|
||||||
|
"position": {"x": 0, "y": 1, "z": 0},
|
||||||
|
"rotation": {"x": 0, "y": 0, "z": 0, "w": 1}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "Rigidbody",
|
||||||
|
"properties": {
|
||||||
|
"mass": 1.0,
|
||||||
|
"useGravity": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"cursor": 0,
|
||||||
|
"pageSize": 25,
|
||||||
|
"nextCursor": null,
|
||||||
|
"hasMore": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://scene/gameobject/{instance_id}/component/{component_name}
|
||||||
|
|
||||||
|
**Purpose:** Single component with full properties.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `instance_id` (int): GameObject instance ID
|
||||||
|
- `component_name` (string): e.g., "Rigidbody", "Camera", "Transform"
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"gameObjectID": 12345,
|
||||||
|
"gameObjectName": "Player",
|
||||||
|
"component": {
|
||||||
|
"type": "Rigidbody",
|
||||||
|
"properties": {
|
||||||
|
"mass": 1.0,
|
||||||
|
"drag": 0,
|
||||||
|
"angularDrag": 0.05,
|
||||||
|
"useGravity": true,
|
||||||
|
"isKinematic": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prefab Resources
|
||||||
|
|
||||||
|
### mcpforunity://prefab-api
|
||||||
|
|
||||||
|
**Purpose:** Documentation for prefab resources.
|
||||||
|
|
||||||
|
### mcpforunity://prefab/{encoded_path}
|
||||||
|
|
||||||
|
**Purpose:** Prefab asset information.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `encoded_path` (string): URL-encoded path, e.g., `Assets%2FPrefabs%2FPlayer.prefab`
|
||||||
|
|
||||||
|
**Path Encoding:**
|
||||||
|
```
|
||||||
|
Assets/Prefabs/Player.prefab → Assets%2FPrefabs%2FPlayer.prefab
|
||||||
|
```
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"assetPath": "Assets/Prefabs/Player.prefab",
|
||||||
|
"guid": "abc123...",
|
||||||
|
"prefabType": "Regular",
|
||||||
|
"rootObjectName": "Player",
|
||||||
|
"rootComponentTypes": ["Transform", "PlayerController"],
|
||||||
|
"childCount": 5,
|
||||||
|
"isVariant": false,
|
||||||
|
"parentPrefab": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://prefab/{encoded_path}/hierarchy
|
||||||
|
|
||||||
|
**Purpose:** Full prefab hierarchy with nested prefab info.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"prefabPath": "Assets/Prefabs/Player.prefab",
|
||||||
|
"total": 6,
|
||||||
|
"items": [
|
||||||
|
{
|
||||||
|
"name": "Player",
|
||||||
|
"instanceId": 12345,
|
||||||
|
"path": "/Player",
|
||||||
|
"activeSelf": true,
|
||||||
|
"childCount": 2,
|
||||||
|
"componentTypes": ["Transform", "PlayerController"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Model",
|
||||||
|
"path": "/Player/Model",
|
||||||
|
"isNestedPrefab": true,
|
||||||
|
"nestedPrefabPath": "Assets/Prefabs/PlayerModel.prefab"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Resources
|
||||||
|
|
||||||
|
### mcpforunity://project/info
|
||||||
|
|
||||||
|
**Purpose:** Static project configuration.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"projectRoot": "/Users/dev/MyProject",
|
||||||
|
"projectName": "MyProject",
|
||||||
|
"unityVersion": "2022.3.10f1",
|
||||||
|
"platform": "StandaloneWindows64",
|
||||||
|
"assetsPath": "/Users/dev/MyProject/Assets"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://project/tags
|
||||||
|
|
||||||
|
**Purpose:** All tags defined in TagManager.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
["Untagged", "Respawn", "Finish", "EditorOnly", "MainCamera", "Player", "GameController", "Enemy"]
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://project/layers
|
||||||
|
|
||||||
|
**Purpose:** All layers with indices (0-31).
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"0": "Default",
|
||||||
|
"1": "TransparentFX",
|
||||||
|
"2": "Ignore Raycast",
|
||||||
|
"4": "Water",
|
||||||
|
"5": "UI",
|
||||||
|
"8": "Player",
|
||||||
|
"9": "Enemy"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://menu-items
|
||||||
|
|
||||||
|
**Purpose:** All available Unity menu items.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
"File/New Scene",
|
||||||
|
"File/Open Scene",
|
||||||
|
"File/Save",
|
||||||
|
"Edit/Undo",
|
||||||
|
"Edit/Redo",
|
||||||
|
"GameObject/Create Empty",
|
||||||
|
"GameObject/3D Object/Cube",
|
||||||
|
"Window/General/Console"
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://custom-tools
|
||||||
|
|
||||||
|
**Purpose:** Custom tools available in the active Unity project.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"project_id": "MyProject",
|
||||||
|
"tool_count": 3,
|
||||||
|
"tools": [
|
||||||
|
{
|
||||||
|
"name": "capture_screenshot",
|
||||||
|
"description": "Capture screenshots in Unity",
|
||||||
|
"parameters": [
|
||||||
|
{"name": "filename", "type": "string", "required": true},
|
||||||
|
{"name": "width", "type": "int", "required": false},
|
||||||
|
{"name": "height", "type": "int", "required": false}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Instance Resources
|
||||||
|
|
||||||
|
### mcpforunity://instances
|
||||||
|
|
||||||
|
**Purpose:** All running Unity Editor instances (for multi-instance workflows).
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"transport": "http",
|
||||||
|
"instance_count": 2,
|
||||||
|
"instances": [
|
||||||
|
{
|
||||||
|
"id": "MyProject@abc123",
|
||||||
|
"name": "MyProject",
|
||||||
|
"hash": "abc123",
|
||||||
|
"unity_version": "2022.3.10f1",
|
||||||
|
"connected_at": "2024-01-15T10:30:00Z"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "TestProject@def456",
|
||||||
|
"name": "TestProject",
|
||||||
|
"hash": "def456",
|
||||||
|
"unity_version": "2022.3.10f1",
|
||||||
|
"connected_at": "2024-01-15T11:00:00Z"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"warnings": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Use with:** `set_active_instance(instance="MyProject@abc123")`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Test Resources
|
||||||
|
|
||||||
|
### mcpforunity://tests
|
||||||
|
|
||||||
|
**Purpose:** All tests in the project.
|
||||||
|
|
||||||
|
**Returns:**
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "TestSomething",
|
||||||
|
"full_name": "MyTests.TestSomething",
|
||||||
|
"mode": "EditMode"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "TestOther",
|
||||||
|
"full_name": "MyTests.TestOther",
|
||||||
|
"mode": "PlayMode"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### mcpforunity://tests/{mode}
|
||||||
|
|
||||||
|
**Purpose:** Tests filtered by mode.
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `mode` (string): "EditMode" or "PlayMode"
|
||||||
|
|
||||||
|
**Example:** `mcpforunity://tests/EditMode`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### 1. Check Editor State First
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Before any complex operation:
|
||||||
|
# Read mcpforunity://editor/state
|
||||||
|
# Check ready_for_tools == true
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Use Find Then Read Pattern
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. find_gameobjects to get IDs
|
||||||
|
result = find_gameobjects(search_term="Player")
|
||||||
|
|
||||||
|
# 2. Read resource for full data
|
||||||
|
# mcpforunity://scene/gameobject/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Paginate Large Queries
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Start with include_properties=false for component lists
|
||||||
|
# mcpforunity://scene/gameobject/{id}/components?include_properties=false&page_size=25
|
||||||
|
|
||||||
|
# Then read specific components as needed
|
||||||
|
# mcpforunity://scene/gameobject/{id}/component/Rigidbody
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. URL-Encode Prefab Paths
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Wrong:
|
||||||
|
# mcpforunity://prefab/Assets/Prefabs/Player.prefab
|
||||||
|
|
||||||
|
# Correct:
|
||||||
|
# mcpforunity://prefab/Assets%2FPrefabs%2FPlayer.prefab
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Multi-Instance Awareness
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Always check mcpforunity://instances when:
|
||||||
|
# - First connecting
|
||||||
|
# - Commands fail unexpectedly
|
||||||
|
# - Working with multiple projects
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,606 @@
|
||||||
|
# Unity-MCP Tools Reference
|
||||||
|
|
||||||
|
Complete reference for all MCP tools. Each tool includes parameters, types, and usage examples.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Infrastructure Tools](#infrastructure-tools)
|
||||||
|
- [Scene Tools](#scene-tools)
|
||||||
|
- [GameObject Tools](#gameobject-tools)
|
||||||
|
- [Script Tools](#script-tools)
|
||||||
|
- [Asset Tools](#asset-tools)
|
||||||
|
- [Material & Shader Tools](#material--shader-tools)
|
||||||
|
- [Editor Control Tools](#editor-control-tools)
|
||||||
|
- [Testing Tools](#testing-tools)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Infrastructure Tools
|
||||||
|
|
||||||
|
### batch_execute
|
||||||
|
|
||||||
|
Execute multiple MCP commands in a single batch (10-100x faster).
|
||||||
|
|
||||||
|
```python
|
||||||
|
batch_execute(
|
||||||
|
commands=[ # list[dict], required, max 25
|
||||||
|
{"tool": "tool_name", "params": {...}},
|
||||||
|
...
|
||||||
|
],
|
||||||
|
parallel=False, # bool, optional - run read-only ops in parallel
|
||||||
|
fail_fast=False, # bool, optional - stop on first failure
|
||||||
|
max_parallelism=None # int, optional - max parallel workers
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### set_active_instance
|
||||||
|
|
||||||
|
Route commands to a specific Unity instance (multi-instance workflows).
|
||||||
|
|
||||||
|
```python
|
||||||
|
set_active_instance(
|
||||||
|
instance="ProjectName@abc123" # str, required - Name@hash or hash prefix
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### refresh_unity
|
||||||
|
|
||||||
|
Refresh asset database and trigger script compilation.
|
||||||
|
|
||||||
|
```python
|
||||||
|
refresh_unity(
|
||||||
|
mode="if_dirty", # "if_dirty" | "force"
|
||||||
|
scope="all", # "assets" | "scripts" | "all"
|
||||||
|
compile="none", # "none" | "request"
|
||||||
|
wait_for_ready=True # bool - wait until editor ready
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scene Tools
|
||||||
|
|
||||||
|
### manage_scene
|
||||||
|
|
||||||
|
Scene CRUD operations and hierarchy queries.
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Get hierarchy (paginated)
|
||||||
|
manage_scene(
|
||||||
|
action="get_hierarchy",
|
||||||
|
page_size=50, # int, default 50, max 500
|
||||||
|
cursor=0, # int, pagination cursor
|
||||||
|
parent=None, # str|int, optional - filter by parent
|
||||||
|
include_transform=False # bool - include local transforms
|
||||||
|
)
|
||||||
|
|
||||||
|
# Screenshot
|
||||||
|
manage_scene(action="screenshot") # Returns base64 PNG
|
||||||
|
|
||||||
|
# Other actions
|
||||||
|
manage_scene(action="get_active") # Current scene info
|
||||||
|
manage_scene(action="get_build_settings") # Build settings
|
||||||
|
manage_scene(action="create", name="NewScene", path="Assets/Scenes/")
|
||||||
|
manage_scene(action="load", path="Assets/Scenes/Main.unity")
|
||||||
|
manage_scene(action="save")
|
||||||
|
```
|
||||||
|
|
||||||
|
### find_gameobjects
|
||||||
|
|
||||||
|
Search for GameObjects (returns instance IDs only).
|
||||||
|
|
||||||
|
```python
|
||||||
|
find_gameobjects(
|
||||||
|
search_term="Player", # str, required
|
||||||
|
search_method="by_name", # "by_name"|"by_tag"|"by_layer"|"by_component"|"by_path"|"by_id"
|
||||||
|
include_inactive=False, # bool|str
|
||||||
|
page_size=50, # int, default 50, max 500
|
||||||
|
cursor=0 # int, pagination cursor
|
||||||
|
)
|
||||||
|
# Returns: {"ids": [12345, 67890], "next_cursor": 50, ...}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GameObject Tools
|
||||||
|
|
||||||
|
### manage_gameobject
|
||||||
|
|
||||||
|
Create, modify, delete, duplicate GameObjects.
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Create
|
||||||
|
manage_gameobject(
|
||||||
|
action="create",
|
||||||
|
name="MyCube", # str, required
|
||||||
|
primitive_type="Cube", # "Cube"|"Sphere"|"Capsule"|"Cylinder"|"Plane"|"Quad"
|
||||||
|
position=[0, 1, 0], # list[float] or JSON string "[0,1,0]"
|
||||||
|
rotation=[0, 45, 0], # euler angles
|
||||||
|
scale=[1, 1, 1],
|
||||||
|
components_to_add=["Rigidbody", "BoxCollider"],
|
||||||
|
save_as_prefab=False,
|
||||||
|
prefab_path="Assets/Prefabs/MyCube.prefab"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Modify
|
||||||
|
manage_gameobject(
|
||||||
|
action="modify",
|
||||||
|
target="Player", # name, path, or instance ID
|
||||||
|
search_method="by_name", # how to find target
|
||||||
|
position=[10, 0, 0],
|
||||||
|
rotation=[0, 90, 0],
|
||||||
|
scale=[2, 2, 2],
|
||||||
|
set_active=True,
|
||||||
|
layer="Player",
|
||||||
|
components_to_add=["AudioSource"],
|
||||||
|
components_to_remove=["OldComponent"],
|
||||||
|
component_properties={ # nested dict for property setting
|
||||||
|
"Rigidbody": {
|
||||||
|
"mass": 10.0,
|
||||||
|
"useGravity": True
|
||||||
|
}
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
# Delete
|
||||||
|
manage_gameobject(action="delete", target="OldObject")
|
||||||
|
|
||||||
|
# Duplicate
|
||||||
|
manage_gameobject(
|
||||||
|
action="duplicate",
|
||||||
|
target="Player",
|
||||||
|
new_name="Player2",
|
||||||
|
offset=[5, 0, 0] # position offset from original
|
||||||
|
)
|
||||||
|
|
||||||
|
# Move relative
|
||||||
|
manage_gameobject(
|
||||||
|
action="move_relative",
|
||||||
|
target="Player",
|
||||||
|
reference_object="Enemy", # optional reference
|
||||||
|
direction="left", # "left"|"right"|"up"|"down"|"forward"|"back"
|
||||||
|
distance=5.0,
|
||||||
|
world_space=True
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### manage_components
|
||||||
|
|
||||||
|
Add, remove, or set properties on components.
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Add component
|
||||||
|
manage_components(
|
||||||
|
action="add",
|
||||||
|
target=12345, # instance ID (preferred) or name
|
||||||
|
component_type="Rigidbody",
|
||||||
|
search_method="by_id"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Remove component
|
||||||
|
manage_components(
|
||||||
|
action="remove",
|
||||||
|
target="Player",
|
||||||
|
component_type="OldScript"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Set single property
|
||||||
|
manage_components(
|
||||||
|
action="set_property",
|
||||||
|
target=12345,
|
||||||
|
component_type="Rigidbody",
|
||||||
|
property="mass",
|
||||||
|
value=5.0
|
||||||
|
)
|
||||||
|
|
||||||
|
# Set multiple properties
|
||||||
|
manage_components(
|
||||||
|
action="set_property",
|
||||||
|
target=12345,
|
||||||
|
component_type="Transform",
|
||||||
|
properties={
|
||||||
|
"position": [1, 2, 3],
|
||||||
|
"localScale": [2, 2, 2]
|
||||||
|
}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Script Tools
|
||||||
|
|
||||||
|
### create_script
|
||||||
|
|
||||||
|
Create a new C# script.
|
||||||
|
|
||||||
|
```python
|
||||||
|
create_script(
|
||||||
|
path="Assets/Scripts/MyScript.cs", # str, required
|
||||||
|
contents='''using UnityEngine;
|
||||||
|
|
||||||
|
public class MyScript : MonoBehaviour
|
||||||
|
{
|
||||||
|
void Start() { }
|
||||||
|
void Update() { }
|
||||||
|
}''',
|
||||||
|
script_type="MonoBehaviour", # optional hint
|
||||||
|
namespace="MyGame" # optional namespace
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### script_apply_edits
|
||||||
|
|
||||||
|
Apply structured edits to C# scripts (safer than raw text edits).
|
||||||
|
|
||||||
|
```python
|
||||||
|
script_apply_edits(
|
||||||
|
name="MyScript", # script name (no .cs)
|
||||||
|
path="Assets/Scripts", # folder path
|
||||||
|
edits=[
|
||||||
|
# Replace entire method
|
||||||
|
{
|
||||||
|
"op": "replace_method",
|
||||||
|
"methodName": "Update",
|
||||||
|
"replacement": "void Update() { transform.Rotate(Vector3.up); }"
|
||||||
|
},
|
||||||
|
# Insert new method
|
||||||
|
{
|
||||||
|
"op": "insert_method",
|
||||||
|
"afterMethod": "Start",
|
||||||
|
"code": "void OnEnable() { Debug.Log(\"Enabled\"); }"
|
||||||
|
},
|
||||||
|
# Delete method
|
||||||
|
{
|
||||||
|
"op": "delete_method",
|
||||||
|
"methodName": "OldMethod"
|
||||||
|
},
|
||||||
|
# Anchor-based insert
|
||||||
|
{
|
||||||
|
"op": "anchor_insert",
|
||||||
|
"anchor": "void Start()",
|
||||||
|
"position": "before", # "before" | "after"
|
||||||
|
"text": "// Called before Start\n"
|
||||||
|
},
|
||||||
|
# Regex replace
|
||||||
|
{
|
||||||
|
"op": "regex_replace",
|
||||||
|
"pattern": "Debug\\.Log\\(",
|
||||||
|
"text": "Debug.LogWarning("
|
||||||
|
},
|
||||||
|
# Prepend/append to file
|
||||||
|
{"op": "prepend", "text": "// File header\n"},
|
||||||
|
{"op": "append", "text": "\n// File footer"}
|
||||||
|
]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### apply_text_edits
|
||||||
|
|
||||||
|
Apply precise character-position edits (1-indexed lines/columns).
|
||||||
|
|
||||||
|
```python
|
||||||
|
apply_text_edits(
|
||||||
|
uri="mcpforunity://path/Assets/Scripts/MyScript.cs",
|
||||||
|
edits=[
|
||||||
|
{
|
||||||
|
"startLine": 10,
|
||||||
|
"startCol": 5,
|
||||||
|
"endLine": 10,
|
||||||
|
"endCol": 20,
|
||||||
|
"newText": "replacement text"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
precondition_sha256="abc123...", # optional, prevents stale edits
|
||||||
|
strict=True # optional, stricter validation
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### validate_script
|
||||||
|
|
||||||
|
Check script for syntax/semantic errors.
|
||||||
|
|
||||||
|
```python
|
||||||
|
validate_script(
|
||||||
|
uri="mcpforunity://path/Assets/Scripts/MyScript.cs",
|
||||||
|
level="standard", # "basic" | "standard"
|
||||||
|
include_diagnostics=True # include full error details
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### get_sha
|
||||||
|
|
||||||
|
Get file hash without content (for preconditions).
|
||||||
|
|
||||||
|
```python
|
||||||
|
get_sha(uri="mcpforunity://path/Assets/Scripts/MyScript.cs")
|
||||||
|
# Returns: {"sha256": "...", "lengthBytes": 1234, "lastModifiedUtc": "..."}
|
||||||
|
```
|
||||||
|
|
||||||
|
### delete_script
|
||||||
|
|
||||||
|
Delete a script file.
|
||||||
|
|
||||||
|
```python
|
||||||
|
delete_script(uri="mcpforunity://path/Assets/Scripts/OldScript.cs")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Asset Tools
|
||||||
|
|
||||||
|
### manage_asset
|
||||||
|
|
||||||
|
Asset operations: search, import, create, modify, delete.
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Search assets (paginated)
|
||||||
|
manage_asset(
|
||||||
|
action="search",
|
||||||
|
path="Assets", # search scope
|
||||||
|
search_pattern="*.prefab", # glob or "t:MonoScript" filter
|
||||||
|
filter_type="Prefab", # optional type filter
|
||||||
|
page_size=25, # keep small to avoid large payloads
|
||||||
|
page_number=1, # 1-based
|
||||||
|
generate_preview=False # avoid base64 bloat
|
||||||
|
)
|
||||||
|
|
||||||
|
# Get asset info
|
||||||
|
manage_asset(action="get_info", path="Assets/Prefabs/Player.prefab")
|
||||||
|
|
||||||
|
# Create asset
|
||||||
|
manage_asset(
|
||||||
|
action="create",
|
||||||
|
path="Assets/Materials/NewMaterial.mat",
|
||||||
|
asset_type="Material",
|
||||||
|
properties={"color": [1, 0, 0, 1]}
|
||||||
|
)
|
||||||
|
|
||||||
|
# Duplicate/move/rename
|
||||||
|
manage_asset(action="duplicate", path="Assets/A.prefab", destination="Assets/B.prefab")
|
||||||
|
manage_asset(action="move", path="Assets/A.prefab", destination="Assets/Prefabs/A.prefab")
|
||||||
|
manage_asset(action="rename", path="Assets/A.prefab", destination="Assets/B.prefab")
|
||||||
|
|
||||||
|
# Create folder
|
||||||
|
manage_asset(action="create_folder", path="Assets/NewFolder")
|
||||||
|
|
||||||
|
# Delete
|
||||||
|
manage_asset(action="delete", path="Assets/OldAsset.asset")
|
||||||
|
```
|
||||||
|
|
||||||
|
### manage_prefabs
|
||||||
|
|
||||||
|
Headless prefab operations.
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Get prefab info
|
||||||
|
manage_prefabs(action="get_info", prefab_path="Assets/Prefabs/Player.prefab")
|
||||||
|
|
||||||
|
# Get prefab hierarchy
|
||||||
|
manage_prefabs(action="get_hierarchy", prefab_path="Assets/Prefabs/Player.prefab")
|
||||||
|
|
||||||
|
# Create prefab from scene GameObject
|
||||||
|
manage_prefabs(
|
||||||
|
action="create_from_gameobject",
|
||||||
|
target="Player", # GameObject in scene
|
||||||
|
prefab_path="Assets/Prefabs/Player.prefab",
|
||||||
|
allow_overwrite=False
|
||||||
|
)
|
||||||
|
|
||||||
|
# Modify prefab contents (headless)
|
||||||
|
manage_prefabs(
|
||||||
|
action="modify_contents",
|
||||||
|
prefab_path="Assets/Prefabs/Player.prefab",
|
||||||
|
target="ChildObject", # object within prefab
|
||||||
|
position=[0, 1, 0],
|
||||||
|
components_to_add=["AudioSource"]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Material & Shader Tools
|
||||||
|
|
||||||
|
### manage_material
|
||||||
|
|
||||||
|
Create and modify materials.
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Create material
|
||||||
|
manage_material(
|
||||||
|
action="create",
|
||||||
|
material_path="Assets/Materials/Red.mat",
|
||||||
|
shader="Standard",
|
||||||
|
properties={"_Color": [1, 0, 0, 1]}
|
||||||
|
)
|
||||||
|
|
||||||
|
# Get material info
|
||||||
|
manage_material(action="get_material_info", material_path="Assets/Materials/Red.mat")
|
||||||
|
|
||||||
|
# Set shader property
|
||||||
|
manage_material(
|
||||||
|
action="set_material_shader_property",
|
||||||
|
material_path="Assets/Materials/Red.mat",
|
||||||
|
property="_Metallic",
|
||||||
|
value=0.8
|
||||||
|
)
|
||||||
|
|
||||||
|
# Set color
|
||||||
|
manage_material(
|
||||||
|
action="set_material_color",
|
||||||
|
material_path="Assets/Materials/Red.mat",
|
||||||
|
property="_BaseColor",
|
||||||
|
color=[0, 1, 0, 1] # RGBA
|
||||||
|
)
|
||||||
|
|
||||||
|
# Assign to renderer
|
||||||
|
manage_material(
|
||||||
|
action="assign_material_to_renderer",
|
||||||
|
target="MyCube",
|
||||||
|
material_path="Assets/Materials/Red.mat",
|
||||||
|
slot=0 # material slot index
|
||||||
|
)
|
||||||
|
|
||||||
|
# Set renderer color directly
|
||||||
|
manage_material(
|
||||||
|
action="set_renderer_color",
|
||||||
|
target="MyCube",
|
||||||
|
color=[1, 0, 0, 1],
|
||||||
|
mode="instance" # "shared"|"instance"|"property_block"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### manage_texture
|
||||||
|
|
||||||
|
Create procedural textures.
|
||||||
|
|
||||||
|
```python
|
||||||
|
manage_texture(
|
||||||
|
action="create",
|
||||||
|
path="Assets/Textures/Checker.png",
|
||||||
|
width=64,
|
||||||
|
height=64,
|
||||||
|
fill_color=[255, 255, 255, 255] # or [1.0, 1.0, 1.0, 1.0]
|
||||||
|
)
|
||||||
|
|
||||||
|
# Apply pattern
|
||||||
|
manage_texture(
|
||||||
|
action="apply_pattern",
|
||||||
|
path="Assets/Textures/Checker.png",
|
||||||
|
pattern="checkerboard", # "checkerboard"|"stripes"|"dots"|"grid"|"brick"
|
||||||
|
palette=[[0,0,0,255], [255,255,255,255]],
|
||||||
|
pattern_size=8
|
||||||
|
)
|
||||||
|
|
||||||
|
# Apply gradient
|
||||||
|
manage_texture(
|
||||||
|
action="apply_gradient",
|
||||||
|
path="Assets/Textures/Gradient.png",
|
||||||
|
gradient_type="linear", # "linear"|"radial"
|
||||||
|
gradient_angle=45,
|
||||||
|
palette=[[255,0,0,255], [0,0,255,255]]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Editor Control Tools
|
||||||
|
|
||||||
|
### manage_editor
|
||||||
|
|
||||||
|
Control Unity Editor state.
|
||||||
|
|
||||||
|
```python
|
||||||
|
manage_editor(action="play") # Enter play mode
|
||||||
|
manage_editor(action="pause") # Pause play mode
|
||||||
|
manage_editor(action="stop") # Exit play mode
|
||||||
|
|
||||||
|
manage_editor(action="set_active_tool", tool_name="Move") # Move/Rotate/Scale/etc.
|
||||||
|
|
||||||
|
manage_editor(action="add_tag", tag_name="Enemy")
|
||||||
|
manage_editor(action="remove_tag", tag_name="OldTag")
|
||||||
|
|
||||||
|
manage_editor(action="add_layer", layer_name="Projectiles")
|
||||||
|
manage_editor(action="remove_layer", layer_name="OldLayer")
|
||||||
|
```
|
||||||
|
|
||||||
|
### execute_menu_item
|
||||||
|
|
||||||
|
Execute any Unity menu item.
|
||||||
|
|
||||||
|
```python
|
||||||
|
execute_menu_item(menu_path="File/Save Project")
|
||||||
|
execute_menu_item(menu_path="GameObject/3D Object/Cube")
|
||||||
|
execute_menu_item(menu_path="Window/General/Console")
|
||||||
|
```
|
||||||
|
|
||||||
|
### read_console
|
||||||
|
|
||||||
|
Read or clear Unity console messages.
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Get recent messages
|
||||||
|
read_console(
|
||||||
|
action="get",
|
||||||
|
types=["error", "warning", "log"], # or ["all"]
|
||||||
|
count=10, # max messages (ignored with paging)
|
||||||
|
filter_text="NullReference", # optional text filter
|
||||||
|
since_timestamp="2024-01-01T00:00:00Z", # optional time filter
|
||||||
|
page_size=50,
|
||||||
|
cursor=0,
|
||||||
|
format="detailed", # "plain"|"detailed"|"json"
|
||||||
|
include_stacktrace=True
|
||||||
|
)
|
||||||
|
|
||||||
|
# Clear console
|
||||||
|
read_console(action="clear")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing Tools
|
||||||
|
|
||||||
|
### run_tests
|
||||||
|
|
||||||
|
Start async test execution.
|
||||||
|
|
||||||
|
```python
|
||||||
|
result = run_tests(
|
||||||
|
mode="EditMode", # "EditMode"|"PlayMode"
|
||||||
|
test_names=["MyTests.TestA", "MyTests.TestB"], # specific tests
|
||||||
|
group_names=["Integration*"], # regex patterns
|
||||||
|
category_names=["Unit"], # NUnit categories
|
||||||
|
assembly_names=["Tests"], # assembly filter
|
||||||
|
include_failed_tests=True, # include failure details
|
||||||
|
include_details=False # include all test details
|
||||||
|
)
|
||||||
|
# Returns: {"job_id": "abc123", ...}
|
||||||
|
```
|
||||||
|
|
||||||
|
### get_test_job
|
||||||
|
|
||||||
|
Poll test job status.
|
||||||
|
|
||||||
|
```python
|
||||||
|
result = get_test_job(
|
||||||
|
job_id="abc123",
|
||||||
|
wait_timeout=60, # wait up to N seconds
|
||||||
|
include_failed_tests=True,
|
||||||
|
include_details=False
|
||||||
|
)
|
||||||
|
# Returns: {"status": "complete"|"running"|"failed", "results": {...}}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Search Tools
|
||||||
|
|
||||||
|
### find_in_file
|
||||||
|
|
||||||
|
Search file contents with regex.
|
||||||
|
|
||||||
|
```python
|
||||||
|
find_in_file(
|
||||||
|
uri="mcpforunity://path/Assets/Scripts/MyScript.cs",
|
||||||
|
pattern="public void \\w+", # regex pattern
|
||||||
|
max_results=200,
|
||||||
|
ignore_case=True
|
||||||
|
)
|
||||||
|
# Returns: line numbers, content excerpts, match positions
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Custom Tools
|
||||||
|
|
||||||
|
### execute_custom_tool
|
||||||
|
|
||||||
|
Execute project-specific custom tools.
|
||||||
|
|
||||||
|
```python
|
||||||
|
execute_custom_tool(
|
||||||
|
tool_name="my_custom_tool",
|
||||||
|
parameters={"param1": "value", "param2": 42}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Discover available custom tools via `mcpforunity://custom-tools` resource.
|
||||||
|
|
@ -0,0 +1,609 @@
|
||||||
|
# Unity-MCP Workflow Patterns
|
||||||
|
|
||||||
|
Common workflows and patterns for effective Unity-MCP usage.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Setup & Verification](#setup--verification)
|
||||||
|
- [Scene Creation Workflows](#scene-creation-workflows)
|
||||||
|
- [Script Development Workflows](#script-development-workflows)
|
||||||
|
- [Asset Management Workflows](#asset-management-workflows)
|
||||||
|
- [Testing Workflows](#testing-workflows)
|
||||||
|
- [Debugging Workflows](#debugging-workflows)
|
||||||
|
- [Batch Operations](#batch-operations)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Setup & Verification
|
||||||
|
|
||||||
|
### Initial Connection Verification
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Check editor state
|
||||||
|
# Read mcpforunity://editor/state
|
||||||
|
|
||||||
|
# 2. Verify ready_for_tools == true
|
||||||
|
# If false, wait for recommended_retry_after_ms
|
||||||
|
|
||||||
|
# 3. Check active scene
|
||||||
|
# Read mcpforunity://editor/state → active_scene
|
||||||
|
|
||||||
|
# 4. List available instances (multi-instance)
|
||||||
|
# Read mcpforunity://instances
|
||||||
|
```
|
||||||
|
|
||||||
|
### Before Any Operation
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Quick readiness check pattern:
|
||||||
|
editor_state = read_resource("mcpforunity://editor/state")
|
||||||
|
|
||||||
|
if not editor_state["ready_for_tools"]:
|
||||||
|
# Check blocking_reasons
|
||||||
|
# Wait recommended_retry_after_ms
|
||||||
|
pass
|
||||||
|
|
||||||
|
if editor_state["is_compiling"]:
|
||||||
|
# Wait for compilation to complete
|
||||||
|
pass
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scene Creation Workflows
|
||||||
|
|
||||||
|
### Create Complete Scene from Scratch
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Create new scene
|
||||||
|
manage_scene(action="create", name="GameLevel", path="Assets/Scenes/")
|
||||||
|
|
||||||
|
# 2. Batch create environment objects
|
||||||
|
batch_execute(commands=[
|
||||||
|
{"tool": "manage_gameobject", "params": {
|
||||||
|
"action": "create", "name": "Ground", "primitive_type": "Plane",
|
||||||
|
"position": [0, 0, 0], "scale": [10, 1, 10]
|
||||||
|
}},
|
||||||
|
{"tool": "manage_gameobject", "params": {
|
||||||
|
"action": "create", "name": "Light", "primitive_type": "Cube"
|
||||||
|
}},
|
||||||
|
{"tool": "manage_gameobject", "params": {
|
||||||
|
"action": "create", "name": "Player", "primitive_type": "Capsule",
|
||||||
|
"position": [0, 1, 0]
|
||||||
|
}}
|
||||||
|
])
|
||||||
|
|
||||||
|
# 3. Add light component (delete cube mesh, add light)
|
||||||
|
manage_components(action="remove", target="Light", component_type="MeshRenderer")
|
||||||
|
manage_components(action="remove", target="Light", component_type="MeshFilter")
|
||||||
|
manage_components(action="remove", target="Light", component_type="BoxCollider")
|
||||||
|
manage_components(action="add", target="Light", component_type="Light")
|
||||||
|
manage_components(action="set_property", target="Light", component_type="Light",
|
||||||
|
property="type", value="Directional")
|
||||||
|
|
||||||
|
# 4. Set up camera
|
||||||
|
manage_gameobject(action="modify", target="Main Camera", position=[0, 5, -10],
|
||||||
|
rotation=[30, 0, 0])
|
||||||
|
|
||||||
|
# 5. Verify with screenshot
|
||||||
|
manage_scene(action="screenshot")
|
||||||
|
|
||||||
|
# 6. Save scene
|
||||||
|
manage_scene(action="save")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Populate Scene with Grid of Objects
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Create 5x5 grid of cubes using batch
|
||||||
|
commands = []
|
||||||
|
for x in range(5):
|
||||||
|
for z in range(5):
|
||||||
|
commands.append({
|
||||||
|
"tool": "manage_gameobject",
|
||||||
|
"params": {
|
||||||
|
"action": "create",
|
||||||
|
"name": f"Cube_{x}_{z}",
|
||||||
|
"primitive_type": "Cube",
|
||||||
|
"position": [x * 2, 0, z * 2]
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
# Execute in batches of 25
|
||||||
|
batch_execute(commands=commands[:25], parallel=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Clone and Arrange Objects
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Find template object
|
||||||
|
result = find_gameobjects(search_term="Template", search_method="by_name")
|
||||||
|
template_id = result["ids"][0]
|
||||||
|
|
||||||
|
# Duplicate in a line
|
||||||
|
for i in range(10):
|
||||||
|
manage_gameobject(
|
||||||
|
action="duplicate",
|
||||||
|
target=template_id,
|
||||||
|
new_name=f"Instance_{i}",
|
||||||
|
offset=[i * 2, 0, 0]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Script Development Workflows
|
||||||
|
|
||||||
|
### Create New Script and Attach
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Create script
|
||||||
|
create_script(
|
||||||
|
path="Assets/Scripts/EnemyAI.cs",
|
||||||
|
contents='''using UnityEngine;
|
||||||
|
|
||||||
|
public class EnemyAI : MonoBehaviour
|
||||||
|
{
|
||||||
|
public float speed = 5f;
|
||||||
|
public Transform target;
|
||||||
|
|
||||||
|
void Update()
|
||||||
|
{
|
||||||
|
if (target != null)
|
||||||
|
{
|
||||||
|
Vector3 direction = (target.position - transform.position).normalized;
|
||||||
|
transform.position += direction * speed * Time.deltaTime;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}'''
|
||||||
|
)
|
||||||
|
|
||||||
|
# 2. CRITICAL: Refresh and compile
|
||||||
|
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
|
||||||
|
|
||||||
|
# 3. Check for errors
|
||||||
|
console = read_console(types=["error"], count=10)
|
||||||
|
if console["messages"]:
|
||||||
|
# Handle compilation errors
|
||||||
|
print("Compilation errors:", console["messages"])
|
||||||
|
else:
|
||||||
|
# 4. Attach to GameObject
|
||||||
|
manage_gameobject(action="modify", target="Enemy", components_to_add=["EnemyAI"])
|
||||||
|
|
||||||
|
# 5. Set component properties
|
||||||
|
manage_components(
|
||||||
|
action="set_property",
|
||||||
|
target="Enemy",
|
||||||
|
component_type="EnemyAI",
|
||||||
|
properties={
|
||||||
|
"speed": 10.0
|
||||||
|
}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Edit Existing Script Safely
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Get current SHA
|
||||||
|
sha_info = get_sha(uri="mcpforunity://path/Assets/Scripts/PlayerController.cs")
|
||||||
|
|
||||||
|
# 2. Find the method to edit
|
||||||
|
matches = find_in_file(
|
||||||
|
uri="mcpforunity://path/Assets/Scripts/PlayerController.cs",
|
||||||
|
pattern="void Update\\(\\)"
|
||||||
|
)
|
||||||
|
|
||||||
|
# 3. Apply structured edit
|
||||||
|
script_apply_edits(
|
||||||
|
name="PlayerController",
|
||||||
|
path="Assets/Scripts",
|
||||||
|
edits=[{
|
||||||
|
"op": "replace_method",
|
||||||
|
"methodName": "Update",
|
||||||
|
"replacement": '''void Update()
|
||||||
|
{
|
||||||
|
float h = Input.GetAxis("Horizontal");
|
||||||
|
float v = Input.GetAxis("Vertical");
|
||||||
|
transform.Translate(new Vector3(h, 0, v) * speed * Time.deltaTime);
|
||||||
|
}'''
|
||||||
|
}]
|
||||||
|
)
|
||||||
|
|
||||||
|
# 4. Validate
|
||||||
|
validate_script(
|
||||||
|
uri="mcpforunity://path/Assets/Scripts/PlayerController.cs",
|
||||||
|
level="standard"
|
||||||
|
)
|
||||||
|
|
||||||
|
# 5. Refresh
|
||||||
|
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
|
||||||
|
|
||||||
|
# 6. Check console
|
||||||
|
read_console(types=["error"], count=10)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Add Method to Existing Class
|
||||||
|
|
||||||
|
```python
|
||||||
|
script_apply_edits(
|
||||||
|
name="GameManager",
|
||||||
|
path="Assets/Scripts",
|
||||||
|
edits=[
|
||||||
|
{
|
||||||
|
"op": "insert_method",
|
||||||
|
"afterMethod": "Start",
|
||||||
|
"code": '''
|
||||||
|
public void ResetGame()
|
||||||
|
{
|
||||||
|
SceneManager.LoadScene(SceneManager.GetActiveScene().name);
|
||||||
|
}'''
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"op": "anchor_insert",
|
||||||
|
"anchor": "using UnityEngine;",
|
||||||
|
"position": "after",
|
||||||
|
"text": "\nusing UnityEngine.SceneManagement;"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Asset Management Workflows
|
||||||
|
|
||||||
|
### Create and Apply Material
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Create material
|
||||||
|
manage_material(
|
||||||
|
action="create",
|
||||||
|
material_path="Assets/Materials/PlayerMaterial.mat",
|
||||||
|
shader="Standard",
|
||||||
|
properties={
|
||||||
|
"_Color": [0.2, 0.5, 1.0, 1.0],
|
||||||
|
"_Metallic": 0.5,
|
||||||
|
"_Glossiness": 0.8
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
# 2. Assign to renderer
|
||||||
|
manage_material(
|
||||||
|
action="assign_material_to_renderer",
|
||||||
|
target="Player",
|
||||||
|
material_path="Assets/Materials/PlayerMaterial.mat",
|
||||||
|
slot=0
|
||||||
|
)
|
||||||
|
|
||||||
|
# 3. Verify visually
|
||||||
|
manage_scene(action="screenshot")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create Procedural Texture
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Create base texture
|
||||||
|
manage_texture(
|
||||||
|
action="create",
|
||||||
|
path="Assets/Textures/Checkerboard.png",
|
||||||
|
width=256,
|
||||||
|
height=256,
|
||||||
|
fill_color=[255, 255, 255, 255]
|
||||||
|
)
|
||||||
|
|
||||||
|
# 2. Apply checkerboard pattern
|
||||||
|
manage_texture(
|
||||||
|
action="apply_pattern",
|
||||||
|
path="Assets/Textures/Checkerboard.png",
|
||||||
|
pattern="checkerboard",
|
||||||
|
palette=[[0, 0, 0, 255], [255, 255, 255, 255]],
|
||||||
|
pattern_size=32
|
||||||
|
)
|
||||||
|
|
||||||
|
# 3. Create material with texture
|
||||||
|
manage_material(
|
||||||
|
action="create",
|
||||||
|
material_path="Assets/Materials/CheckerMaterial.mat",
|
||||||
|
shader="Standard"
|
||||||
|
)
|
||||||
|
|
||||||
|
# 4. Assign texture to material (via manage_material set_material_shader_property)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Organize Assets into Folders
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Create folder structure
|
||||||
|
batch_execute(commands=[
|
||||||
|
{"tool": "manage_asset", "params": {"action": "create_folder", "path": "Assets/Prefabs"}},
|
||||||
|
{"tool": "manage_asset", "params": {"action": "create_folder", "path": "Assets/Materials"}},
|
||||||
|
{"tool": "manage_asset", "params": {"action": "create_folder", "path": "Assets/Scripts"}},
|
||||||
|
{"tool": "manage_asset", "params": {"action": "create_folder", "path": "Assets/Textures"}}
|
||||||
|
])
|
||||||
|
|
||||||
|
# 2. Move existing assets
|
||||||
|
manage_asset(action="move", path="Assets/MyMaterial.mat", destination="Assets/Materials/MyMaterial.mat")
|
||||||
|
manage_asset(action="move", path="Assets/MyScript.cs", destination="Assets/Scripts/MyScript.cs")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Search and Process Assets
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Find all prefabs
|
||||||
|
result = manage_asset(
|
||||||
|
action="search",
|
||||||
|
path="Assets",
|
||||||
|
search_pattern="*.prefab",
|
||||||
|
page_size=50,
|
||||||
|
generate_preview=False
|
||||||
|
)
|
||||||
|
|
||||||
|
# Process each prefab
|
||||||
|
for asset in result["assets"]:
|
||||||
|
prefab_path = asset["path"]
|
||||||
|
# Get prefab info
|
||||||
|
info = manage_prefabs(action="get_info", prefab_path=prefab_path)
|
||||||
|
print(f"Prefab: {prefab_path}, Children: {info['childCount']}")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing Workflows
|
||||||
|
|
||||||
|
### Run Specific Tests
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. List available tests
|
||||||
|
# Read mcpforunity://tests/EditMode
|
||||||
|
|
||||||
|
# 2. Run specific tests
|
||||||
|
result = run_tests(
|
||||||
|
mode="EditMode",
|
||||||
|
test_names=["MyTests.TestPlayerMovement", "MyTests.TestEnemySpawn"],
|
||||||
|
include_failed_tests=True
|
||||||
|
)
|
||||||
|
job_id = result["job_id"]
|
||||||
|
|
||||||
|
# 3. Wait for results
|
||||||
|
final_result = get_test_job(
|
||||||
|
job_id=job_id,
|
||||||
|
wait_timeout=60,
|
||||||
|
include_failed_tests=True
|
||||||
|
)
|
||||||
|
|
||||||
|
# 4. Check results
|
||||||
|
if final_result["status"] == "complete":
|
||||||
|
for test in final_result.get("failed_tests", []):
|
||||||
|
print(f"FAILED: {test['name']}: {test['message']}")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run Tests by Category
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Run all unit tests
|
||||||
|
result = run_tests(
|
||||||
|
mode="EditMode",
|
||||||
|
category_names=["Unit"],
|
||||||
|
include_failed_tests=True
|
||||||
|
)
|
||||||
|
|
||||||
|
# Poll until complete
|
||||||
|
while True:
|
||||||
|
status = get_test_job(job_id=result["job_id"], wait_timeout=30)
|
||||||
|
if status["status"] in ["complete", "failed"]:
|
||||||
|
break
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test-Driven Development Pattern
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Write test first
|
||||||
|
create_script(
|
||||||
|
path="Assets/Tests/Editor/PlayerTests.cs",
|
||||||
|
contents='''using NUnit.Framework;
|
||||||
|
using UnityEngine;
|
||||||
|
|
||||||
|
public class PlayerTests
|
||||||
|
{
|
||||||
|
[Test]
|
||||||
|
public void TestPlayerStartsAtOrigin()
|
||||||
|
{
|
||||||
|
var player = new GameObject("TestPlayer");
|
||||||
|
Assert.AreEqual(Vector3.zero, player.transform.position);
|
||||||
|
Object.DestroyImmediate(player);
|
||||||
|
}
|
||||||
|
}'''
|
||||||
|
)
|
||||||
|
|
||||||
|
# 2. Refresh
|
||||||
|
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
|
||||||
|
|
||||||
|
# 3. Run test (expect pass for this simple test)
|
||||||
|
result = run_tests(mode="EditMode", test_names=["PlayerTests.TestPlayerStartsAtOrigin"])
|
||||||
|
get_test_job(job_id=result["job_id"], wait_timeout=30)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Debugging Workflows
|
||||||
|
|
||||||
|
### Diagnose Compilation Errors
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Check console for errors
|
||||||
|
errors = read_console(
|
||||||
|
types=["error"],
|
||||||
|
count=20,
|
||||||
|
include_stacktrace=True,
|
||||||
|
format="detailed"
|
||||||
|
)
|
||||||
|
|
||||||
|
# 2. For each error, find the file and line
|
||||||
|
for error in errors["messages"]:
|
||||||
|
# Parse error message for file:line info
|
||||||
|
# Use find_in_file to locate the problematic code
|
||||||
|
pass
|
||||||
|
|
||||||
|
# 3. After fixing, refresh and check again
|
||||||
|
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
|
||||||
|
read_console(types=["error"], count=10)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Investigate Missing References
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Find the GameObject
|
||||||
|
result = find_gameobjects(search_term="Player", search_method="by_name")
|
||||||
|
|
||||||
|
# 2. Get all components
|
||||||
|
# Read mcpforunity://scene/gameobject/{id}/components
|
||||||
|
|
||||||
|
# 3. Check for null references in serialized fields
|
||||||
|
# Look for fields with null/missing values
|
||||||
|
|
||||||
|
# 4. Find the referenced object
|
||||||
|
result = find_gameobjects(search_term="Target", search_method="by_name")
|
||||||
|
|
||||||
|
# 5. Set the reference
|
||||||
|
manage_components(
|
||||||
|
action="set_property",
|
||||||
|
target="Player",
|
||||||
|
component_type="PlayerController",
|
||||||
|
property="target",
|
||||||
|
value={"instanceID": result["ids"][0]} # Reference by ID
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Check Scene State
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Get hierarchy
|
||||||
|
hierarchy = manage_scene(action="get_hierarchy", page_size=100, include_transform=True)
|
||||||
|
|
||||||
|
# 2. Find objects at unexpected positions
|
||||||
|
for item in hierarchy["data"]["items"]:
|
||||||
|
if item.get("transform", {}).get("position", [0,0,0])[1] < -100:
|
||||||
|
print(f"Object {item['name']} fell through floor!")
|
||||||
|
|
||||||
|
# 3. Visual verification
|
||||||
|
manage_scene(action="screenshot")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Batch Operations
|
||||||
|
|
||||||
|
### Mass Property Update
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Find all enemies
|
||||||
|
enemies = find_gameobjects(search_term="Enemy", search_method="by_tag")
|
||||||
|
|
||||||
|
# Update health on all enemies
|
||||||
|
commands = []
|
||||||
|
for enemy_id in enemies["ids"]:
|
||||||
|
commands.append({
|
||||||
|
"tool": "manage_components",
|
||||||
|
"params": {
|
||||||
|
"action": "set_property",
|
||||||
|
"target": enemy_id,
|
||||||
|
"component_type": "EnemyHealth",
|
||||||
|
"property": "maxHealth",
|
||||||
|
"value": 100
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
# Execute in batches
|
||||||
|
for i in range(0, len(commands), 25):
|
||||||
|
batch_execute(commands=commands[i:i+25], parallel=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mass Object Creation with Variations
|
||||||
|
|
||||||
|
```python
|
||||||
|
import random
|
||||||
|
|
||||||
|
commands = []
|
||||||
|
for i in range(20):
|
||||||
|
commands.append({
|
||||||
|
"tool": "manage_gameobject",
|
||||||
|
"params": {
|
||||||
|
"action": "create",
|
||||||
|
"name": f"Tree_{i}",
|
||||||
|
"primitive_type": "Capsule",
|
||||||
|
"position": [random.uniform(-50, 50), 0, random.uniform(-50, 50)],
|
||||||
|
"scale": [1, random.uniform(2, 5), 1]
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
batch_execute(commands=commands, parallel=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cleanup Pattern
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Find all temporary objects
|
||||||
|
temps = find_gameobjects(search_term="Temp_", search_method="by_name")
|
||||||
|
|
||||||
|
# Delete in batch
|
||||||
|
commands = [
|
||||||
|
{"tool": "manage_gameobject", "params": {"action": "delete", "target": id}}
|
||||||
|
for id in temps["ids"]
|
||||||
|
]
|
||||||
|
|
||||||
|
batch_execute(commands=commands, fail_fast=False)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Recovery Patterns
|
||||||
|
|
||||||
|
### Stale File Recovery
|
||||||
|
|
||||||
|
```python
|
||||||
|
try:
|
||||||
|
apply_text_edits(uri=script_uri, edits=[...], precondition_sha256=old_sha)
|
||||||
|
except Exception as e:
|
||||||
|
if "stale_file" in str(e):
|
||||||
|
# Re-fetch SHA
|
||||||
|
new_sha = get_sha(uri=script_uri)
|
||||||
|
# Retry with new SHA
|
||||||
|
apply_text_edits(uri=script_uri, edits=[...], precondition_sha256=new_sha["sha256"])
|
||||||
|
```
|
||||||
|
|
||||||
|
### Domain Reload Recovery
|
||||||
|
|
||||||
|
```python
|
||||||
|
# After domain reload, connection may be lost
|
||||||
|
# Wait and retry pattern:
|
||||||
|
import time
|
||||||
|
|
||||||
|
max_retries = 5
|
||||||
|
for attempt in range(max_retries):
|
||||||
|
try:
|
||||||
|
editor_state = read_resource("mcpforunity://editor/state")
|
||||||
|
if editor_state["ready_for_tools"]:
|
||||||
|
break
|
||||||
|
except:
|
||||||
|
time.sleep(2 ** attempt) # Exponential backoff
|
||||||
|
```
|
||||||
|
|
||||||
|
### Compilation Block Recovery
|
||||||
|
|
||||||
|
```python
|
||||||
|
# If tools fail due to compilation:
|
||||||
|
# 1. Check console for errors
|
||||||
|
errors = read_console(types=["error"], count=20)
|
||||||
|
|
||||||
|
# 2. Fix the script errors
|
||||||
|
# ... edit scripts ...
|
||||||
|
|
||||||
|
# 3. Force refresh
|
||||||
|
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
|
||||||
|
|
||||||
|
# 4. Verify clean console
|
||||||
|
errors = read_console(types=["error"], count=5)
|
||||||
|
if not errors["messages"]:
|
||||||
|
# Safe to proceed with tools
|
||||||
|
pass
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue