[번역]UE Plugin and Tool Development: 기본 패키지 자동

텐센트 라이트스피드 스튜디오에서 개발 관련 하여 엔지니어로 일 하고 있는 "查利鹏" 엔지니어 블로그 발췌 토픽을 번역 했습니다.

기본 패키지 자동화

CI/CD에 통합하여 자동 빌드 패키징이 필요할 때, UE의 BuildGraph를 사용하여 UBT와 UAT 작업을 안내할 수 있습니다.

다음 명령을 직접 사용할 수 있습니다(엔진, 프로젝트, 플랫폼은 실제 상황에 맞게 수정):

E:\\UnrealEngine\\Launcher\\UE_4.25\\Engine\\Build\\BatchFiles\\RunUAT.bat BuildCookRun -nocompileeditor -installed -nop4 -project="E:/Examples/Blank425/Blank425.uproject" -cook -stage -archive -archivedirectory="E:/Examples/Blank425/Package" -package -pak -prereqs -nodebuginfo -targetplatform=Android -cookflavor=ASTC -build -target=Blank425 -clientconfig=Development -utf8output

---

지원되는 플랫폼 이름:

Win32,Win64,HoloLens,Mac,XboxOne,PS4,IOS,Android,HTML5,Linux,LinuxAArch64,AllDesktop,TVOS,Switch,Lumin

---

자체적으로 BuildGraph 스크립트를 작성하여 패키징 단계를 더 정확하게 제어할 수도 있습니다. 여기서는 더 이상 설명하지 않으니 관련 기사를 온라인에서 검색하세요.

위의 명령을 통해 명령줄 방식으로 UE 프로젝트를 패키징할 수 있으며, 스크립트를 추가로 작성하여 CI/CD 플랫폼에 통합할 수 있습니다.

패키징 자체는 이 섹션의 핵심이 아니며, 핵심은 패키징 후 즉시 UE가 생성한 paklist*.txt 파일을 추출하는 것입니다.

UE가 기본 패키지를 빌드할 때 프로젝트에 구성된 리소스를 pak 파일로 패키징합니다. UE의 패키징 프로세스에서도 paklist*.txt 파일을 생성하여 어떤 리소스가 pak으로 패키징되어야 하는지 기록합니다. 따라서 paklist*.txt 파일을 추출하기만 하면 현재 기본 패키지에 어떤 파일(uasset뿐만 아니라)이 포함되어 있는지 알 수 있습니다.

HotPatcher는 기본 패키지의 Release 정보(기본 패키지의 모든 리소스 정보를 기록하는 데 사용됨)를 생성하는 두 가지 방법을 제공합니다:

1. 기본 패키지 빌드 시 생성된 paklist 파일 가져오기
2. 패키징 디렉토리 직접 지정 및 외부 파일 추가

첫 번째 방법을 사용하는 것이 좋습니다. 더 정확하며 기본 패키지의 모든 파일(uasset/non-uasset)을 정확하게 분석할 수 있고, 다른 플랫폼의 기본 패키지에서 차이 파일을 분석하여 완전히 정확한 기본 패키지 정보를 내보낼 수 있기 때문입니다.

UE가 기본 패키지를 빌드할 때 기본적으로 paklist 파일을 다음 경로에 저장합니다(소스 버전과 설치 버전의 경로가 다름):

설치 버전 엔진:

%AppData%\\Unreal Engine\\AutomationTool\\Logs\\엔진경로연결\\PakList_*.txt

---

여기서 엔진경로연결의 규칙은 다음과 같습니다:

# 엔진 경로
E:\\UnrealEngine\\Launcher\\UE_4.25
# 연결 후
E+UnrealEngine+Launcher+UE_4.25

---

소스 버전 엔진:

Engine\\Programs\\AutomationTool\\Saved\\Logs\\BuildCookRun\\PakList_*.txt

---

따라서 기본 패키지를 빌드한 후에는 위의 경로 규칙에 따라 paklist_*.txt 파일을 추출하면 됩니다. 설치버전을 예로 들면, Windows에서는 다음 파일 복사 명령을 사용할 수 있습니다:

echo f|xcopy /y/i/s/e"%AppData%\\Unreal Engine\\AutomationTool\\Logs\\E+UnrealEngine+Launcher+UE_4.25\\PakList_*.txt""E:\\ClientVersion\\0.0.1.0"

---

이렇게 하면 현재 디렉토리에서 paklist_*.txt 패턴과 일치하는 모든 파일이 지정된 디렉토리로 복사됩니다.

소스 버전과 설치 버전의 paklist 경로 차이를 통일하기 위해 Python 스크립트를 작성할 수 있습니다:

