BuildPatch Tool Instructions (1.4.0)

설치 및 프로세싱 - 클로즈 베타

12 분 소요

시작하기 전에

크리덴셜 ID를 찾는 방법

개발자 포털(Developer Portal)에서 몇 가지 ID를 찾아야 합니다.

제품의 클라이언트 ID 및 클라이언트 암호

  1. 개발자 포털 대시보드(Developer Portal Dashboard) > 제품(Product) > 게임 서비스(Games Services) > 제품 세팅(Product Settings) 으로 이동합니다.
  2. 제품 세팅(Product Settings) > SDK 크리덴셜(SDK Credentials) > BPT 크리덴셜(BPT Credentials) 에서 크리덴셜을 확인합니다.

오퍼 아티팩트 이름 및 ID

  • 제품(Product) > 아티팩트(Artifacts) 페이지** > 오퍼 아티팩트(Offer Artifact) > 세부사항 편집 (Edit Details)** 드롭다운을 선택합니다.

  • 아티팩트 이름 및 ID는 아티팩트 관리(Manage Artifact) 모달** > 세부사항 편집(Edit Details) 드롭다운에 표시됩니다.

오퍼에 대한 오퍼 ID

  • 제품(Product) > 오퍼(Offers) 페이지 > 오퍼(Offer) 로 이동합니다.

  • 오퍼 ID는 오퍼 편집(Edit Offer) 메뉴의 하단에 있습니다.

조직의 빌드 패치 툴 크리덴셜 보기

조직(Organization)에서 역할(Roles)이 오너(Owner), 관리자(Admin) 혹은 스토어(Store)인 모든 사용자는 제품의 빌드 패치 툴 크리덴셜을 확인할 수 있습니다. 크리덴셜을 클립보드에 복사할 수도 있습니다.

다음은 조직의 빌드 패치 툴 크리덴셜을 확인하는 방법입니다.

  1. 개발자 포털(Dev Portal)에 로그인합니다.
  2. 크리덴셜을 확인할 제품을 선택합니다.
  3. 제품 세팅(Product Settings) 을 선택합니다.
  4. 스크롤을 내려 SDK 크리덴셜(SDK Credentials) > BPT 크리덴셜(BPT Credentials) 로 이동합니다.
  5. 크리덴셜을 클립보드에 복사하려면 복사(Copy) 를 누릅니다.

명령줄에서 경로 지정

명령 프롬프트는 명령줄에서 \" (백슬래시 뒤 큰따옴표)를 따로 인식하므로, BuildPatchTool 아규먼트에서 경로를 지정할 때 다음 지침 중 최소한 한 가지를 준수해야 합니다.

  • 디렉터리 이름의 마지막에 슬래시를 붙이지 않습니다.
  • 디렉터리 구분자로 포워드 슬래시(/)를 사용합니다.
  • 경로를 따옴표로 묶지 않습니다(경로에 공백이 한 칸 이상 있으면 사용 불가).
  • 경로를 큰따옴표로 묶은 경우, 뒤쪽 백슬래시에만 백슬래시를 하나 더 붙여 이스케이프 처리합니다(오류가 쉽게 발생하므로 비추천).

유효한 경로 구문 예시

  • -BuildRoot="D:/MyFolder/"
  • -BuildRoot=D:\MyFolder\
  • -BuildRoot=D:\MyFolder
  • -BuildRoot="D:\MyFolder"
  • -BuildRoot=D:/MyFolder/
  • -BuildRoot=D:/MyFolder
  • -BuildRoot="D:\MyFolder\\"

잘못된 경로 구문

명령줄에 경로를 다음과 같이 정의한 구문은 제대로 작동하지 않습니다.

-BuildRoot="D:\MyFolder\"

초기 구성

BuildPatchTool ZIP 파일(BuildPatchTool ZIP file)의 콘텐츠를 압축 해제하여 업로드하려는 빌드와 액세스할 수 있는 장치에 전송합니다. 또한, 해당 장치에서 에픽 백엔드와 소통하려면 인터넷에 액세스할 수 있어야 합니다.

