도구와 RQL
Unity MCP를 통해 AI 에이전트가 Unity 에디터에서 할 수 있는 일 - RQL 쿼리와 변경, 스크린샷, C# 스크립트, 테스트, 패키지, 프로파일링.
이 페이지는 Unity MCP가 연결된 후 AI 에이전트가 여러분의 Unity 프로젝트에서 무엇을 할 수 있는지 설명합니다: 어떤 도구를 볼 수 있는지, RQL로 에디터의 거의 모든 것을 어떻게 읽고 변경하는지, 그리고 어떤 도구가 설치되어 있지만 숨겨져 있는지 다룹니다. 매개변수를 포함해 검색 가능한 전체 목록은 Unity 도구 카탈로그에 있고, 쿼리 언어는 RQL 레퍼런스에 문서화되어 있습니다.
에이전트가 기본적으로 보는 도구
버전 1.0.0부터 플러그인은 에이전트의 도구 목록을 짧게 유지합니다. 설치 후 다음 일곱 가지 도구가 표시됩니다:
| 도구 | 하는 일 |
|---|---|
rql-query | RQL 쿼리로 에디터 데이터를 읽습니다: 씬, GameObject, 컴포넌트, 에셋, Console, 설정, 테스트, 프로파일러. |
rql-mutate | RQL로 에디터 데이터를 변경하거나 에디터 작업을 호출합니다: 오브젝트와 에셋 생성, 수정, 이동, 삭제, 씬 열기 및 저장. |
rql-schema | RQL이 사용할 수 있는 소스, 타입, 멤버, 호출을 설명하고 토픽 가이드를 출력합니다. 에이전트는 확실하지 않을 때 여기서 시작합니다. |
script-execute | Roslyn으로 에디터에서 C# 코드를 컴파일하고 실행한 뒤 결과를 반환합니다. |
screenshot-isolated | 선택한 각도에서 하나의 GameObject를 격리해 렌더링하며, 선택적으로 2x2 합성 이미지로 만들어 모델이 그것을 볼 수 있게 합니다. |
tests-run | EditMode 또는 PlayMode 테스트를 실행하고 테스트별 결과를 반환합니다. |
unity-tool-list | 모든 도구와 에이전트가 해당 도구를 볼 수 있는지 여부를 나열합니다. |
짧은 목록은 토큰을 덜 소모하고 모델이 추론할 여유를 더 남겨 줍니다. 다른 도구들도 여전히 설치되어 있습니다. 숨겨진 도구를 참고하세요.
RQL: 에디터 전체를 위한 하나의 언어
RQL은 에디터의 실시간 데이터를 다루는 쿼리 언어입니다. 쿼리는 소스로 시작해 |로 구분된 단계들을 거치며 결과를 전달합니다. 단계에는 where, select, get, set, call 등이 있습니다. 작업마다 도구를 하나씩 두는 대신(예전의 gameobject-create, scene-save, console-get-logs 등 수십 개), 에이전트는 하나의 쿼리를 작성합니다.
열려 있는 씬의 전체 계층 구조를 읽습니다:
roots | recurse children | select name active플레이어를 찾습니다:
objects | where name == "Player" | select path name active바닥 평면을 생성합니다:
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})컴포넌트를 추가하고 저장합니다:
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()Console에서 오류만 읽습니다:
console | where logType == "Error"각 rql-mutate 호출은 하나의 Undo 그룹이므로 Ctrl+Z로 되돌릴 수 있으며, 변경된 에셋과 씬, 열려 있는 프리팹은 변경 후 저장됩니다. rql-mutate는 또한 dry_run으로 무엇이 변경될지 미리 보고, max_targets로 하나의 변경이 건드릴 수 있는 오브젝트 수를 제한할 수 있습니다.
Unity의 RQL 소스
| 소스 | 내용 |
|---|---|
scenes, roots, objects | 로드된 씬, 각 씬의 루트 GameObject, 그리고 그 안의 모든 GameObject. |
selection | 현재 에디터 선택 항목. |
prefab | 프리팹 모드에서 열려 있는 프리팹. |
editor | 에디터 작업: GameObject, 머티리얼, 폴더, 씬 생성; 씬과 프리팹 열기 및 저장; 에셋 복사, 이동, 삭제; 메뉴 항목 실행; 플레이 모드 상태. |
settings | 프로젝트 설정. |
console | 캡처된 에디터 로그 항목. |
shaders, componentTypes | 사용 가능한 셰이더와 컴포넌트 타입. |
tests, testResults | 테스트 트리와 마지막 결과. |
profiler | 메모리, 렌더링, 스크립트, 프레임 데이터; 캡처 시작, 중지, 저장, 불러오기. |
lighting | 활성 씬의 환경(앰비언트, 안개, 스카이박스, 태양, 반사), Lighting Settings 및 베이크. |
에셋은 unity.asset("Assets/…")로 경로를 지정하거나 unity.assets("t:Material")로 검색합니다. 설치된 모든 확장은 자체 소스와 타입을 추가합니다. 예를 들어 tilemap이나 cinemachine이 있습니다.
RQL은 리플렉션을 통해 동작하므로, 에이전트는 Unity 기본 컴포넌트뿐 아니라 여러분이 직접 만든 컴포넌트의 멤버도 읽고 설정할 수 있습니다. 사용자 정의 어댑터로 RQL에 여러분의 타입을 알려 줄 수 있습니다.
스크립트와 C# 실행
script-execute는 Roslyn으로 C# 스니펫을 컴파일하고 에디터에서 실행합니다. 코드와 함께 선택적으로 className, methodName, 추가 usings, include할 헬퍼 파일을 받습니다. RQL이 다루지 못하는 모든 것을 위한 탈출구입니다. 터미널에서는 unity-mcp-cli exec가 같은 도구를 호출합니다:
unity-mcp-cli exec 'Application.unityVersion'코드를 실행하는 대신 파일을 작성하려면 숨겨진 도구 script-read, script-update-or-create, script-delete가 프로젝트의 .cs 파일을 관리합니다. 변경 후 Unity가 재컴파일하며, 도메인 리로드 동안 연결이 잠시 끊겼다가 저절로 복구됩니다.
테스트
tests-run은 EditMode 또는 PlayMode 테스트를 실행합니다(testMode, 기본값 EditMode). 어셈블리, 네임스페이스, 클래스 또는 메서드로 필터링하거나, tests 소스에 대한 RQL 선택을 전달해 원하는 테스트만 한 번의 실행으로 정확히 실행할 수 있습니다. 결과는 testResults에 대한 RQL로 필터링할 수 있습니다. 옵션을 통해 통과한 테스트, 메시지, 스택 트레이스, Console 로그의 포함 여부를 제어하므로 출력이 작게 유지됩니다.
unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'스크린샷
screenshot-isolated는 기본적으로 표시됩니다. 세 가지는 숨겨져 있습니다: screenshot-scene-view, screenshot-game-view, screenshot-camera. 이미지는 MCP 전송을 통과할 수 있도록 가장 긴 변이 3840픽셀로 제한됩니다. 스크린샷에는 그래픽 장치가 필요합니다: -nographics로 시작된 Editor는 빈 이미지 대신 오류를 반환합니다.
숨겨진 도구
이 도구들은 설치되어 있지만 에이전트의 목록에는 없습니다. 숨겨진 도구도 이름으로 호출하면 여전히 실행됩니다.
- 스크린샷:
screenshot-scene-view,screenshot-game-view,screenshot-camera. - 스크립트:
script-read,script-update-or-create,script-delete. - 패키지: Unity Package Manager용
package-list,package-search,package-add,package-remove. - 도구 관리:
tool-set-visibility및 사용 중단된 별칭tool-set-enabled-state.
AI Game Developer 창(Tools > Open)에서, tool-set-visibility 도구로, 또는 다음 방법으로 표시할 수 있습니다:
unity-mcp-cli configure ./MyUnityProject --enable-tools package-add,package-list프롬프트와 스킬
이 플러그인은 또한 여섯 그룹(스크립팅, GameObject와 컴포넌트, 씬, 디버깅과 테스트, 에셋 관리, 애니메이션과 타임라인)으로 46개의 MCP 프롬프트(setup-basic-scene 또는 add-event-system 같은 슬래시 명령 템플릿)를 제공합니다. 기본적으로 숨겨져 있으며, 원하는 것을 Prompts > Open에서 활성화하세요.
Skills는 플러그인이 에이전트의 스킬 폴더에 생성하는 Markdown 파일입니다. 여기에는 Unity와 설치된 모든 확장에 대한 RQL 문법을 담은 unity-rql 가이드와 설정 및 CLI 노트가 포함됩니다. 창의 Skills > Auto-generate에서 켜거나 unity-mcp-cli setup-skills <agent>를 실행하세요.
이전 튜토리얼의 도구 이름
버전 1.0.0에서는 액션당 하나의 도구를 제공하던 도구들이 제거되었습니다. 튜토리얼에서 그중 하나를 언급한다면 대신 RQL을 사용하세요:
gameobject-create,gameobject-find,gameobject-modify,gameobject-destroy,gameobject-component-*:set및call과 함께objects,roots,selection에 대한 RQL.scene-create,scene-open,scene-save:editor | call NewScene(…),OpenScene(…),SaveScenes().assets-*,assets-prefab-*,assets-material-create:unity.asset(…),unity.assets(…)및CreateMaterial,CopyAsset,InstantiatePrefab같은editor호출.console-get-logs,console-clear-logs:console소스 및editor | call ClearConsole().editor-application-*,editor-selection-*:isPlaying및selection같은editor멤버.reflection-method-find,reflection-method-call,type-get-json-schema: RQLcall및rql-schema.profiler-*:profiler소스.
관련 페이지
- Unity 도구 카탈로그 및 RQL 레퍼런스.
- 나만의 도구를 추가하려면 사용자 정의 도구.
- 프롬프트 작성을 위한 Unity 모범 사례.