Merge pull request #934 from Scriptwonder/bug-fix-and-doc-update-0315

Bug-Fix and Doc-Update

Author: Scriptwonder

.claude/skills/unity-mcp-skill/SKILL.md

@@ -24,20 +24,26 @@ Before applying a template:
 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
+5. Verify results         → read_console, manage_camera(action="screenshot"), resources
 ```
 
 ## Critical Best Practices
 
-### 1. After Writing/Editing Scripts: Always Refresh and Check Console
+### 1. After Writing/Editing Scripts: Wait for Compilation and Check Console
 
 ```python
 # After create_script or script_apply_edits:
-refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
+# Both tools already trigger AssetDatabase.ImportAsset + RequestScriptCompilation automatically.
+# No need to call refresh_unity — just wait for compilation to finish, then check console.
+
+# 1. Poll editor state until compilation completes
+# Read mcpforunity://editor/state → wait until is_compiling == false
+
+# 2. Check for compilation errors
 read_console(types=["error"], count=10, include_stacktrace=True)
 ```
 
-**Why:** Unity must compile scripts before they're usable. Compilation errors block all tool execution.
+**Why:** Unity must compile scripts before they're usable. `create_script` and `script_apply_edits` already trigger import and compilation automatically — calling `refresh_unity` afterward is redundant.
 
 ### 2. Use `batch_execute` for Multiple Operations
 
@@ -55,26 +61,35 @@ batch_execute(
 
 **Max 25 commands per batch by default (configurable in Unity MCP Tools window, max 100).** Use `fail_fast=True` for dependent operations.
 
+**Tip:** Also use `batch_execute` for discovery — batch multiple `find_gameobjects` calls instead of calling them one at a time:
+```python
+batch_execute(commands=[
+    {"tool": "find_gameobjects", "params": {"search_term": "Camera", "search_method": "by_component"}},
+    {"tool": "find_gameobjects", "params": {"search_term": "Player", "search_method": "by_tag"}},
+    {"tool": "find_gameobjects", "params": {"search_term": "GameManager", "search_method": "by_name"}}
+])
+```
+
 ### 3. Use Screenshots to Verify Visual Results
 
 ```python
 # Basic screenshot (saves to Assets/, returns file path only)
-manage_scene(action="screenshot")
+manage_camera(action="screenshot")
 
 # Inline screenshot (returns base64 PNG directly to the AI)
-manage_scene(action="screenshot", include_image=True)
+manage_camera(action="screenshot", include_image=True)
 
 # Use a specific camera and cap resolution for smaller payloads