참고: 최신 버전의 BPT에서는 ZIP 파일 링크를 항상 최신 상태로 유지합니다. 파일에 액세스할 수 없는 경우 케이스를 생성하세요

인증

인증은 BuildPatchTool에 클라이언트 ID클라이언트 암호 를 넣는 방식으로 진행됩니다. ID와 암호는 명령줄 아규먼트를 사용하는 모든 연산에 필요합니다.

참고: BuildPatchTool에서는 게임이 사용할 수 있는 EOS 클라이언트 ID와 다른 고유 클라이언트 ID 및 클라이언트 암호를 사용합니다. (보통 xyza 로 시작하는) EOS 클라이언트 ID는 BuildPatchTool에 사용할 수 없습니다.

에픽의 백엔드 서비스와 상호작용하는 모든 작업에는 반드시 ClientId 파라미터를 제공해야 합니다. 또한 ClientSecret 혹은 ClientSecretEnvVar 파라미터를 사용하여 반드시 클라이언트 암호를 제공해야 합니다.

ClientSecret 파라미터를 사용할 때는 클라이언트 암호를 다음 파라미터 값 그대로 전달해야 합니다.

Engine\Binaries\Win64>BuildPatchTool.exe
-ClientId="<YourClientId>"
-ClientSecret="<YourClientSecret>"

ClientSecretEnvVar 파라미터를 사용할 경우, 다음과 같이 클라이언트 암호를 포함하는 OS 환경 변수의 이름을 전달해야 합니다.

Engine\Binaries\Win64>set MyEpicSecret=<YourClientSecret>
Engine\Binaries\Win64>BuildPatchTool.exe
-ClientId="<YourClientId>"
-ClientSecretEnvVar="MyEpicSecret"

숨겨진 값이 시스템 로그나 명령줄 내역에 보이지 않도록 막으려면 되도록 ClientSecretEnvVar 파라미터를 사용하는 편이 좋습니다. 가장 좋은 방법은 클라이언트 암호를 해시코프 볼트(Hashicorp Vault)와 같은 암호 관리 시스템에 저장한 뒤, 실행할 때마다 빌드 시스템의 환경에 안전하게 입력하는 것입니다. 이 시스템을 구성하는 방법은 해당 문서의 주제를 벗어납니다.

빌드를 처리하는 방법

Engine/Binaries/Win64/ 디렉터리로 이동합니다. 명령줄을 열고 PatchGeneration 모드에서 BuildPatchTool.exe를 실행한 뒤 자신의 빌드를 지정합니다(다음 CLI 아규먼트 내용을 참조하세요). 그러면 빌드를 처리한 다음, 클라우드 저장 장치에 업로드하고 빌드를 에픽의 백엔드에 등록합니다.

Engine\Binaries\Win64>BuildPatchTool.exe
-OrganizationId="<YourOrg>"
-ProductId="<YourProduct>"
-ArtifactId="<YourArtifact>"
-ClientId="<YourClientId>"
-ClientSecretEnvVar="<YourSecretEnvVar>"
-mode=PatchGeneration
-BuildRoot="<LocationOfLocalBuild>"
-CloudDir="<YourCloudDir>"
-BuildVersion="<YourBuildVersion>"
-AppLaunch="<AppToRun>"
-AppArgs="<LaunchArguments>"
-FileAttributeList="<LocationOfAttributesFile>"
-FileIgnoreList="<LocationOfIgnoreFile>"

