hera-agent-unity — Unity 에디터를 AI가 직접 만지는 가벼운 CLI

hera-agent-unity — Unity 에디터를 AI가 직접 만지는 가벼운 CLI

2026년 6월, Unity 개발 현장에서 LLM이 코드를 "추측"하지 않고 에디터에서 "측정"하게 만드는 도구가 공개됐다. hera-agent-unity는 Go 단일 바이너리 CLI와 C# UPM 패키지 한 개로 구성된 미니멀한 MCP 대안이다. 런타임 의존성은 0개, MIT 라이선스, MIT 라이선스다. Python 미들웨어도, WebSocket도, JSON-RPC도 없이 localhost HTTP 하나로 끝낸다.

미들웨어 없는 한 줄 다리

Hera의 핵심은 단순함이다. 터미널의 Go 바이너리가 Unity Editor의 localhost:8090 포트와 HTTP로 통신한다. Unity를 열면 AgentConnector UPM 패키지가 자동으로 시작되고, HeraAgent 메뉴가 등록된다. 이 시점부터 AI 에이전트는 exec, editor, console, scene, batch, profiler 같은 CLI 명령으로 에디터에 손을 댄다.

LLM은 학습 데이터 cutoff 이후의 Unity API를 정확히 모른다. 그래서 가짜 API를 지어내거나, 콘솔 에러를 추측하고, Play Mode 결과를 상상한다. hera-agent-unity는 그 모든 "추측"을 "측정"으로 바꾼다. AI가 코드를 추측하기 전에 Editor에서 직접 실행하고 결과를 돌려받는다. 에러를 가정하기 전에 실제 로그를 타입별로 필터링해서 가져온다. Play Mode 결과를 가설로 세우기 전에 진입하고 끝날 때까지 기다린다. 존재하지 않는 API를 지어내기 전에 라이브 어셈블리를 리플렉션한다. Guessing is expensive. Measurement is the command. 가 이 프로젝트의 모토다.

다섯 개 엔드포인트로 끝내는 UI 파이프라인

AI에게 Unity UI를 만들라고 하면 대부분 실패한다. HTML/CSS는 잘 알지만 RectTransform anchor, pivot, stretch offset, LayoutGroup, 9-slice sprite는 다른 영역이다. 그래서 모델은 앵커 수학을 추측하고, 해상도가 바뀌면 깨지는 절대 좌표를 하드코딩하고, 가장 큰 문제로 자기 작업물을 참조 이미지와 비교할 방법이 없다. 결과는 "대충 맞고 픽셀은 틀린" 레이아웃이 된다.

ui_doc는 이 문제를 결정론적이고 자가 교정하는 파이프라인으로 바꾼다. 에이전트는 자신이 진짜로 능숙한 언어, 즉 HTML 모양의 JSON IR(ui_doc/2)로 설계를 짜고, Hera가 Unity 쪽 정확한 번역을 수행한다. 그리고 거의 어떤 AI 툴도 시도하지 않는 일, 즉 구축한 결과를 참조 이미지와 측정해서 차이를 고친다.

reference image (screenshot / mockup)↓1. sample   read the true colors out of the reference image2. author   write the ui_doc/2 IR (HTML-shaped JSON)3. apply    the IR becomes a real uGUI hierarchy4. capture  render exactly what you built → PNG5. compare  diff against the reference, then fix the IR└── repeat until capture matches the reference

다섯 개 엔드포인트가 하나의 계약으로 묶인다. export는 실제 uGUI 서브트리를 IR로 직렬화해서 에이전트가 프로젝트의 진짜 구조 위에 설계를 짜게 한다. apply는 IR을 --mode create 또는 upsert로 실제 UI에 입힌다. gen_sprite는 절차적 스프라이트(solid, rounded_rect, gradient, nine_slice)를 굽고 임포트한다. 외부 의존성 0개다. capture는 ScreenSpaceOverlay 캔버스까지 포함해 정확히 무엇이 만들어졌는지 PNG로 렌더링한다. sample은 참조 이미지에서 측정된 hex 색을 읽는다.

UI Juicy Mode — 기능만 한 UI는 죽은 UI다

AI가 만드는 UI는 동작은 하지만 감정이 없다. 버튼은 작동하지만 호버해도 아무 일도 안 일어난다. 점수는 0에서 1000으로 한 프레임에 점프한다. 디자이너는 이걸 "juice"라고 부른다. 보통 AI가 만드는 UI가 가장 먼저 빠뜨리는 요소이기도 하다.

UI Juicy Mode는 그 기본값을 뒤집는다. 옵트인 토글 하나로, 에이전트가 UI 요소를 만들 때마다 Hera가 *Game UI/UX Bible*에서 가져온 구체적이고 숫자가 포함된 레시피를 agent_hint로 함께 건네준다. 버튼이 호버 시 110%로 부풀고, 누르면 95%로 눌렸다가 백 오버슈트로 100%로 돌아온다. 점수는 0.25초에 걸쳐 부드럽게 카운트업한다. 데미지 숫자는 크게 punch in하고 50px 위로 떠오르며 사라진다. crit은 더 크게, 화면 흔들림과 함께.

