언리얼 엔진 애셋 툴킷
애셋 툴킷은 아직 UE5 또는 1.0 릴리스에서 완전히 테스트되지 않았습니다. |
이 문서는 작업 중입니다. 문제가 발생하면 디스코드에서 저희에게 연락해 주십시오. |
커뮤니티 멤버 Archengius는 컴파일된 언리얼 엔진 게임에서 콘텐츠를 덤프하고 언리얼 엔진 에디터로 가져오는 데 유용한 두 개의 플러그인 세트를 만들었습니다.
대부분의 새티스팩토리 게임 파일은 다운로드 크기 및 저작권 문제로 인해 시작 프로젝트와 함께 배포할 수 없습니다. 대신 프로젝트에는 빈 "자리 표시자" 애셋이 포함되어 있습니다. 이를 통해 모드를 컴파일하고 기본 게임 콘텐츠를 참조할 수 있지만, 에디터에서 콘텐츠를 미리 보는 것은 어렵습니다.
애셋 툴킷을 사용하여 아이콘, 메쉬, 일부 머티리얼 등을 포함한 시작 프로젝트의 복사본을 생성할 수 있으며, 기본 게임 콘텐츠와 작업하는 것이 훨씬 더 편리해집니다.
완전한 프로젝트 복사본을 생성하기로 결정한 경우, 콘텐츠 폴더가 깃허브 또는 유사한 곳에서 공개적으로 사용 가능하지 않도록 하십시오. 플러그인 수준의 저장소만 있는 경우에는 문제가 되지 않지만, 프로젝트 수준의 저장소인 경우 주의해야 합니다. |
설치
애셋 툴킷 저장소는 두 개의 플러그인으로 구성되어 있습니다.
게임에 설치할 덤퍼와
에디터에 설치할 애셋 생성기입니다.
두 플러그인은 애셋 툴킷 저장소에 포함되어 있습니다.
저장소의 zip 파일을 다운로드하여 적절한 위치에 추출하거나,
원한다면 복제하십시오.
어떤 경우든, 얻은 복사본이 dev
분기인지 확인하십시오. 최신 수정 사항이 포함되어 있습니다.
파일을 다운로드한 후,
두 플러그인을 포함하는 폴더를 이동하거나
각 플러그인 폴더를 이동하여
모딩 프로젝트의 Mods/
폴더에 넣으십시오.
중간에 추가 폴더가 있어도 괜찮습니다.
UE는 여전히 이를 발견할 수 있습니다.
컴파일
플러그인을 모딩 프로젝트로 이동한 후, Visual Studio 프로젝트 파일을 다시 생성하고 Development Editor를 위해 빌드하십시오.
컴파일을 기다리는 동안 각 플러그인의 역할에 대한 정보는 다음과 같습니다.
AssetDumper 플러그인은 이미 새티스팩토리 모드로 설정되어 있으며, 컴파일 후 알파킷 모드 목록에 나타납니다. 나중에 게임에 빌드되고 설치됩니다. 이 플러그인은 AssetGenerator 플러그인이 애셋을 재생성하는 데 사용하는 파일을 생성합니다.
AssetGenerator 플러그인은 에디터 측에서만 사용됩니다. 알파킷 모드 목록에 나타나지 않습니다. 이 플러그인은 덤퍼가 생성한 파일을 가져와 에디터에서 사용할 수 있는 uasset 파일을 생성합니다.
컴파일 오류 문제 해결
-
빌드하기 전에 Visual Studio 프로젝트 파일을 다시 생성했는지 확인하십시오.
-
위의 링크에서 저장소의 최신 버전으로 플러그인을 업데이트했는지 확인하십시오.
-
MaterialGenerator.h
에서 Material Graph가 정의되지 않았다는 오류가 발생하면, 파일 상단에 다음 가져오기를 추가해 보십시오:
#include "MaterialGraph/MaterialGraph.h" #include "MaterialEditingLibrary.h"
-
해결되지 않은 외부 모듈에 대한 오류가 발생하면, 프로젝트의
Intermediates
폴더를 삭제하고, 프로젝트 파일을 다시 생성한 후 다시 빌드해 보십시오. -
디스코드에서 도움을 요청하십시오.
게임 애셋 덤프
이미 애셋 덤퍼와 생성기를 사용한 경우, 위의 지침에 따라 업데이트된 버전을 다운로드하는 것이 좋습니다. 그렇지 않으면 덤프 및 생성 중에 모호한 오류가 발생할 수 있습니다. |
사용자 인터페이스가 덤퍼를 사용하는 데 존재하지만, 몇 가지 충돌 문제가 있으므로 이 지침에서는 대신 명령줄 버전을 사용하는 방법을 다룰 것입니다.
애셋을 덤프하려면 Powershell에서 게임 설치 디렉터리로 이동하십시오.
예를 들어 C:\EpicGamesGames\SatisfactoryEarlyAccess
그 다음, 해당 디렉터리에서 다음 Powershell 명령을 편집하여 게임 실행 파일을 가리키도록 한 후 실행하십시오:
FactoryGameEGS.exe -EpicPortal -NoSteamClient -DumpAllGameAssets -RootAssetPath=/Game -ExcludePackagePaths=/Game/WwiseAudio -ExcludePackageNames=/Game/Geometry/Meshes/1M_Cube_Chamfer -PackagesPerTick=32 -ExitOnFinish -log -NewConsole
위 명령은 에픽게임즈 복사본
|
|
Powershell 명령은 즉시 완료되어
다른 명령을 실행할 수 있는 옵션을 제공합니다.
잠시 후, 새티스팩토리 스플래시 화면과 덤프 과정에 대한 정보를 제공하는
콘솔 창이 표시됩니다(-log -NewConsole
을 사용했기 때문입니다).
콘솔 로그 창이 열리면 Powershell 창을 안전하게 닫을 수 있지만, 충돌 시 다시 시작하기 위해 열어 두는 것이 좋습니다.
일반적으로 덤퍼는 게임 메뉴 렌더링에 낭비되는 처리 능력을
피하기 위해 -nullrhi
플래그와 함께 실행되지만, 이 인수는
새티스팩토리 1.0부터 고장난 것으로 보여 명령에서 제외되었습니다.
게임 창이 열리며 FPS가 매우 낮고 사운드 효과 재생이 지연됩니다.
애셋 덤퍼가 작동하는 동안 최소화하고 콘솔 창에 집중하십시오.
게임 로딩 과정이 완료되면 LogAssetDumper
메시지 시퀀스를 볼 수 있어야 합니다.
이 과정은 시간이 걸리므로, 가서 도마멍멍이와 놀고 있으십시오.
1분 정도가 지나도 `LogAssetDumper`가 보이지 않으면 덤퍼가 실행되지 않는 것입니다.
아마도 모드를 올바르게 패키징하지 않았을 것입니다.
명령 프롬프트 창이 닫히고 게임 로그 파일이 충돌 덤프 없이 끝나면 완료된 것입니다.
전체 덤프는 약 8.5GB를 차지할 것으로 예상됩니다. 애셋 생성기를 성공적으로 사용한 후 나중에 삭제할 수 있습니다.
완료되면 콘솔 창과 게임이 닫히고,
게임 설치 디렉터리 내에 새로운
FactoryGame/AssetDump/
폴더가 생성됩니다.
애셋 덤프는 게임 업데이트 시 시작 프로젝트 스텁을 생성하는 데에도 사용됩니다. 이 작업이 어떻게 이루어지는지에 관심이 있다면, CI 스크립트를 확인하거나 디스코드에서 저희에게 연락하여 더 많은 정보를 얻으십시오. |
애셋 덤프 충돌 문제 해결
인크레더빌드에서 제공하는 링크를 통해 최신 버전의 애셋 덤퍼로 업데이트했는지 확인하십시오.
WaitForDebugger 플래그를 추가하여 디버거를 연결하여 충돌을 더 자세히 조사할 수 있습니다.
문제가 계속 발생하면 디스코드에서 도움을 요청하십시오.
덤프된 애셋을 에디터로 가져오기
모든 애셋이 가져와진 콘텐츠 폴더는 약 6GB를 차지할 것으로 예상됩니다. 비교하자면, 자리 표시자가 있는 콘텐츠 폴더는 366MB를 차지합니다.
에디터가 아직 열려 있다면 닫으십시오.
기존 콘텐츠 폴더 이동
애셋 생성기를 사용하기 전에 기존 모딩 프로젝트의 콘텐츠 폴더를 다른 위치로 이동하십시오.
예를 들어, Content_PreGenerate
로 이름을 바꾸는 것입니다.
이는 두 가지 목적을 수행합니다.
첫째, 애셋 생성이 성공하지 않을 경우 파일의 복사본을 반환할 수 있습니다.
둘째, 폴더를 이동하면 애셋이 있던 빈 디렉터리가 남아 있어 애셋 생성기가 모든 애셋을 재생성하도록 보장하며,
기존 파일을 업데이트하려고 시도할 때 발생할 수 있는 애셋 생성기 충돌을 방지합니다.
생성기 커맨드렛 실행
생성기를 실행하기 전에 기존 콘텐츠 폴더를 다른 위치로 이동하는 것이 중요합니다. 애셋이 이미 존재할 경우 생성기가 다르게 작동하며, 애셋이 존재할 경우 문제를 일으킬 수 있습니다. 예를 들어, 머티리얼 슬롯 할당이 잘못될 수 있습니다. |
다음 단계는 애셋 생성기의 커맨드렛 기능을 사용하여 덤프된 파일을 에디터에서 사용할 수 있는 애셋으로 변환하는 것입니다.
아래는 애셋 생성기 커맨드렛을 사용하기 위해 adamsogm이 원래 작성한 Powershell 스크립트의 수정된 버전입니다. 스크립트의 처음 몇 줄을 수정하여 언리얼 엔진 설치, 프로젝트 경로 및 선택한 덤프 디렉터리를 가리키도록 해야 합니다.
새 Powershell 스크립트 파일(예: generate_assets.ps1
)을 원하는 위치에 생성한 후,
아래 스크립트를 복사하여 경로 줄을 수정한 후 저장하십시오.
Powershell 스크립트 파일은 실제로 `.ps1`로 끝나는 텍스트 파일입니다.
이러한 파일을 만드는 방법을 잘 모른다면,
여기를 참고하십시오.
스크립트를 실행하려면, 먼저 생성 애셋 파일이 있는 폴더에서 새 Powershell 터미널 창을 여십시오. 파일 탐색기에서 빈 공간을 Shift + 우클릭하여 "여기에서 Powershell 창 열기"를 선택하면 됩니다. 자세한 정보는 여기에서 찾을 수 있습니다.
스크립트를 우클릭 후 "Powershell로 실행"을 선택하면 스크립트가 실행되지만, 오류가 발생할 경우 창이 즉시 닫혀 오류 메시지를 읽을 수 없으므로 권장하지 않습니다.
Windows 설치에서 Powershell 스크립트를 한 번도 실행한 적이 없다면, 시스템 실행 정책을 수정하여 스크립트 실행을 허용해야 할 수 있습니다.
# 아래 경로 줄을 시스템의 실제 파일 및 폴더 위치에 맞게 변경하십시오.
# \를 탈출할 필요가 없도록 아포스트로피를 사용하십시오.
$UECmdPath = 'C:\Program Files\Unreal Engine - CSS\Engine\Binaries\Win64\UnrealEditor-Cmd.exe'
$UProjectPath = 'D:\GitSecondary\SF_ModProject\FactoryGame.uproject'
$AssetDumpDirectory = 'D:\Programs\EpicGamesGames\SatisfactoryExperimental\FactoryGame\AssetDump'
# 아래는 수정할 필요가 없습니다.
# 과정에서 임시 파일 이름을 정의하고 임시 파일을 정리하는 기능을 정의합니다.
$ForceGenerateFile = 'ForceGeneratePackageNames.txt'
$SkipSaveFile = 'SkipSavePackages.txt'
$BlacklistFile = 'BlacklistPackageNames.txt'
$TempFiles = $ForceGenerateFile, $SkipSaveFile, $BlacklistFile
function CleanupTempFiles {
foreach ($FileName in $TempFiles) {
if (Test-Path $FileName) {
Remove-Item $FileName
Write-Output "Cleaned up $FileName"
}
}
}
# 스크립트가 이전에 종료되었거나 충돌한 경우 임시 파일을 정리합니다.
CleanupTempFiles
# https://github.com/satisfactorymodding/UnrealProjectUpdater/blob/master/ForceGeneratePackages.txt 에서 강제로 생성된 패키지 이름
Write-Output "/Game/FactoryGame/Buildable/-Shared/Widgets/Widget_Output_Slot" >> $ForceGenerateFile
# https://github.com/satisfactorymodding/UnrealProjectUpdater/blob/master/SkipSavePackages.txt 에서 저장 패키지 이름을 건너뜁니다.
Write-Output "/Game/FactoryGame/Interface/UI/BPI_ShoppingList" >> $SkipSaveFile
Write-Output "/Game/FactoryGame/Unlocks/BPI_UnlockableInterface" >> $SkipSaveFile
Write-Output "/Game/FactoryGame/Interface/UI/InGame/Graph/BPW_Graph" >> $SkipSaveFile
Write-Output "/Game/FactoryGame/-Shared/Blueprint/BP_OnlineHelpers" >> $SkipSaveFile
Write-Output "/Game/FactoryGame/AvailabilityDependencies/BPI_AvailabilityDependencyInterface" >> $SkipSaveFile
Write-Output "/Game/FactoryGame/Schematics/Research/BPD_ResearchTreeNode" >> $SkipSaveFile
# 에디터에서 발생하는 성가신 문제를 일으키는 몇 가지 애셋을 건너뜁니다 (예: 누락된 애니메이션 데이터 도배 오류)
# TODO: 이 기능이 작동하지 않는 것 같은데?
Write-Output "/Game/FactoryGame/Character/Player/Animation/FirstPerson/" >> $BlacklistFile
Write-Output "/Game/FactoryGame/Character/Player/Animation/ThirdPerson/" >> $BlacklistFile
# 생성기 커맨드렛 실행
& $UECmdPath $UProjectPath -run=AssetGenerator -DumpDirectory="$AssetDumpDirectory" -ForceGeneratePackageNames="$(Get-Location)\\$ForceGenerateFile" -SkipSavePackages="$(Get-Location)\\$SkipSaveFile" -BlacklistPackageNames="$(Get-Location)\\$BlacklistFile" -stdout -unattended -NoLogTimes
# 종료 시 임시 파일을 정리합니다.
CleanupTempFiles
한국어로 번역되면서 정상적으로 스크립트를 실행하기 위해서는 파일 저장 시 인코딩 형식을 UTF-8 with BOM(또는 UTF-8-SIG)으로 지정해야 합니다. 또는 한국어를 지우고 저장할 수도 있습니다. |
이 스크립트는 상당한 시간이 걸릴 것입니다. 전문가들은 그동안 도마멍멍이와 놀고 있을 권장합니다. 이 과정에서 잘못될 수 있는 많은 것들이 있으므로, 아래 단계를 통해 문제를 해결할 준비를 하십시오. 완료되면 Powershell 창이 닫히거나 다른 명령을 입력하라는 메시지가 표시됩니다.
작업이 완료되면 모딩 프로젝트의 콘텐츠 폴더는 약 6GB가 될 것입니다.
애셋 생성 충돌 문제 해결
커맨드렛이 충돌하는 경우, 문제를 해결하기 위해 몇 가지 접근 방식을 사용할 수 있습니다.
위에 설명된 최신 버전의 애셋 생성기로 업데이트했는지 확인하십시오.
문제를 해결하기 위한 첫 번째 단계는 생성기가 충돌하기 전에 어떤 애셋을 처리하고 있었는지 확인하는 것입니다.
이를 추적하려면 LogAssetGenerator 로깅 범주 세부 수준을 VeryVerbose
로 변경해야 합니다.
이를 위해 <시작 프로젝트 경로>\Config\DefaultEngine.ini
(plural 구성이 아니며, 이는 모드 구성입니다)를 편집하고
LogAssetGenerator=VeryVerbose
를 [Core.Log]
섹션에 추가하십시오.
그런 다음, Visual Studio 디버거를
실행 중인 프로세스에 연결하십시오. 목록에서 UnrealEditor-Cmd.exe
라는 프로세스입니다.
이제 처리 중인 패키지가 로그 메시지로 표시됩니다.
애셋 생성기를 다시 실행한 후, 다음에 충돌할 때 디버거가 중단점으로 멈추고 로그 메시지를 확인하여 문제의 애셋을 찾을 수 있습니다. 그런 다음 해당 애셋을 삭제하고 애셋 생성기를 다시 실행하십시오. 디버거는 때때로 비충돌 오류에 대해 중단점에서 멈출 수 있으므로, 로그를 검토한 후 계속 진행하여 정상적으로 복구되는지 확인하십시오.
문제가 계속 발생하면 디스코드에서 도움을 요청하십시오.
애셋 생성이 충돌하는 경우, 컴퓨터의 메모리가 부족해질 가능성이 높습니다. 특히 디버거가 연결된 경우에는 더욱 그렇습니다. 가능한 한 많은 메모리를 확보하기 위해 컴퓨터를 재시작하십시오. 재시작 후, 생성기를 다시 실행하십시오. 이전 실행에서 생성된 대부분의 파일을 유지하므로, 다음 메모리 부족 충돌까지 약간 더 진행할 수 있습니다. |
애셋 생성기 커맨드렛을 사용하는 데 여전히 문제가 있는 경우, 에디터 내 GUI를 대신 사용해 보십시오. 그러나 이는 적극적으로 유지 관리되지 않습니다.
사용자 정의 애셋 복원
일부 애셋은 일반 시작 프로젝트와 함께 배포되며, 생성기가 제공할 수 있는 것보다 더 완전하고/또는 유용합니다. 예를 들어, 커피 스테인이 제공한 일부 재료 애셋의 원본 복사본이 있습니다. 생성기를 실행하면 이러한 애셋이 덜 정확한 생성된 애셋으로 대체됩니다. 애셋 생성이 완료된 후, 스타터 프로젝트 콘텐츠의 백업 복사본에서 여러 파일을 가져와 새로 생성된 복사본의 애셋을 교체해야 합니다.
에디터가 열려 있지 않은지 확인하십시오!
이동할 파일 목록은
UnrealProjectUpdater 저장소의 CustomAssets.txt 파일에 있으며,
목록에 언급된 텍스처 애셋(TX_
로 시작하는 애셋)은 건너뛰어야 합니다.
생성기의 텍스처 복사본이 더 정확하기 때문입니다.
또한 Content/Localization/StringTables
폴더를 가져와야 합니다.
이는 pak 파일에 원시로 저장되며(utoc/ucas가 아님) 자동화가 현재 이를 추출하지 않기 때문입니다.
UnrealProjectUpdater 저장소의 열린 풀 리퀘스트를 확인하여 아직 프로젝트 목록에 병합되지 않은 추가 맞춤 애셋이 있는지 확인하십시오. |
백업 폴더를 잃어버린 경우, 시작 프로젝트 깃 저장소에서 다운로드할 수 있습니다.
손상된 애셋 삭제
불행히도 애셋 생성기는 모든 애셋을 올바르게 재생성할 수 없습니다. 생성 완료 후 손상된 애셋을 정리해야 합니다. 어떤 애셋이 수정이 필요한지는 업데이트마다 달라지며, 이전에 수행한 애셋 덤프/생성 문제 해결 단계에 따라 달라지므로, 여기에서 완전한 목록을 제공하는 것은 불가능합니다.
언리얼은 일반적으로 에디터가 열릴 때 메시지 로그(창 > 메시지 로그)에서 이러한 애셋에 대해 경고할 것입니다.
이러한 애셋을 감지하기 위해, 프로젝트에서 SML과 같은 모드를 패키징해 보십시오. 패키징 작업이 실패하고 출력 로그에 이러한 애셋을 참조하는 오류 메시지가 표시됩니다.
이러한 애셋을 처리하는 방법에는 몇 가지 옵션이 있습니다:
-
에디터가 열려 있을 때 애셋을 삭제(대체 없이)
-
참고: 이렇게 하면 다른 애셋이 업데이트됩니다. 삭제된 애셋이 가리키고 있던 객체가 제거되었기 때문입니다.
-
이러한 다른 애셋에 대한 변경 사항을 저장하지 않고 종료하면, 아래에 설명한 상황이 발생합니다.
-
-
에디터가 닫혀 있을 때 파일 시스템에서 애셋을 삭제
-
향후 삭제된 애셋에 의존하는 다른 애셋을 열면 에디터가 누락된 참조를 감지하고 이를 비우며, 애셋을 다시 저장하고 요청합니다. 저장하면 입력란이 비워진 상태로 애셋이 저장됩니다. 저장하지 않으면 에디터가 열릴 때마다 이를 감지합니다.
-
-
에디터가 닫혀 있을 때 "스텁" 버전으로 애셋을 교체
-
이 접근 방식은 위에서 언급한 부작용을 겪지 않을 것입니다.
-
손상된 애셋을 처리한 후, 모드는 정상적으로 다시 패키징할 수 있어야 합니다.
정리
애셋 생성이 완료되면,
게임 설치 디렉터리에서 AssetDump
폴더를 안전하게 삭제할 수 있습니다.
게임 설치에서 애셋 덤퍼 모드를 제거하는 것도 좋습니다.
게임 시작 시간을 상당히 늘리기 때문입니다.
추가 문서
애셋 툴킷에 대해 더 알고 싶다면 아래를 계속 읽어보십시오.
애셋 생성기 커맨드렛 문서
다음은 다양한 커맨드렛 옵션이 수행하는 작업에 대한 설명입니다. Archengius가 작성했습니다:
커맨드렛 이름은 AssetGenerator입니다.
-DumpDirectory=는 덤프의 루트 디렉터리 경로로, 애셋 덤퍼에서 지정한 대로입니다.
-ForceGeneratePackageNames=는 선택적 파일로, 먼저 생성할 패키지의 줄 바꿈으로 구분된 목록을 포함합니다. /Game/FactoryGame/Buildable/-Shared/Widgets/Widget_Output_Slot을 여기에 포함하여 전체 프로젝트를 처음부터 생성할 때 에디터가 충돌하는 이상한 버그를 피하십시오.
-BlacklistPackageNames=는 선택적이며, ForceGeneratePackageNames와 동일한 의미를 가지지만, 경로가 /로 끝나는 경우 와일드카드 경로도 지원합니다. 기본적으로 필요하지 않습니다.
-AssetClassWhitelist=는 생성할 애셋 클래스의 선택적 쉼표로 구분된 목록으로, 전체 프로젝트 생성을 위해선 비워 두어야 합니다.
-PublicProject는 선택적이며, 생성된 프로젝트에서 배포할 수 없는 애셋을 null로 설정합니다. 지정하지 않으면 게임에 있는 모델과 텍스처를 포함하는 전체 프로젝트가 생성됩니다.
-NoRefresh는 선택적이며, 지정된 경우 생성기가 기존 애셋을 건드리지 않도록 합니다.
UI를 사용하여 덤프/생성하기
애셋 툴킷의 명령줄 버전을 사용할 때 문제가 발생하는 경우, UI를 사용해도 문제가 해결되지 않을 것입니다! 디스코드에서 도움을 요청하십시오. 현재 애셋 툴킷 플러그인의 UI를 사용할 때 여러 충돌 문제가 발생하고 있습니다. UI를 사용할 특별한 이유가 없다면, 위의 명령줄 지침을 사용하여 애셋을 덤프하고 생성하는 것이 좋습니다. |
덤프하기
애셋을 에디터로 가져오기 위해 추출하려면,
새티스팩토리 복사본을 실행하고 인게임 개발자 콘솔을 열어야 합니다.
이는 억음/물결표 키(`
또는 ~
)를 누르거나 F2를 눌러 열 수 있습니다.
dumper.OpenAssetDumper
를 입력하고 Enter를 누르십시오. 아래처럼 UI가 나타날 것입니다:
출력 폴더 경로를 기본값으로 두고
<게임 설치 디렉터리>\FactoryGame\AssetDump
에 내보내거나,
…
버튼을 사용하여 특정 경로를 선택할 수 있습니다.
다음으로, 덤프할 애셋 경로를 선택하십시오. 일반적으로 Game/FactoryGame/
를 선택하고,
애셋 유형 필터 드롭다운으로 내보내는 내용을 선택적으로 제한할 수 있습니다.
준비가 되면 "애셋 덤프 시작"을 누르십시오. 시간이 걸릴 수 있으니, 도마멍멍이와 놀면서 기다리십시오.