자동화 툴( Unreal Automation Tool, 이하 UAT )은 패키징 프로세스에서 언리얼 엔진(UE) 프로젝트의 조작에 사용되는 유틸리티 스크립트 세트를 실행하는 데 사용되는 툴입니다. 자동화 툴은 패키징 프로세스에서 BuildCookRun 이라는 특별한 명령을 사용합니다. 이 명령은 플랫폼에 사용할 콘텐츠를 쿠킹하고, 배포를 위해 플랫폼의 네이티브 포맷으로 패키징하며, 이를 디바이스에 디플로이하고, 가능한 프로젝트에 한해서 자동으로 프로젝트를 실행합니다. 하지만 프로젝트를 패키징할 때 UAT만 사용해야 하는 것은 아닙니다. UE 툴바 의 플랫폼(Platforms) 버튼으로 사용 가능한 플랫폼을 선택하거나 명령줄을 이용해 플랫폼용 콘텐츠를 쿠킹 및 패키징할 수 있습니다.
다음 스테이지들은 UAT의 BuildCookRun 명령의 일부로, 패키징 파이프라인의 여러 스테이지를 구성합니다.
- 빌드(Build): 선택한 플랫폼의 실행 파일을 컴파일하는 스테이지입니다.
- 쿠킹(Cook): 특별한 모드에서 UE를 실행하여 콘텐츠를 쿠킹하는 스테이지입니다.
- 스테이지(Stage): 실행 파일과 콘텐츠를 개발 디렉터리 외부의 독립형 디렉터리인 스테이징 영역에 복사하는 스테이지입니다.
- 패키징(Package): 프로젝트를 플랫폼의 네이티브 배포 포맷으로 패키징하는 스테이지입니다.
- 디플로이(Deploy): 빌드를 타깃 디바이스에 디플로이하는 스테이지입니다.
- 실행(Run): 타깃 플랫폼에 패키징된 프로젝트를 실행하는 스테이지입니다.
사전 정의된 태스크의 목록은 BuildGraph 스크립트 태스크 레퍼런스 페이지를 참조하세요.
패키징 메서드
콘텐츠를 테스트, 디버깅, 릴리즈 준비할 타깃 플랫폼에 디플로이할 수 있는 여러 가지 방법이 있으므로 다음과 같이 다양하게 패키지를 테스트할 수 있습니다.
- UE 툴바를 사용하여 테스트와 디버깅에 사용할 현재 로드된 레벨 의 일부를 빠르게 테스트합니다.
- 프로젝트 런처(Project Launcher)로 디폴트 프로파일을 사용하거나, 커스텀 프로파일을 생성해 프로젝트의 최신 빌드를 대상으로 프로파일링, 디버깅 같은 행동을 수행합니다.
- 이미 패키지로 만든 게임을 가져와 콘솔이나 모바일 디바이스 같은 플랫폼에 디플로이합니다.
아래의 섹션을 따라 이에 해당하는 패키징 메서드와 메서드를 이용해 게임을 패키징하는 방법을 알아보세요.
UE 툴바
UE 툴바 의 플랫폼(Platforms) 버튼을 사용하여 프로젝트를 패키징할 플랫폼을 선택합니다. 이 옵션을 사용하여 프로젝트를 패키징할 경우, 패키징한 프로젝트는 선택한 폴더에 저장되지만 디바이스에 디플로이되지는 않습니다.
플랫폼(Platforms) 의 드롭다운 메뉴에서 다음과 같은 작업을 수행할 수 있습니다.
-
사용 가능한 디바이스에서 프로젝트를 빌드하고 실행합니다. 버튼을 클릭하면 실행 프로세스가 자동으로 필요한 콘텐츠를 쿠킹하고, 코드를 빌드한 뒤 선택된 플랫폼에 실행합니다. 빌드는 액티브 개발 도중 매번 프로젝트 전체를 컴파일 및 실행하지 않고도 빠르게 기능을 테스트할 수 있는 방법입니다.
-
타깃 플랫폼을 선택하고 개발(Development), Shipping 등 해당 빌드 환경설정 을 조정합니다.
-
프로젝트 런처(Project Launcher), 디바이스 매니저(Device Manager), 패키징 세팅(Packaging Settings), 지원 플랫폼(Supported Platforms) 에 액세스합니다.
디플로이하려는 플랫폼이 보이지 않거나 해당 메뉴에서 선택할 수 없는 경우, 다음 사항을 점검합니다.
- 플랫폼에서 SDK를 요구하는 경우, 해당 SDK가 제대로 설치되었으며 사용 중인 엔진 버전에서 이를 지원하는지 확인합니다. 대부분의 경우, Engine/Source/Programmings/UnrealBuiltTools/Platforms 에 있는 플랫폼의 UEBuild.cs 파일에서 확인할 수 있습니다. 예를 들어, Android를 지원하는 SDK를 찾을 때는 UEBuildAndroid.cs 파일에서 확인하면 됩니다.
- Visual Studio 익스텐션 등의 필요한 파일이 설치되었는지 확인합니다.
- 콘솔 등 일부 플랫폼은 외부 툴이 있어야 디바이스에 연결할 수 있습니다. 제대로 작동되는지, 디바이스가 발견되었는지 확인하세요.
- 언리얼 엔진의 디바이스 매니저(Device Manager) 를 사용해 필요한 디바이스를 모두 '독점'합니다. 단, 자신의 로컬 머신에서만 사용할 수 있습니다.
프로젝트 런처
프로젝트 런처를 사용하면 단일 위치, 또는 단일 실행 프로파일에서도 다양한 플랫폼에 디플로이할 수 있습니다. 플랫폼(Platforms) > 프로젝트 런처(Project Launcher) 를 클릭하여 프로젝트 런처를 엽니다.
콘텐츠를 디플로이할 플랫폼마다 디폴트 실행 프로파일이 존재합니다. 실행 프로파일은 메인 창 목록에서 찾을 수 있습니다. 커스텀 프로파일을 생성해 고급 설정이 다수 포함된 프로젝트를 빌드할 수도 있습니다. 사용 가능한 설정에는 명령줄 아규먼트 적용, 다운로드 콘텐츠(DLC) 테스트, 릴리즈 패치 등이 있습니다.
추가 정보는 프로젝트 런처 레퍼런스 페이지를 참조하세요.
커스텀 실행 프로파일
프로젝트 런처에서 커스텀 실행 프로파일(Custom Launch Profile) 을 생성할 수 있습니다. 이 프로파일은 모든 플랫폼에서 사용할 수 있으며 여기에는 따로 지정한 플랫폼도 포함됩니다. 이 프로파일로 사용 가능한 빌드 작업을 호출하여, 쿠킹, 패키징, 디플로이 방식을 설정해 지정한 방식대로 콘텐츠를 빌드할 수 있습니다.
커스텀 실행 프로파일을 추가하려면 커스텀 실행 프로파일 창 우측의 추가(Add) 버튼을 클릭합니다.
클릭하면 바로 커스텀 실행 프로파일 창이 실행됩니다. 알아보기 쉽도록 이름(Name) 과 설명(Description) 을 입력합니다.
명령줄
자동화 툴을 사용하면 명령줄을 사용하여 게임을 쿠킹 및 패키징할 수 있으며, 모든 빌드 작업은 UAT에서 수행하므로 유효한 아규먼트가 포함된 경우 RunUAT.bat 에서 명령줄로 직접 실행할 수 있습니다.
RunUAT 파일은 Engine/Build/BatchFiles 에 있습니다. Windows에서는 RunUAT.bat 파일을, Mac/Linux에서는 RunUAT.sh 파일을 사용합니다.
UnrealEditor.exe 또는 UnrealEditor-cmd.exe 파일에 다음의 명령줄 아규먼트를 추가하여 기본적인 쿠킹을 수행할 수 있습니다.
UnrealEditor.exe [게임 이름 또는 .uproject] -run=cook -targetplatform=[플랫폼] -cookonthefly -iterate -map=[맵 이름]
커맨드릿은 -run=cook 을 통해 지정해야 하며, 쿠킹할 플랫폼도 지정해야 합니다. 완료 시 지정된 플랫폼에서 쿠킹된 데이터를 생성하고 다음 위치에 저장합니다.
[UnrealEditor Project]/Saved/Sandboxes/Cooked-[플랫폼]
명령줄 아규먼트를 직접 입력하면 수고가 들며 실수로 오류가 발생할 확률도 높습니다. 따라서 빌드에 사용할 명령줄을 정확하게 생성하기 위해 커스텀 실행 프로파일 사용을 권장합니다. 커스텀 실행 프로파일에 입력된 모든 파라미터는 자동으로 명령줄을 생성하고, 프로젝트의 쿠킹 및 빌드에 사용될 때 출력 로그(Output Log) 창에 이를 표시합니다. BuildCookRun 다음으로 등장하는 모든 텍스트는 RunUAT.bat 을 사용하여 명령줄 아규먼트의 형태로 직접 전달할 수 있습니다.
다음은 프로젝트 런처 및 RunUAT.bat 에 사용하기 위해 직접 작성해야 하는 동일한 내용의 명령줄에서 생성한 출력 결과의 예시입니다.
-
프로젝트 런처 로그 창
Automation.ParseCommandLine: Parsing Command Line: -ScriptsForProject=MyProject.uproject BuildCookRun -project=MyProject.uproject -clientconfig=Development -
직접 작성
[UnrealEngineRoot]/Engine/Build/BatchFiles/RunUAT.bat BuildCookRun -project=MyProject.uproject -clientconfig=Development
추가 정보는 콘텐츠 쿠킹 페이지를 참조하세요.
콘텐츠 쿠킹
UE의 콘텐츠는 플랫폼에서 지원되는 특정 포맷으로 저장됩니다. 예를 들어 텍스처 데이터는 PNG, 오디오는 WAV 파일로 저장됩니다. 하지만 이러한 콘텐츠의 포맷과 개발 중인 플랫폼에서 사용하는 포맷이 다를 수 있습니다. 쿠킹(Cooking) 프로세스는 UE에서 사용하는 에셋(Assets) 을 디플로이할 플랫폼에서 읽을 수 있는 형태로 변환합니다. 쿠킹된 콘텐츠 중 일부는 콘솔과 같이 지정한 플랫폼에서만 읽을 수 있는 전용 포맷으로 변환되기도 합니다.
다양한 플랫폼에 대한 콘텐츠 쿠킹은 명령줄이나 프로젝트 런처 및 UE 인터페이스를 사용하여 수행할 수 있습니다. 일부 플랫폼의 경우, 디바이스에서 용도에 맞게 사용하려면 모든 콘텐츠를 쿠킹해야 합니다. 이 경우, 개발 중인 플랫폼을 확인해 해당 절차를 진행해야 하는지 알아봐야 할 수도 있습니다.
프로젝트의 콘텐츠 쿠킹 방식에는 절차적(By The Book) 과 즉흥적(On The Fly) 두 가지가 있습니다.
절차적 쿠킹
절차적 쿠킹(Cook By The Book, CBTB) 은 쿠킹 프로세스를 미리 전부 수행하여, 쿠킹 서버를 사용해 레벨에서 필요할 때마다 에셋을 쿠킹하지 않고 빌드할 때 한 번에 모두 디플로이할 수 있습니다. 이 옵션은 개별 에셋에 반복작업을 하지 않는 개발자나, 서버에서 쿠킹된 콘텐츠를 전달하는 동안 기다리는 일 없이 최고 속도로 게임을 하려는 사람들에게 유용합니다. 일반적으로 퍼포먼스 및 플레이 테스트에서 이 메서드를 사용합니다.
CBTB 수행 시에는 빌드에 셋업을 추가하지 않아도 됩니다. 프로젝트 런처를 사용해 커스텀 실행 프로파일 생성을 수행한 다음, 쿠킹(Cook) 섹션의 드롭다운 메뉴에서 By The Book 을 선택합니다.
따로 추가할 게임 전용 명령이 있다면 고급 세팅(Advanced Settings) 을 연 다음 추가 쿠커 옵션(Additional Cooker Options) 에 아규먼트를 추가합니다.
예시:
-nomcp
해당 쿠킹 메서드와 사용 가능한 옵션에 대한 추가 정보는 프로젝트 런처 레퍼런스 페이지를 참조하세요.
즉흥적 쿠킹
콘텐츠를 즉흥적으로 쿠킹(Cook On The Fly, COTF) 하는 경우, 게임을 플랫폼에 디플로이할 때까지 쿠킹 절차가 연기됩니다. 실행 파일과 일부 기본적인 파일만 설치되며, 해당 파일은 콘텐츠가 필요할 때 요청을 위해 쿠킹 서버(Cook Server) 와 네트워크로 통신합니다. COTF를 사용하면 콘텐츠를 주기적으로 변경해야 하는 개발자와 게임의 일부만 체험하는 사람들이 빠르게 반복작업을 수행할 수 있습니다.
COTF를 진행하려면 우선 사용 가능한 전체 프로젝트가 설치된 머신에서 쿠킹 서버를 실행해야 합니다. 로컬 머신 또는 쿠킹 프로세스를 수행하는 원격 서버에서 실행할 수 있습니다. UnrealEditor-cmd.exe 에서 다음 아규먼트를 사용하는 명령줄 모드로 UE를 시작하면 쿠킹 서버를 실행할 수 있습니다.
UnrialEditor-cmd.exe [FullAbsolutePathToProject.uproject]-run=cook -targetplatform=Windows -cookonthefly
개발자의 로컬 머신에서 쿠킹을 진행할 경우, 프로젝트 런처에서 커스텀 실행 프로파일에 액세스한 뒤, 디플로이(Deploy) 섹션에서 파일 서버(File Server) 에 대한 메서드를 설정하세요. 디폴트 디플로이 플랫폼(Default Deploy Platform) 을 사용해 단일 플랫폼을 선택하거나 토글 설정으로 여러 플랫폼에 대한 빌드 및 디플로이 기능을 활성화할 수도 있습니다.
실행 파일에 로드할 콘텐츠의 위치를 알려주려면 쿠킹 서버에서 실행 중인 머신의 IP 주소를 알아야 합니다. 클라이언트 명령줄(x.x.x.x는 호스트의 IP 주소)에 다음의 명령줄 아규먼트를 전달해야 해당 주소를 알 수 있습니다.
-filehostip=123.456.78.90
아규먼트는 추가 명령줄 파라미터(Additional Command Line Parameters) 텍스트 박스 실행(Launch) 섹션의 커스텀 실행 프로파일에서 지정할 수 있습니다. IP 주소를 지정하지 않을 경우, 빌드는 콘텐츠를 기존 로컬 파일에서 로드하며 쿠킹 서버 연결을 시도하지 않습니다.
해당 쿠킹 메서드와 사용 가능한 옵션에 대한 추가 정보는 프로젝트 런처 레퍼런스 페이지를 참조하세요.
빌드 디플로이
프로젝트 런처에서 빌드를 디플로이하려면 쿠킹 및 패키징된 프로젝트가 있어야 합니다. 다양한 방법으로 이러한 빌드 유형을 플랫폼에 디플로이할 수 있습니다. 디플로이(Deploy) 섹션의 커스텀 실행 프로파일에서 빌드의 디플로이 방식을 설정할 수 있습니다.
- 파일 서버(File Server): 런타임 시 디바이스의 요구에 따라 콘텐츠를 쿠킹 및 디플로이합니다.
- 디바이스에 복사(Copy to Device): 쿠킹된 빌드 전체를 디바이스에 복사합니다.
- 디플로이하지 않음(Do Not Deploy): 쿠킹 및 패키징이 완료되어도 디바이스에 빌드를 디플로이하지 않습니다.
- 저장소 복사(Copy Repository): 지정한 파일 위치에 있는 빌드를 디바이스에 디플로이합니다.
해당 디플로이 메서드와 사용 가능한 옵션에 대한 추가 정보는 프로젝트 런처 레퍼런스 페이지를 참조하세요.