언리얼 엔진의 언리얼 게임 싱크 레퍼런스 가이드 | 언리얼 엔진 5.3 문서

이 페이지에서는 스튜디오 디플로이를 위해 언리얼 게임 싱크(UGS) 를 환경설정하는 방법을 설명합니다.

오리엔테이션

언리얼 게임 싱크(UnrealGameSync, UGS)의 소스 코드는 Engine/Source/Programs/UnrealGameSync 에 있습니다.

언리얼 게임 싱크 솔루션은 다음 프로젝트로 구성됩니다.

프로젝트	설명
UnrealGameSync	메인 프로그램입니다.
UnrealGameSyncLauncher	새 버전을 사용할 수 있게 되면 메인 프로그램을 자동 업데이트하는 UGS 런처입니다.
MetadataServer	USG와 함께 디플로이하여 빌드에 대한 코멘트 작성, 빌드 상태에 대한 투표, 불량 빌드 표시, PostBadgeStatus에서 제출한 지속적 통합 시스템(Continuous Integration System, CIS) 결과 표시 등, 전체 기능 세트를 활성화하는 REST API입니다. 메타데이터 서버(Metadata Server)는 IIS 7.0 이상 및 .NET 4.6.2가 설치된 Windows 서버 머신에 디플로이해야 합니다.
Installer	UnrealGameSyncLauncher의 MSI 인스톨러입니다. 일반적으로 개발자의 머신에 런처를 가져오는 데 사용되며 그런 다음 개발자의 머신은 퍼포스(Perforce)에서 프로그램을 자동으로 업데이트하고 실행할 수 있습니다. 빌드에는 Wix 3.8이 필요합니다.
PostBadgeStatus	빌드 결과를 MetadataServer 인스턴스로 푸시하는 유틸리티입니다.

환경설정

UGS의 디플로이 세팅은 Engine/Source/Programs/UnrealGameSync/UnrealGameSync/DeploymentSettings.cs 에 지정되어 있습니다. 이 파일을 자신의 팀에 맞는 세팅으로 수정하고, 배포할 실행 파일로 컴파일링합니다.

세팅은 다음과 같습니다.

세팅	설명
`ApiUrl`	개발자에게 정보를 제공하는 데 사용할 메타데이터 서비스(아래 참조)의 실행 중인 인스턴스 URL입니다.
`DefaultDepotPath`	UnrealGameSyncLauncher가 UnrealGameSync 실행 파일을 동기화하는 디폴트 퍼포스 Depot 경로입니다. 이 폴더의 배치 방법은 아래를 참조하세요.
`bSendTelemetry`	빌드 시간에 대한 원격 측정을 메타데이터 서비스에 게시할지 여부입니다.

자동 업데이트

다양한 분기 및 프로젝트를 사용하여 UGS를 대역 밖에서 개발할 수 있도록, 버전 관리에 퍼포스를 사용하는 자체 패치 메커니즘을 통해 UGS를 배포합니다.

거의 업데이트되지 않는 런처 애플리케이션은 Microsoft 인스톨러(MSI) 패키지('Installer' 프로젝트)를 사용하여 각 개발자 머신에 수동으로 설치됩니다(UnrealGameSyncLauncher). 이를 설치하면 시작 메뉴 아이콘이 생성되고 실행하면 최신 UGS 실행 파일을 퍼포스에서 동기화하고 실행합니다. 해당 경로는 모니터링되며 새 실행 파일이 제출되면 프로그램을 재시작하고 재동기화합니다.

이 파일 동기화에는 워크스페이스가 필요하지 않습니다. 퍼포스 서버에서 비저장 방식으로 가져오기 때문입니다.

인스톨러를 빌드하려면 Wix 3.8이 필요합니다.

UnrealGameSyncLauncher가 애플리케이션 업데이트에 사용하는 경로는 DeploymentSettings.cs (위의 링크)를 통해 애플리케이션으로 컴파일링되는 DefaultDepotPath 변수로 지정됩니다. 이 폴더는 다음과 같이 배치해야 합니다(예: DefaultDepotPath = "//depot/UnrealGameSync")

//depot/UnrealGameSync/Release/UnrealGameSync.exe //depot/UnrealGameSync/Release/UnrealGameSync.exe.config //depot/UnrealGameSync/Release/UnrealGameSync.pdb //depot/UnrealGameSync/Release/Ionic.Zip.Reduced.dll

