niqibiao/unity-cli-plugin

Unity Editor를 위한 AI 코딩 에이전트 플러그인 — Claude Code 및 Codex CLI 지원

unity-csharpconsole 기반

씬 편집(scene editing), 컴포넌트(components), 에셋(assets), 스크린샷(screenshots), 프로파일링(profiling) 등을 위한 40개 이상의 명령어를 제공합니다.

unity-csharpconsole에 의존합니다 — 이는 Unity를 위한 Roslyn 기반의 대화형 C# REPL입니다.

빠른 시작 · 사용법 · 명령어 · 사용자 정의 명령어 · 아키텍처

영어 | 中文

사용자: "원을 그리며 10개의 큐브를 생성하고 각각에 Rigidbody를 추가해줘"
Claude: 완료되었습니다. 반지름 5인 원에 10개의 큐브가 생성되었으며, 각 큐브에는 Rigidbody 컴포넌트가 추가되었습니다.

Claude Code의 스킬 시스템(skill system)을 통해 노출되는 CLI 명령어입니다.

토큰 효율적 (Token-efficient). 스킬이 필요할 때만 로드됩니다.
제한 없음 (Unrestricted). 미리 정의된 도구에 국한되지 않고 전체 Roslyn C# REPL로 전환됩니다.
사이드카 없음 (No sidecar). 서비스가 Unity Editor 내부에서 실행됩니다. 별도의 프로세스가 필요 없습니다.
워크플로우 인식 (Workflow-aware). Unity의 컴파일 라이프사이클(compile lifecycle), 플레이 모드(play mode), 도메인 리로드(domain reload)를 이해합니다.
자동 사용자 정의 명령어 발견 (Automatic custom command discovery). 사용자가 정의한 C# 명령어가 스킬 카탈로그(skill catalog)에 동기화됩니다.
런타임 / IL2CPP 지원 (Runtime / IL2CPP support). 런타임 빌드를 위해 HybridCLR과 함께 작동합니다.

사전 요구 사항: Claude Code, Unity 2022.3 이상, Python 3.7 이상

# 1. 마켓플레이스를 추가하고 플러그인을 설치합니다
claude plugin marketplace add niqibiao/unity-cli-plugin
claude plugin install unity-cli-plugin
...

참고: Codex CLI는 아직 공식적으로 서드파티 플러그인 배포를 지원하지 않습니다. 아래 단계는 로컬 워크스페이스 마켓플레이스에 의존하며, 이는 향후 릴리스에서 변경될 수 있습니다.

사전 요구 사항: Codex CLI, Unity 2022.3 이상, Python 3.7 이상

# 1. Unity 프로젝트에서 Codex를 시작합니다
cd /path/to/your/unity-project
codex
...

수동 설치 / 이미 마켓플레이스가 있는 경우

cd /path/to/your/unity-project
git clone --depth=1 -b codex-plugin https://github.com/niqibiao/unity-cli-plugin.git plugins/unity-cli-plugin
rm -rf plugins/unity-cli-plugin/.git

그 다음 .agents/plugins/marketplace.json에 추가합니다.

:

{
"name": "local-workspace",
"plugins": [{
...

그저 Claude에게 원하는 것을 말하세요:

방향성 조명 (Directional Light)을 추가하고 X축으로 45도 회전시켜라
모든 "Enemy" 오브젝트를 찾아 그 컴포넌트(Component)들을 나열하라
Scene View의 스크린샷을 찍어라
...

Claude는 필요에 따라 적절한 명령어를 선택하거나 C# 코드를 작성합니다.

명령어	설명
/unity-cli-setup	Unity 패키지 설치
/unity-cli-status	패키지 및 서비스 상태 확인
/unity-cli-refresh	에셋 리프레시 (Asset refresh) / 재컴파일 (Recompile) 트리거
/unity-cli-refresh-commands	캐시된 커스텀 명령어 목록 리프레시
/unity-cli-sync-catalog	로컬 명령어 카탈로그와 라이브 목록 비교

python cli/cs.py exec --json --project . "Debug.Log(\"Hello\")"
python cli/cs.py command --json --project . gameobject create '{"name":"Cube","primitiveType":"Cube"}'
python cli/cs.py refresh --json --project . --exit-playmode --wait 60
...

13개의 네임스페이스 (Namespace)에 걸쳐 50개의 내장 명령어가 제공됩니다. 모든 명령어는 --json 출력을 지원합니다.

동작 (Action)	설명
find	이름, 태그(Tag) 또는 컴포넌트 타입(Component type)으로 GameObject 찾기
create	새로운 GameObject 생성 (빈 오브젝트 또는 프리미티브 (Primitive))
destroy	GameObject 삭제
get	GameObject에 대한 상세 정보 가져오기
modify	이름, 태그, 레이어 (Layer), 활성화 상태 (Active state) 또는 스태틱 플래그 (Static flag) 변경
set_parent	GameObject의 부모 재설정 (Reparent)
duplicate	GameObject 복제

동작 (Action)	설명
add	GameObject에 컴포넌트 추가
remove	GameObject에서 컴포넌트 제거
get	컴포넌트의 직렬화된 필드 (Serialized field) 데이터 가져오기
modify	컴포넌트의 직렬화된 필드 수정

동작 (Action)	설명
get	위치 (Position), 회전 (Rotation), 스케일 (Scale) 가져오기
set	위치, 회전 및/또는 스케일 설정 (로컬 또는 월드)

동작 (Action)	설명
hierarchy	전체 씬 계층 구조 (Scene hierarchy) 트리 가져오기 (선택 사항으로 컴포넌트 정보 포함)

동작 (Action)	설명
create	씬의 GameObject로부터 프리팹 (Prefab) 에셋 생성
instantiate	프리팹을 활성화된 씬에 인스턴스화 (Instantiate)
unpack	프리팹 인스턴스 언팩 (Unpack)

Action	Description
create	지정된 셰이더 (Shader)를 사용하여 새로운 머티리얼 (Material) 에셋 생성
get	에셋 또는 렌더러 (Renderer)로부터 머티리얼 속성 (Properties) 가져오기
assign	렌더러 (Renderer) 컴포넌트에 머티리얼 할당

Action	Description
scene_view	씬 뷰 (Scene View)를 이미지 파일로 캡처
game_view	게임 뷰 (Game View)를 이미지 파일로 캡처

Action	Description
start	프로파일러 (Profiler) 기록 시작 (선택적 딥 프로파일링 (Deep Profiling))
stop	프로파일러 (Profiler) 기록 중지
status	현재 프로파일러 (Profiler) 상태 가져오기
save	기록된 프로파일러 (Profiler) 데이터를 .raw 파일로 저장

Action	Description
status	에디터 (Editor) 상태 및 플레이 모드 (Play Mode) 정보 가져오기
playmode.status	현재 플레이 모드 (Play Mode) 상태 가져오기
playmode.enter	플레이 모드 (Play Mode) 진입
playmode.exit	플레이 모드 (Play Mode) 종료
menu.open	경로를 통해 메뉴 아이템 실행
window.open	타입 이름으로 에디터 윈도우 (Editor Window) 열기
console.clear	에디터 콘솔 (Console) 비우기
console.mark	에디터 로그 (Editor Log)에 검색 가능한 마커 (Marker) 작성

Action	Description
move	에셋 이동 또는 이름 변경
copy	에셋을 새로운 경로로 복사
delete	하나 이상의 에셋 삭제
create_folder	에셋 데이터베이스 (Asset Database)에 폴더 생성

Action	Description
scene.list	프로젝트 내의 모든 씬 (Scene) 목록 표시
scene.open	경로를 통해 씬 (Scene) 열기
scene.save	현재 씬 (Scene) 저장
selection.get	현재 에디터 선택 항목 가져오기
selection.set	에디터 선택 항목 설정
asset.list	타입 필터에 따른 에셋 목록 표시
asset.import	경로를 통해 에셋 임포트 (Import)
asset.reimport	경로를 통해 에셋 리임포트 (Reimport)

Action	Description
list	활성화된 REPL 세션 목록 표시
inspect	세션 상태 조사
reset	세션의 컴파일러 (Compiler) 및 실행기 (Executor) 초기화

Action	Description
list	등록된 모든 명령 (Built-in + Custom) 목록 표시

커스텀 명령 (Custom commands)이 지원됩니다. 명령을 정의하고 등록하는 방법은 unity-csharpconsole을 참조하세요.

이 플러그인은 프로젝트별로 커스텀 명령 (Custom commands) 카탈로그를 지속적으로 유지 관리합니다. cs catalog sync를 실행하여 Unity로부터 최신 목록을 가져와 디스크에 캐시(cache)하세요. cs catalog list를 실행하면 Editor에 연결하지 않고도 오프라인 상태에서 캐시된 카탈로그를 볼 수 있습니다.

Claude Code Unity Editor
┌──────────────────┐ ┌──────────────────────────┐
│ Skills │ │ com.zh1zh1.csharpconsole│
...

플러그인 계층 (Plugin layer): Claude Code에 의해 호출되는 기술 (Skills) 및 슬래시 명령 (slash commands)
CLI 계층 (CLI layer): Python 디스패처 (dispatcher), 요청을 JSON으로 직렬화 (serialize)
Unity 계층 (Unity layer): unity-csharpconsole — HTTP 서비스, 자동 검색된 명령 핸들러 (command handlers), Roslyn C# REPL

프로젝트 루트 (project root)와 서비스 포트 (service port)를 자동으로 감지합니다. 수동 설정이 필요 없습니다.

문제	해결 방법
service: UNREACHABLE	Unity Editor가 프로젝트를 로드한 상태로 열려 있는지 확인하세요
package: NOT FOUND	/unity-cli-setup을 실행하거나 Packages/manifest.json을 확인하세요
포트 충돌 (Port conflict)	서비스가 다음 사용 가능한 포트로 자동 전환됩니다. Temp/CSharpConsole/refresh_state.json을 확인하세요
명령을 찾을 수 없음 (Commands not found)	패키지가 성공적으로 컴파일되었는지 확인하세요 (Unity Console에 에러가 없어야 함)
버전 불일치 (Version mismatch)	/unity-cli-status를 실행하여 버전 정보를 확인하세요. 프로토콜이 다를 경우 패키지를 업데이트하세요

이 플러그인이 시간을 절약해 주었다면, 별(star)을 눌러주는 것을 고려해 주세요. 다른 사람들이 이 프로젝트를 찾는 데 도움이 됩니다.