# 시작하기 — Unreal Engine · AI Game Developer Wiki

Unreal MCP를 처음 연결하고, ai-game.dev에 로그인한 뒤, AI 클라이언트를 연결하고 Unreal Editor에서 첫 AI 프롬프트를 실행하세요.

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

이 페이지는 플러그인 설치부터 Unreal Editor에서의 첫 AI 기반 변경까지 안내합니다. [Installation](https://ai-game.dev/ko/docs/wiki/unreal/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](https://ai-game.dev/ko/docs/wiki/unreal/connecting-ai-clients#custom)에서 설명합니다.

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

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

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

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

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

그러면 프로젝트 폴더에 `.mcp.json`이 기록됩니다. `unreal-mcp-cli setup-mcp --list`를 실행하면 지원되는 모든 에이전트와 각 구성 파일 위치를 볼 수 있습니다. 모든 옵션은 [Connecting AI clients](https://ai-game.dev/ko/docs/wiki/unreal/connecting-ai-clients)에 있습니다.

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

## 4단계: 연결 확인하기

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

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

에이전트는 `rql-query`를 호출하고 열려 있는 레벨의 실제 액터로 답해야 합니다. Unreal 도구가 없다고 하면 클라이언트가 MCP 서버를 로드하지 않은 것이니 [Troubleshooting](https://ai-game.dev/ko/docs/wiki/unreal/troubleshooting#agent-no-tools)을 참고하세요.

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

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

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

```text
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.
```

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

```text
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](https://ai-game.dev/docs/best-practices/unreal)에 있습니다.

## 다음 단계

- 에이전트가 할 수 있는 모든 것은 [Tools](https://ai-game.dev/ko/docs/wiki/unreal/tools)에서 확인하세요.
- [Extensions](https://ai-game.dev/ko/docs/wiki/unreal/extensions)로 Niagara, PCG, Enhanced Input 등을 추가하세요.
- [Configuration](https://ai-game.dev/ko/docs/wiki/unreal/configuration)에서 표시 여부, 타임아웃, 로깅을 세부 조정하세요.
- [CLI reference](https://ai-game.dev/ko/docs/wiki/unreal/cli)로 스크립트에서 에디터를 제어하세요.

---

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

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