핵심 정리

unity-cli status
unity-cli editor play --wait
unity-cli console --filter all
unity-cli exec "Application.dataPath"

가능한 작업

MCP 없이 셸 친화적으로 Unity를 다루는 접근이 Codex와 잘 맞는 이유

unity-cli는 Unity 에디터를 셸 명령으로 직접 제어하게 해 주는 커뮤니티 도구이며, README는 "MCP 없이, Python 없이, 단일 바이너리"라는 점을 핵심으로 내세웁니다. Codex는 원래 셸 명령 실행에 강하므로, 별도 MCP 구성을 하지 않고도 unity-cli status, unity-cli editor play --wait, unity-cli exec ... 같은 명령을 바로 호출할 수 있다는 점이 큰 장점입니다. 도구 프로토콜 기반 연동보다 Codex가 셸에서 Unity를 다루는 흐름이 더 자연스러운 팀이라면 unity-cli가 더 가볍고 빠르게 맞을 수 있습니다.

unity-connector가 에디터와 CLI를 연결하는 방식

Unity 쪽에서는 unity-connector 패키지를 넣으면 에디터 시작 시 자동으로 HTTP 엔드포인트를 열고 인스턴스를 등록합니다. unity-cli는 이 엔드포인트를 찾아 연결하는 구조입니다. 이 설계 덕분에 Unity가 이미 실행 중이면 CLI에서 즉시 명령을 보낼 수 있습니다. --port와 --project 옵션으로 멀티 인스턴스 환경에서 대상을 명시적으로 고를 수도 있어, 여러 Unity 프로젝트를 동시에 열어 둔 상황에도 대응합니다.

exec 명령이 강력한 만큼 작업 범위를 명확히 줘야 하는 이유

README 기준으로 상태 확인, 플레이 모드 제어, 콘솔 로그 읽기, 임의 C# 실행, 메뉴 아이템 호출, 리시리얼라이즈, 프로파일러 조회, 커스텀 툴 호출까지 폭넓게 지원합니다. 이 중 exec는 실제 C#을 실행하므로 매우 강력한 대신 영향 범위도 큽니다. Codex에게 exec 기반 작업을 맡길 때는 어떤 API를 호출할지, 어떤 에셋이나 씬에 영향을 주는지를 더 명확히 지정해야 예상치 못한 에디터 상태 변경을 막을 수 있습니다.

Editor Throttling이 꺼져 있어야 명령 응답이 안정적이다

README는 Unity가 백그라운드일 때 명령 처리가 늦어질 수 있으니 Editor Throttling을 꺼 두는 것을 권합니다. Throttling이 켜진 상태에서는 CLI 명령에 대한 응답이 지연되거나 타임아웃이 발생해, Codex가 결과를 받지 못하고 재시도하거나 오류로 처리하는 상황이 생길 수 있습니다. 자동화 흐름에서 특히 문제가 되므로, unity-cli를 쓸 때는 이 설정을 먼저 확인하는 습관이 필요합니다.

unity-cli 와 unity-mcp 를 나누는 기준
- 셸 명령 몇 개로 상태 확인과 제어가 충분할 때: unity-cli
- 도구 단위로 구조화된 Unity 워크플로우가 필요할 때: unity-mcp
- 일회성 상태 확인이나 플레이모드 제어: unity-cli 가 더 가볍다

언제 이 도구를 쓸까

주의할 점

실패 예시
- 여러 Unity 인스턴스가 열린 상태에서 --project 나 --port 없이 unity-cli exec 를 실행함
- 결과: 의도와 다른 프로젝트에 명령이 들어가거나 어느 인스턴스가 대상인지 모호해짐
- 대응: 멀티 인스턴스 환경에서는 대상 프로젝트나 포트를 먼저 고정한다