Unity Agentic Tools
이 스킬은 Unity Agentic Tools CLI 설정, 명령어 탐색, 명령어 실행, 라이브 에디터 브리지 워크플로우 및 고급 프로젝트 자동화에 사용됩니다.
중요: 유니티 작업에는 CLI 명령어 실행기를 사용하세요. 사용자가 명시적으로 원시 파일 작업을 요청하지 않는 한, 유니티 직렬화 파일(.unity, .prefab, .asset, .mat, .anim, .controller, .meta, ProjectSettings/)을 수동으로 변경하지 마세요.
명령어 표
| 명령어 | 설명 |
|---|---|
list [query] | 내장된 별칭, 속성 기반 프로젝트 명령어 및 선택적 원시 정적 API를 탐색합니다. --brief는 인수별 세부 정보를 생략하고, --raw는 원시 정적 API를 추가합니다. |
run <target> [args...] | Unity 브리지를 통해 명령어 별칭 또는 원시 공개 정적 C# 메서드/프로퍼티를 실행합니다. |
stream [topic] | WebSocket을 통해 실시간 브리지 이벤트를 관찰합니다. |
install | Unity 브리지 패키지를 설치합니다. |
uninstall | Unity 브리지 패키지를 제거합니다. |
cleanup | 오래된 브리지 상태 또는 재구성 가능한 .unity-agentic 캐시를 제거합니다. |
status | 명령어 실행기 및 브리지 연결 가능 여부를 확인하고, 에디터가 무엇을 처리 중인지 알려주는 readiness 블록을 표시합니다. |
명령어는 기본적으로 간결한 한 줄 JSON을 출력하며, 들여쓰기 출력을 원하면 --pretty를 전달하세요. 탐색 시 list <query> --brief를 선호합니다.
기본적으로 install은 GitHub 패키지 URL을 작성합니다. 로컬 브리지 패키지 개발 시 install --local [path]를 사용하고, 기존 file: 종속성은 install --remote가 전달되지 않는 한 유지됩니다.
기본 경로
unity-agentic-tools status -p <project>unity-agentic-tools list <query> --brief -p <project>query.*,scene.hierarchy,ui.snapshot또는 스크린샷으로 현재 상태를 확인합니다.unity-agentic-tools run <target> ... -p <project>- 해당하는 쿼리, 스냅샷, 스크린샷, 테스트 또는 콘솔 스트림으로 확인합니다.
예제
unity-agentic-tools list scene --brief -p <project>
unity-agentic-tools run project.refresh -p <project>
unity-agentic-tools run query.scene Assets/Scenes/Main.unity -p <project>
unity-agentic-tools run create.gameobject Assets/Scenes/Main.unity EnemyRoot Gameplay -p <project>
unity-agentic-tools run update.transform Assets/Scenes/Main.unity Player 1,2,3 0,90,0 1,1,1 -p <project>
unity-agentic-tools stream console --type Error -p <project>
unity-agentic-tools cleanup --cache -p <project>
구조화된 인수는 작은따옴표로 위치적으로 전달하세요. CLI가 외부 JSON 배열 자체를 인코딩하므로 추가 이스케이프가 필요 없습니다. -로 시작하는 인수에는 --args '<json array>'를 사용하세요. reference/troubleshooting.md의 "JSON Args"를 참조하세요.
unity-agentic-tools run update.batch Assets/Scenes/Main.unity '[{"gameObjectPath":"Player","propertyPath":"m_Name","value":"Hero"}]' -p <project>
별칭 또는 [AgenticCommand] 래퍼가 없을 때는 원시 공개 정적 API를 직접 호출할 수 있습니다.
unity-agentic-tools run UnityEditor.AssetDatabase.Refresh -p <project>
unity-agentic-tools run UnityEditor.EditorApplication.ExecuteMenuItem "File/Save" -p <project>
프로젝트 명령어
각 Unity 작업에 새 CLI 명령어를 추가하지 마세요. 대신 Unity Editor C#에서 공개 정적 메서드/프로퍼티에 [AgenticCommand]를 추가하여 프로젝트별 동작을 노출하세요:
using UnityAgenticTools.Commands;
public static class BuildCommands
{
[AgenticCommand("build.addressables", "Addressables 콘텐츠를 빌드합니다.")]
public static object BuildAddressables(string profile)
{
return new { success = true, profile };
}
}
그런 다음 사용:
unity-agentic-tools list build --brief -p <project>
unity-agentic-tools run build.addressables Production -p <project>
참고 자료
reference/live-editor-workflows.md: 라이브 에디터 설정, 변경, UI 및 배치 워크플로우reference/command-reference.md: 인수 힌트(<required>[optional])가 포함된 생성된 별칭 참조reference/troubleshooting.md: 브리지, 타임아웃, 참조, JSON 인수 및 확인
문제 해결
전체 세부 사항은 reference/troubleshooting.md에 있습니다. 빠른 참고 사항:
- 브리지 연결 안 됨: "브리지 연결 불가" 참조 (설치, Unity 열기, 컴파일 대기, 상태, 정리).
reachable: true이고is_stable: false이면 사용 중이지 고장이 아닙니다. - 긴 빌드 시간 초과:
run기본값은 60초입니다. "장기 실행 명령어" 참조 (--timeout 1200000,--no-wait). play.enter직후 플레이 모드가 잘못 표시됨: 응답은 요청된 상태가 아닌 현재 상태를 보고합니다.play.state를 폴링하세요.reference/live-editor-workflows.md의 "플레이 모드 전환" 참조.- 전환 중 읽기가 느림: 예상된 동작입니다. 읽기는 실패하는 대신 최대 30초 동안 도메인 리로드를 기다립니다. "장기 실행 명령어"의 "도메인 리로드" 참조.
- 오래된
@hN/@uN참조:scene.hierarchy또는ui.snapshot을 다시 실행하세요. "오래된 참조" 참조. - 콘솔 로그 필요:
unity-agentic-tools stream console --duration 5000 -p <project>. - 원시 API 필요:
unity-agentic-tools list <type-or-namespace> --raw -p <project>.