시작하기

이 페이지는 플러그인 설치부터 Unreal Editor에서의 첫 AI 기반 변경까지 안내합니다. Installation을 마쳤다고 가정합니다.

1단계: AI Game Developer 창 열기#

1. Unreal Editor에서 프로젝트를 엽니다(앱에서 Open Editor를 사용하거나, unreal-mcp-cli open ./YourProject를 사용하거나, 평소처럼 열면 됩니다).
2. Tools 메뉴를 열고 AI Game Developer를 선택합니다.

이 창은 플러그인의 중심 창입니다. 위에서 아래로 로그 레벨, 로그 폴더를 여는 버튼과 플러그인 버전, Connection 섹션, AI agent 섹션, Extensions 섹션, 그리고 도움말과 버그 리포트 링크가 표시됩니다.

2단계: 서버에 연결하기#

Connection 섹션에는 Custom / Cloud 전환이 있습니다. Cloud가 기본값이며 대부분에게 적합한 선택입니다. ai-game.dev의 호스팅 서버를 사용하므로 로컬에서 실행할 것이 없습니다.

1. Cloud가 선택되어 있는지 확인합니다.
2. Authorize를 클릭합니다. 창에 인증 링크와 짧은 사용자 코드가 표시됩니다.
3. 링크를 열거나(Open verification page 사용) ai-game.dev에 로그인한 뒤 코드를 입력하고 승인합니다.
4. 창에 **Authorized — signed in to AI Game Dev.**가 표시됩니다.

이미 이 컴퓨터에서 unreal-mcp-cli login이나 AI Game Dev 앱으로 로그인했다면 에디터가 그 로그인을 재사용할 수 있습니다. 첫 승인 이후에는 이후 에디터 실행 시 클릭 없이 다시 연결됩니다.

상태 표시줄을 확인하세요. 초록 점과 함께 Unreal: Connected가 표시되면 플러그인, 브리지, 서버가 연결된 것입니다. **Unreal: Connecting…**은 브리지가 시작되는 몇 초 동안 정상입니다.

참고: 모든 것을 자신의 컴퓨터에서 유지하고 싶다면 Custom을 선택하고 로컬 gamedev-mcp-server를 실행하세요. 방법은 Connecting AI clients에서 설명합니다.

3단계: AI 클라이언트 연결하기#

AI agent 섹션에서 AI 클라이언트를 자동으로 구성합니다.

1. 드롭다운에서 에이전트를 선택합니다. 예를 들어 Claude Code, Cursor, Visual Studio Code (Copilot), Codex, Gemini 등입니다.
2. Configure를 클릭합니다. 플러그인이 해당 에이전트의 MCP 구성 파일에 Unreal MCP 항목을 기록합니다.
3. 에이전트가 이미 실행 중이었다면 새 서버를 인식하도록 재시작하거나 다시 로드하세요.

터미널에서 CLI로도 동일하게 할 수 있습니다. Claude Code의 경우:

unreal-mcp-cli setup-mcp claude-code --path ./YourProject

그러면 프로젝트 폴더에 .mcp.json이 기록됩니다. unreal-mcp-cli setup-mcp --list를 실행하면 지원되는 모든 에이전트와 각 구성 파일 위치를 볼 수 있습니다. 모든 옵션은 Connecting AI clients에 있습니다.

에이전트가 연결되면 Connection 섹션의 AI agents 행에 표시됩니다.

4단계: 연결 확인하기#

에디터만 답할 수 있는 질문을 에이전트에게 해보세요:

List the actors in the current level with their class names.

에이전트는 rql-query를 호출하고 열려 있는 레벨의 실제 액터로 답해야 합니다. Unreal 도구가 없다고 하면 클라이언트가 MCP 서버를 로드하지 않은 것이니 Troubleshooting을 참고하세요.

5단계: 첫 실제 프롬프트#

작고 구체적으로 시작하세요. 서로 다른 도구 계열을 보여주는 몇 가지 프롬프트입니다:

Spawn three cubes in a row and a point light above them.

Create a new Actor Blueprint called BP_Coin with a static mesh component
using the engine sphere, compile it, and place three of them in the level.

Take a screenshot of the viewport and tell me what you see.

Create a C++ actor class called AHealthPickup with a float Heal property,
then compile the project and fix any errors.

RQL을 통해 이루어지는 모든 에디터 변경은 하나의 실행 취소 단계이므로 에디터에서 Ctrl+Z로 되돌릴 수 있습니다. 컴파일 도구는 구조화된 오류 목록을 반환하므로 "컴파일하고 오류를 수정해줘"는 좋은 후속 프롬프트입니다.

팁: 스크린샷 도구는 실제 GPU 기반 에디터가 필요합니다. 에디터가 -nullrhi로 실행되면 오류를 반환합니다.

Unreal Editor에서 AI를 쓰는 좋은 습관#

• 이름을 붙이세요. "KeyLight라고 표시된 라이트의 강도를 변경해줘"가 "라이트 변경해줘"보다 더 잘 동작합니다.
• 먼저 살펴보게 하세요. "변경하기 전에 BP_Door의 컴포넌트를 보여줘"라고 하면 에이전트가 필요한 사실을 파악합니다.
• 검증하게 하세요. 변경 후 스크린샷이나 컴파일을 요청하세요.
• 작업을 저장하세요. 큰 변경 전에 에이전트에게 레벨 저장을 요청하거나 에디터에서 저장하세요.
• 세션을 집중시키세요. 대화당 하나의 작업이 에이전트의 컨텍스트를 작고 정확하게 유지합니다.

더 많은 조언은 Unreal best practices에 있습니다.

다음 단계#

• 에이전트가 할 수 있는 모든 것은 Tools에서 확인하세요.
• Extensions로 Niagara, PCG, Enhanced Input 등을 추가하세요.
• Configuration에서 표시 여부, 타임아웃, 로깅을 세부 조정하세요.
• CLI reference로 스크립트에서 에디터를 제어하세요.