<div align="center">
VibeUE — AI 기반 Unreal Engine 개발
🧩 MCP 확장 + Unreal Engine 5.8+용 AI 에디터 도구 세트
Unreal Engine
MCP
License: MIT
Discord
Donate
</div>
VibeUE는 Unreal Engine 5.8+를 위한 MCP 확장 및 AI 에디터 도구 세트입니다. Unreal 5.8은 내장된 MCP 서버와 AI 도구 세트를 추가했으며, VibeUE는 이들에 직접 연결되는 **MCP 확장(MCP Expansion)**이자 깊이 있는 **AI 에디터 도구 세트(AI Editor Toolset)**를 제공합니다. 이 도구 세트는 Blueprints, materials, landscape, foliage, animation, Niagara, UMG, audio, StateTree, Behavior Trees & Blackboards, gameplay tags, input, UVs, 성능/프로파일링(performance/profiling) 등 에디터 기능 라이브러리를 포함하며, 이 모든 것이 엔진 자체의 ToolsetRegistry와 ModelContextProtocol 서버에 등록됩니다. 또한 Unreal의 네이티브 AgentSkill 시스템을 통해 풍부한 도메인 **기술(skills)**도 제공합니다. MCP 기능을 갖춘 어떤 에이전트(Claude Code, Cursor, Copilot 등)라도 Unreal의 표준 MCP 엔드포인트를 통해 사용자의 에디터를 구동할 수 있습니다.
⚠️ VibeUE를 사용하려면 먼저 Unreal의 네이티브 MCP가 설정되어야 합니다. Unreal MCP 플러그인(자동으로 Toolset Registry 활성화)과 Editor Tools 플러그인을 활성화한 후, MCP 서버를 시작하십시오. Epic의 가이드라인을 따르세요: Unreal Editor에서 Unreal MCP.
VibeUE는 이 엔드포인트를 확장합니다 — 별도의 서버나 에디터 내 채팅이 필요 없습니다. 무료 API 키( Editor Preferences → Plugins → VibeUE에 설정)를 사용하면 실제 세계의 지형(terrain) 도구를 사용할 수 있으며, 그 외 모든 기능은 API 키 없이도 작동합니다.
✨ VibeUE가 추가하는 것
Unreal 5.8 자체적으로 AI 도구 세트(Blueprints, materials, actors, assets, meshes, data tables 등)를 제공합니다. VibeUE는 이것들을 보완하며 — 엔진이 다루지 않는 영역과 깊이에 초점을 맞춥니다:
- 지형 및 월드(Terrain & world) — 지형 조각/높이맵/스플라인, 지형 자동 머티리얼 + RVT, 식생, 절차적 FPS 맵 블록아웃, 그리고 실제 세계 지형 (높이맵 + GPS 기반 물).
- 오디오(Audio) — MetaSound 및 SoundCue 그래프 작성.
- 애니메이션 에셋(Animation assets) — AnimSequence 키프레임 편집, AnimMontage 작성, AnimBP 상태 머신, 스켈레톤 본/소켓/리타겟/블렌드 프로파일 편집.
- FX 심화(FX depth) — Niagara 이미터 색상/커브 작성 및 사용자 정의 HLSL 스크래치패드 모듈.
- UI — MVVM 바인딩을 사용한 UMG 위젯, 애니메이션 작성, 그리고 미리보기/PIE 검증.
- 고차원 블루프린트 작성(Higher-order Blueprint authoring) — 타임라인, 이벤트 디스패처, 델리게이트, 사용자 정의 이벤트 핀, 주석 상자, 그리고 일괄
build_graph 빌더.
- AI 행동 작성(AI behavior authoring) — 구조적 경로를 통한 Behavior Tree 노드/데코레이터/서비스 편집과 블랙보드 키 바인딩, JSON 트리 라운드 트립, 검증/수정; 전체 Blackboard 에셋 + 키 CRUD. 쓰기는 PIE 및 오픈 에디터 인식 거부 가드를 가진 에디터 EdGraph를 통해 이루어짐.
- 에디터 안전성(Editor safety) —
TransactionService는 에디터의 트랜잭션 버퍼(실행 취소/다시 실행/체크포인트)를 감싸서 에이전트가 자체 편집을 그룹화하고 롤백할 수 있게 함—엔진의 도구 세트는 이를 노출하지 않음.
- 검증된 워크플로우(Verified workflows) —
WorkflowService는 권위 있는 엔진/빌드 매니페스트, 영향을 받는 에셋 출처가 포함된 영속적인 작업 저널, 비동기 PIE 시나리오(컴파일 → 입력 → 주장 → 캡처 → 보장된 정리), 그리고 드라이-런 우선의 재개 가능한 대규모 유지보수를 추가함.
- ⚡ 성능 및 프로파일링(Performance & profiling) — VibeUE의 강점: 아래 전용 섹션을 확인하세요.
- Python 기반 접근(Python-first access) — 에디터에서 모든
unreal.* Python을 실행하고 전체 API를 인트로스펙트할 수 있음.
- 웹 리서치(Web research) — 컨텍스트 내 연구 및 지형 워크플로우를 위한 검색/가져오기/지리 코딩 서비스.
이는 엔진의 일반적인 도구들(기본 에셋/액터/블루프린트/머티리얼 CRUD, 스크린샷, 로그, PIE)을 중복하지 않음—에이전트는 해당 용도로 Unreal의 네이티브 도구 세트를 사용함.
⚡ 성능 및 프로파일링 (핵심 기능)
Unreal의 네이티브 AI 도구 세트는 성능 측정 도구가 전무합니다 — PIE/Simulate를 시작할 수는 있지만 아무것도 측정할 수 없습니다. VibeUE의 PerformanceService는 이 격차를 메워 에이전트가 프레임 속도를 실제로 진단하고 수정할 수 있게 합니다:
frame_timing() — 게임/렌더/GPU/RHI 스레드 분할 + CPU 대 GPU 바운드 판정 및 구체적인 다음 단계 힌트. 이것을 먼저 실행하세요 — CPU에 바운드된 프레임에서는 GPU를 최적화해도 아무 소용이 없습니다.- Unreal Insights 캡처 —
start_trace / stop_trace / get_trace_status, 그리고 bookmark 및 region_start / region_end 마커.
analyse() — 트레이스 및 로그를 읽어 성능 요약(프레임 통계, 최악의 프레임, 끊김 현상, 주목할 만한 로그 라인)을 반환합니다.- 트레이스 연결
start_standalone — 에디터 뷰포트뿐만 아니라 대표적인 독립 실행형 빌드를 프로파일링합니다.
import unreal
print(unreal.PerformanceService.frame_timing())
unreal.PerformanceService.start_trace("cap", "")
...
profiling 및 frame-rate 스킬과 결합하여 전체적인 CPU/GPU 심층 분석을 수행할 수 있습니다.
🏗️ 아키텍처
VibeUE는 세 가지 네이티브 UE 5.8+ 시스템에 연결됩니다:
- 도구 세트 (Toolsets) (
ToolsetRegistry) — VibeUE의 서비스들은 UToolsetDefinition으로 등록되어, 그 메서드들이 MCP 엔드포인트에서 AICallable 도구가 됩니다. 또한 이들은 BlueprintCallable이므로, 동일한 메서드를 Python에서 unreal.<Name>Service.<method>()로 호출할 수 있습니다.
- MCP 서버 (
ModelContextProtocol) — 소수의 VibeUE 유틸리티 도구들이 엔드포인트에 직접 등록됩니다: execute_python_code, discover_python_module/_class/_function, list_python_subsystems, deep_research, terrain_data.
- 스킬 (Skills) (
AgentSkillToolset) — 약 36개의 마크다운 스킬 팩이 네이티브 UAgentSkill로 등록되며, 이는 ListSkills를 통해 발견되고 엔진 자체의 스킬과 함께 GetSkills을 통해 지연 로딩됩니다.
효율적인 사용 (에이전트용): execute_python_code가 핵심 작업 도구입니다. 이 도구는 전체 다단계 작업을 한 번의 왕복(round-trip)으로 배치 처리하며, 모든 VibeUE 서비스와 완전한 unreal.* API에 접근할 수 있습니다. call_tool은 스킬이나 Python 경로가 없는 몇몇 엔진 툴셋(스크린샷 등)에만 사용하세요. 전체 에이전트 가이드는 Content/samples/AGENTS.md.sample를 참조하십시오.
🚀 설치 및 설정
필수 사항: Unreal Engine 5.8 이상 · Git
단계 1 — Unreal의 네이티브 MCP 설정 (가장 먼저 수행)
VibeUE는 Unreal에 내장된 MCP 지원을 확장한 것이므로, 이 기능을 먼저 활성화해야 합니다. 자세한 내용은 Epic의 가이드: **Unreal Editor에서 Unreal MCP**를 참조하십시오.
- 편집(Edit) → 플러그인(Plugins) → Unreal MCP 활성화 (이것은 자동으로 Toolset Registry도 활성화함) 및 에디터 도구(Editor Tools) 활성화 (엔진 자체의 AI 툴셋이므로 에이전트가 둘 다 사용하게 됩니다). 이들은 실험적(Experimental) 기능입니다. 요청 시 재시작하십시오.
- 편집(Edit) → 에디터 환경 설정(Editor Preferences) → 일반(General) → 모델 컨텍스트 프로토콜(Model Context Protocol) → 자동 서버 시작(Auto Start Server) 활성화 (또는 콘솔 명령어
ModelContextProtocol.StartServer 실행). 기본 엔드포인트는 http://127.0.0.1:8000/mcp입니다 (포트/경로 설정 가능). **툴 검색(Tool Search)**을 활성화하면 에이전트의 컨텍스트가 작게 유지됩니다. 이는 list_toolsets / describe_toolset / call_tool만 보고 필요할 때 툴을 로드하기 때문입니다.
단계 2 — VibeUE 설치
프로젝트 내 플러그인 폴더로 이동합니다.
cd /path/to/YourProject/Plugins
git clone https://github.com/kevinpbuckley/VibeUE.git
프로젝트 스크립트를 사용하여 빌드합니다:
Plugins/VibeUE/BuildAndLaunchGame.ps1 # 에디터를 빌드하고 실행합니다
Plugins/VibeUE/BuildAndLaunchGame.ps1 -StrictRebuild # 전체 재컴파일 (경고를 오류로 처리)
Plugins/VibeUE/BuildAndLaunchGame.ps1 -Map /Game/Maps/MyMap # 특정 맵 열기 (issue #554)
Linux 또는 macOS에서는 플랫폼 감지 셸 스크립트를 사용합니다:
Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5
Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5 --strict-rebuild
Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5 --map /Game/Maps/MyMap
그런 다음 Edit → Plugins로 이동하여 VibeUE를 활성화하고 다시 시작합니다. VibeUE의 서비스, 도구 및 기능이 이제 엔진 자체와 함께 동일한 엔드포인트에 등록됩니다.
3단계 — 에이전트 연결하기
에디터에서 콘솔 명령어를 두 가지 실행합니다 (콘솔은 ` 로 열 수 있습니다):
1. MCP 서버 설정 작성 (프로젝트 루트의 .mcp.json 파일):
ModelContextProtocol.GenerateClientConfig ClaudeCode
(지원 모델: ClaudeCode, Cursor, VSCode, Gemini, Codex, 또는 All.)
2. VibeUE의 에이전트 가이드 작성 (어시스턴트가 효율적인 패턴을 사용하도록 합니다):
VibeUE.GenerateAgentConfig ClaudeCode
이 명령어는 에이전트에 필요한 올바른 파일에 가이드를 작성합니다 — CLAUDE.md (Claude Code), GEMINI.md (Gemini), AGENTS.md (Codex / Hermes / Cursor), 또는 .github/copilot-instructions.md (Copilot)입니다. 또는 All을 전달하여 한 번에 CLAUDE.md + GEMINI.md + AGENTS.md를 작성할 수 있습니다. 이 명령어는 플러그인 위치를 자동으로 해결하므로, VibeUE가 FAB에서 설치되었든 Git에서 설치되었든 작동합니다. 가이드는 관리된 블록으로 저장되므로, 사용자의 자체 노트에 방해받지 않고 언제든지 재실행하여 새로 고칠 수 있습니다. import를 전달하면 복사하는 대신 한 줄의 @import로 가이드를 연결할 수 있습니다 (Claude Code / Gemini 전용 — 다른 에이전트는 임포트를 해결하지 못하므로 항상 사본을 받습니다).
MCP 서버는 인증 기능이 없는 루프백 전용이며, 동일 머신에서만 사용해야 합니다 (Epic의 문서 참조).
이 가이드에서는 다음 내용을 다룹니다: 호출하기 전에 탐색하기 (discover_python_class), execute_python_code로 배치 처리하기, ListSkills/GetSkills를 통해 스킬 로드하기, 그리고 언제 deep_research / terrain_data를 사용해야 하는지.
🎯 Skills (스킬)
스킬은 Unreal의 기본 제공 AgentSkillToolset에 의해 제공되는 지연 로딩된 도메인 지식(워크플로우, 주의사항, 속성 형식)입니다:
# discover (요약만 — 저렴함)
call_tool(tool_name="ListSkills", toolset_name="ToolsetRegistry.AgentSkillToolset")
...
ListSkills는 사용 가능한 항목에 대한 실시간 진실 공급원입니다 (각 팩의 SKILL.md를 읽습니다). 스킬은 무엇을 해야 하고 왜 해야 하는지를 알려주며, 코드를 작성하기 전에 정확한 시그니처를 얻으려면 discover_python_class('unreal.<이름>Service', method_filter='…')를 사용하세요.
🔧 Plugin dependencies (플러그인 의존성)
네이티브 엔진 전제 조건 (Step 1에서 활성화 — Epic의 MCP 스택):
| 플러그인 | 목적 |
|---|
Unreal MCP (ModelContextProtocol) | 네이티브 MCP 서버 엔드포인트 |
| ... | |
VibeUE에 의해 자동 활성화: PythonScriptPlugin (the unreal.* API), EditorScriptingUtilities, 그리고 해당 서비스가 필요로 하는 도메인 플러그인들 — Niagara, MetaSound, EnhancedInput, ModelViewViewModel, StateTree, MeshModelingToolset, GameplayTagsEditor. (VibeUE는 또한 ToolsetRegistry + ModelContextProtocol에 의존하므로, VibeUE를 활성화하면 이들이 함께 활성화됩니다 — 하지만 여전히 Editor Tools를 활성화하고 Step 1에서 서버를 시작해야 합니다.) | |
🛠️ Build & launch script (빌드 및 실행 스크립트)
BuildAndLaunchGame.ps1 (프로젝트 루트 또는 Plugins/VibeUE/)는 실행 중인 에디터를 중지하고, 빌드한 다음 재실행합니다:
-StrictRebuild — 경고를 오류로 간주하여 전체 플러그인 재컴파일-Clean — 중간 파일/바이너리 먼저 삭제-SkipBuild — 재실행만 수행
📚 The live API (실시간 API)
VibeUE는 이 README에 정적 메서드 카탈로그를 의도적으로 포함하지 않았습니다—표면은 엔진과 함께 진화하기 때문입니다. 권위 있고 항상 최신 참조 정보는 다음과 같습니다:
ListSkills → 어떤 도메인이 존재하며 언제 사용해야 하는지.discover_python_class('unreal.<Name>Service') → 정확한 메서드 시그니처.describe_toolset('VibeUE.<Name>Service') → 도구 세트의 도구와 JSON 스키마 (토큰 사용량이 많으므로, skills + discovery를 선호합니다).
라이선스
MIT — LICENSE 참조. 프로젝트 홈: https://www.vibeue.com/