//depot/UnrealGameSync/UnstableRelease/UnrealGameSync.exe //depot/UnrealGameSync/UnstableRelease/UnrealGameSync.exe.config //depot/UnrealGameSync/UnstableRelease/UnrealGameSync.pdb //depot/UnrealGameSync/UnstableRelease/Ionic.Zip.Reduced.dll

체크인된 UnrealGameSync의 사본은 두 개이며 하나는 'Release' 폴더 아래, 다른 하나는 'UnstableRelease' 폴더 아래 있습니다.

기본적으로 Release 폴더 아래 실행 파일이 사용되지만, UnstableRelease 폴더는 UGS 애플리케이션 세팅(Application Settings) 대화창을 통해서 또는 런처 시작 중에 Shift를 눌러 옵트인 사용자에게 테스트 빌드를 배포하는 데 사용할 수 있습니다.

UnrealGameSync의 새 버전은 단순히 새 실행 파일을 제출함으로써 푸시할 수 있습니다. 애플리케이션은 제출된 변경 사항에 대해 폴더를 폴링하고 새 변경 사항이 발견되면 바이너리를 재시작하고 재동기화합니다.

메타데이터 서비스 설정하기

UGS는 웹 서비스와 통신하여 팀원 간에 정보를 공유합니다. 설정 없이도 이 기능을 실행할 수는 있지만 강력한 협업 기능 일부를 사용할 수 없게 됩니다.

빌드 결과 보기 및 빌드 손상에 대한 데스크톱 알림 제공
사용자가 변경 사항에 대한 평가를 표시하고 다른 팀원에게 빌드 문제를 조사 중임으로 다른 팀원에게 표시
사용자별로 동기화된 변경 사항 표시

메타데이터 서비스는 ASP.NET에서 구현되며 데이터베이스 백엔드에 MySql 인스턴스를 설정해야 합니다.

데이터베이스 프로세스는 (이상적으로는) 사용 가능한 모든 머신 리소스를 활용할 수 있어야 하기 때문에 메타데이터 서버가 있는 IIS 인스턴스와 데이터베이스 백엔드를 별도의 머신에서 호스팅하는 것이 좋습니다. 그러나 이것이 필수는 아닙니다.

MySql 백엔드 설정하기

설정을 진행하기 전에 최소 요구사항이 MySQL 8.0이라는 점을 확인해주세요.

MySql 백엔드를 설정하려면 다음 단계를 수행합니다.

MySql 인스톨러의 최신 버전을 다운로드합니다. https://dev.mysql.com/downloads/installer/
설정 타입 선택(Choosing a Setup Type) 에서 서버만 사용(Server Only) 을 선택합니다.
환경설정 단계(Configuration Steps) 에서 다음을 설정합니다.
1. 높은 가용성(High Availability) : 독립형 MySql 서버입니다.
2. 유형 및 네트워킹(Type and Networking) : 위와 같이 IIS 인스턴스와 공유하고 있다면 서버 컴퓨터(Server Computer) 를, 별도의 인스턴스라면 전용 서버(Dedicated Server) 를 선택합니다. TCP/IP 환경설정 및 포트는 모두 디폴트 상태로 둡니다.
3. 인증 방법(Authentication Method) : 강력한 비밀번호 암호화를 사용합니다.
4. 계정(Accounts) 및 역할(Roles) :
  1. 루트 사용자 이름과 비밀번호를 선택합니다. 이것은 데이터베이스의 마스터 계정이므로 비밀번호를 분실하지 않도록 합니다.
  2. IIS 인스턴스가 연결에 사용하는 서비스 계정으로 다른 사용자를 추가합니다. 루트 계정을 사용하지 마십시오.
5. Windows 서비스 (Windows 머신에 설치한 경우): 이 옵션은 그대로 둡니다.
로컬 워크스테이션에 MySql Workbench를 설치합니다. https://dev.mysql.com/downloads/workbench/. MySql Workbench에서 데이터베이스를 보고 조작할 수 있습니다. 또한 백업이나 복원과 같은 관리 작업을 수행할 수 있습니다.

문제 해결하기

ONLY_FULL_GROUP_BY 비활성화하기

ONLY_FULL_GROUP_BY 함수를 활성화하면 MySQL 스크립트를 실행하는 동안 오류가 발생할 수 있습니다. 이 함수를 비활성화하려면 명령을 실행하거나(방법 1) MySQL 옵션 파일을 수정합니다(방법 2).

방법 1: 명령 실행

명령줄에서 MySQL 서버를 시작하고 다음을 실행합니다.

	mysql > SET GLOBAL sql_mode=(SELECT_REPLACE(@@sql_mode, 'ONLY_FULL_GROUP_BY', ''));

