# 도구 — Unreal Engine · AI Game Developer Wiki

Unreal MCP의 27가지 내장 도구 - RQL, Blueprint, C++ 소스, Python, 스크린샷, 콘솔 - 와 Unreal Editor에서 AI를 위한 예제 프롬프트.

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

이 페이지는 AI 에이전트가 Unreal MCP를 통해 Unreal Editor에서 무엇을 할 수 있는지 설명합니다. 플러그인은 **7개 제품군에 걸쳐 27개의 도구**를 제공합니다. 도구를 이름으로 호출하는 경우는 드뭅니다. 평범한 언어로 요청하면 에이전트가 도구를 고릅니다. 제품군을 알면 에이전트가 실제로 할 수 있는 일을 요청하는 데 도움이 됩니다.

도구별 카드와 매개변수는 [Unreal 도구 카탈로그](https://ai-game.dev/docs/tools/unreal)에서 확인하세요.

## RQL: 편집기 데이터를 위한 하나의 쿼리 언어

Unreal MCP는 편집기 작업마다 도구가 하나씩 있지 않습니다. 대신 편집기 데이터는 **RQL**을 거칩니다. RQL은 한 번의 호출로 액터, 컴포넌트, 에셋, 레벨, 편집기 상태를 읽고 변경하는 쿼리 언어입니다.

| 도구 | 기능 |
| --- | --- |
| `rql-query` | 라이브 편집기에 대한 읽기 전용 쿼리, 간결한 표 결과 |
| `rql-mutate` | `set` 또는 `call`로 끝나는 쿼리; 전부 아니면 전무, 실행 취소 한 단계, `dry_run` 미리보기 |
| `rql-schema` | 소스, 함수, 클래스를 나열합니다. 타입을 지정하면 해당 타입의 멤버와 메서드를 나열합니다. |

RQL이 어떤 모습인지 몇 가지 예시(에이전트가 대신 작성합니다):

```text
actors | where $ is PointLight | select $ref Label Intensity
actors | where Label == "Door_01" | set Location = "(0, 0, 100)"
editor | call SpawnActor("PointLight")
console | where Verbosity == "Error"
```

액터와 컴포넌트 외에도 RQL은 다음에 접근합니다:

- **에셋과 레벨:** 에셋 생성, 복사, 이동, 삭제, 가져오기, 폴더와 머티리얼 인스턴스 생성, 레벨 열기·생성·저장, 스트리밍 서브레벨 추가.
- **편집기 상태:** 선택, Play In Editor 상태, 실행 취소 기록, 편집기 로그.
- **DataTable:** 행 읽기 및 편집(`Rows["Sword"].Damage`), 행 추가, 제거, 이름 변경, 복제.
- **게임플레이 태그:** 태그 나열, 추가, 제거, 이름 변경.
- **Project Settings 및 Editor Preferences:** 설정 속성을 읽고 변경하며, 올바른 `.ini` 파일에 저장됩니다.
- **블루프린트 그래프:** 함수 호출, 변수, 이벤트, 캐스트, 분기, 루프 추가, 핀 연결, 그다음 `call Compile()`.
- **위젯 블루프린트:** 위젯 트리를 순회하고 편집, 위젯 추가 및 레이아웃 설정.
- **사용자 정의 구조체:** 필드 추가, 제거, 이름 변경.
- **레벨 시퀀스:** 액터 바인딩, 트랙과 키 추가.

모든 변경은 하나의 편집기 트랜잭션이므로 **Ctrl+Z**로 되돌릴 수 있습니다. 에이전트는 `unreal-rql` 스킬에서 이 언어를 배우며, 이 스킬에는 설치된 [확장](https://ai-game.dev/ko/docs/wiki/unreal/extensions)이 추가하는 내용도 나열됩니다.

예제 프롬프트:

- "레벨의 모든 포인트 라이트와 그 강도를 나열한 다음, 어두운 것들의 강도를 두 배로 늘려 줘."
- "5x4 그리드로 200 단위 간격의 큐브 20개를 스폰해 줘."
- "DT\_Weapons DataTable에 Damage 7인 Bow 행을 추가해 줘."
- "게임 기본 맵을 /Game/Maps/Arena로 설정해 줘."

## 블루프린트 제품군

블루프린트 작성은 Unreal의 주요 스크립팅 표면이며, 에이전트는 완전한 피드백 루프를 갖습니다: 생성, 편집, 컴파일, 오류 읽기, 수정.

| 도구 | 기능 |
| --- | --- |
| `blueprint-create` | 부모 클래스에서 블루프린트 클래스 생성 |
| `blueprint-get` | 블루프린트 요약: 변수, 컴포넌트, 함수, 이벤트, 부모 체인 |
| `blueprint-add-component` | 생성 스크립트에 컴포넌트 추가 |
| `blueprint-remove-component` | 컴포넌트 제거 |
| `blueprint-add-variable` | 타입이 지정된 멤버 변수 추가 |
| `blueprint-modify-variable` | 멤버 변수 변경 |
| `blueprint-set-default` | 클래스 기본값 속성 설정 |
| `blueprint-add-function` | 함수 스텁 추가 |
| `blueprint-add-event` | BeginPlay 또는 Tick 같은 이벤트 추가 |
| `blueprint-compile` | 컴파일하고 오류와 경고의 구조화된 목록 반환 |
| `blueprint-spawn` | 레벨에 블루프린트 인스턴스 배치 |

예: "정적 메시 컴포넌트와 bool 변수 IsOpen이 있는 액터 블루프린트 BP\_Door를 만들고, 컴파일한 뒤 원점에 하나 배치해 줘."

## 소스 / C++ 제품군

| 도구 | 기능 |
| --- | --- |
| `source-read` | 프로젝트 C++ 파일을 조각 단위로 읽기 |
| `source-create-class` | 새 C++ 클래스 스캐폴딩(헤더와 소스) |
| `source-update` | 소스 파일 편집 |
| `source-delete` | 소스 파일 삭제 |
| `source-list` | 모듈의 소스 파일 나열 |
| `source-compile` | Live Coding이 활성화되어 있으면 Live Coding으로, 아니면 Unreal Build Tool로 컴파일하고 구조화된 오류 보고서 반환 |

모든 파일 작업은 `<Project>/Source/`로 제한됩니다. 예: "MaxHealth와 TakeDamage 함수가 있는 C++ 컴포넌트 UHealthComponent를 만들고, 컴파일한 뒤 오류를 수정해 줘."

## Python 제품군

| 도구 | 기능 |
| --- | --- |
| `python-execute` | `unreal` 모듈이 미리 임포트된 상태로 편집기에서 Python 실행 |

마지막 표현식이 결과로 반환되고, `print` 출력은 로그로 돌아오며, 오류는 실패한 줄을 가리킵니다. `include`는 `<Project>/.ai-game-dev/snippets`에서 헬퍼 파일이나 폴더를 추가하고, `timeout`(기본 30초)은 폭주하는 스크립트를 중단시킵니다. 이 플러그인은 Unreal의 Python Editor Script Plugin을 활성화합니다. Python은 에디터 전용이며 패키징된 게임에 포함되지 않습니다. Blueprint 그래프 연결은 Python에 노출되지 않으므로, 그 작업에는 Blueprint 도구나 RQL을 사용하세요.

터미널에서 `unreal-mcp-cli exec`로 Python을 실행할 수도 있습니다. 자세한 내용은 [CLI reference](https://ai-game.dev/ko/docs/wiki/unreal/cli#exec)를 참고하세요.

## 스크린샷 계열

| 도구 | 하는 일 |
| --- | --- |
| `screenshot-viewport` | 활성 에디터 뷰포트 캡처 |
| `screenshot-game-view` | Play In Editor 게임 뷰 캡처 |
| `screenshot-camera` | 카메라 액터에서 렌더링 |
| `screenshot-isolated` | 액터 하나만 따로 렌더링 |

이미지는 모델이 볼 수 있는 PNG 콘텐츠로 반환되며, 기본 1024픽셀이고 한 변당 최대 2048픽셀입니다. GPU 기반 에디터가 필요하며, `-nullrhi`에서는 오류를 반환합니다. 예: "CameraActor\_Main에서 스크린샷을 찍고 조명이 너무 어두운지 알려줘."

## 콘솔 및 도구 목록

| 도구 | 하는 일 |
| --- | --- |
| `console-run-command` | Unreal 콘솔 명령을 실행하거나 콘솔 변수를 설정 |
| `unreal-tool-list` | 선택적 필터, 설명, 입력과 함께 숨겨진 도구를 포함한 모든 도구 나열 |

로그, Play In Editor 상태, 선택 항목 읽기는 RQL을 통해 이루어집니다.

## 에이전트가 볼 수 없는 도구

CLI와 앱을 위해 동작하는 몇 가지 **시스템 도구**는 AI 에이전트에게 표시되지 않습니다:

- `ping`: 플러그인, 브리지, 서버 체인을 확인합니다.
- `unreal-skill-generate`: 도구마다 하나의 `SKILL.md`를 스킬 폴더(기본 `.claude/skills`)에 작성합니다. **Generate skill files** 버튼이 이것을 사용합니다.
- `unreal-skill-create`: 플러그인의 에디터 모듈에 새 C++ 도구 파일을 생성합니다. 플러그인의 소스 설치와 도구가 동작하기 전 에디터 재빌드가 필요합니다.
- `editor-quit`: CLI 세션이 시작한 에디터를 저장하고 종료합니다.

## 프롬프트와 리소스

이 플러그인은 MCP 프롬프트 하나인 `level-design-brief`(테마로부터 만드는 레벨 디자인 브리프)와 리소스 두 개인 `unreal://project/levels`(활성 월드와 그 레벨들의 JSON 스냅샷), `unreal://project/icon`도 함께 제공합니다.

## 에이전트가 보는 항목 제어

필요 없는 도구는 **MCP Tools** 창에서 숨기거나, `UNREAL_MCP_TOOLS`로 고정된 집합만 제공할 수 있습니다. [Configuration](https://ai-game.dev/ko/docs/wiki/unreal/configuration#tool-visibility)을 참고하세요. 기능을 추가하려면 [extensions](https://ai-game.dev/ko/docs/wiki/unreal/extensions)를 설치하거나 [custom tools](https://ai-game.dev/ko/docs/wiki/unreal/custom-tools)을 작성하세요.

## 에디터 전용

27개 도구 모두 에디터를 제어합니다. 일부는 강력한 기능(`rql-mutate`, `console-run-command`, `python-execute`)이므로 어느 것도 패키징된 게임에 컴파일되지 않습니다. [runtime connection](https://ai-game.dev/ko/docs/wiki/unreal/custom-tools#runtime)을 선택한 게임은 자체적으로 등록한 도구만 노출합니다.

이 도구들을 최대한 활용하는 팁은 [Unreal best practices](https://ai-game.dev/docs/best-practices/unreal)에 있습니다.

---

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

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