// hera-agent-unity manage_ui create button --name PlayButton (with Juicy Mode on){"instance_id": -8420,"agent_hint": "[Hera] UI Juicy Mode is on — make this feel alive.\n  Button feel (Normal → Hover → Press → Release):\n    - Hover:   100% → 110%, EaseOut 0.15s, +5% brightness\n    - Press:   → 95%, EaseOut 0.05s (immediate), −10% color\n    - Release: 95% → 110% → 100% with Back overshoot, 0.2s; click SFX; 10ms haptic on mobile"}

DOTween이 활성화돼 있으면 DOScale 스타일 트윈을 쓰고, 없으면 코루틴/lerp 방식으로 폴백한다. 강한 모션은 항상 reduce-motion 옵션 뒤에 게이트된다. juice가 멀미로 변하지 않는다.

설치와 첫 명령

macOS/Linux는 한 줄 설치다.

curl -fsSL https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.sh | sh

Unity 쪽에서는 Package Manager에서 https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector를 추가한다. Unity 6000.0 이상, macOS/Linux/Windows 모두 지원한다. 6000.5+는 Connector 0.0.20+가 필요하다. 6000.5가 기존 EditorUtility.InstanceIDToObject / Object.GetInstanceID API를 컴파일 에러로 격상시켰기 때문이다. Core/EntityIdCompat shim이 UNITY_6000_5_OR_NEWER 게이트 뒤에서 27개 콜사이트를 새 EntityId API로 라우팅한다. 2022.x 이하는 지원하지 않는다.

설정이 끝나면 이 한 줄이 끝이다.

hera-agent-unity status

status는 토큰을 거의 안 쓰는 liveness 프로브다. 그 다음은 AI 에이전트에게 AGENTS.md 또는 CLAUDE.md를 한 줄 추가해 두는 게 표준 패턴이다. Codex, Claude Code, Kimi Code, Cursor, Copilot, Continue.dev, Google Antigravity — 셸 명령을 돌릴 수 있는 어떤 에이전트든 동작한다. doctor --agent-rules가 클린한 룰 바디를 그 자리에 직접 emit 해 준다. Cursor의 .mdc는 YAML 프런트매터가 없으면 조용히 무시되니 --format cursor 플래그를 쓴다.

AI 친화적 도구 큐 — v0.0.6 이후

다섯 개 도구 큐가 2026-05-28에 잠겼고, 각각 exec의 csc 워밍업 비용이나 C# 래핑 부담이 AI 에이전트 워크플로우에서 너무 높았던 빈자리를 채웠다. manage_gameobject (v0.0.5)는 얕은 instance_id로 리네임·리페어런팅을 견디고, manage_packages (v0.0.6)는 async 잡을 job_id로 통과시키고 도메인 리로드 후 [InitializeOnLoad] 워처가 결과를 검증한다. manage_components (v0.0.8)는 SerializedProperty 원시 경로(m_Mass, m_Materials.Array.data[0])로 동작하고 이후 모든 manage_*의 패턴이 된다. unity_docs (v0.0.10 → 0.0.12)는 31,581개 Unity 6 ScriptReference를 UPM 패키지 내부에 1.2 MiB gzipped JSONL로 동봉한다. 임베딩 모델, 벡터 DB, 외부 API가 없다. 사전 룩업은 1ms 미만, typo 1글자는 2ms, 2글자는 4ms.

그 뒤 v0.0.14의 에셋 편집 세트(describe_shader, manage_material, manage_prefab, manage_asset_import), v0.0.15의 manage_ui, v0.0.19의 UI Juicy Mode, v0.0.20의 Unity 6000.5 호환, v0.0.21→0.0.27의 ui_doc 풀 파이프라인이 이어진다. v0.0.28은 보수적인 성능 패스로 VBCSCompiler pre-warm, in-memory assembly cache 32→128, batch 50MB 응답 가드, 7 콜 = 725B ≈ 181 토큰의 스모크 벤치마크를 안정적으로 찍는다. v0.0.31은 macOS/Linux에서 exec의 Windows-PE csc.exe를 Unity 번들 Mono 호스트로 통과시킨다. v0.0.32→0.0.34는 Unity 6.5+의 비라틴(한국어/일본어/중국어) Windows에서 csc.dll 우선 + UTF-8 BOM 강제로 CP949 콘솔 크래시를 해소했다.

운영자용 가드레일과 결론

Unity 6 + AI 에이전트 조합을 실무에 깔려는 팀에게 hera-agent-unity는 의외로 단순한 출발점을 준다. 미들웨어를 새로 띄울 필요도, Python 가상환경을 맞출 필요도 없다. Go 바이너리 하나, UPM 패키지 하나, localhost HTTP 하나. AI는 "추측" 대신 "측정"으로 응답하고, UI는 "동작"만이 아니라 "느껴지는" 결과물로 나온다. 2026년 6월 기준으로 가장 가벼운 MCP 대안이자, LLM이 Unity 에디터를 진짜 손으로 만지게 만드는 가장 정직한 도구다.