명령줄에서 MySQL 서버를 실행하기 어려운 Windows 사용자는 MySQL 8.0 레퍼런스 매뉴얼의 Windows 명령줄에서 MySQL 시작하기를 참조하세요.

방법 2: 옵션 파일 수정

요구사항: MySQL 옵션 파일의 사용법을 잘 모른다면 MySQL 8.0 레퍼런스 매뉴얼의 옵션 파일 사용하기를 참조하세요.

my.cnf 옵션 파일을 찾아서 엽니다.
다음 쿼리를 실행하여 sql_mode 를 확인합니다.
```
         SELECT @@sql_mode;
		
```
SELECT @@sql_mode;
쿼리 결과를 확인합니다. 결과는 다음 값들과 비슷해야 합니다.
```
         ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
		
```
ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
이전 단계의 값을 다음 sql_mode 구문([mysqld] 아래)에 입력하여 my.cnf 를 편집합니다.
```
         sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
		
```
sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
구문에는 ONLY_FULL_GROUP_BY 값은 포함되지 않았다는 점에 유의합니다.
MySQL 서버를 재시작합니다.

더 자세한 정보는 MySQL 8.0 레퍼런스 매뉴얼의 다음 섹션을 참조합니다.

서버 SQL 모드
MySQL GROUP BY 처리하기

메타데이터 서비스 설정하기

메타데이터 서비스를 설정하려면 다음 단계를 수행합니다.

UGS 실행 파일을 수정하여 ApiUrl을 설정합니다.

ASP.NET 웹 퍼블리싱 툴이 설치된 것을 확인합니다. 이 패키지는 Visual Studio 설치에 포함되어 있습니다. 이 패키지를 설치하지 않으면 "TransformXml 작업을 찾을 수 없음"(TransformXml task not found) 오류와 함께 프로젝트 빌드에 실패합니다.
프로젝트는 기존의 web.config 파일 대신 web.template.config.xml 을 제공하며, 이는 .debug 및 .release XML 파일에 대해 변환되어 web.config 를 동적으로 생성합니다. 소스 컨트롤에서 web.config가 아닌 web.template.config 를 체크해야 합니다.
.debug 및 .release XML 파일에서 '연결 스트링(Connection String)' 프로퍼티를 통해 MySql 데이터베이스가 존재하는 장소의 경로를 지정할 수 있습니다. 이것은 MySql의 표준 연결 스트링과 같은 모습입니다.
```
         <add name="ConnectionString" connectionString="server=localhost;UserId=service_account_username;password=service_account_password;" providerName="MySql.Data.Client"/>
		
```
<add name="ConnectionString" connectionString="server=localhost;UserId=service_account_username;password=service_account_password;" providerName="MySql.Data.Client"/>
service_account_username 과 service_account_password 는 MySql 설정 프로세스에서 입력되는 계정 크리덴셜입니다.
데이터베이스는 처음 사이트를 시작할 때 자동으로 시드됩니다.

서버가 올바르게 환경설정되었는지 확인하려면 웹 브라우저에서 servername.com/api/latest 를 엽니다. 그러면 다음과 같은 내용이 표시됩니다.

	<LatestData xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/MetadataServer.Models">
	  <LastBuildId>0</LastBuildId>
	  <LastCommentId>0</LastCommentId>
	  <LastEventId>0</LastEventId>
	</LatestData>

데이터베이스를 올바르게 초기화하기 위해 생성에 실패하거나 찾을 수 없으면 사이트가 종료됩니다. 사이트 디플로이 후에 404 오류가 발생한 경우에는 이것이 원인일 수 있습니다. 연결 스트링을 확인하고, 별도의 인스턴스에 있는 경우 IIS 인스턴스가 데이터베이스와 통신할 수 있는지도 확인합니다.

빌드 프로세스와 통합하기

배지

UGS는 제출된 체인지리스트에 표시되는 배지(Badges) 를 통해 빌드 시스템의 결과(빌드가 '진행 중'이라는 알림)를 제공할 수 있습니다. 빌드가 손상되면 마지막 성공 이후에 제출한 개발자에게 알림이 표시됩니다. 배지를 클릭하면 웹 브라우저가 열리고 빌드 로그가 포함된 URL 페이지가 표시됩니다.

이 정보는 메타데이터 서비스에 저장되며 PostBadgeStatus 유틸리티를 사용하여 항목을 추가할 수 있습니다.

PostBadgeStatus

