시작하기

이 페이지는 플러그인을 설치한 상태에서 AI 에이전트가 Unity 씬을 변경하는 단계까지 안내합니다. ai-game.dev를 통한 기본 Cloud 연결과 Claude Code를 예시 에이전트로 사용하며, 다른 클라이언트에서도 단계는 동일합니다. 플러그인이 아직 설치되지 않았다면 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을 참고하세요.

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 클라이언트를 시작하거나, 이미 실행 중이었다면 다시 시작하여 새 설정을 불러오게 하세요.

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

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

setup-skills는 에디터가 열려 있고 연결되어 있어야 합니다. 다른 클라이언트와 수동 설정은 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단계: 첫 프롬프트#

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

Explain my scene hierarchy.

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

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

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

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

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

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

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을 참고하세요.

Unity best practices 페이지에 프롬프트 작성 조언이 더 있습니다.

다음 단계#

• Tools and RQL: 에이전트가 할 수 있는 모든 것.
• Extensions: Animation, Cinemachine, ProBuilder, Tilemap 및 기타 팩을 추가합니다.
• Custom tools: 자신만의 C# 메서드를 에이전트에 노출합니다.
• 막혔나요? Troubleshooting을 확인하세요.