hatayama/unity-cli-loop

Unity CLI Loop – 명령줄에서 AI 기반 Unity 개발

개요 – Unity 패키지와 소형 크로스 플랫폼 CLI(uloop)로 구성되어, 대규모 언어 모델 에이전트(Claude Code, Codex 등)가 사람이 에디터를 만지지 않고도 Unity 프로젝트를 컴파일, 테스트, 편집, 제어할 수 있게 합니다. 프로젝트별 '러너'를 설치하여 Unity 에디터 내부의 IPC 서버와 통신하고, 일련의 스킬(예: /uloop-compile, /uloop-screenshot, /uloop-pause-point)을 노출하는 방식으로 작동합니다.

중요성 – 일반적인 Unity 워크플로우는 개발자가 에디터를 열고 빌드를 클릭하고, 테스트를 실행하고, 로그를 읽고, 씬을 수동으로 조정해야 합니다. Unity CLI Loop는 가장 일반적인 단계를 LLM이 호출할 수 있는 CLI 명령으로 묶어, 완전 자동화된 개발 루프(컴파일 → 테스트 실행 → 로그 읽기 → 실행 일시 중지 → 코드 핫 리로드 → 스크린샷으로 UI 검증)를 언어 모델 프롬프트만으로 실현합니다.

핵심 기능(번들된 21개 스킬)

카테고리	스킬(예)
개발 루프	`compile`, `run-tests`, `get-logs`, `clear-console`, `hot-reload`, `pause-point`
에디터 자동화	`launch`, `focus-window`, `get-hierarchy`, `find-game-objects`, `execute-dynamic-code`, `screenshot`, `set-game-view-size`, `record-video`
PlayMode 테스트	`simulate-mouse-ui`, `simulate-mouse-input`, `simulate-keyboard`, `replay-input`, `control-play-mode`

이러한 도구는 의도적으로 최소화되어 있습니다. 다른 대부분의 에디터 작업은 실행 중인 Unity 프로세스 내에서 임의의 C# 스니펫을 실행하는 execute-dynamic-code로 수행할 수 있습니다.

빠른 시작(터미널 전용)

CLI 설치 – curl … | sh(macOS/Linux) 또는 PowerShell irm … | iex. uloop -v로 확인.
Unity 패키지 추가 – 프로젝트 루트에서 uloop package install 실행. OpenUPM 레지스트리 항목과 io.github.hatayama.uloopmcp 종속성을 주입합니다.
Unity 실행 – uloop launch(실행 중인 에디터에 포커스하거나 새 에디터 시작).
LLM 스킬 설치 – 예: Claude Code의 경우 uloop skills install --claude, .agents/skills를 읽는 도구의 경우 --agents.

동일한 단계를 Unity UI에서 Window > Package Manager 및 Window > Unity CLI Loop > Settings를 통해 수행할 수 있습니다.

LLM 사용 방법

LLM은 스킬 명령을 셸 명령으로 보냅니다. 프롬프트 → 스킬 매핑 예:

"프로젝트를 컴파일하고 오류를 알려줘." → /uloop-compile
"단위 테스트를 실행하고 실패 로그를 알려줘." → /uloop-run-tests + /uloop-get-logs
"Player.cs의 42행에서 일시 중지하고 변수 값을 표시해." → /uloop-pause-point
"플레이어가 스폰된 후 Game 뷰의 스크린샷을 찍어." → /uloop-screenshot
"전체 재컴파일 없이 이 메서드 본문 수정을 적용해." → /uloop-hot-reload

CLI는 Unix 도메인 소켓(macOS/Linux) 또는 named pipe(Windows)를 통해 통신하므로 네트워크 포트가 필요 없고 여러 Unity 인스턴스를 공존시킬 수 있습니다.

도구 세트 확장

개발자는 프로젝트에 Skill/SKILL.md 파일(또는 셸 스크립트/C# 스니펫)을 배치하여 사용자 정의 스킬을 추가할 수 있습니다. CLI는 시작 시 이를 로드하며, 스킬 디렉터리에 액세스할 수 있는 모든 LLM은 기본 제공 스킬과 동일하게 호출할 수 있습니다.

설치 참고 사항 및 호환성

Unity 2022.3+ 필요.
셸 명령을 실행하고 스킬 파일을 읽을 수 있는 모든 LLM(Claude Code, Codex 등)과 호환.
Claude Code의 경우 샌드박스에서 uloop * 명령을 제외해야 합니다(README의 sandbox.excludedCommands 예제 참조).
V3에서는 Node.js가 필요 없습니다. 프로젝트별 러너는 자동으로 다운로드되며 .uloop/project-runner-pin.json에서 버전이 고정됩니다.

라이선스

MIT – 자유롭게 사용, 수정, 재배포할 수 있습니다.

결론 – Unity CLI Loop는 Unity 에디터를 헤드리스 스크립트 가능한 서비스로 변환하여 LLM 에이전트가 구동할 수 있게 하고, AI 지원 게임 개발 루프를 실용적이고 재현 가능하게 만듭니다.