# Unity MCP Orchestrator (project-scoped)

Entry point for any work that drives the Unity Editor through MCP. Encodes project facts so agents do not have to rediscover them each turn.

## When to use
Load before any `mcp__UnityMCP__*` call, or when reasoning about whether a change is bounded or destructive.

## Project facts (do not rediscover)

- **Unity version**: 2022.3.25f1 (LTS).
- **Render pipeline**: URP 14.0.11 (not HDRP). URP assets in `Assets/Settings/URP-*.asset`.
- **MCP bridge**: `com.coplaydev.unity-mcp`. Tool prefix: `mcp__UnityMCP__`.
- **Active emulation scene**: `Assets/Scenes/LaparoscopicSurgeryEmulation.unity`.
- **Authored root hierarchy** (do not rename or move):
  - `SurgeryBenchmark/Shared/AnatomySlot`
  - `SurgeryBenchmark/Shared/CavitySlot`
  - `SurgeryBenchmark/Shared/InstrumentSlot`
  - `SurgeryBenchmark/Scenarios/Scenario_01_CleanTissue` (active by default)
  - `SurgeryBenchmark/Scenarios/Scenario_02_WetSpecular` (inactive)
  - `SurgeryBenchmark/Scenarios/Scenario_03_LowTexture` (inactive)
  - `SurgeryBenchmark/Scenarios/Scenario_04_PartialOcclusion` (inactive)
  - `SurgeryBenchmark/Scenarios/Scenario_05_InstrumentOcclusion` (inactive)
- **Preserved from `MainScene`**: stereo rig, `Blending`, UI, WebRTC objects, RPC objects.
- **Off-limits scripts**: `Rotator.cs`, `BlendShaderController.cs`, `DepthGetter.cs`, `DepthRenderPassFeature.cs`, `DepthTester.cs`, `TexturesSettings.cs`, `WEBRTCSender.cs`, `CrpcApi.cs`, `MinimalRpcServer.cs`, plus `Assets/Scripts/UDP/`, `Assets/Scripts/VideoChat/`, `Assets/Scripts/Editor/`.
- **Material inventory** (`Assets/Materials/LaparoscopicBenchmark/`): `CavityWall.mat`, `InstrumentProxy.mat`, `Tissue_Default.mat`, `Tissue_LowTexture.mat`, `Tissue_Wet.mat`.
- **Texture inventory** (`Assets/Textures/LaparoscopicBenchmark/`): `TissueMucosa.png`.
- **Model inventory** (`Assets/Models/`): `FabOrgans/stylizeddigestivesystem.fbx`, `organs/archive.fbx`.
- **Render-pipeline assets** (`Assets/Settings/`): `URP-Balanced.asset`, `URP-HighFidelity.asset`, `URP-Performant.asset`, `SampleSceneProfile.asset` (Volume profile), `TexturesSettings.asset`.
- **Shaders**: `Assets/Shaders/RenderDepth.shader`, `Assets/Shaders/BlendShader.compute` — leave alone unless explicitly approved.

## MCP tool discipline

1. **Inspect first.** Before any mutation, run read-only tools:
   - `mcp__UnityMCP__find_gameobjects` to locate authored roots.
   - `mcp__UnityMCP__manage_scene(action="get_hierarchy")` to confirm the live scene.
   - `mcp__UnityMCP__manage_graphics(action="pipeline_get_info")` to confirm URP asset.
   - `mcp__UnityMCP__read_console(types=["error","warning"])` for pre-existing errors.
2. **Propose a bounded change.** One parent container, one material variant, one Volume override, one prefab edit, one script change. Anything more is not bounded.
3. **Execute, then verify.** Re-read affected objects, `read_console`, screenshot.

## Bounded vs destructive (cheat sheet)

| Change class | Examples | Required step |
|---|---|---|
| Read-only | find, get_hierarchy, get_material_info, screenshot | None — just run |
| Bounded write | rename one GameObject, set one material property, add one Volume override, toggle one scenario root | State the change in one sentence, then run |
| Destructive | delete objects/assets, replace URP asset, rename scenario roots, move stereo rig, edit off-limits scripts, modify `Packages/manifest.json` | **Stop. Ask for explicit approval.** |

## Cross-tool composition patterns

- Group read-only inspection with `batch_execute`.
- Script edits: prefer `script_apply_edits` over `apply_text_edits`. Wait for `is_compiling == false`, then `read_console`.
- Material edits: use `set_material_shader_property` (numeric/enum), `set_material_color` (colors), `assign_material_to_renderer` (binding).
- Volume edits: `volume_add_effect` (if missing) then `volume_set_effect`.
- Scene saves: only after a verified bounded change.

## Handoff format

```
ROLE: <agent name>
OBSERVED: <what inspection found>
CHANGED: <exact objects/assets/settings modified>
NOT CHANGED: <intentionally left alone>
RISKS: <at least one item>
NEXT SAFE OPTIONS: <bounded suggestions>
```