defGetPakListFileRules(target_platform,engine_root_dir):
    b_installed_engine =False
    installedbuild_txt_path ="%s\\\\Engine\\\\Build\\\\InstalledBuild.txt" % engine_root_dir
if os.path.exists(InstalledBuild_txt_path):
        b_installed_engine =True

    ue_paklist_dir =""
if b_installed_engine:
        sys_appdata_dir = os.getenv("APPDATA")
        ue_aut_log_dir ="Unreal Engine\\\\AutomationTool\\\\Logs"
        engine_log_dir = engine_root_dir
        engine_log_dir = engine_log_dir.replace(':','')
        engine_log_dir = engine_log_dir.replace('\\\\','+')
        engine_log_dir = engine_log_dir.replace('/','+')
        ue_paklist_dir ="%s\\\\%s\\\\%s\\\\BuildCookRun" % (sys_appdata_dir,ue_aut_log_dir,engine_log_dir)
else:
        ue_paklist_dir ="%s\\\\Engine\\\\Programs\\\\AutomationTool\\\\Saved\\\\Logs\\\\BuildCookRun" % engine_root_dir
print(ue_paklist_dir)
    ue_pak_list_rule ="%s\\\\PakList_pakchunk*-%s.txt" % (ue_paklist_dir,GetRealPlatformName(target_platform))
return ue_pak_list_rule

호출 방법:

ue_paklist_rules = GetPakListFileRules("Android_ASTC","C:\\\\Program Files\\\\Epic Games\\\\UE_4.26")

---

프로젝트 요구에 맞게 간단히 수정하면 됩니다.

참고: 각 플랫폼을 패키징한 후에는 즉시 해당 플랫폼 기본 패키지의 paklist 파일을 추출해야 합니다. 다음 패키징 작업을 실행할 때 해당 디렉토리의 파일이 정리되기 때문입니다.

기본 패키지 정보 자동화 추출

이전 단계의 기본 패키지 자동화에서는 두 가지 핵심 자동화 요소를 구현했습니다:

1. UE 패키징
2. 현재 플랫폼의 기본 패키지 paklist 추출

이번 섹션의 핵심은 0.0.1.0 버전의 여러 플랫폼에 대한 기본 패키지를 패키징하고 해당 paklist 파일을 추출한 후, 여러 플랫폼의 릴리스 프로세스를 생성하는 방법입니다.

추출된 여러 플랫폼의 Paklist 디렉토리 구조는 다음과 같습니다:

---

 

E:\\ClientVersion\\0.0.1.0>tree /a /f
볼륨 Document의 폴더 PATH 목록
볼륨 일련 번호는 0003-AEBB
E:.
+---Android_ASTC
|       PakList_pakchunk0-Android_ASTC.txt
|       PakList_pakchunk1-Android_ASTC.txt
|       PakList_pakchunk2-Android_ASTC.txt
|
+---IOS
|       PakList_pakchunk0-ios.txt
|       PakList_pakchunk1-ios.txt
|       PakList_pakchunk2-ios.txt
|
\\---WindowsNoEditor
        PakList_pakchunk0-WindowsNoEditor.txt
        PakList_pakchunk1-WindowsNoEditor.txt
        PakList_pakchunk2-WindowsNoEditor.txt

---

여러 플랫폼의 paklist 저장 구조와 파일명은 동일한 규칙을 가지고 있습니다. 규칙이 있으면 자동화 처리가 가능합니다.

HotPatcher는 HotRelease Commandlet을 제공하여 명령줄 방식으로 Release를 내보낼 수 있으며, 구성 파일을 지정할 수 있습니다:

UE4Editor.exe PROJECT.uproject -run=HotRelease -config="release-config.json"

---

하지만, 단순히 구성 파일을 지정하는 것은 명령줄에 그다지 친숙하지 않습니다. 먼저 config 파일을 생성해야 지정할 수 있기 때문입니다. 따라서 최근에 HotRelease Commandlet을 개선하여 명령줄을 통해 config 매개변수를 완전히 제어할 수 있고, config 파일 지정 없이도 사용할 수 있도록 했습니다.

앞서 언급했듯이 HotPatcher는 Release 정보를 내보내는 두 가지 모드를 지원합니다. paklist 가져오기 모드를 사용할 때는 다음과 같은 주요 매개변수만 지정하면 됩니다:

1. VersionId 현재 Release 버전 번호
2. ByPakList Paklist 모드 활성화
3. PlatformsPakListFiles 각 플랫폼에 해당하는 paklist*.txt 파일 지정
4. SavePath Release 저장 경로

UE의 리플렉션 메커니즘을 사용하여 명령줄에서 매개변수 구조에 정의된 이름을 지정하여 실제 구성 정보를 구성할 수 있도록 구현했습니다(현재 배열 지정은 지원하지 않음). commandlet 실행 시 위 매개변수를 직접 지정할 수 있습니다.