다음은 지정해야 하는 파라미터에 대한 설명입니다. 어떤 모드든 뒤에 "-help" 옵션을 추가하여(예: "BuildPatchTool.exe -mode=PatchGeneration -help" ) 필요한 아규먼트에 관한 정보를 볼 수 있습니다.

  • OrganizationID – 크리덴셜과 함께 제공된 조직 ID(Organization ID) 스트링을 사용합니다.

  • ProductID – 크리덴셜과 함께 제공된 제품 ID(Product ID) 스트링을 사용합니다.

  • ArtifactID – 크리덴셜과 함께 제공된 아티팩트 ID(Artifact ID) 스트링을 지정합니다.

  • ClientId 인증(Authentication) 을 참조하세요.

  • ClientSecretEnvVar 인증(Authentication) 을 참조하세요.

  • BuildRoot – 읽고 처리할 빌드가 포함된 디렉터리의 경로입니다. 이 경로는 상대 경로가 아니라 드라이브 루트에서 시작되는 절대 경로여야 합니다. 그리고 파일의 OS MAX_PATH 제한(보통 260자)을 초과하지 않도록 해당 경로를 드라이브 루트 근처에 배치하는 것을 권장합니다.

  • CloudDir – 처리된 기존 빌드 데이터를 인식하고 새 데이터가 추가되는 디렉터리입니다.

    • 이 경로는 BuildRoot 와 마찬가지로 드라이브 루트에서 시작되는 절대 경로여야 합니다. 이 위치는 기존 빌드에 관한 정보를 캐시하는 데 사용되며, BuildRoot 파라미터와는 다른 디렉터리여야 합니다. 처음에 이 디렉터리가 비어 있어도 괜찮습니다. BuildPatchTool은 필요에 따라 에픽 백엔드에서 정보를 다운로드해 ‘CloudDir’에 저장합니다.
  • BuildVersion – 빌드의 버전 스트링입니다. 지정한 아티팩트의 빌드마다 고유한 스트링을 사용해야 합니다. 빌드 버전의 스트링에는 다음과 같은 제한이 있습니다. 문자 길이 제한 1~100자, 공백 입력 불가, a-z/A-Z/0-9/+- 문자만 포함 가능

  • AppLaunch – 게임과 함께 실행되며 BuildRoot와 관련 있는 (BuildRoot 내부에 존재) 앱 실행 파일의 경로입니다. Mac 빌드의 경우 이 파일은 .app 폴더(보통은 Game.app/Contents/MacOS/Game 에 위치)에 포함된 실행 파일이어야 합니다.

  • AppArgs – 실행 시 앱으로 전송할 명령줄입니다. 필요한 추가 아규먼트가 없을 때 “” 으로 설정할 수 있습니다.

  • FileAttributeList (선택 사항) – 설정해야 하는 파일 목록과 이에 해당하는 특별한 어트리뷰트(예: 실행 비트)를 포함하는 텍스트 파일의 절대 경로입니다. 파일 콘텐츠에 대한 설명은 특수 파일 어트리뷰트 세팅(Setting Special File Attributes)을 참조하세요.

    • 참고: 실수로 빌드 콘텐츠에 포함시키는 것을 방지하기 위해 어트리뷰트 파일을 BuildRoot 내부에 배치하지 않습니다.
  • FileIgnoreList (선택 사항) – 생성된 패치 데이터에서 제외해야 하는 파일 목록이 담긴 텍스트 파일의 절대 경로입니다. 각 항목은 새로운 행에 배치되어야 하며, BuildRoot의 상대 경로여야 합니다. 그리고 포워드 슬래시("/") 구분자를 사용해야 합니다.

    • 참고: 무시할 파일이 BuildRoot 안에 있을 경우, 해당 파일의 상대 경로를 무시할 대상 목록에 포함시켜 패치 데이터에서 제외해야 합니다.

특수 파일 어트리뷰트 설정하기

PatchGeneration 모드로 -FileAttributeList 부가 파라미터를 사용하여 빌드 내 파일에 실행파일이나 파일의 태그 지정 그룹 같은 특수 어트리뷰트를 적용할 수 있습니다. 참고로 실행 앱(-AppLaunch 아규먼트로 지정)은 자동으로 실행파일로 표시되므로, 해당 파일을 이 환경설정 파일에 명시적으로 포함하지 않아도 됩니다. 특수 어트리뷰트를 세팅할 필요가 없을 경우, -FileAttributeList 아규먼트를 생략할 수 있습니다.

커스텀 FileAttributeList 파일은 하나 이상의 줄바꿈 구분 항목이 있는 텍스트 파일이어야 합니다. 각 행에 다음과 같이 따옴표로 묶인 BuildRoot 상대 경로를 포함하고, 이후 레퍼런스 파일에 적용할 하나 이상의 어트리뷰트를 공백으로 구분하여 적어야 합니다.

"<QuotedRelativePathToFile>" <list of attributes>

