서론

Unity 공식 CLI인 Unity CLI가 출시되었습니다.

이번에는 Unity CLI의 설치 방법과 AI 에이전트와의 연동에 대해 해설하고, 최종적으로는 게임 제작까지 진행해 보겠습니다.

TL;DR

• Unity 공식 스탠드얼론(Standalone) CLI인 "Unity CLI" (베타 버전)가 공개되었습니다. 에디터 설치부터 프로젝트 조작까지 가능합니다. 진가는 com.unity.pipeline 패키지와의 연동에 있습니다. 실행 중인 Unity 에디터를 HTTP를 통해 풀 원격 조작할 수 있습니다 (recompile, 테스트 실행, C#의 eval, GameObject 조작, 스크린샷까지 약 140개의 커맨드).
• 이를 Claude Code에 전달했더니, 에디터에 한 번도 손대지 않고 벽돌 깨기 구현 → 씬(Scene) 구축 → Play Mode에서의 동작 검증 → 디버깅까지 완수했습니다.

Unity CLI란

Unity CLI는 Unity Hub와는 독립적으로 배포되는 커맨드 라인 툴입니다 (현재 베타).

아래 커맨드로 설치가 가능합니다.

# 설치 (macOS / 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

설치 후에는 패스(Path)가 설정되어 있지 않을 수 있으므로, source ~/.zshrc를 실행하거나 터미널을 재시작합니다.

다음과 같은 커맨드를 사용할 수 있습니다.

unity install lts # Unity Editor (LTS 버전) 설치
unity install 6000.2.10f1 # 버전을 지정한 Unity Editor 설치
unity open ./MyProject # 프로젝트 열기
...

기존의 Hub CLI ("Unity Hub" -- --headless ...)의 후속으로, JSON/TSV 출력과 예측 가능한 종료 코드(Exit Code)를 갖춘 "CI·자동화 퍼스트" 방식의 구조로 되어 있습니다.

Unity CLI로 Unity Editor를 조작하기

Unity CLI에서 Unity Editor를 조작하기 위해서는 com.unity.pipeline 패키지가 필요합니다.

Unity 프로젝트를 생성하고, 프로젝트 직하에서 unity pipeline install을 실행하면 com.unity.pipeline 패키지가 설치되며, 에디터 내에 로컬 HTTP 서버가 구동됩니다.

• 바인딩(Bind)은 127.0.0.1로만 제한되어 있으며 (외부 접근 불가), Bearer 토큰 인증이 포함되어 있습니다.
• 에디터 탐색은 Library/Pipeline/.unity-pipeline-port에 기록되는 포트 기술 파일을 통해 이루어집니다.
• CLI에서 unity command <name>으로 실행합니다.

unity command # 사용 가능한 커맨드 목록 (약 140개)
unity command editor_status # 에디터 상태
unity command recompile # 재컴파일 (비동기, status를 폴링)
...

커맨드는 에디터 제어, 씬(Scene)/GameObject/프리팹(Prefab) 조작, 에셋(Asset) 관리, UPM 패키지 조작, 빌드, 베이크(Bake), 애니메이션 편집까지 커버합니다. 파괴적인 조작에는 --confirm true가 필수이며, --dry_run으로 미리 확인해 볼 수 있는 안전한 설계입니다.

은근히 중요한 것이 set_autotick입니다. 에디터가 포커스되지 않은 상태에서도 계속 tick이 수행되므로, 터미널 작업 중에도 컴파일이나 테스트가 백그라운드에서 진행됩니다.

주의할 점: 에디터를 찾을 수 없는 경우

서버는 살아있는데 CLI가 "No Unity Editor instances found"라고 말하는 경우가 있었습니다. 조사한 결과는 다음과 같습니다.

• CLI는 포트 기술 파일(Port description file)
  Library/Pipeline/.unity-pipeline-port

만을 의존하여 에디터를 발견합니다 (브로드캐스트 등은 없습니다). 이 파일이 어떤 타이밍(도메인 리로드 시 삭제 후 재생성 충돌?)에 사라지면, 서버가 포트 7800에서 LISTEN하고 있더라도 연결 수단이 없어집니다.

복구는 에디터 메뉴의 Pipeline ▸ Stop Server → Start Server입니다 (기술 파일이 다시 작성됩니다).

원인 파악에 사용한 명령어는 다음과 같습니다.

unity pipeline list # 패키지 상태 및 Server Reachable 여부
lsof -nP -iTCP:7800-7849 -sTCP:LISTEN # LISTEN 중인 포트 확인
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7800/api/status # 401이면 생존

본론: AI 에이전트에게 벽돌 깨기 게임을 만들게 하기

이 명령어 군은 요컨대 "에디터 조작의 완전한 API"이므로, AI 에이전트에게 전달하면 어떤 일이 일어날지 시험해 보았습니다. 패키지에는 Claude Code용 스킬 정의까지 동봉되어 있습니다 (.claude/skills/unity-pipeline).

Claude Code에게 "이 명령어를 사용해서 벽돌 깨기를 만들어줘. 완성될 때까지 시도를 계속해"라고만 지시한 결과, 사람이 에디터에 손을 대지 않고도 다음과 같은 과정이 전 자동으로 완료되었습니다.

1. 씬 구축 및 코딩

unity command create_scene --path Assets/Scenes/Breakout.unity
# → C# 스크립트 4개를 디스크에 작성 (GameManager / 패들 / 볼 / 입력 추상화)
unity command recompile && unity command recompile_status # 에러 제로 확인
...

설계상의 고안으로, 아레나(벽·패들·볼·블록 40개)는 GameManager가 기동 시 코드상에서 생성하는 방식으로 하여, CLI를 통한 씬 조립을 최소화했습니다.

2. Play Mode에서의 자동 검증

이 부분이 가장 흥미로운 지점입니다. 에이전트는 Play Mode에 진입하여, 키보드 대신 eval로 게임을 조작하며 동작을 검증했습니다.

unity command editor_play
# eval로 볼을 발사 → 8초 후 상태 관측
unity command eval --code '...FindFirstObjectByType<BallController>().Launch();...'
...

승리 조건 테스트에서는, eval로 패들을 화면 너비만큼 넓혀서 볼이 떨어지지 않는 상태를 만든 뒤, 총 40개의 블록을 파괴하여 Won 상태로의 전이를 확인했습니다. 리스타트와 게임 오버 전이도 리플렉션(Reflection)을 통해 검증하고 있어, 테스트 하네스(Test Harness)를 스스로 발명하고 있다는 느낌을 줍니다.

unity command capture_game_view --save_path Temp/breakout.png # 외관 확인도 스크린샷으로

3. 완성

이러한 흐름을 거쳐 AI가 약 10분 만에 플레이 가능한 벽돌 깨기 게임을 단번에 만들어 주었습니다.

반년 전 검증했을 때는, 동작은 하지만 움직임이 미묘하여 몇 번의 수정을 거치며 진행하는 느낌이었기에, 이번 결과는 AI의 진화를 실감하게 합니다.

감상 및 고찰

"에디터 조작의 API화"가 주는 임팩트가 매우 큽니다. 지금까지 Unity 자동화는 배치 모드(Batch Mode, 에디터 실행 오버헤드가 매번 발생)이거나 자체적인 에디터 확장(Editor Extension)이 필요했습니다. 실행 중인 에디터에 외부에서 명령어를 흘려보낼 수 있으므로, 개발 루프가 차원이 다르게 빨라집니다.

AI 에이전트와의 궁합이 매우 좋습니다. 구조화된 출력(JSON), 예측 가능한 종료 코드(Exit Code), dry_run, confirm 게이트, 비동기 명령어의 상태 폴링(Status Polling) 등 에이전트가 안전하게 사용할 수 있는 도구들이 처음부터 갖춰져 있습니다. eval이 있기 때문에 "명령어에 없는 조작"도 에이전트가 스스로 어떻게든 해낼 수 있습니다.

스크린샷으로 자기 검증이 가능합니다 (screenshot...

/capture_game_view

)를 통해 에이전트가 단순히 "만들고 끝"내는 것이 아니라, 시각적인 부분까지 확인하는 루프가 완성됩니다. - 한편으로는
베타 버전다운 불안정성이 존재합니다 (포트 기술 파일 소실 문제). - OnGUI의 HUD는 캡처에 찍히지 않으며,
run_tests

는 테스트 실패 시 상세 정보를 가져오지 못할 때가 있는 등 세부적인 제약 사항들도 있습니다.

요약

Unity CLI + Pipeline 패키지는 "터미널에서 Unity 에디터를 조작한다"는 것을 공식적으로 본격 구현하기 위해 나온 기능으로, CI/자동화뿐만 아니라 AI 에이전트 시대의 Unity 개발 워크플로우의 토대가 될 것으로 보입니다. 실험적인 패키지이므로 향후 변경 사항에 주의하면서, 직접 사용해 볼 가치는 충분합니다.

참고 링크

Discussion