c51e6d1369
:Release Notes: - Agents files for opencode and claude - Skills for opencode and claude - 3d models with medical organs - Some textures :Detailed Notes: - :Testing Performed: - :QA Notes: - Looks like shit :) :Issues Addressed: TG-1
104 lines
9.0 KiB
Markdown
104 lines
9.0 KiB
Markdown
---
|
|
name: unity-mcp-orchestrator
|
|
description: Orchestrate Unity Editor operations through the Coplay Unity MCP bridge in this project. Use when an agent needs to inspect, create, or modify scene content, scripts, materials, prefabs, or render settings. Provides project-specific URP facts, the SurgeryBenchmark scene contract, MCP tool discipline, and the inspect → propose → verify loop.
|
|
---
|
|
|
|
# Unity MCP Orchestrator (project-scoped)
|
|
|
|
This skill is the entry point for any agent that needs to drive the Unity Editor through MCP. It is project-specific: it encodes the facts of this repository (Unity 2022.3.25f1, URP 14.0.11, the `LaparoscopicSurgeryEmulation` scene, the `SurgeryBenchmark/*` authoring contract) so agents do not have to rediscover them on every turn.
|
|
|
|
## When to load
|
|
|
|
Load this skill whenever an agent:
|
|
- Is about to call any `mcp__unity__*` tool (`manage_gameobject`, `manage_components`, `manage_material`, `manage_scene`, `manage_prefabs`, `manage_graphics`, `manage_camera`, `manage_script`, `script_apply_edits`, `validate_script`, `read_console`, `refresh_unity`, `run_tests`, `manage_profiler`, `batch_execute`, `find_gameobjects`, `execute_menu_item`, `execute_code`).
|
|
- Needs to reason about whether a change is bounded or destructive.
|
|
- Needs the canonical handoff format for cross-agent communication.
|
|
|
|
## Project facts (do not rediscover)
|
|
|
|
- **Unity version**: 2022.3.25f1 (LTS).
|
|
- **Render pipeline**: **URP 14.0.11** (not HDRP). URP assets live in `Assets/Settings/URP-*.asset`. Do not propose HDRP features (volumes, planar reflection probes, ray-traced reflections, exposure in physical units) — translate to URP equivalents (Volume profile + overrides, reflection probe `Refresh Mode = Via Scripting`, post-processing via `PostProcessing` Volume overrides).
|
|
- **MCP bridge**: `com.coplaydev.unity-mcp` installed from git via `Packages/manifest.json`. Coplay bridge runs inside the Editor.
|
|
- **Active emulation scene**: `Assets/Scenes/LaparoscopicSurgeryEmulation.unity`.
|
|
- **Authored root hierarchy** (do not rename, do not move camera objects):
|
|
- `SurgeryBenchmark/Shared`
|
|
- `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`** and not to be edited without approval: stereo rig, `Blending`, UI, WebRTC objects, RPC objects.
|
|
- **Off-limits scripts** (modify only with explicit approval): `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` (the canonical PBR base for tissue; check its import settings — sRGB on, normal map not needed unless authored).
|
|
- **Model inventory** (`Assets/Models/`): `FabOrgans/stylizeddigestivesystem.fbx` (stylized, has diffuse + normal + roughness PNGs), `organs/archive.fbx` (has its own `Materials/`, `source/`, `textures/`, `archive.fbm/`). The two are not interchangeable.
|
|
- **Render-pipeline assets** (`Assets/Settings/`): `URP-Balanced.asset`, `URP-Balanced-Renderer.asset`, `URP-HighFidelity.asset`, `URP-HighFidelity-Renderer.asset`, `URP-Performant.asset`, `URP-Performant-Renderer.asset`, `SampleSceneProfile.asset` (Volume profile), `TexturesSettings.asset`.
|
|
- **Shaders**: `Assets/Shaders/RenderDepth.shader`, `Assets/Shaders/BlendShader.compute`, `Assets/Shaders/Hidden_RenderDepth.mat` — leave alone unless a bounded change statement is approved.
|
|
|
|
## MCP tool discipline (read-only by default)
|
|
|
|
1. **Inspect first.** Before any mutation, run read-only tools:
|
|
- `find_gameobjects` to locate the authored roots.
|
|
- `manage_scene` with `action=get_hierarchy` to confirm the live scene.
|
|
- `manage_graphics` with `action=pipeline_get_info` to confirm URP is active and which URP asset is current.
|
|
- `read_console` with `types=["error","warning"]` to see if prior edits left residue.
|
|
2. **Propose a bounded change.** A bounded change is: one parent container, one material variant, one camera component tweak, one Volume override, one prefab edit. Anything that touches more than one authored root, more than one URP asset, or any of the "off-limits" objects is **not** bounded.
|
|
3. **Execute, then verify.** Run the change, then re-read the affected objects and `read_console` for errors. Capture a screenshot through `manage_camera(action="screenshot")` for any visual change.
|
|
|
|
## Bounded vs destructive (cheat sheet)
|
|
|
|
| Change class | Examples | Required step |
|
|
|---|---|---|
|
|
| Read-only | find, get_hierarchy, get_material_info, pipeline_get_info, screenshot | None — just run |
|
|
| Bounded write | rename one GameObject, set one material property, add one Volume override, activate/deactivate one scenario root, instantiate a prefab into one slot | State the change in one sentence, then run |
|
|
| Destructive | delete objects, delete assets, replace URP asset, rename scenario roots, move camera/stereo rig, edit off-limits scripts, modify `Packages/manifest.json` | **Stop. Ask for explicit approval.** |
|
|
|
|
## Cross-tool composition patterns
|
|
|
|
- **Apply one coherent change set at a time.** Use `batch_execute` to group read-only inspection or to apply a bounded write (e.g., assign the same material to N children in one batch).
|
|
- **Script edits**: prefer `script_apply_edits` (structured) over `apply_text_edits` (raw). `create_script`, `script_apply_edits`, and `apply_text_edits` already trigger `AssetDatabase.ImportAsset` + `RequestScriptCompilation` — do **not** call `refresh_unity` immediately after, just wait for `is_compiling == false` on `mcpforunity://editor/state` and then `read_console`.
|
|
- **Material edits**: `manage_material(action="set_material_shader_property")` for numeric/enum, `set_material_color` for colors, `assign_material_to_renderer` for binding, `create` for new materials. Always pass `material_path` as `Assets/...` and re-read with `get_material_info` to confirm.
|
|
- **Volume/profile edits**: `manage_graphics(action="volume_set_effect", effect="Bloom"|"Vignette"|... )` to set override parameters. For URP, the override type names are the URP package's `VolumeComponent` types (e.g., `Bloom`, `Vignette`, `DepthOfField`, `MotionBlur`, `Tonemapping`, `ColorAdjustments`, `ChromaticAberration`, `FilmGrain`, `LensDistortion`).
|
|
- **Scene management**: `manage_scene(action="get_active"|"load"|"save")`. Save only after a verified bounded change.
|
|
|
|
## Handoff format (required for any multi-agent work)
|
|
|
|
After any action, emit this block (see `change-reporting-handoff` skill for the full template):
|
|
|
|
```
|
|
ROLE: <which agent>
|
|
OBSERVED: <what the inspection found>
|
|
CHANGED: <exact objects/assets/settings modified>
|
|
NOT CHANGED: <what was intentionally left alone>
|
|
RISKS: <visual / technical / performance / safety / uncertainty>
|
|
NEXT SAFE OPTIONS: <one-sentence suggestions for the next agent>
|
|
```
|
|
|
|
## Anti-patterns to refuse
|
|
|
|
- Suggesting HDRP-specific code (ray-traced reflections, planar reflection probes, path tracer) on a URP project.
|
|
- Renaming `SurgeryBenchmark/Scenarios/Scenario_0X_*` roots or the slot anchors.
|
|
- Moving the stereo rig, `Blending`, UI, WebRTC, or RPC objects.
|
|
- Bulk-editing URP assets without a per-asset bounded change statement.
|
|
- Generating clinical/anatomical/operative instructions, claims of medical accuracy, or "do this surgery" steps. See `medical-simulation-safety` skill.
|
|
- Modifying `Packages/manifest.json` or any `*.csproj` / `.sln` file directly.
|
|
- Claiming a fix is correct without `read_console` + visual verification.
|
|
|
|
## Quick reference: which skill pairs with which MCP tool
|
|
|
|
| MCP tool | Pair with |
|
|
|---|---|
|
|
| `manage_scene` (get_hierarchy, get_active) | `unity-hierarchy-hygiene` |
|
|
| `manage_gameobject` (create, modify, delete) | `unity-hierarchy-hygiene` |
|
|
| `manage_components` | `unity-hierarchy-hygiene` + the domain skill (camera, light, material) |
|
|
| `manage_material` | `pbr-materials-tissue` |
|
|
| `manage_graphics` (volume_*, pipeline_*, skybox_*, bake_*) | `urp-render-pipeline` |
|
|
| `manage_camera` (screenshot, set_lens, create_camera) | `cinematic-laparoscope-camera` |
|
|
| `manage_prefabs` (create_from_gameobject, modify_contents) | `unity-hierarchy-hygiene` |
|
|
| `create_script`, `script_apply_edits`, `apply_text_edits`, `validate_script` | `unity-mcp-orchestrator` (this file) + `medical-simulation-safety` |
|
|
| `read_console`, `refresh_unity`, `run_tests`, `manage_profiler` | `realtime-performance-budget` |
|
|
| `find_gameobjects`, `execute_menu_item`, `execute_code` | `unity-mcp-orchestrator` (this file) |
|