입력 예시:

"Relative/Path/To/My/file.bin" executable tag:my_tag
"Second/Path/To/A/file.txt" tag:txt_files

지원하는 파일 어트리뷰트 플래그는 다음과 같습니다.

  • executable

  • tag:my_tag

파일 태그 지정은 주로 Windows 시스템에서 Mac 빌드를 업로드할 때 실행파일을 명시적으로 표시하기 위해 사용합니다. 이 기능은 에픽게임즈 런처의 선택적 다운로드 기능에도 사용되며, 현지화된 에셋 양이 많은 일부 게임의 다운로드 크기를 줄여줍니다.

데스크탑 바로가기 아이콘 설정하기

데스크탑 바로가기 아이콘은 기본적으로 AppLaunch 아규먼트에서 표시하는 앱 실행파일의 아이콘으로 설정됩니다. 이 아이콘을 업데이트하는 방법은 두 가지입니다.

  • 앱 실행파일에 내장된 아이콘 업데이트

  • 앱 실행파일과 이름이 동일한 .ico 파일을 따로 추가(예: 실행파일이 launch.exe일 경우 launch.ico 파일 생성)

기존 바이너리를 나열하는 방법

백엔드에 다음과 같이 쿼리를 수행하여, ListBinaries 모드에서 이미 등록한 바이너리 목록을 가져올 수도 있습니다.

Engine\Binaries\Win64>BuildPatchTool.exe
-OrganizationId="<YourOrg>"
-ProductId="<YourProduct>"
-ArtifactId="<YourArtifact>"
-ClientId="<YourClientId>"
-ClientSecretEnvVar="<YourSecretEnvVar>"
-mode=ListBinaries

바이너리를 복사하는 방법

CopyBinary 모드를 사용하여 빌드를 다시 업로드할 필요 없이 한 아티팩트의 코드 바이너리를 다른 아티팩트로 복사할 수 있습니다. 최종 빌드를 스테이지(Stage) 아티팩트에서 라이브(Live) 아티팩트로 옮길 때 유용합니다.

-help 명령을 사용하면 모드에 필요한 모든 아규먼트 목록을 생성할 수 있습니다.

예시: C:\Users\Name.Name\Desktop\Engine\Binaries\Win64>BuildPatchTool.exe -help -mode=CopyBinary

필요한 아규먼트

필요한 아규먼트 대부분은 위에서 나열한 모드에서 사용하는 것과 동일합니다.

SourceArtifactId="" — 바이너리가 복사되는 아티팩트의 ID를 지정합니다.

DestArtifactId="" — 바이너리가 붙여넣기되는 아티팩트의 ID를 지정합니다.

업데이트 크기 줄이기

v1.4.0 이상 필요

BuildPatchTool은 PatchGeneration 모드에서 업로드되는 모든 바이너리에 일반 패치 시스템을 사용합니다. 이 시스템을 사용하면 에픽게임즈 스토어가 사용자 컴퓨터의 바이너리 버전을 다른 버전으로 업데이트할 수 있도록 허용하여, 업데이트에 필요한 다운로드 크기를 최소화합니다.

ChunkDeltaOptimise 모드는 에픽 서비스에 이미 업로드된 두 개의 바이너리를 획득한 다음, 두 특정 버전 사이에 업데이트하는 모든 사용자의 다운로드 크기를 줄여줍니다. 이 방식을 A-to-B 패치라고 합니다. 해당 명령을 실행하는 것은 선택 사항이지만, 출시하는 패치의 규모가 평소보다 크고 대부분의 플레이어가 특정 빌드 버전(빌드 ‘A’)을 사용 중일 때 해당 명령으로 사용자 경험을 개선할 수 있습니다.

다음은 두 빌드 간의 델타 패치를 개선하는 명령줄 예시입니다.

Engine\Binaries\Win64>BuildPatchTool.exe
-OrganizationId="<YourOrg>"
-ProductId="<YourProduct>"
-ArtifactId="<YourArtifact>"
-ClientId="<YourClientId>"
-ClientSecretEnvVar="<YourSecretEnvVar>"
-mode=ChunkDeltaOptimise
-CloudDir="<YourCloudDir>"
-BuildVersionA="<YourSourceBuildVersion>"
-BuildVersionB="<YourDestinationBuildVersion>"

