도구
Unreal MCP의 27가지 내장 도구 - RQL, Blueprint, C++ 소스, Python, 스크린샷, 콘솔 - 와 Unreal Editor에서 AI를 위한 예제 프롬프트.
이 페이지는 AI 에이전트가 Unreal MCP를 통해 Unreal Editor에서 무엇을 할 수 있는지 설명합니다. 플러그인은 7개 제품군에 걸쳐 27개의 도구를 제공합니다. 도구를 이름으로 호출하는 경우는 드뭅니다. 평범한 언어로 요청하면 에이전트가 도구를 고릅니다. 제품군을 알면 에이전트가 실제로 할 수 있는 일을 요청하는 데 도움이 됩니다.
도구별 카드와 매개변수는 Unreal 도구 카탈로그에서 확인하세요.
RQL: 편집기 데이터를 위한 하나의 쿼리 언어
Unreal MCP는 편집기 작업마다 도구가 하나씩 있지 않습니다. 대신 편집기 데이터는 RQL을 거칩니다. RQL은 한 번의 호출로 액터, 컴포넌트, 에셋, 레벨, 편집기 상태를 읽고 변경하는 쿼리 언어입니다.
| 도구 | 기능 |
|---|---|
rql-query | 라이브 편집기에 대한 읽기 전용 쿼리, 간결한 표 결과 |
rql-mutate | set 또는 call로 끝나는 쿼리; 전부 아니면 전무, 실행 취소 한 단계, dry_run 미리보기 |
rql-schema | 소스, 함수, 클래스를 나열합니다. 타입을 지정하면 해당 타입의 멤버와 메서드를 나열합니다. |
RQL이 어떤 모습인지 몇 가지 예시(에이전트가 대신 작성합니다):
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 스킬에서 이 언어를 배우며, 이 스킬에는 설치된 확장이 추가하는 내용도 나열됩니다.
예제 프롬프트:
- "레벨의 모든 포인트 라이트와 그 강도를 나열한 다음, 어두운 것들의 강도를 두 배로 늘려 줘."
- "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를 참고하세요.
스크린샷 계열
| 도구 | 하는 일 |
|---|---|
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을 참고하세요. 기능을 추가하려면 extensions를 설치하거나 custom tools을 작성하세요.
에디터 전용
27개 도구 모두 에디터를 제어합니다. 일부는 강력한 기능(rql-mutate, console-run-command, python-execute)이므로 어느 것도 패키징된 게임에 컴파일되지 않습니다. runtime connection을 선택한 게임은 자체적으로 등록한 도구만 노출합니다.
이 도구들을 최대한 활용하는 팁은 Unreal best practices에 있습니다.