Unity CLI와 MCP를 사용하여 게임 개발하기
Unity CLI
Unity가 7월에 Unity CLI라는 것을 발표했다. CLI니까 맞다. 명령줄 커맨드다.
음, Unity 에디터에 있는 GUI도 아직 숙지 못했는데, CLI가 내게 소용이 있을까?
당시 이런 생각 때문에 '이런 게 나왔구나' 하고 넘어갔는데 오늘 유튜브에서 재밌는 영상을 보았다. Unity CLI와 MCP를 이용해서 게임 개발을 하는 영상이었다.
Unity CLI MCP 깔끔하게 소개합니다 (with Codex)
Codex나 Claude처럼 자주 사용하는 에이전트에 Unity CLI와 MCP를 연결해서 게임 개발을 하는 것이 어떤 이점이 있는지 알기 위해 해당 영상을 보며 학습했다.
어떻게 설치하는가
영상에서는 Unity CLI 안내 페이지에서 명령어를 이용해서 설치하는 방법과 Unity Hub에서 설치하는 방법 두 가지를 안내했다.
나는 명령어를 이용해서 설치했다.
# macOS or Linux
curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
# Windows
$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
에이전트에 Skills 주입하기
다음으로 에이전트에 Skills를 주입했다. 유니티에서 제공하는 Skills 깃허브 페이지에서 ZIP 파일을 다운받고, 이를 Codex에 다음의 프롬프트와 같이 집어넣었다. 내용은 영상의 것과 똑같다.
$skill-creator 해당 파일은 Unity Engine에 대한 스킬입니다. Unity 폴더로 스킬을 설치해주세요.
설치 완료했습니다.
- 위치: ~/.codex/skills/Unity
- Unity 스킬: 31개
- 전체 파일: 199개
- 설치 후 검증: 모두 통과
- 호환되지 않던 11개 스킬은 의미를 유지하면서 YAML 프런트매터만 정규화했습니다. 사용한 스킬: skill-creator — 스킬 구조 확인 및 유효성 검증에 적용했습니다.
Codex는 위와 같은 답변과 함께 스킬 설치를 완료했다.
Claude에도 똑같은 방식으로 설치하려고 했는데, Zip contains too many files (maximum 200)라는 메시지와 함께 스킬 설치가 불가능했다. 그래서 Claude에는 다른 방법을 사용했는데, 이 방법이 더 편한 것 같다. Codex를 사용하는 사람들도 밑의 방법을 쓰는 게 더 나아보인다.
에이전트에 더 쉽게 Skills 주입하기
현재 이 글은 Unity CLI 1.0.0-beta.9를 기준으로 작성했다. 해당 버전에서는 다음 명령어를 이용해 Skills를 쉽게 설치할 수 있다.
unity skill install <agent-name>
MCP 설정하기
이제 MCP를 설정할 차례다. 터미널에 unity mcp configure만 입력하면 설정할 수 있는 mcp 목록이 나오는데, 웬만한 에이전트는 다 뜨고, 처음 보는 에이전트도 뜨는 것을 볼 수 있었다. 글을 작성 중인 현재 사용하고 있는 Unity CLI 버전은 1.0.0-beta.9인데, Gemini는 없어서 놀라웠다.
unity mcp configure codex
그다음으로 위의 명령어로 Codex에 MCP를 설정했다.
Unity 프로젝트 시작하기
이제 Unity 프로젝트를 열고 작업을 시작하면 되는데, 우선은 영상에 나오는 것처럼 기존에 있는 프로젝트에 연결하는 방법을 따라하기 위해, 프로젝트 생성 시 Use Unity CLI 버튼을 체크하지 않고 시작했다. 만약 체크를 한다면 Pipeline 패키지가 자동으로 설치되어서 후술할 작업을 하지 않아도 된다.
Pipeline 패키지 설치하기 (프로젝트 생성 때 체크 안 했을 시만)
프로젝트가 열리면, 해당 경로 안에서
unity pipeline install
를 입력하여 Pipeline 패키지를 설치하면 Unity CLI MCP를 사용할 모든 준비가 마무리된다.
인데...
unity status 커맨드를 이용하여, 현재 Unity MCP 서버의 상태를 확인하니 Error: No Unity Editor instances found with the Pipeline package installed. Open Unity and install the Pipeline package, or run unity pipeline install 이렇게 에러가 나온다.
혹시 몰라 새로운 터미널을 열어서 다시 입력해봐도 에러 메시지는 동일했는데, Unity 프로젝트 창으로 돌아가니 갑자기 막 무언가를 설치한다. 그러고 나서 다시 명령어를 입력하니 에러 없이 돌아가는 것을 확인했다. 혹시 비슷한 에러가 발생한다면 프로젝트로 돌아가서 패키지가 설치되는지 확인해보자.
MCP 서버 연결하기
이제 Unity 프로젝트도 만들었고, pipeline도 설치했으면 Unity 프로젝트와 터미널, 에이전트를 열고 다음과 같이 진행한다.
먼저, 터미널에서 (경로는 프로젝트 경로)
unity mcp
명령어로 mcp 서버를 열고, 그다음으로 codex에서 해당 프로젝트 경로로 새 세션을 만들어 Unity MCP와 연결해 달라고 하면 연결 작업을 진행한다. 나의 경우에는 Codex가 Unity MCP 설정을 프로젝트에 등록한 후 새로운 세션을 만들어야 MCP 설정이 로드되었다.
하지만 그렇게 해도 Codex와 Unity MCP 서버가 연결이 안 되었다. 이를 해결하기 위해 진행한 방법은 다음과 같다.
- 터미널에서 실행한 MCP 서버 종료하기
- Unity 에디터 재시작하고, 로딩과 스크립트 컴파일 완료까지 기다리기
이때, 로딩 완료 후 프로젝트 경로에서
명령어 입력
unity status --format json
결과
...
"instances": [
{
"port": 7800,
"project": "/Users/kangseungmin/Desktop/git/My project",
"version": "6000.3.15f1",
"pid": 35542,
"state": "ready"
}
]
...
로, 인스턴스가 뜨는지 확인하고
명령어 입력
unity pipeline list --format json
...
"isRunning": true,
"hasPipelinePackage": true,
"pipelineVersion": "0.7.0-exp.1",
"updateAvailable": false,
"pipelineServer": {
"port": 7800,
"isReachable": true,
"apiUrl": "http://127.0.0.1:7800/api/editor_status"
},
"safeMode": null
...
이런 식으로
isRunning: true
hasPipelinePackage: true
pipelineServer.isReachable: true
위와 같은 상태가 나오는지 확인하면 된다.
- Codex의 MCP 설정을 확인하여 unity가 있는지 확인하기
- Codex 재시작하기
이렇게 하고 Codex에서 /mcp 를 입력하여, 나타나는 서버 목록에 Unity가 있고 사용함이라는 문구가 떠있으면 된다.
이렇게 체크하고 다시 Codex에서 Unity MCP 서버에 연결해 달라고 하니 이제는 정상적으로 연결되는 것을 확인할 수 있었다.
그리고 앞으로의 작업에서는 터미널에 unity mcp 서버를 열 필요 없이, 그냥
- Unity Editor에서 진행하고자 하는 프로젝트 열기
- 컴파일과 로딩이 끝날 때까지 기다리기
- Codex에서 해당 프로젝트의 작업 열기
- “Unity MCP를 사용해서…”라고 요청하기
이렇게 하면 MCP 서버로 연결해서 작업할 수 있다고 한다. 중요한 점은 Editor가 반드시 열려 있어야 한다.
실제 게임 만들어보기
이제 게임을 만들어 봐야 하는데, 영상에서 나오는 것처럼 코코넛 피하기 게임을 만들었다. 정확히는 영상은 사방에서 날아오는 코코넛 피하기 게임이었고, 나는 옛날의 똥 피하기 게임에서 똥이 코코넛으로 치환되었을 뿐이다...
프롬프트는 Codex에게 질문하여 나온 것을 그대로 사용했다.
Unity MCP를 사용해 현재 열린 Unity 프로젝트 안에 간단하지만 완성된 2D 게임을 만들어주세요.
게임 이름은 “Coconut Dodge”입니다. 플레이어가 화면 아래에서 좌우로 움직이며 위에서 떨어지는 코코넛을 피하는 게임입니다.
중요한 작업 원칙:
1. Unity Editor와의 상호작용에는 Unity MCP 도구를 사용하세요.
2. 터미널의 Unity CLI로 대체하거나 `.unity`, `.prefab`, `.asset` YAML을 직접 수정하지 마세요.
3. 스크립트와 텍스트 파일도 가능한 한 Unity MCP의 파일/스크립트 관련 도구로 생성하세요.
4. 작업 전 Editor 상태, 열린 Scene, Console 상태, 현재 Hierarchy를 먼저 확인하세요.
5. 기존 `SampleScene`은 수정하거나 덮어쓰지 마세요.
6. 외부 이미지나 유료 에셋을 다운로드하지 마세요. Unity 기본 기능과 단순한 도형, 색상만 사용하세요.
7. 작업 도중 컴파일이 발생하면 완료될 때까지 기다린 뒤 Console 오류를 확인하세요.
8. 파괴적이거나 기존 파일을 덮어써야 하는 상황이 생기면 진행하기 전에 저에게 알려주세요.
프로젝트 구조:
Assets/CoconutDodge/
├── Scenes/
│ └── CoconutDodge.unity
├── Scripts/
├── Prefabs/
└── Art/
다음 기능을 구현하세요.
게임 화면:
- 16:9 가로 화면을 기준으로 구성합니다.
- 기존 URP 2D 환경을 유지합니다.
- 배경은 밝은 하늘색 계열로 설정합니다.
- 화면 아래에 모래 또는 잔디를 나타내는 단순한 바닥 영역을 만듭니다.
- 외부 에셋 없이 SpriteRenderer와 기본 도형으로 플레이어와 코코넛을 표현합니다.
- 플레이어, 코코넛, 배경이 시각적으로 명확하게 구분되도록 색상을 지정합니다.
플레이어:
- 화면 아래에서 좌우로만 이동합니다.
- 방향키와 A/D 키를 지원합니다.
- 현재 프로젝트의 Input 설정을 먼저 확인하고 호환되는 입력 방식을 사용합니다.
- 플레이어가 카메라 화면 밖으로 나가지 않게 제한합니다.
- Rigidbody2D와 적절한 Collider2D를 사용합니다.
코코넛:
- 화면 위쪽의 무작위 X 위치에서 생성됩니다.
- Rigidbody2D와 Collider2D를 사용해 아래로 떨어집니다.
- 회전하면서 낙하하게 만듭니다.
- 플레이어와 충돌하면 게임 오버를 발생시킵니다.
- 화면 아래로 벗어난 코코넛은 제거합니다.
- 재사용할 수 있는 Prefab으로 만듭니다.
게임 진행:
- 처음에는 여유 있게 코코넛이 생성되며 시간이 지나면 생성 간격이 점차 짧아집니다.
- 생존 시간에 따라 점수가 증가합니다.
- 게임 오버 시 코코넛 생성을 중단하고 플레이어 입력을 정지합니다.
- 게임 오버 문구, 최종 점수, 재시작 안내를 표시합니다.
- R 키와 화면의 Restart 버튼 모두로 재시작할 수 있게 합니다.
코드 구조:
- 역할을 명확하게 분리한 작은 MonoBehaviour 스크립트를 사용하세요.
- 예: PlayerController, Coconut, CoconutSpawner, GameManager.
- 필요한 참조는 Inspector에서 연결하고, 불필요한 런타임 검색과 전역 상태 사용을 피하세요.
- 공개 필드보다는 `[SerializeField] private` 필드를 우선 사용하세요.
- 주요 값인 이동 속도, 생성 간격, 난이도 증가율은 Inspector에서 조정할 수 있게 하세요.
UI:
- 현재 프로젝트에서 사용할 수 있는 UI 방식을 확인한 후 가장 단순하고 안정적인 방식을 선택하세요.
- 점수를 항상 표시하세요.
- 게임 오버 패널은 평소에는 숨기고 게임 종료 시 표시하세요.
- Restart 버튼을 포함하세요.
- 추가 패키지가 꼭 필요하지 않다면 설치하지 마세요.
검증 절차:
1. 모든 스크립트를 생성하고 컴파일합니다.
2. 컴파일 오류와 Unity Console 오류를 확인하고 모두 해결합니다.
3. Scene과 Prefab을 저장합니다.
4. Play Mode에 진입합니다.
5. 일정 시간 동안 코코넛 생성과 점수 증가가 정상인지 확인합니다.
6. 가능하다면 Play Mode에서 코코넛을 플레이어 위치로 이동시켜 충돌과 게임 오버를 검증합니다.
7. NullReferenceException이나 반복되는 경고가 없는지 확인합니다.
8. Game View를 캡처해 최종 모습을 보여주세요.
9. Play Mode를 종료하고 Scene이 저장된 상태인지 다시 확인합니다.
완료 보고에는 다음을 포함하세요.
- 실제 사용한 Unity MCP 도구
- 생성한 Scene, Prefab, 스크립트 목록
- 최종 Hierarchy
- 수행한 Play Mode 테스트와 결과
- Console 오류 및 경고 상태
- Game View 캡처
- 제가 직접 확인해야 할 조작 항목이나 남은 제한 사항
중간 단계마다 설명만 길게 하지 말고, 안전하게 계속 진행해 완성된 플레이 가능한 결과를 만들어주세요. Unity MCP 연결이 실패하면 다른 방식으로 대체하지 말고 정확한 오류와 중단 지점을 알려주세요.
정말 상세하게 작성되어 있는데, 이러면 Codex가 뚝딱하고 다 만들어줄까 싶었지만 그렇진 않았다. 특히, 현재 프로젝트의 Input 설정을 먼저 확인하고 호환되는 입력 방식을 사용합니다. 문구가 있음에도 Legacy Input API를 사용해서 오류가 발생했다. 이 부분은 수정을 통해서 해결되었다.
결과물
그렇게 완성된 결과물은 위 이미지와 같다. 누군가에게는 퀄리티가 떨어져 보이겠지만, 여기서 스프라이트를 교체하고 스테이지를 추가하고 난이도를 추가하면 그럴싸해 보이는 게임이 나올지도 모른다.
느낀 점
Unity CLI와 MCP를 사용해 보면서, 1인 개발의 진입 장벽이 확실히 낮아지고 있다는 느낌을 받았다. 예전에는 강의를 따라가며 하나씩 익혀야 했던 작업도 이제는 에이전트와 대화하면서 결과를 만들고, 그 과정에서 부족한 지식을 배울 수 있다. 머릿속에만 있던 아이디어를 일단 움직이는 형태로 꺼내볼 수 있다는 점은 분명 매력적이다.
동시에 개발자에게 필요한 역량이 무엇인지 혼란스럽기도 하다. 지금은 사람이 더 꼼꼼하게 설계하고 결과를 검증할 수 있다고 말하지만, 그 차이마저 빠르게 줄어들지 모른다.
설렘과 불안이 함께 찾아오는 시기다. AI가 개발자를 대신할지를 걱정하기보다, 이제 개발자가 무엇을 판단하고 책임져야 하는지를 고민해야 한다고 하는데, 그것마저 AI에게 따라잡히는 것은 아닐까 걱정된다.
나는 어떤 마음으로 다음 걸음을 내디뎌야 할까.