ChunkDeltaOptimise 모드를 실행하는 동안, BuildPatchTool에서는 에픽게임즈의 클라우드 네트워크에 있는 기존 바이너리 데이터를 스트리밍 및 재분석한 뒤 새 A-to-B 전용 패치 데이터를 업로드합니다. BuildVersionABuildVersionB 사이에 진행되는 표준 다운로드의 크기가 클 경우, 이 프로세스의 진행 시간이 기본 PatchGeneration 모드보다 더 오래 걸릴 수 있습니다.

일반적으로는 현재 라이브 바이너리를 BuildVersionA로, 다음에 출시할 바이너리를 BuildVersionB로 사용하는 ChunkDeltaOptimise 모드를 실행하시는 편이 좋습니다. 툴 실행 중에 네트워크가 끊기는 등의 문제가 생길 경우를 대비하여 출시하기 며칠 전 해당 과정을 미리 완료하도록 계획하는 편이 좋습니다.

현재 라이브 바이너리 버전을 확인하려면 ListBinaries 모드를 사용하세요. ChunkDeltaOptimise 가 제공된 두 BuildVersion 값 사이에 이미 실행 중인 경우, 프로세스에서 출력부에 표시된 연산을 단축할 수 있습니다.

Running optimization for patching 1.3.0-Windows -> 1.3.1-Windows
...
** 제공된 매니페스트에 대한 청크 델타 최적화를 이미 마침 **
Loaded optimised delta file E:/CloudDir/Deltas/jd63jdu7-jsg58dh58dki8dk323/a5nbd0jbweof98fvytsvnthcsvf.delta

프로세스가 끝나면 출력부에서 수행한 개선사항을 표시합니다.

  • "Final unknown compressed bytes, plus meta [Bytes]"

  • 해당 수치는 BuildVersionA와 BuildVersionB 사이에 패치를 적용하며 얻은 신규 다운로드 크기를 나타냅니다.

  • "Original unknown compressed bytes [Bytes]"

  • 해당 수치는 최적화를 실행하기 전 BuildVersionA와 BuildVersionB 사이에 패치를 적용하며 얻은 다운로드 크기를 나타냅니다.

  • "Improvement: [Percentage]"

  • 해당 수치는 패치로 얻은 개선사항을 보여줍니다. 퍼센티지는 감소된 크기를 나타내며, 클수록 좋습니다.

출력 예시:

Final unknown compressed bytes, plus meta 400000
Original unknown compressed bytes 1000000
Improvement: 60%

다운로드 가능 콘텐츠(DLC)

에픽게임즈 스토어는 다운로드 가능 콘텐츠(DLC)를 전부 지원합니다.

제품(Product) > 아티팩트(Artifacts) > 새 아티팩트 생성(Create New Artifact) 을 선택한 다음, 새 아티팩트를 논의 중인 애드온 오퍼에 연결하여 애드온 오퍼에 대한 아티팩트 다운로드를 활성화할 수 있습니다. 따라서 DLC의 항목마다 적절한 지정 아티팩트 ID로 독자적인 패치 생성 프로세스를 실행해야 합니다. 이 프로세스는 따로 생성되므로, DLC 항목에 대한 패치 생성 작업을 수행할 때는 기본 게임 및 다른 DLC 항목이 패치 생성 프로세스 도중 BuildRoot 파라미터에 지정된 폴더에서 동시에 존재하지 않도록 해야 합니다. 아니면 BuildRoot 폴더에 게임 본편 혹은 DLC 항목이 포함된 경우, BuildPatchTool 명령줄에 -FileIgnoreList 파라미터를 지정하여 해당 항목을 이전에 생성된 바이너리에서 제외할 수도 있습니다. 자세한 내용은 빌드를 프로세스하는 방법(How to Process a Build)을 참조하세요.

