# 도구와 RQL — Unity · AI Game Developer Wiki

Unity MCP를 통해 AI 에이전트가 Unity 에디터에서 할 수 있는 일 - RQL 쿼리와 변경, 스크린샷, C# 스크립트, 테스트, 패키지, 프로파일링.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/unity/tools-and-rql).

이 페이지는 Unity MCP가 연결된 후 AI 에이전트가 여러분의 Unity 프로젝트에서 무엇을 할 수 있는지 설명합니다: 어떤 도구를 볼 수 있는지, RQL로 에디터의 거의 모든 것을 어떻게 읽고 변경하는지, 그리고 어떤 도구가 설치되어 있지만 숨겨져 있는지 다룹니다. 매개변수를 포함해 검색 가능한 전체 목록은 [Unity 도구 카탈로그](https://ai-game.dev/docs/tools/unity)에 있고, 쿼리 언어는 [RQL 레퍼런스](https://ai-game.dev/docs/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` | 모든 도구와 에이전트가 해당 도구를 볼 수 있는지 여부를 나열합니다. |

짧은 목록은 토큰을 덜 소모하고 모델이 추론할 여유를 더 남겨 줍니다. 다른 도구들도 여전히 설치되어 있습니다. [숨겨진 도구](https://ai-game.dev/ko/docs/wiki/unity/tools-and-rql#hidden-tools)를 참고하세요.

## RQL: 에디터 전체를 위한 하나의 언어

RQL은 에디터의 실시간 데이터를 다루는 쿼리 언어입니다. 쿼리는 **소스**로 시작해 `|`로 구분된 단계들을 거치며 결과를 전달합니다. 단계에는 `where`, `select`, `get`, `set`, `call` 등이 있습니다. 작업마다 도구를 하나씩 두는 대신(예전의 `gameobject-create`, `scene-save`, `console-get-logs` 등 수십 개), 에이전트는 하나의 쿼리를 작성합니다.

열려 있는 씬의 전체 계층 구조를 읽습니다:

```text
roots | recurse children | select name active
```

플레이어를 찾습니다:

```text
objects | where name == "Player" | select path name active
```

바닥 평면을 생성합니다:

```text
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
```

컴포넌트를 추가하고 저장합니다:

```text
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()
```

Console에서 오류만 읽습니다:

```text
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")`로 검색합니다. 설치된 모든 [확장](https://ai-game.dev/ko/docs/wiki/unity/extensions)은 자체 소스와 타입을 추가합니다. 예를 들어 `tilemap`이나 `cinemachine`이 있습니다.

RQL은 리플렉션을 통해 동작하므로, 에이전트는 Unity 기본 컴포넌트뿐 아니라 여러분이 직접 만든 컴포넌트의 멤버도 읽고 설정할 수 있습니다. [사용자 정의 어댑터](https://ai-game.dev/docs/rql/custom-adapters)로 RQL에 여러분의 타입을 알려 줄 수 있습니다.

## 스크립트와 C# 실행

`script-execute`는 Roslyn으로 C# 스니펫을 컴파일하고 에디터에서 실행합니다. 코드와 함께 선택적으로 `className`, `methodName`, 추가 `usings`, `include`할 헬퍼 파일을 받습니다. RQL이 다루지 못하는 모든 것을 위한 탈출구입니다. 터미널에서는 `unity-mcp-cli exec`가 같은 도구를 호출합니다:

```bash
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 로그의 포함 여부를 제어하므로 출력이 작게 유지됩니다.

```bash
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` 도구로, 또는 다음 방법으로 표시할 수 있습니다:

```bash
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`: RQL `call` 및 `rql-schema`.
- `profiler-*`: `profiler` 소스.

## 관련 페이지

- [Unity 도구 카탈로그](https://ai-game.dev/docs/tools/unity) 및 [RQL 레퍼런스](https://ai-game.dev/docs/rql).
- 나만의 도구를 추가하려면 [사용자 정의 도구](https://ai-game.dev/ko/docs/wiki/unity/custom-tools).
- 프롬프트 작성을 위한 [Unity 모범 사례](https://ai-game.dev/docs/best-practices/unity).

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/unity/tools-and-rql

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/unity/tools-and-rql