따라서 HotRelease Commandlet 명령은 다음과 같습니다(보기 쉽게 매개변수를 줄바꿈하여 분리했습니다):

E:\\UnrealEngine\\Launcher\\UE_4.25\\Engine\\Binaries\\UE4Editor-cmd.exe
E:\\Examples\\Blank425\\Blank425.uproject
-run=HotRelease
-versionid="0.0.1.0"
-ByPakList=true
-AddPlatformPakList=WindowsNoEditor+E:\\ClientVersion\\0.0.1.0\\WindowsNoEditor\\PakList_pakchunk0-WindowsNoEditor.txt+E:\\ClientVersion\\0.0.1.0\\WindowsNoEditor\\PakList_pakchunk1-WindowsNoEditor.txt+E:\\ClientVersion\\0.0.1.0\\WindowsNoEditor\\PakList_pakchunk2-WindowsNoEditor.txt
-savepath.path="E:\\ClientVersion\\"

---

AddPlatformPakList는 명령줄을 통해 Platform-PaklistFiles 매개변수를 지정하는 방법으로, 요구사항은 다음과 같습니다:

PLATFORM_NAME+Paklist_0.txt+PakList_1.txt,PLATFORM_NAME+Paklist_0.txt+PakList_1.txt

---

여러 플랫폼을 지정할 수 있으며 쉼표(,)로 구분합니다. 각 플랫폼의 첫 번째 항목은 플랫폼 이름이며 + 기호로 구분하고, 이후에는 원하는 수의 Paklist 파일을 지정할 수 있습니다.

WindowsNoEditor/Android_ASTC/IOS 세 가지 플랫폼을 지정하는 예시입니다:

-AddPlatformPakList=WindowsNoEditor+E:\\Paklist_chunk01_WindowsNoEditor.txt+E:\\Paklist_chunk02_WindowsNoEditor.txt,Android_ASTC+E:\\Paklist_chunk01_Android_ASTC.txt+E:\\Paklist_chunk02_Android_ASTC.txt,IOS+E:\\Paklist_chunk01_IOS.txt+E:\\Paklist_chunk02_IOS.txt

---

플랫폼과 파일 경로 지정에는 모두 규칙이 있으므로, Python 등의 스크립트를 사용하여 프로젝트 관리 스타일에 맞게 래핑한 다음 os.system을 사용하여 commandlet을 실행할 수 있습니다. 이렇게 하면 에디터에서 HotPatcher 에디터를 통해 ByRelease를 수동으로 실행하는 것과 동일한 효과를 얻을 수 있습니다.

참고: Release.json에는 Non-uasset 파일의 절대 경로가 기록되지만, 실제 버전 비교 시 파일의 절대 경로는 확인하지 않습니다. 따라서 Release.json 파일은 기기 간에 범용으로 사용할 수 있는 정보입니다(리소스 경로, 마운트 경로로 비교).

패치 자동화 생성

이전 섹션에서 Release 정보를 자동으로 생성하는 방법을 소개했습니다. Release 생성에 필요한 구성 옵션은 많지 않지만, Patch는 매우 많은 구성이 필요합니다. 따라서 config 파일을 완전히 포기하는 것은 더 번거로운 일이므로, 일반 구성 파일과 명령줄에서 특별한 매개변수를 지정하는 절충안을 생각했습니다.

그렇다면, 일반적인 구성 파일에는 어떤 것들이 있을까요?

• Patch가 스캔할 리소스 디렉토리
• 추가할 파일(ini/shaderbytecode/assetregistry)
• Non-uasset 파일 및 디렉토리
• Chunk 분할

명령줄로 지정할 수 있는 것들은 무엇일까요?

• VersionID
• 기본 버전의 Release 파일
• 현재 Patch의 리소스를 Cook할지 여부
• Patch를 생성할 플랫폼
• Pak 파일 명명 규칙
• 저장 디렉토리

이전 버전의 HotPatcher에서는 구성 파일이 다양한 매개변수의 절대 경로(추가된 Non-uasset 파일)에 의존했습니다. 최근에 개선하여 프로젝트 디렉토리 기준의 상대 경로를 지원할 수 있도록 했습니다.

Content/Script 디렉토리 추가를 예로 들면, 이전 버전에서는 절대 경로의 폴더만 선택할 수 있었습니다:

이제는 [PROJECT_CONTENT_DIR]로 대체할 수 있습니다:

Path 실행 중에 현재 프로젝트의 절대 경로로 대체됩니다.
[] 표시를 지원하는 상대 경로는 다음과 같습니다:

[ENGINEDIR]
[ENGINE_CONTENT_DIR]
[PROJECTDIR]
[PROJECT_CONTENT_DIR]
[PROJECT_SAVED_DIR]
[PROJECT_CONFIG_DIR]

---

필요에 따라 사용할 수 있으며, 이 방식을 사용하면 범용 구성을 내보낼 수 있습니다.

PatchTemplate.json

{
"bByBaseVersion":true,
"baseVersion":
{
"filePath":""
},
"versionId":"",
"assetIncludeFilters":[
{
"path":"/Game"
}
],
"assetIgnoreFilters":[],
"bForceSkipContent":true,
"forceSkipContentRules":[
{
"path":"/Engine/Editor"
},
{
"path":"/Engine/VREditor"
}
],
"forceSkipAssets":[],
"bIncludeHasRefAssetsOnly":false,
"bAnalysisFilterDependencies":true,
"bRecursiveWidgetTree":true,
"assetRegistryDependencyTypes":[
"Packages"
],
"includeSpecifyAssets":[],
"bIncludeAssetRegistry":true,
"bIncludeGlobalShaderCache":false,
"bIncludeShaderBytecode":false,
"bIncludeEngineIni":false,
"bIncludePluginIni":false,
"bIncludeProjectIni":false,
"bEnableExternFilesDiff":true,
"ignoreDeletionModulesAsset":[],
"addExternAssetsToPlatform":[
{
"targetPlatform":"AllPlatforms",
"addExternFileToPak":[],
"addExternDirectoryToPak":[
{
"directoryPath":
{
"path":"[PROJECT_CONTENT_DIR]/Script"
},
"mountPoint":"../../../Blank425/Content/Script"
}
]
}
],
"bIncludePakVersionFile":false,
"pakVersionFileMountPoint":"../../../Blank425/Versions/version.json",
"bEnableChunk":false,
"chunkInfos":[],
"bCookPatchAssets":true,
"pakCommandOptions":[],
"replacePakCommandTexts":[],
"unrealPakOptions":[
"-compress",
"-compressionformats=Zlib"
],
"pakTargetPlatforms":[],
"bCustomPakNameRegular":false,
"pakNameRegular":"{VERSION}_{CHUNKNAME}_{PLATFORM}_001_P",
"bIgnoreDeleatedAssetsInfo":false,
"bSaveDeletedAssetsToNewReleaseJson":true,
"bSavePakList":true,
"bSaveDiffAnalysis":true,
"bSaveAssetRelatedInfo":false,
"bSavePatchConfig":true,
"savePath":
{
"path":""
}
}

Expand

이 구성은 Path 생성 시 리소스 관련 일반 구성 파일로 사용할 수 있습니다. 패키징 구성을 수정하려면 이 파일만 수정하면 됩니다.

다른 버전 관련 매개변수는 모두 HotPatcher commandlet 명령줄을 통해 지정할 수 있습니다:

E:\\UnrealEngine\\Launcher\\UE_4.25\\Engine\\Binaries\\UE4Editor-cmd.exe
E:\\Examples\\Blank425\\Blank425.uproject
-run=HotPatcher
-config="E:\\ClientVersion\\PatchTemplate.json"
-versionid="0.0.1.1"
-baseVersion.filePath="E:\\ClientVersion\\0.0.1.0\\0.0.1.0_Release.json"
-AddPatchPlatforms="WindowsNoEditor,Android_ASTC,IOS"
-savePath.path="E:\\ClientVersion\\"

---

마찬가지로, 이 명령의 매개변수에도 일정한 패턴이 있습니다. 디렉토리 구조가 잘 정리되어 있다면, 현재 Patch의 기본 버전과 현재 버전 번호만 지정하면 완전히 자동화된 패키징이 가능합니다.

마찬가지로, Path 생성 프로세스도 Python 등의 스크립트로 래핑할 수 있으며, CI/CD 플랫폼에서 엔진 디렉토리, 프로젝트 디렉토리, 기준 버전, 현재 버전, 어떤 플랫폼의 patch를 생성할지 등의 매개변수를 지정하여 쉽게 제어할 수 있습니다.

결론

이 글에서는 HotPatcher를 사용하여 핫 업데이트 프로세스를 자동화하는 방법을 소개했습니다. UE 자동화 기본 패키지, paklist 추출, Release 생성, 일반적인 Patch 생성 규칙 등을 포함하여 CI/CD 플랫폼에 쉽게 통합하여 수동 개입을 피할 수 있습니다. 시간이 되면 HotPatcher를 위한 Release/Patch 자동 내보내기용 Python 스크립트를 작성하여 쉽게 사용할 수 있도록 하겠습니다.