# 시작하기 — Unity · AI Game Developer Wiki

Unity MCP로 첫 AI 에이전트를 Unity 에디터에 연결하고, 연결을 확인한 뒤 Claude Code, Cursor, Copilot에서 첫 프롬프트를 시험해 보세요.

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

이 페이지는 플러그인을 설치한 상태에서 AI 에이전트가 Unity 씬을 변경하는 단계까지 안내합니다. ai-game.dev를 통한 기본 Cloud 연결과 Claude Code를 예시 에이전트로 사용하며, 다른 클라이언트에서도 단계는 동일합니다. 플러그인이 아직 설치되지 않았다면 [Installation](https://ai-game.dev/ko/docs/wiki/unity/installation)부터 시작하세요.

## 1단계: AI Game Developer 창 열기

Unity에서 프로젝트를 열고 **Window > AI Game Developer — MCP**를 선택하세요(Ctrl+Alt+A, macOS에서는 Cmd+Option+A). 창의 탭 이름은 **Game Developer**입니다. Scene View 툴바의 **AI** 버튼을 클릭해도 됩니다.

창에는 연결 상태가 위에서 아래로 이어지는 타임라인으로 표시됩니다: **Unity**, **MCP server**, **AI agent**. 각 지점에는 상태 원이 있으며, 목표는 세 지점을 모두 초록색으로 만드는 것입니다.

## 2단계: 로그인(Cloud 모드)

상단의 **Connection** 스위치에는 **Custom**과 **Cloud** 두 가지 옵션이 있습니다. 새로 설치하면 **Cloud**가 사용됩니다.

1. **Cloud Token** 필드 옆의 **Authorize**를 클릭하세요.
2. 브라우저에서 ai-game.dev 기기 로그인 페이지가 열립니다. 창에 짧은 코드가 표시되며("Code: … — Authorize in browser"), 브라우저에 같은 코드가 표시되는지 확인하고 승인하세요.
3. 필드가 "Signed in via account"로 바뀌고 Unity 상태가 **Connected**가 됩니다.

로그인 정보는 머신 전체 단위로 `~/.ai-game-dev/credentials.json`에 저장됩니다. 이미 `unity-mcp-cli login`이나 AI Game Dev 앱으로 로그인했다면 에디터가 해당 자격 증명을 가져오므로 이 단계를 건너뛸 수 있습니다. 자세한 내용은 [Authentication](https://ai-game.dev/docs/auth)을 참고하세요.

**참고**

플러그인을 사용해 보는 데 계정은 필요하지 않습니다. 연결을 **Custom**으로 전환하면 머신에서 로컬 MCP 서버를 실행할 수 있습니다. [Configuration](https://ai-game.dev/ko/docs/wiki/unity/configuration#connection-modes)을 참고하세요.

## 3단계: AI 에이전트 구성

1. **AI agent** 섹션에서 드롭다운으로 클라이언트를 선택하세요. 예를 들어 **Claude Code**입니다.
2. **Model Context Protocol (MCP)** 아래에서 **Configure**를 클릭하세요. 플러그인이 해당 클라이언트의 MCP 설정 파일(Claude Code의 경우 프로젝트 루트의 `.mcp.json`)에 이 프로젝트에 고정된 URL을 기록합니다.
3. **Skills** 아래에서 **Auto-generate**를 켜거나 **Generate**를 클릭하세요. 에이전트가 Unity MCP와 RQL을 사용하는 방법을 익히기 위해 읽는 스킬 파일이 생성됩니다(Claude Code의 경우 `.claude/skills`에 생성). 스킬을 지원하는 에이전트는 스킬이 있을 때 눈에 띄게 더 잘 동작합니다.
4. 프로젝트 폴더에서 AI 클라이언트를 시작하거나, 이미 실행 중이었다면 다시 시작하여 새 설정을 불러오게 하세요.

터미널에서도 동일하게 수행할 수 있습니다:

```bash
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-skills claude-code ./MyUnityProject
```

`setup-skills`는 에디터가 열려 있고 연결되어 있어야 합니다. 다른 클라이언트와 수동 설정은 [Connecting AI clients](https://ai-game.dev/ko/docs/wiki/unity/connecting-ai-clients)에서 다룹니다.

## 4단계: 연결 확인

- 창에서 Unity 상태가 **Connected**로 표시되고, AI agent 지점에 클라이언트가 구성된 것으로 나타납니다.
- AI 클라이언트에서 MCP 서버나 도구 목록을 확인하세요. Claude Code에서는 `/mcp`를 실행하면 되고, `ai-game-developer`와 함께 `rql-query`, `rql-mutate`, `rql-schema`, `script-execute`, `screenshot-isolated`, `tests-run`, `unity-tool-list` 같은 도구가 보여야 합니다.
- Unity가 준비되기 전에 클라이언트를 연결했다면 다시 연결하여 도구 목록이 다시 표시되도록 하세요.

터미널에서 `unity-mcp-cli status ./MyUnityProject`를 실행하면 Unity가 실행 중인지, 구성된 서버에 접근할 수 있는지 확인할 수 있습니다.

## 5단계: 첫 프롬프트

먼저 씬을 읽는 요청으로 시작하고, 그다음 씬을 변경하는 요청을 해보세요:

```text
Explain my scene hierarchy.
```

```text
Create 3 spheres stacked on top of each other, then save the scene.
```

```text
Create a metallic golden material and assign it to a new sphere.
```

Hierarchy를 지켜보세요. 에이전트가 작업하는 대로 오브젝트가 나타납니다. 내부적으로 에이전트는 RQL을 전송하는데, 예를 들어 다음과 같은 뮤테이션을 보냅니다:

```text
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
```

모든 RQL 변경은 하나의 Undo 단계로 기록되므로 Ctrl+Z(Cmd+Z)로 수동 편집처럼 되돌릴 수 있습니다.

여러 도구를 사용하는 더 긴 예시:

```text
Create a new scene called Playground. Add a plane scaled to 10, 1, 10 and a capsule
named Player at 0, 1, 0 with a Rigidbody. Write a PlayerController script that moves
the Player with WASD, attach it, and take a screenshot of the Player.
```

더 시도해 볼 만한 것들:

- "Console을 읽고 오류가 있는지 알려줘."
- "모든 EditMode 테스트를 실행하고 실패 항목을 요약해 줘."
- "열린 씬의 모든 Rigidbody와 그 질량을 나열해 줘."
- "프로파일러를 시작하고 Play 모드를 몇 초간 기록한 뒤 프레임 시간을 보고해 줘."

## 더 나은 결과를 위한 팁

- 이름, 위치, 파일 경로를 구체적으로 지정하세요. 요청이 정확할수록 수정이 줄어듭니다.
- 클라이언트에서 강력한 모델을 선택하세요. 도구를 많이 사용하는 작업에 유리합니다.
- VS Code에서 Copilot을 사용하는 경우 채팅을 **Agent** 모드로 전환해야 도구가 호출됩니다.
- 에이전트의 도구 목록은 짧게 유지하세요. 숨겨진 도구도 이름으로 호출되면 실행되며, 보이는 도구가 적을수록 추론에 더 많은 컨텍스트를 쓸 수 있습니다. [Configuration](https://ai-game.dev/ko/docs/wiki/unity/configuration#tools-prompts-resources)을 참고하세요.

[Unity best practices](https://ai-game.dev/docs/best-practices/unity) 페이지에 프롬프트 작성 조언이 더 있습니다.

## 다음 단계

- [Tools and RQL](https://ai-game.dev/ko/docs/wiki/unity/tools-and-rql): 에이전트가 할 수 있는 모든 것.
- [Extensions](https://ai-game.dev/ko/docs/wiki/unity/extensions): Animation, Cinemachine, ProBuilder, Tilemap 및 기타 팩을 추가합니다.
- [Custom tools](https://ai-game.dev/ko/docs/wiki/unity/custom-tools): 자신만의 C# 메서드를 에이전트에 노출합니다.
- 막혔나요? [Troubleshooting](https://ai-game.dev/ko/docs/wiki/unity/troubleshooting)을 확인하세요.

---

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

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