-manage_scene(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
+manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
 
 # Batch surround: captures front/back/left/right/top/bird_eye around the scene
-manage_scene(action="screenshot", batch="surround", max_resolution=256)
+manage_camera(action="screenshot", batch="surround", max_resolution=256)
 
 # Batch surround centered on a specific object
-manage_scene(action="screenshot", batch="surround", look_at="Player", max_resolution=256)
+manage_camera(action="screenshot", batch="surround", look_at="Player", max_resolution=256)
 
 # Positioned screenshot: place a temp camera and capture in one call
-manage_scene(action="screenshot", look_at="Player", view_position=[0, 10, -10], max_resolution=512)
+manage_camera(action="screenshot", look_at="Player", view_position=[0, 10, -10], max_resolution=512)
 ```
 
 **Best practices for AI scene understanding:**
@@ -87,10 +102,10 @@ manage_scene(action="screenshot", look_at="Player", view_position=[0, 10, -10],
 ```python
 # Agentic camera loop: point, shoot, analyze
 manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player")
-manage_scene(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
+manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
 # → Analyze image, decide next action
 
-# Alternative: use manage_camera for screenshot (same underlying infrastructure)
+# Screenshot from a different camera
 manage_camera(action="screenshot", camera="FollowCam", include_image=True, max_resolution=512)
 manage_camera(action="screenshot_multiview", max_resolution=480)  # 6-angle contact sheet
 ```
@@ -157,14 +172,14 @@ uri="file:///full/path/to/file.cs"
 |----------|-----------|---------|
 | **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 |
+| **Scripts** | `create_script`, `script_apply_edits`, `validate_script` | C# code management (auto-refreshes on create/edit) |
+| **Assets** | `manage_asset`, `manage_prefabs` | Asset operations. **Prefab instantiation** is done via `manage_gameobject(action="create", prefab_path="...")`, not `manage_prefabs`. |
 | **Editor** | `manage_editor`, `execute_menu_item`, `read_console` | Editor control, package deployment (`deploy_package`/`restore_package` actions) |
 | **Testing** | `run_tests`, `get_test_job` | Unity Test Framework |
 | **Batch** | `batch_execute` | Parallel/bulk operations |
 | **Camera** | `manage_camera` | Camera management (Unity Camera + Cinemachine). **Tier 1** (always available): create, target, lens, priority, list, screenshot. **Tier 2** (requires `com.unity.cinemachine`): brain, body/aim/noise pipeline, extensions, blending, force/release. 7 presets: follow, third_person, freelook, dolly, static, top_down, side_scroller. Resource: `mcpforunity://scene/cameras`. Use `ping` to check Cinemachine availability. See [tools-reference.md](references/tools-reference.md#camera-tools). |
 | **Graphics** | `manage_graphics` | Rendering and post-processing management. 33 actions across 5 groups: **Volume** (create/configure volumes and effects, URP/HDRP), **Bake** (lightmaps, light probes, reflection probes, Edit mode only), **Stats** (draw calls, batches, memory), **Pipeline** (quality levels, pipeline settings), **Features** (URP renderer features: add, remove, toggle, reorder). Resources: `mcpforunity://scene/volumes`, `mcpforunity://rendering/stats`, `mcpforunity://pipeline/renderer-features`. Use `ping` to check pipeline status. See [tools-reference.md](references/tools-reference.md#graphics-tools). |
-| **Packages** | `query_packages` (read-only), `manage_packages` (mutating) | Install, remove, search, and manage Unity packages and scoped registries. `query_packages`: list installed, search registry, get info, ping, poll status. `manage_packages`: add/remove packages, embed for editing, add/remove scoped registries, force resolve. Validates identifiers, warns on git URLs, checks dependents before removal (`force=true` to override). See [tools-reference.md](references/tools-reference.md#package-tools). |
+| **Packages** | `manage_packages` | Install, remove, search, and manage Unity packages and scoped registries. Query actions: list installed, search registry, get info, ping, poll status. Mutating actions: add/remove packages, embed for editing, add/remove scoped registries, force resolve. Validates identifiers, warns on git URLs, checks dependents before removal (`force=true` to override). See [tools-reference.md](references/tools-reference.md#package-tools). |
 | **ProBuilder** | `manage_probuilder` | 3D modeling, mesh editing, complex geometry. **When `com.unity.probuilder` is installed, prefer ProBuilder shapes over primitive GameObjects** for editable geometry, multi-material faces, or complex shapes. Supports 12 shape types, face/edge/vertex editing, smoothing, and per-face materials. See [ProBuilder Guide](references/probuilder-guide.md). |
 | **UI** | `manage_ui`, `batch_execute` with `manage_gameobject` + `manage_components` | **UI Toolkit**: Use `manage_ui` to create UXML/USS files, attach UIDocument, inspect visual trees. **uGUI (Canvas)**: Use `batch_execute` for Canvas, Panel, Button, Text, Slider, Toggle, Input Field. **Read `mcpforunity://project/info` first** to detect uGUI/TMP/Input System/UI Toolkit availability. (see [UI workflows](references/workflows.md#ui-creation-workflows)) |
 
@@ -173,14 +188,14 @@ uri="file:///full/path/to/file.cs"
 ### Creating a New Script and Using It
 
 ```python
-# 1. Create the script
+# 1. Create the script (automatically triggers import + compilation)
 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)
+# 2. Wait for compilation to finish
+# Read mcpforunity://editor/state → wait until is_compiling == false
 
 # 3. Check for compilation errors
 read_console(types=["error"], count=10)