BuildPatch Tool Instructions (1.4.0)

BPT 1.4.0의 설정 및 처리 지침입니다.

12 분 소요

시작하기 전에

크리덴셜 ID를 찾는 방법

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

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

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

오퍼의 아티팩트 이름 및 ID

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

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

오퍼의 오퍼 ID

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

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

조직의 BuildPatch Tool 크리덴셜 보기

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

다음은 조직의 BuildPatch Tool 크리덴셜을 확인하는 방법입니다.

  1. 개발자 포털에 로그인합니다.
  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 파일의 콘텐츠를 추출합니다. 이 머신은 에픽 백엔드와 통신할 인터넷 연결도 필요합니다.

참고: ZIP 파일 링크를 통해 항상 최신 버전의 BPT를 다운로드할 수 있습니다. 파일에 액세스할 수 없다면, 케이스를 생성하세요.

인증

인증은 BuildPatchTool에 클라이언트 ID클라이언트 비밀 키 를 넣는 방식으로 진행됩니다. 명령줄 실행인자를 사용하는 모든 작업에 이러한 ID와 암호를 제공해야 합니다.

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

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

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

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

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

빌드를 처리하는 방법

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

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

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

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

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

  • ClientId 인증을 참고하세요.

  • ClientSecretEnvVar 인증을 참고하세요.

  • BuildRoot – 읽고 처리할 빌드가 포함된 디렉터리의 경로입니다. 이 경로는 상대 경로가 아니라 드라이브 루트에서 시작되는 절대 경로여야 합니다. 또한, OS MAX_PATH 제한(일반적으로 260자)을 초과하는 파일이 없도록, 이 경로는 드라이브 루트 가까이에 두는 것이 좋습니다.

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

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

  • AppLaunch – 게임과 함께 실행되며 BuildRoot에 상대적이고 BuildRoot 내부에 존재하는 앱 실행 파일의 경로입니다. Mac 빌드의 경우 이 파일은 보통 Game.app/Contents/MacOS/Game 에 위치한 .app 폴더에 있는 실행 파일이어야 합니다.

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

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

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

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

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

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

커스텀 FileAttributeList 파일은 하나 이상의 줄바꿈 구분 항목이 있는 텍스트 파일이어야 합니다. 각 줄에는 인용된(BuildRoot 상대) 파일 경로가 포함되어야 하며, 그 뒤에 참조된 파일에 적용할 공백으로 구분된 어트리뷰트가 하나 이상 나와야 합니다.

입력 예시:

다음과 같은 파일 어트리뷰트 플래그가 지원됩니다.

  • executable

  • tag:my_tag

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

바탕화면 바로 가기 아이콘 설정하기

기본적으로 바탕화면 바로 가기 아이콘은 AppLaunch 실행인자로 표시된 앱 실행 파일의 아이콘으로 설정됩니다. 이 아이콘은 두 가지 방법으로 업데이트할 수 있습니다.

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

  • 앱 실행 파일과 이름이 같은 별도의 .ico 파일 추가(예: 실행 파일이 launch.exe인 경우, launch.ico를 사용해야 함)

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

에픽의 백엔드에 쿼리하여 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')을 사용 중일 때 해당 명령으로 사용자 경험을 개선할 수 있습니다.

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

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

일반적으로는 현재 라이브 바이너리를 BuildVersionA로, 다음에 출시할 바이너리를 BuildVersionB로 사용하는 ChunkDeltaOptimise 모드를 실행하는 편이 좋습니다. 네트워크 손실 등, 툴 실행에 문제가 발생할 상황에 대비하여 출시 며칠 전에 이 프로세스가 완료되도록 계획하는 것이 이상적입니다.

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

프로세스가 완료되면, 달성한 개선도가 출력에 표시됩니다.

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

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

  • "Original unknown compressed bytes [Bytes]"

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

  • "Improvement: [%]"

  • 달성된 개선도를 나타냅니다. 백분율은 감소한 크기를 나타내며, 클수록 좋습니다.

출력 예시:

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

에픽게임즈 스토어에서는 다운로드 가능한 콘텐츠(DLC)를 완벽하게 지원합니다.

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

최종 사용자 머신에 설치될 때, 메인 게임 및 관련 DLC의 모든 항목이 같은 디렉터리에 설치됩니다. 이는 공통 파일 경로를 공유하는 DLC 항목이나 메인 게임 내에 파일이 없어야 한다는 제한으로 이어집니다. BuildPatchTool은 이러한 제한을 검사하고 이 규칙을 위반하는 파일이 있으면 패치 생성 프로세스가 발생하지 않도록 합니다. 즉, 기본 게임은 설치 위치에서 상대 경로를 통해 설치된 DLC를 찾을 수 있어야 한다는 뜻입니다.

일반적인 오류 해결

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

일반적인 오류

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

점검 사항

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

  • 모든 필수 파라미터가 제공되었는지 확인합니다.

  • 파라미터에 잘못된 대소문자나 공백 문제 등 오타가 없는지 확인합니다.

  • 공백이 포함된 파라미터에 따옴표가 누락되었는지 확인합니다.

Error - Failed to retrieve list of binaries from Epic services

오류 설명 – 사용 중인 클라이언트 크리덴셜에서 지정된 아티팩트를 업로드할 권한을 허가하지 않고 있습니다. 크리덴셜이나 다른 파라미터에서 오타가 났을 수도 있고, 클라이언트에 부여된 권한 문제일 수도 있습니다.

Error - Missing parameters

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

Error - Missing credentials

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

Error - Authentication error

오류 설명 – 사용 중인 클라이언트 크리덴셜이 에픽게임즈의 기록과 일치하지 않습니다. 크리덴셜이나 다른 파라미터에서 오타가 났을 수도 있고, 클라이언트에 부여된 권한 문제일 수도 있습니다.

Error - Unexpected error

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