Unity Pipeline 패키지 및 Unity CLI: 설치 가이드 및 사용법
주요 내용 요약
- Unity Pipeline 패키지는 Unity 에디터 내에서 실행되며 HTTP 및 JSON API 통해 명령을 제공합니다.
- Unity CLI는 터미널, 에이전트 및 자동화 스크립트가 해당 명령을 실행할 수 있도록 하는 독립형 클라이언트입니다.
- 내장 명령과 사용자 지정 명령은 프로젝트 설정, 재컴파일, 테스트 및 런타임 제어와 같은 반복 가능한 워크플로를 지원합니다.
- 동일한 명령 계약을 사용하여 Unity CLI, 에이전트 워크플로 및 사용자 지정 인터페이스를 구동할 수 있습니다.
개요
Unity CLI는 무료이며 현재 베타 버전입니다. Unity Pipeline 패키지와 함께 사용하면 터미널에서 CI, 스크립팅 및 AI 에이전트를 위한 에디터를 제어할 수 있습니다.
Unity Pipeline 패키지는 Unity 에디터 내부에 경량 서버를 추가하여 표준 웹 프로토콜을 통해 터미널이나 다른 도구와 직접 통신할 수 있도록 합니다. 외부에서 상태 확인, 컴파일 또는 테스트 실행과 같은 명령을 실행할 수 있습니다. 이러한 작업은 비동기적으로 관리되므로 스크립트 변경 후 에디터가 다시 로드되더라도 활성 상태를 유지합니다. 이러한 설정을 통해 자동화를 일관성 있고 예측 가능하며 스크립트 작성도 간편하게 할 수 있습니다.
컴포넌트
- Unity CLI: Unity CLI는 에디터와 별도로 설치되는 독립 실행형 바이너리로, 실행 중인 에디터에 연결하여 터미널에서 에디터를 제어합니다. Pipeline 패키지를 사용하려면 Unity 6.0 이상이 필요합니다.
- Unity Pipeline 패키지 : 이 패키지는 CLI를 통해 프로젝트(com.unity.pipeline)에 설치됩니다. 해당 패키지는 에디터 내부에서 실행되며 에디터가 로드될 때 로컬 서버를 자동으로 시작합니다.
- 명령어 : 각 명령어는 프로젝트 내의 함수이며, Unity 자동으로 등록할 수 있도록 태그가 지정되어 있습니다. 내장 명령어는 플레이 모드, 상태, 재컴파일 및 테스트 실행을 지원하며, 사용자 지정 명령어를 추가할 수도 있습니다.
- 평가: 이 기능은 일회성 작업을 위해 실제 Unity 인스턴스 (에디터 또는 실행 중인 빌드) 내에서 C# 코드를 직접 실행합니다. 이 프로그램은 임의의 C# 코드를 실행할 수 있으며 보안 토큰으로 접근이 제한됩니다. 원격 코드 실행처럼 취급하여 로컬 개발 환경에서만 사용하십시오.
건축
- 고객 : 호출자(예: 터미널 , 에이전트 , CI/CD 설정 또는 사용자 지정 UI)
- Unity CLI: 명령어를 API 호출로 변환하는 기본 클라이언트이며, 사용자 정의 UI도 프로토콜을 직접 사용할 수 있습니다.
- 규약: HTTP + JSON 그리고 고객과 Unity 간의 계약
- HTTP 요청을 보낼 수 있는 클라이언트라면 어떤 언어로든 Unity 실행할 수 있습니다. 기본적으로 서버는 localhost에 바인딩되므로 클라이언트는 편집기와 동일한 컴퓨터에서 실행됩니다. 원격 호출자는 사용자가 노출하는 네트워크 경로를 통해 서버에 접근할 수 있습니다.
- Unity 파이프라인 패키지 : 프로젝트에 설치되어 에디터 실행 시 자동으로 시작됩니다.
- Pipeline 패키지는 두 개의 서버를 호스팅합니다. 하나는 에디터 서버 (재생 모드, 상태, 재컴파일, 테스트 실행, 프로젝트 설정)이고, 다른 하나는 런타임 서버 (런타임 파이프라인 관리자를 통해 실행 중인 빌드에서 실시간 편집 가능)입니다.
설정
1단계: Unity CLI를 설치하세요
Unity CLI는 독립 실행형 바이너리(실험적)입니다. 스크립트를 사용하거나 패키지 관리자를 통해 설치한 다음 확인하십시오. 자세한 지침은 Unity CLI 설명서를 참조하십시오.
# macOS / Linux — install script
curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
# macOS / Linux — Homebrew (keeps it current)
brew install --cask unity-cli
# Windows — PowerShell install script
$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
unity --version # verify it's on your PATH2단계: 로그인
에디터를 제어하려면 인증된 세션 필요합니다.
unity auth login # opens a browser sign-in flow
unity auth status # confirm you're signed in3단계: 프로젝트에 Unity Pipeline 패키지를 추가하세요.
Unity Pipeline 패키지는 에디터 내에서 실행되며 Unity CLI에 연결됩니다. 터미널에서 설치하는 경우, 설치하려는 Unity 프로젝트의 루트 디렉터리에 있는지 확인하십시오. Unity Pipeline Install을 실행하면 기본적으로 현재 디렉터리 또는 실행 중인 에디터를 대상으로 합니다. 패키지 관리자를 통해 com.unity.pipeline을 추가할 수도 있습니다. Unity Pipeline 패키지 문서를 참조하세요.
unity pipeline install설치가 완료되면 에디터가 자동으로 서버를 시작합니다. 새로운 파이프라인 메뉴를 확인하여 확정하세요.
4단계: 연결하고 명령어를 나열하세요
패키지를 설치했으면 실행 중인 에디터에 연결하고 스크립트 가능한 항목을 나열하세요.
unity command # list this project's commands이 목록에는 내장 기능(재생 모드, 상태, 재컴파일, 테스트 실행)과 사용자 지정 명령이 모두 포함됩니다. 별도의 설정 없이 모든 에이전트와 호환됩니다.
터미널에서 에디터를 실행하세요
플레이 모드로 들어가거나, 테스트를 실행하거나, 빌드 대상을 나열하거나, 스크린샷을 찍을 수 있습니다.
unity command editor_play
unity command run_tests
unity command list_build_targets
unity command screenshot실행 결과는 예측 가능하며, 위 내용은 극히 일부분에 불과합니다. `unity list` 명령어를 실행하면 내장된 전체 기능(장면, 프리팹, 재질, 애니메이션, 조명/NavMesh 베이킹, 빌드, 스크린샷, 패키지 등)을 확인할 수 있습니다.
사용자 지정 명령
사용자 지정 명령은 일련의 작업을 명령줄에서 한 번의 호출로 묶어줍니다. 명령어는 프로젝트에서 태그가 지정된 함수입니다. 예시:
- 테스트 실행 및 알림: 진단 도구를 실행하고 결과를 팀원들과 한 번의 통화로 공유하세요.
- 사용하지 않는 자산을 리포트 : 프로젝트를 스캔하여 참조가 없는 자산 목록을 만들어 빌드 전에 삭제합니다.
서면 명령은 확정적이고 반복 가능합니다. 동일한 호출은 동일한 결과를 가져오므로 상담원에게 전달하기도 간단합니다.
런타임 제어
런타임 서버는 실행 중인 빌드를 제어합니다. 빈 GameObject를 추가하고, Runtime Pipeline Manager 구성 요소를 추가하고, 빌드에서 활성화를 선택하면 활성화됩니다. 빌드가 실행 중인 상태에서 터미널을 열면 다음과 같습니다.
- 시간을 느리게 하거나, 일시 정지하거나, 다시 시작하세요.
- 실행 중에 게임 오브젝트의 값을 즉시 변경하고 크기를 조정하거나 이동 변환을 수행할 수 있습니다.
- 실행 중에 에셋과 효과를 교체합니다.
반복적인 작업을 위해서는 게임 내에 포함되는 런타임 명령어를 작성하세요 (게임플레이 값 조정, 게임 모드 재정의 등). 이는 결정론적이고, 반복 가능하며, 에이전트에 의해 호출될 수 있습니다.
에이전트 및 평가
모든 명령은 CLI 또는 MCP 모드를 통해 모든 에이전트에서 사용할 수 있습니다. 내장 명령, 사용자 지정 명령 및 평가 명령이 모두 포함됩니다. 에이전트는 두 가지 기능을 가지고 있습니다.
- 반복 가능한 단계를 위한 결정론적 명명 명령
- 명령이 아직 존재하지 않을 때 일회성 C#에 대한 평가를 수행합니다.
한 가지 사용 사례는 에이전트가 eval을 사용하여 무언가를 구축하거나 변경하고, 결정론적 명령을 실행하여 테스트하고, 스크린샷을 찍고, 프롬프트와 이미지를 비교하여 일치할 때까지 반복하는 것입니다. eval은 토큰 게이트 방식의 임의의 C# 코드이므로 에이전트가 접근할 수 있는 범위를 제한해야 합니다.
보안
Unity CLI 및 Pipeline 패키지는 로컬 개발용으로 제작되었으며, 출시용 게임에는 적합하지 않습니다. 기본적으로 모든 것은 사용자의 컴퓨터에 저장되며, 개발 중에만 실행됩니다. 또한, 실제 코드 실행(평가)은 프로젝트별 액세스 키로 제한되므로, 해당 키 없이는 에이전트가 사용자의 에디터에서 임의의 C# 코드를 실행할 수 없습니다. AI 에이전트에게 CLI를 넘겨주는 것은 마치 컴퓨터 접근 권한을 주는 것과 같습니다. 사용자가 할 수 있는 모든 작업을 수행할 수 있으므로, 어떤 작업을 허용할지 신중하게 결정하고, eval 명령어는 로컬 작업에만 사용하도록 해야 합니다.
추가 자료