최종 사용자의 컴퓨터에 설치하면 게임 본편 및 관련된 모든 DLC 항목이 동일한 디렉터리에 설치됩니다. 다만 이렇게 하면 본편이나 DLC 항목 내부에 같은 경로를 공유하는 파일이 있으면 안 된다는 제한이 생깁니다. BuildPatchTool은 이 규칙을 위반하는 파일이 있는지 점검하고, 위반하는 파일이 있으면 패치 생성 프로세스가 시작되지 못하도록 막습니다. 다시 말해 기본 게임에서는 DLC가 설치된 장소의 상대 경로를 이용해 설치된 DLC를 발견할 수 있어야 합니다.

흔히 발생하는 오류 해결

BPT 사용 시, 명령줄이 정확히 입력되었는지 확인하세요. 잘못된 경우 다음 유형의 오류와 관련된 메시지가 표시됩니다.

흔히 발생하는 오류

다음은 흔히 발생하는 오류입니다. 특정 모드를 사용하는 BPT에서 -help 명령을 실행하여 오류를 유발하는 원인에 대한 정보를 얻을 수 있습니다.

점검사항

사용 중인 클라이언트 ID와 클라이언트 암호는 BuildPatchTool에서 사용하기 위해 특별히 표시됩니다. 올바른 클라이언트는 제품 세팅(Product Settings) 페이지의 클라이언트(Clients) 섹션에 BPT 클라이언트(BPT Client) 로 나열됩니다. EOS 기능에 접속하기 위한 클라이언트가 존재할 수 있는데, 이 클라이언트에는 BuildPatchTool 권한이 없습니다.

  • 필요한 파라미터를 전부 제공할 것

  • 파라미터에 대소문자나 공백 등 오타가 없을 것

  • 공백을 포함한 파라미터에 따옴표가 없을 것

Error - 에픽 서비스에서 바이너리 목록을 얻지 못함

Please check your provided OrganizationId, ProductId and ArtifactId are
correct, and that you should have access to create binaries for this
artifact.
Tool exited with: 6

오류 설명 – 사용 중인 클라이언트 크리덴셜에서 지정된 아티팩트를 업로드할 권한을 주지 않고 있습니다. 크리덴셜 및 다른 파라미터에 오타가 있거나 클라이언트에 부여된 권한으로 인해 오류가 발생했을 가능성이 있습니다.

Error - 파라미터 없음

CloudDir, BuildRoot, ArtifactId, BuildVersion, AppLaunch, and AppArgs
are required parameters
Tool exited with: 2

오류 설명 – BPT에서 위에 나열된 파라미터를 하나 이상 발견하지 못했습니다. 파라미터가 누락되었거나 잘못 추가되었을 가능성이 있습니다.

Error - 크리덴셜 없음

Please ensure you have specified ClientId and also one of ClientSecret or
ClientSecretEnvVar. If using ClientSecretEnvVar, ensure the env variable
is properly set.
Tool exited with: 9

오류 설명 – BPT에서 위에 나열된 파라미터를 하나 이상 발견하지 못했습니다. 파라미터가 누락되었거나 잘못 추가되었을 가능성이 있습니다.

Error - 인증 오류

An authentication error occurred - Check you have specified ClientId, and
either ClientSecret or ClientSecretEnvVar parameters correctly.
Message: Sorry the client credentials you are using are invalid
Tool exited with: 10

오류 설명 - 사용 중인 클라이언트 크리덴셜이 에픽게임즈의 기록과 일치하지 않습니다. 크리덴셜 및 다른 파라미터에 오타가 있거나 클라이언트에 부여된 권한으로 인해 오류가 발생했을 가능성이 있습니다.

Error - 예상치 못한 오류

An unexpected error occurred. Error code: errors.com.epicgames.common.missing_permission;
Error message: Sorry your login does not possess the permissions
'artifact:o-7kyv8uwtz74njnl544kbxzt5xqephw:3bc138d96fb24d9597d4bbff23b9ecee:asdfasd READ'
needed to perform the requested operation
Tool exited with: 5

오류 설명 – 사용 중인 클라이언트 크리덴셜에서 지정된 아티팩트를 업로드할 권한이 없습니다. 제품 세팅(Product Setting) 페이지에서 표시한 대로 올바른 BPT 클라이언트를 사용하고 있는지 확인하세요.