Skill update (CoplayDev#888)

Scriptwonder · web-flow · commit d01ac7cf8d2f · 2026-03-07T02:46:19.000-05:00
diff --git a/.claude/skills/unity-mcp-skill/SKILL.md b/.claude/skills/unity-mcp-skill/SKILL.md
@@ -89,6 +89,10 @@ manage_scene(action="screenshot", look_at="Player", view_position=[0, 10, -10],
 manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player")
 manage_scene(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
 # → Analyze image, decide next action
+
+# Alternative: use manage_camera for screenshot (same underlying infrastructure)
+manage_camera(action="screenshot", camera="FollowCam", include_image=True, max_resolution=512)
+manage_camera(action="screenshot_multiview", max_resolution=480)  # 6-angle contact sheet
 ```
 
 ### 4. Check Console After Major Changes
@@ -158,7 +162,8 @@ uri="file:///full/path/to/file.cs"
 | **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 |
-| **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 13 shape types, face/edge/vertex editing, smoothing, and per-face materials. See [ProBuilder Guide](references/probuilder-guide.md). |
+| **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). |
+| **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)) |
 
 ## Common Workflows
diff --git a/.claude/skills/unity-mcp-skill/references/tools-reference.md b/.claude/skills/unity-mcp-skill/references/tools-reference.md
@@ -15,6 +15,7 @@ Complete reference for all MCP tools. Each tool includes parameters, types, and
 - [UI Tools](#ui-tools)
 - [Editor Control Tools](#editor-control-tools)
 - [Testing Tools](#testing-tools)
+- [Camera Tools](#camera-tools)
 - [ProBuilder Tools](#probuilder-tools)
 
 ---
@@ -793,6 +794,131 @@ Discover available custom tools via `mcpforunity://custom-tools` resource.
 
 ---
 
+## Camera Tools
+
+### manage_camera
+
+Unified camera management (Unity Camera + Cinemachine). Works without Cinemachine using basic Camera; unlocks presets, pipelines, and blending when Cinemachine is installed. Use `ping` to check availability.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action` | string | Yes | Action to perform (see categories below) |
+| `target` | string | Sometimes | Target camera (name, path, or instance ID) |
+| `search_method` | string | No | `by_id`, `by_name`, `by_path` |
+| `properties` | dict \| string | No | Action-specific parameters |
+
+**Screenshot parameters** (for `screenshot` and `screenshot_multiview` actions):
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `camera` | string | Camera to capture from (defaults to Camera.main) |
+| `include_image` | bool | Return base64 PNG inline (default false) |
+| `max_resolution` | int | Downscale cap in px (default 640) |
+| `batch` | string | `"surround"` (6 angles) or `"orbit"` (configurable grid) |
+| `look_at` | string\|int\|list | Target to aim at (GO name/path/ID or [x,y,z]) |
+| `view_position` | list[float] | World position [x,y,z] to place camera |
+| `view_rotation` | list[float] | Euler rotation [x,y,z] (overrides look_at) |
+
+**Actions by category:**
+
+**Setup:**
+- `ping` — Check Cinemachine availability and version
+- `ensure_brain` — Ensure CinemachineBrain exists on main camera. Properties: `camera` (target camera), `defaultBlendStyle`, `defaultBlendDuration`
+- `get_brain_status` — Get Brain state (active camera, blend status)
+
+**Creation:**
+- `create_camera` — Create camera with optional preset. Properties: `name`, `preset` (follow/third_person/freelook/dolly/static/top_down/side_scroller), `follow`, `lookAt`, `priority`, `fieldOfView`. Falls back to basic Camera without Cinemachine.
+
+**Configuration:**
+- `set_target` — Set Follow and/or LookAt targets. Properties: `follow`, `lookAt` (GO name/path/ID)
+- `set_priority` — Set camera priority for Brain selection. Properties: `priority` (int)
+- `set_lens` — Configure lens. Properties: `fieldOfView`, `nearClipPlane`, `farClipPlane`, `orthographicSize`, `dutch`
+- `set_body` — Configure Body component (Cinemachine). Properties: `bodyType` (to swap), plus component-specific properties
+- `set_aim` — Configure Aim component (Cinemachine). Properties: `aimType` (to swap), plus component-specific properties
+- `set_noise` — Configure Noise (Cinemachine). Properties: `amplitudeGain`, `frequencyGain`
+
+**Extensions (Cinemachine):**
+- `add_extension` — Add extension. Properties: `extensionType` (CinemachineConfiner2D, CinemachineDeoccluder, CinemachineImpulseListener, CinemachineFollowZoom, CinemachineRecomposer, etc.)
+- `remove_extension` — Remove extension by type. Properties: `extensionType`
+
+**Control:**
+- `list_cameras` — List all cameras with status
+- `set_blend` — Configure default blend on Brain. Properties: `style` (Cut/EaseInOut/Linear/etc.), `duration`
+- `force_camera` — Override Brain to use specific camera
+- `release_override` — Release camera override
+
+**Capture:**
+- `screenshot` — Capture from a camera. Supports inline base64, batch surround/orbit, positioned capture.
+- `screenshot_multiview` — Shorthand for screenshot with batch='surround' and include_image=true.
+
+**Examples:**
+
+```python
+# Check Cinemachine availability
+manage_camera(action="ping")
+
+# Create a third-person camera following the player
+manage_camera(action="create_camera", properties={
+    "name": "FollowCam", "preset": "third_person",
+    "follow": "Player", "lookAt": "Player", "priority": 20
+})
+
+# Ensure Brain exists on main camera
+manage_camera(action="ensure_brain")
+
+# Configure body component
+manage_camera(action="set_body", target="FollowCam", properties={
+    "bodyType": "CinemachineThirdPersonFollow",
+    "cameraDistance": 5.0, "shoulderOffset": [0.5, 0.5, 0]
+})
+
+# Set aim
+manage_camera(action="set_aim", target="FollowCam", properties={
+    "aimType": "CinemachineRotationComposer"
+})
+
+# Add camera shake
+manage_camera(action="set_noise", target="FollowCam", properties={
+    "amplitudeGain": 0.5, "frequencyGain": 1.0
+})
+
+# Set priority to make this the active camera
+manage_camera(action="set_priority", target="FollowCam", properties={"priority": 50})
+
+# Force a specific camera
+manage_camera(action="force_camera", target="CinematicCam")
+
+# Release override (return to priority-based selection)
+manage_camera(action="release_override")
+
+# Configure blend transitions
+manage_camera(action="set_blend", properties={"style": "EaseInOut", "duration": 2.0})
+
+# Add deoccluder extension
+manage_camera(action="add_extension", target="FollowCam", properties={
+    "extensionType": "CinemachineDeoccluder"
+})
+
+# Screenshot from a specific camera
+manage_camera(action="screenshot", camera="FollowCam", include_image=True, max_resolution=512)
+
+# Multi-view screenshot (6-angle contact sheet)
+manage_camera(action="screenshot_multiview", max_resolution=480)
+
+# List all cameras
+manage_camera(action="list_cameras")
+```
+
+**Tier system:**
+- Tier 1 actions (ping, create_camera, set_target, set_lens, set_priority, list_cameras, screenshot, screenshot_multiview) work without Cinemachine — they fall back to basic Unity Camera.
+- Tier 2 actions (ensure_brain, get_brain_status, set_body, set_aim, set_noise, add/remove_extension, set_blend, force_camera, release_override) require `com.unity.cinemachine`. If called without Cinemachine, they return an error with a fallback suggestion.
+
+**Resource:** Read `mcpforunity://scene/cameras` for current camera state before modifying.
+
+---
+
 ## ProBuilder Tools
 
 ### manage_probuilder
@@ -806,7 +932,7 @@ Unified tool for ProBuilder mesh operations. Requires `com.unity.probuilder` pac
 | `action` | string | Yes | Action to perform (see categories below) |
 | `target` | string | Sometimes | Target GameObject name/path/id |
 | `search_method` | string | No | How to find target: `by_id`, `by_name`, `by_path`, `by_tag`, `by_layer` |
-| `properties` | dict | No | Action-specific parameters |
+| `properties` | dict \| string | No | Action-specific parameters (dict or JSON string) |
 
 **Actions by category:**
 
diff --git a/.claude/skills/unity-mcp-skill/references/workflows.md b/.claude/skills/unity-mcp-skill/references/workflows.md
@@ -11,6 +11,7 @@ Common workflows and patterns for effective Unity-MCP usage.
 - [Testing Workflows](#testing-workflows)
 - [Debugging Workflows](#debugging-workflows)
 - [UI Creation Workflows](#ui-creation-workflows)
+- [Camera & Cinemachine Workflows](#camera--cinemachine-workflows)
 - [ProBuilder Workflows](#probuilder-workflows)
 - [Batch Operations](#batch-operations)
 
@@ -1426,6 +1427,107 @@ Both systems are active simultaneously. For UI, prefer `InputSystemUIInputModule
 
 ---
 
+## Camera & Cinemachine Workflows
+
+### Setting Up a Third-Person Camera
+
+```python
+# 1. Check Cinemachine availability
+manage_camera(action="ping")
+
+# 2. Ensure Brain on main camera
+manage_camera(action="ensure_brain")
+
+# 3. Create third-person camera with preset
+manage_camera(action="create_camera", properties={
+    "name": "FollowCam", "preset": "third_person",
+    "follow": "Player", "lookAt": "Player", "priority": 20
+})
+
+# 4. Fine-tune body
+manage_camera(action="set_body", target="FollowCam", properties={
+    "cameraDistance": 5.0, "shoulderOffset": [0.5, 0.5, 0]
+})
+
+# 5. Add camera shake
+manage_camera(action="set_noise", target="FollowCam", properties={
+    "amplitudeGain": 0.3, "frequencyGain": 0.8
+})
+
+# 6. Verify with screenshot
+manage_camera(action="screenshot", camera="FollowCam", include_image=True, max_resolution=512)
+```
+
+### Multi-Camera Setup with Blending
+
+```python
+# 1. Read current cameras
+# Read mcpforunity://scene/cameras
+
+# 2. Create gameplay camera (highest priority = active by default)
+manage_camera(action="create_camera", properties={
+    "name": "GameplayCam", "preset": "follow",
+    "follow": "Player", "lookAt": "Player", "priority": 10
+})
+
+# 3. Create cinematic camera (lower priority, activated on demand)
+manage_camera(action="create_camera", properties={
+    "name": "CinematicCam", "preset": "dolly",
+    "lookAt": "CutsceneTarget", "priority": 5
+})
+
+# 4. Set blend transition
+manage_camera(action="set_blend", properties={"style": "EaseInOut", "duration": 2.0})
+
+# 5. Force cinematic camera for a cutscene
+manage_camera(action="force_camera", target="CinematicCam")
+
+# 6. Release override to return to priority-based selection
+manage_camera(action="release_override")
+```
+
+### Camera Without Cinemachine
+
+```python
+# Tier 1 actions work with plain Unity Camera
+manage_camera(action="create_camera", properties={
+    "name": "MainCam", "fieldOfView": 50
+})
+
+# Set lens
+manage_camera(action="set_lens", target="MainCam", properties={
+    "fieldOfView": 60, "nearClipPlane": 0.1, "farClipPlane": 1000
+})
+
+# Point camera at target (uses manage_gameobject look_at under the hood)
+manage_camera(action="set_target", target="MainCam", properties={
+    "lookAt": "Player"
+})
+
+# Screenshot from this camera
+manage_camera(action="screenshot", camera="MainCam", include_image=True, max_resolution=512)
+```
+
+### Camera Inspection Workflow
+
+```python
+# 1. Read all cameras via resource
+# Read mcpforunity://scene/cameras
+# → Shows brain status, all Cinemachine cameras (priority, pipeline, targets),
+#   all Unity cameras (FOV, depth, brain)
+
+# 2. Get brain status for blending info
+manage_camera(action="get_brain_status")
+
+# 3. List cameras via tool (alternative to resource)
+manage_camera(action="list_cameras")
+
+# 4. Multi-view screenshot to see from different angles
+manage_camera(action="screenshot_multiview", max_resolution=480)
+```
+
+---
+
 ## ProBuilder Workflows
 
 When `com.unity.probuilder` is installed, prefer ProBuilder shapes over primitive GameObjects for any geometry that needs editing, multi-material faces, or non-trivial shapes. Check availability first with `manage_probuilder(action="ping")`.
diff --git a/tools/UPDATE_DOCS_PROMPT.md b/tools/UPDATE_DOCS_PROMPT.md
@@ -60,6 +60,10 @@ Here's what you need to do:
       - Translate the summary text to Chinese
       - Same 4-entry rotation rule applies
 
+   g) **unity-mcp-skill** - Skill Update
+      - Detect if this feature needs extra care via Skills
+      - If so, update the .md files based on the updates
+
 3. **Important formatting rules**:
    - Use backticks around tool/resource names
    - Separate items with • (bullet point)
diff --git a/unity-mcp-skill/SKILL.md b/unity-mcp-skill/SKILL.md
@@ -89,6 +89,10 @@ manage_scene(action="screenshot", look_at="Player", view_position=[0, 10, -10],
 manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player")
 manage_scene(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
 # → Analyze image, decide next action
+
+# Alternative: use manage_camera for screenshot (same underlying infrastructure)
+manage_camera(action="screenshot", camera="FollowCam", include_image=True, max_resolution=512)
+manage_camera(action="screenshot_multiview", max_resolution=480)  # 6-angle contact sheet
 ```
 
 ### 4. Check Console After Major Changes
@@ -158,6 +162,7 @@ uri="file:///full/path/to/file.cs"
 | **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 |
+| **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). |
 | **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)) |
 
diff --git a/unity-mcp-skill/references/resources-reference.md b/unity-mcp-skill/references/resources-reference.md
@@ -5,6 +5,7 @@ Resources provide read-only access to Unity state. Use resources to inspect befo
 ## Table of Contents
 
 - [Editor State Resources](#editor-state-resources)
+- [Camera Resources](#camera-resources)
 - [Scene & GameObject Resources](#scene--gameobject-resources)
 - [Prefab Resources](#prefab-resources)
 - [Project Resources](#project-resources)
@@ -125,6 +126,60 @@ mcpforunity://{category}/{resource_path}[?query_params]
 
 ---
 
+## Camera Resources
+
+### mcpforunity://scene/cameras
+
+**Purpose:** List all cameras in the scene (Unity Camera + CinemachineCamera) with full status. Read this before using `manage_camera` to understand the current camera setup.
+
+**Returns:**
+```json
+{
+  "brain": {
+    "exists": true,
+    "gameObject": "Main Camera",
+    "instanceID": 55504,
+    "activeCameraName": "Cam_Cinematic",
+    "activeCameraID": -39420,
+    "isBlending": false
+  },
+  "cinemachineCameras": [
+    {
+      "instanceID": -39420,
+      "name": "Cam_Cinematic",
+      "isLive": true,
+      "priority": 50,
+      "follow": {"name": "CameraTarget", "instanceID": -26766},
+      "lookAt": {"name": "CameraTarget", "instanceID": -26766},
+      "body": "CinemachineThirdPersonFollow",
+      "aim": "CinemachineRotationComposer",
+      "noise": "CinemachineBasicMultiChannelPerlin",
+      "extensions": []
+    }
+  ],
+  "unityCameras": [
+    {
+      "instanceID": 55504,
+      "name": "Main Camera",
+      "depth": 0.0,
+      "fieldOfView": 50.0,
+      "hasBrain": true
+    }
+  ],
+  "cinemachineInstalled": true
+}
+```
+
+**Key Fields:**
+- `brain`: CinemachineBrain status — which camera is active, blend state
+- `cinemachineCameras`: All CinemachineCamera components with pipeline info (body, aim, noise, extensions)
+- `unityCameras`: All Unity Camera components with depth and FOV
+- `cinemachineInstalled`: Whether Cinemachine package is available
+
+**Use with:** `manage_camera` tool for creating/configuring cameras
+
+---
+
 ## Scene & GameObject Resources
 
 ### mcpforunity://scene/gameobject-api
diff --git a/unity-mcp-skill/references/tools-reference.md b/unity-mcp-skill/references/tools-reference.md
diff --git a/unity-mcp-skill/references/workflows.md b/unity-mcp-skill/references/workflows.md