PostBadgeStatus 의 명령줄 구문은 다음과 같습니다.

	PostBadgeStatus.exe
	    //(UGS에 표시되는 배지 이름.)
	  -Name=Editor
	    //(컴파일 중인 체인지리스트.)
	  -Change=123456
	    //(배지를 표시할 프로젝트. 이것은 실제 .uproject 파일이 아니라 폴더의 경로입니다.)
	  -Project=//UE4/Main/Samples/StarterContent
	    //(UGSAPI가 디플로이된 베이스 URI )
	  -RestUrl="http://ugsapi-server.net"
	    //(빌드의 상태. 유효 값은 'Starting', 'Failure', 'Warning' 및 'Success'입니다.)
	  -Status=Success
	    //(사용자가 배지를 클릭하면 이 링크를 통해 빌드 로그로 이동하게 됩니다.)
	  -Url=http://link-to-build-log

프로젝트 커스터마이징하기

브랜딩

UGS에 표시할 프로젝트 로고를 추가하려면 프로젝트가 포함된 디렉터리에 Build\UnrealGameSync.png 파일을 넣습니다. 이미지는 높이 126 픽셀로 조정됩니다.

권장 크기는 200x126 픽셀입니다.

참고용 이미지는 무료로 다운로드할 수 있습니다.

프로젝트 환경설정 파일

프로젝트별 환경설정 파일에서 프로젝트를 사용자에게 표시하는 방법을 커스터마이징할 수 있습니다. 프로젝트 환경설정 파일은 <ProjectDir>/Build/UnrealGameSync.ini 로 퍼포스에 제출해야 합니다.

사용 가능한 세팅은 다음과 같습니다.

기본적으로 UGS는 프로젝트의 소스 코드 변경으로 인한 빌드 실패 알림만 표시합니다. 콘텐츠를 제출하는 개발자에게 표시해야 할 배지가 있는 경우에는 다음과 같이 화이트리스트에 추가합니다.
```
          [Notifications]
          +ContentBadges=Content
		
```
[Notifications] +ContentBadges=Content

클릭 가능한 버튼을 CL 설명 열에 추가하는 경우, 해당 버튼을 클릭하면 CL 설명에 정규식을 실행하여 사용자를 URL로 이동시킵니다. 예를 들어 다음 사용 사례에서는 Jira의 해당 문제로 가는 링크가 포함된 #jira 태그가 있는 배지를 모든 CL 옆에 추가합니다.

          [Badges]
          +DescriptionBadges=(Pattern="(?i)#\\s*jira\\s*:?\\s+([A-Za-z]+-[0-9]+)", Name="$1", Group="Jira", Color="#c0c0c0", HoverColor="#e0e0e0", Url="https://jira.it.yourcompany.net/browse/$1")

이 예시에는 다음 어트리뷰트가 사용되었습니다.

어트리뷰트	설명
Pattern	일치하는 정규식을 지정합니다. 일치하는 텍스트의 일부를 캡처할 수 있으며 이는 나중에 대체될 수 있습니다.
Label	배지에 표시되는 라벨을 지정합니다.
Group	임의의 식별자를 지정해 공백으로 구분하지 않고 관련 배지를 그룹화합니다.
Color	배지에 대한 16진법 RGB 값을 지정합니다.
HoverColor	배지에 마우스 커서를 가져갔을 때의 16진법 RGB 값을 지정합니다.
Url	C# 프로세스에서 열 경로를 지정합니다. 배지를 클릭하면 호출을 엽니다.

특정 분기에 해당하는 상태 패널의 색상과 '오늘의 메시지'를 추가합니다.

		[//UE4/Main/Samples/Games/ShooterGame/ShooterGame.uproject]
		Message=:alert: 수정 마감 시간은 **금요일 오후 5시입니다**. 이 분기에는 1.2.3 릴리스 수정만 제출해야 합니다. 1/23 현재 123개의 문제가 남아 있습니다.
		StatusPanelColor=#e20000

		StatusPanelColor 옵션을 사용하면 쉽게 스트림을 식별할 수 있습니다. 또한 메시지 옵션을 사용할 때는 다음을 포함하여 마크다운의 제한된 서브셋이 지원됩니다.

		[web links](http://www.google.com)
		*italic*
		_italic_
		**bold**
		__bold__

아이콘은 :icon: 구문을 사용하여 지원되지만 현재 사용 가능한 아이콘은 :alert: 뿐입니다.

배지 크기와 CIS 열의 배열을 커스터마이징합니다.
```
          [Default]
          ColumnWidth_CIS=580
          +BadgeGroups=Editor
          +BadgeGroups=And, Lin, PS4, XB1, Win, IOS, Mac, Swi
          +BadgeGroups=Content
		
```
[Default] ColumnWidth_CIS=580 +BadgeGroups=Editor +BadgeGroups=And, Lin, PS4, XB1, Win, IOS, Mac, Swi +BadgeGroups=Content
프로젝트별 동기화 필터는 다음과 같이 정의합니다.
```
          [Options]
          +SyncCategory=(UniqueId="d9610e2f-7f6f-4898-bc98-d39dd7053d75", Name="FirstCategory", Paths="/MyGame/Content/Foo/...")
		
```
[Options] +SyncCategory=(UniqueId="d9610e2f-7f6f-4898-bc98-d39dd7053d75", Name="FirstCategory", Paths="/MyGame/Content/Foo/...")
- UniqueId 는 무작위 생성된 GUID입니다.
- Name 은 UGS UI에 표시됩니다.
- Paths 는 세미콜론으로 구분됩니다.
기존의 카테고리 세팅을 수정하려면 .../UnrealGameSync/Workspace.cs 의 DefaultSyncCategories 배열에 있는 GUID 를 지정합니다. 기본적으로 UGS는 기존 목록에 지정 경로를 추가하지만 Clear=true 로 설정하면 대체합니다.

사전 컴파일링된 바이너리

사용자가 로컬로 컴파일된 것 대신 사전 컴파일링 에디터 빌드를 다운로드하게 하기 위해서 필요한 바이너리가 포함된 Zip 파일을 퍼포스에 제출하고, UnrealGameSync가 대신 동기화를 수행하여 추출하게 할 수 있습니다. 이때 로컬로 컴파일링할 때와 같은 유저 인터페이스를 사용하지만, 일치하는 바이너리가 없는 변경 사항은 회색으로 표시됩니다. 환경설정이 완료되면 사용자는 옵션(Options) 메뉴 아래 있는 사전 컴파일링된 바이너리 동기화(Sync Precompiled Binaries) 항목을 선택하여 사전 컴파일링된 바이너리 사용을 허용받을 수 있습니다.

사전 컴파일링된 바이너리의 경로를 환경설정하려면 프로젝트 아래에 Build\UnrealGameSync.ini 파일을 추가하고 다음과 같이 제출된 퍼포스 서버 내 위치를 참조합니다.

	[//UE4/Main/Samples/Games/ShooterGame/ShooterGame.uproject]
	ZippedBinariesPath=//UE4/Dev-Binaries/++UE4+Main-Editor.zip

사전 컴파일링된 바이너리는 일반적인 개발 스트림 외의 위치를 사용하여 바이너리를 사용하지 않는 사람의 혼란을 방지하는 것이 좋습니다. 이를 위해 별도의 워크스페이스를 유지할 필요는 없습니다. 언리얼 게임 싱크는 파일을 동기화하는 데 사용하는 것과 동일한 로그인 크리덴셜을 사용하여 비저장 방식으로 PCB를 가져옵니다.

사전 컴파일링된 바이너리를 사용하기 위해 메타데이터 서버를 설정할 필요는 없습니다. 각 Zip 파일의 수정에 해당하는 체인지리스트는 체인지리스트 설명([CL 12345678] 태그로 시작해야 함)에서 파싱합니다.

에디터 바이너리를 올바른 형식으로 생성하고 제출하는 방법을 보여주는 샘플 스크립트는 다음에서 이용할 수 있습니다. Engine/Build/Graph/Examples/BuildEditorAndTools.xml

이것을 수행하는 일반적인 명령줄은 다음과 같습니다.

	Engine\Build\BatchFiles\RunUAT.bat
	  BuildGraph
	  -Script=Engine/Build/Graph/Examples/BuildEditorAndTools.xml
	  -Target="Submit To Perforce for UGS"
	  -set:EditorTarget=ShooterGameEditor
	  -set:ArchiveStream=//UE4/Dev-Binaries
	  -p4
	  -submit

여기서는 '//UE4/Dev-Binaries/++UE4+Main-Editor.zip'에 zip 파일을 제출합니다. 여기서 '++UE4+Main' 은 슬래시가 '+' 문자로 이스케이프 처리된 현재 분기의 이름입니다. UnrealGameSync.ini 내의 ZippedBinariesPath 값도 동일한 경로로 설정해야 합니다.

BuildEditorAndTools.xml 사용에 관한 추가 정보는 파일 시작 시의 코멘트에서 찾을 수 있습니다.

동기화 필터

이 기능에 관한 자세한 내용은 이 레퍼런스동기화 필터를 참조하세요.