Android 파일 서버(Android File Server, AFS) 는 Development, Debug 또는 Test 프로젝트(또는 선택적으로 Shipping 프로젝트, 아래 참조 빌드를 패키징할 때 Android 애플리케이션에 파일 서버를 임베드하는 언리얼 엔진(UE) 플러그인입니다. 파일 서버가 실행 중이면 UnrealAndroidFileTool 을 사용하여 파일을 관리하고, 푸시하고, 볼 수 있습니다. AFS를 포함하는 빌드에서 언리얼 엔진은 AFS로 빠른 실행을 디플로이합니다. Android Debug Bridge(ADB) 대신 AFS와 UnrealAndroidFileTool을 함께 사용하면 언리얼 엔진의 워크플로에 맞춰진 여러 동일한 기능을 이용할 수 있습니다.
빠른 실행 처리를 위해 디바이스의 SD 카드 외부 스토리지를 사용하는 대신 AFS는 패키지 샌드박스 스토리지를 사용합니다. 이를 통해 프로젝트를 개발하고 빌드를 디플로이하는 동안 번거로울 수 있는 스토리지 권한 또는 범위가 지정된 액세스를 다시 활성화할 필요 없이 파일 작업을 계속할 수 있습니다. AFS는 또한 WiFi 연결, USB 연결 또는 두 가지 모두를 사용하여 더욱 빠른 디플로이가 가능합니다.
구성 및 설정
이 섹션에서는 AFS의 패키징 및 연결을 환경설정하는 방법을 설명합니다. 프로젝트 세팅(Project Settings) > 플러그인(Plugins) > AndroidFileServer 에서 세팅을 확인할 수 있습니다. 이 섹션은 환경설정 가능한 각 파라미터를 보여줍니다.
패키징 세팅
패키징(Packaging) 섹션에는 AFS를 포함할 빌드 타입과 파일 서버의 기능을 환경설정하는 세팅이 포함되어 있습니다. AFS는 기본적으로 활성화되고, Shipping 이외의 빌드의 경우 비활성화되지 않는 한 프로젝트에 자동으로 파일 서버를 임베드합니다. Shipping 빌드에는 기본적으로 AFS가 포함되지 않지만 이를 활성화할 세팅이 있습니다.
| 파라미터 | 설명 |
|---|---|
| Android 파일 서버 사용(Use AndroidFileServer) | 활성화되면 프로젝트에 패키징된 빌드 및 빠른 실행 빌드의 임베드된 파일 서버가 포함됩니다. 비활성화되면 프로젝트에서 AFS를 사용하지 않고, 언리얼 엔진에서는 ADB를 사용하도록 예비 전환합니다. |
| 네트워크 연결 허용(Allow Network Connection) | 활성화되면 AFS에서 WiFi 연결과 USB를 통한 연결을 허용합니다. 자세한 내용은 연결 세팅을 참조하세요. |
| 보안 토큰(Security Token) | AFS를 보호하고 토큰이 없는 다른 누군가가 원격으로 시작하는 것을 방지하는 데 사용할 수 있는 고유한 스트링입니다. 자세한 내용은 보안 토큰 사용하기를 참조하세요. |
| Shipping에 포함(Include in Shipping) | 활성화되면 AFS가 Shipping 빌드에 포함됩니다. 자세한 내용은 Shipping 빌드에서 AFS 사용하기를 참조하세요. |
| Shipping에서 외부 시작 허용(Allow External Start in Shipping) | Shipping에 포함(Include in Shipping)과 함께 사용하는 파라미터로서, UnrealAndroidFileTool을 사용하거나 빠른 실행을 위해 파일 서버를 시작하도록 외부 요청을 허용합니다. |
| AFS 프로젝트 컴파일(Compile AFSProject) | 활성화되면 언리얼 엔진에서 프로젝트를 패키징할 때 AFS를 별도의 APK로 컴파일합니다. 자세한 내용은 AFS 프로젝트 컴파일하기를 참조하세요. |
Shipping 빌드에서 AFS 사용하기
Shipping 빌드에는 일반적으로 AFS가 포함되지 않지만 Shipping에 포함(Include in Shipping) 및 Shipping에서 외부 시작 허용(Allow External Start in Shipping) 을 활성화하여 추가할 수 있습니다. Shipping에 포함(Include in Shipping)만 활성화한 경우 AFS를 사용할 수는 있지만 빠른 실행에 사용할 수는 없고, 애플리케이션 내부에서 수동으로 시작 및 중지해야 합니다.
AFS 시작 및 중지하기
Shipping 이외의 빌드를 사용할 때, 또는 Shipping 빌드에서 외부 시작이 활성화된 경우 리시버가 등록되어 파일 서버의 원격 시작 및 중지가 가능합니다. 이후 UnrealAndroidFileTool을 사용하여 디바이스의 파일 서버에 연결하고 파일을 관리할 수 있습니다. 그렇지 않으면 AFS가 활성화된 상태에서 언리얼 엔진 애플리케이션 내에서 파일 서버를 수동으로 시작해야 합니다. 자세한 내용은 블루프린트를 사용하여 수동으로 AFS 시작 및 중지하기를 참조하세요.
보안 토큰 사용하기
보안 토큰(Security Token) 필드를 입력한 경우 일치하는 보안 토큰을 제공하기 위해 파일 서버에 UnrealAndroidFileTool로부터 수신되는 연결 요청이 필요합니다. 자세한 내용은 UnrealAndroidFileTool 레퍼런스를 참조하세요.
보안 토큰은 기본적인 보안만을 제공하며, 어떠한 방식으로도 암호화되지 않습니다. Android 파일 서버 블루프린트 라이브러리를 사용하여 Shipping 빌드의 보안을 자체적으로 강화할 수 있습니다. 보안 토큰을 사용할 때 토큰을 조직 외부에 제공해서는 안 됩니다.
수동으로 AFS 프로젝트 컴파일 및 설치하기
AFS 프로젝트 컴파일(Compile AFSProject) 이 활성화된 경우 파일 서버가 포함된 독립형 APK는 프로젝트의 구성 및 키 사이닝과 일치하도록 패키징됩니다. 이 APK를 디바이스에 설치하고 adb install -r 옵션을 사용하여 새 파일이나 기존 파일을 관리할 수 있습니다. 이후 내부 또는 외부 데이터 파일에 영향을 미치지 않고 동일한 옵션으로 실제 APK를 다시 설치할 수 있습니다. 이는 특히 서버가 내장되지 않은 Shipping 빌드에서 파일을 관리해야 하는 경우에 유용합니다.
Shipping 빌드는 AFS 프로젝트 컴파일의 활성화 여부와 무관하게 AFS 프로젝트를 컴파일합니다.
디플로이 세팅(로깅 및 압축)
디플로이(Deployment) 섹션에서는 파일 서버가 로그에 보고하는 정보를 제어합니다.
| 파라미터 | 설명 |
|---|---|
| 압축 사용(베타)(Use Compression (Beta)) | 파일 서버의 데이터 파일에 압축을 적용합니다. UE 5.0에서는 전송 시간에 최소한의 영향을 미칩니다. |
| 로그 파일(Log Files) | 디바이스로 푸시되는 파일 목록을 보여줍니다. |
| 보고 통계(Report Stats) | 디바이스로 푸시된 파일의 수와 연결을 통해 푸시된 바이트 수 목록을 보여줍니다. |
로그 출력 세팅이 활성화되면 언리얼 엔진은 빠른 실행 도중 AFS의 설치 프로세스에 관한 정보를 콘솔(Console) 창에 로깅합니다.
USB와 네트워크가 모두 활성화된 상태에서 로깅하기
USB 및 네트워크가 모두 활성화된 경우 AFS 로그에서 접두사를 통해 파일이 어떤 연결 타입을 통해 전송되었는지 보여줍니다.
| 접두사 | 설명 |
|---|---|
| 1> | 파일이 USB를 통해 전송되었습니다. |
| 2> | 파일이 WiFi를 통해 전송되었습니다. |
예를 들어 다음은 맵 파일이 USB를 통해 전송되었음을 보여줍니다.
1> TestGameEntry.umap
USB와 WiFi를 모두 사용하는 경우 다른 연결이 사용 중인 동안 하나의 연결이 우선 사용됩니다.
1> TestGameEntry.umap
2> TestTexture.uasset
2> TestMaterial.uasset
1> TestPawn.uasset
연결 세팅
연결(Connection) 섹션에는 AFS에서 컴퓨터를 디바이스에 연결하는 데 사용하는 연결 타입을 환경설정하는 옵션이 포함되어 있습니다.
| 파라미터 | 설명 |
|---|---|
| 연결 타입(Connection Type) | USB, WiFi 또는 두 가지 모두를 사용하여 파일 서버에 연결할지 결정합니다. |
| 수동 IP 주소 사용(Use Manual IP Address) | 활성화되면 빠른 실행에서 수동 IP 주소(Manual IP Address) 필드에 입력된 IP에서 Android 디바이스를 사용합니다. 그렇지 않으면 연결된 경우 USB를 통해 IP 주소를 검색합니다. |
| 수동 IP 주소(Manual IP Address) | 빠른 실행에서 연결할 Android 디바이스의 IP 주소입니다. 디바이스는 로컬 WiFi 네트워크에 연결되어야 합니다. |
연결 타입
연결 타입(Connection Type) 드롭다운에서 파일 푸시에 사용할 연결 타입을 선택합니다.
| 연결 타입 | 설명 |
|---|---|
| USB | USB 연결을 통해 파일을 Android 디바이스로 푸시합니다. |
| WiFi Network | 컴퓨터와 동일한 로컬 영역 WiFi 네트워크에서 WiFi 네트워크 연결을 통해 파일을 Android 디바이스로 푸시합니다. 네트워크 연결 허용(Allow Network Connection) 세팅이 활성화되어야 합니다. |
| USB and Network Combined | USB 연결과 WiFi 연결을 동시에 사용하여 파일을 푸시합니다. 한쪽 연결이 파일이나 배치 파일의 전송 영역을 차지하면 대기열에서 다른 연결이 다음 파일을 이어받습니다. 그에 따라 더욱 빠른 파일 전송이 가능합니다. 이 과정은 디플로이 프로세스의 일부로 통합됩니다. |
오버라이드하지 않는 한 AFS의 디폴트 포트는 57099입니다.
수동 IP 주소 사용하기
수동 IP 주소 사용(Use Manual IP Address) 세팅을 활성화하고 Android 디바이스의 IP 주소를 제공한 경우 AFS는 일반 디바이스 매니저 워크플로에서 이 디바이스를 디폴트 디바이스 대신 연결합니다. 디바이스가 컴퓨터와 동일한 WiFi 네트워크에 연결되어 있어야 합니다.
블루프린트를 사용하여 수동으로 AFS 시작 및 중지하기
Android 파일 서버 블루프린트 라이브러리를 사용하여 UE 애플리케이션 내부에서 파일 서버를 시작, 중지하고 상태를 확인할 수 있습니다.
| 노드 | 설명 |
|---|---|
| Start File Server | 지정된 연결용 포트를 사용하여 파일 서버를 시작합니다. 이 노드를 사용하여 서버를 시작할 때 USB 또는 네트워크 연결을 허용할지 여부를 선택할 수 있습니다. 반환 값은 서버가 성공적으로 시작되었는지 여부를 나타내는 부울입니다. |
| Stop File Server | 실행 중인 경우 파일 서버를 중지합니다. 특정 연결 타입만 종료할 수 있습니다. 반환 값은 서버가 성공적으로 종료되었는지 여부를 나타내는 부울입니다. |
| Is File Server Running |
|
AFS에서 프로젝트를 위해 생성된 고유 토큰을 사용하는 기본 보안을 제공할 수 있지만 디폴트 브로드캐스트 리시버를 사용하는 경우와 비교하여 AFS를 시작 및 중지하는 보다 안전한 수단으로 블루프린트 노드가 있습니다.
UnrealAndroidFileTool
UnrealAndroidFileTool은 디바이스에 디플로이된 파일 서버에 연결하여 수동으로 파일을 관리할 수 있는 툴입니다. 엔진의 설치 디렉터리인 Engine/Binaries/DotNET/Android/UnrealAndroidFileTool 에서 찾을 수 있습니다. 이 디렉터리에는 실행파일의 Linux, MacOS 및 Windows 버전 폴더가 있습니다.
3개 운영체제 모두에 사용할 UnrealAndroidFileTool 실행파일 버전이 필요한 경우 프로젝트 세팅(Project Settings) > 플랫폼(Platforms) > Android 를 열고 Generate Install Files for all platforms 를 활성화합니다. 이 세팅이 활성화되지 않은 경우 언리얼 엔진은 패키징된 타깃 디렉터리의 에디터 호스트 타입과 일치하는 실행파일만 제공합니다.
명령줄을 통해 이 실행파일을 실행할 경우, 파일의 사용 가능 함수를 전부 보여주는 메뉴가 표시됩니다. 명령줄에 있는 명령을 사용하여 실행파일을 실행할 수 있습니다.
명령 레퍼런스
UnrealAndroidFileTool 명령은 툴에 연결을 설정할 대상을 알리는 파라미터 세트와 그 뒤에 파일 서버로의 전송 명령 으로 구성됩니다. 예를 들어 다음은 특정 일련 번호를 가진 디바이스에서 셸 명령을 실행하고 특정 프로젝트의 파일을 조회합니다.
UnrealAndroidFileTool.exe -s AB187923123CD123 -p com.OrganizationName.ProjectName shell
경로 포맷 지정
AFS의 경로는 명령줄 경로에 일반 규칙을 사용하지만 파일 계층구조 탐색을 위해 여러 바로가기를 지원합니다.
| 텍스트 | 설명 |
|---|---|
^^ |
cd 명령으로 설정한 현재 베이스 디렉터리를 참조합니다. 자세한 내용은 쿼리 및 탐색 명령을 참조하세요. |
^-n |
지정된 횟수만큼 상위 디렉터리로 이동하며, n 이 원하는 횟수입니다. 예를 들어 ^-3 은 세 번 상위 디렉터리로 이동합니다. 여러 개의 /.. 인스턴스 사용 없이 상대 경로를 처리하기가 더욱 쉽습니다. |
^[key] |
바로가기 역할을 하거나 지정된 키를 쿼리하는 파일 경로의 시작에 사용되고, [key] 는 키의 텍스트로 바뀝니다. 예를 들어 ^ext/ 는 외부 패키지 디렉터리이고, ^commandfile 은 UECommandLine.txt 파일의 바로가기입니다. 아래에서 유용한 바로가기 목록을 참조하세요. |
다음은 ^[key] 를 사용하는 일반적인 바로가기입니다. 필수는 아니지만 편리한 기능입니다.
| 바로가기 | 설명 |
|---|---|
| 디렉터리 바로가기 | |
^ext/ |
외부 스토리지 디렉터리. |
^int/ |
내부 스토리지 디렉터리. |
^storage/ |
외부 스토리지 디렉터리(READ_EXTERNAL_STORAGE 및/또는 WRITE_EXTERNAL_STORAGE 권한 필요). |
^obb/ |
obb 디렉터리. |
^unreal/ |
UnrealGame 디렉터리. |
^project/ |
UnrealGame/[project] 디렉터리. |
^engine/ |
UnrealGame/Engine 디렉터리. |
^game/ |
UnrealGame/[project]/[project] 디렉터리. |
^saved/ |
Saved 디렉터리. |
^logs/ |
Logs 디렉터리. |
| 특정 파일의 바로가기 | |
^commandfile |
UECommandLine.txt 파일. |
^logfile |
프로젝트 로그 파일. |
^mainobb |
메인 .obb 파일 경로. |
^patchobb |
패치 .obb 파일 경로. |
| 파일 경로 이외의 쿼리 | |
^packagename |
프로젝트의 패키지 이름. |
^version |
패키지 버전 코드. |
^ip |
네트워크에 있는 디바이스의 IP 주소. |
파라미터
파일 서버 명령 앞에 다음 파라미터를 입력하여 특정 타깃 디바이스 및 프로젝트를 위한 연결을 환경설정할 수 있습니다.
| 명령 | 설명 |
|---|---|
-s [device serial number] |
명령을 지정된 일련 번호의 디바이스로 보냅니다. |
-ip [IP address] |
디바이스를 지정된 IP 주소에 연결합니다. |
-t [port] |
디바이스 연결에 사용되는 포트를 오버라이드합니다. 별도로 지정되지 않으면 디폴트 포트는 57099 가 됩니다. |
-p [package name] |
연결할 애플리케이션의 리버스 도메인 패키지 이름입니다. 예시는 다음과 같습니다. com.OrganizationName.ProjectName . 패키지 이름은 대소문자를 구분하며 프로젝트 세팅의 스트링과 정확히 일치해야 합니다. |
-k [security token] |
보안 토큰 사용하기에서 설명하는 것과 같이 파일 서버에 연결하는 데 필요한 보안 토큰을 입력합니다. |
디바이스 관리 명령
다음 표는 사용 가능한 디바이스 및 인식된 패키지에 관한 정보를 가져오거나 원격 서버를 중지하는 데 사용할 수 있는 명령입니다.
| 명령 | 설명 |
|---|---|
help [command] |
파라미터가 있는 다른 명령의 이름과 함께 help 명령을 사용하는 경우 UnrealAndroidFileTool은 해당 명령과 포맷 지정 방법에 관한 정보를 제공합니다. |
devices |
액세스할 수 있는 연결된 디바이스 목록이 표시됩니다. @ 접두사가 있는 디바이스는 인증된 디바이스입니다. 일련 번호에 -s 를 입력한 경우 @ 를 포함하지 마세요. |
packages |
AFS 리시버가 활성화된 패키지 목록이 표시됩니다. |
stop-all [-w] |
리시버가 있는 모든 패키지에 중지 요청을 보냅니다. -w 를 추가하는 경우 UnrealAndroidFileTool에서 모든 리슨 바인드가 종료되기를 기다리며, 종료된 이후에 다시 상호작용할 수 있습니다. |
terminate |
지정된 원격 서버를 중지합니다. |
push , pull 또는 shell 과 같이 파일 서버와 상호작용하는 명령은 묵시적으로 서버 시작을 요청하므로, 서버 시작 명령은 없습니다.
인터랙티브 모드 명령
다음 명령을 사용하여 인터랙티브 모드(Interactive Mode) 를 시작 및 종료할 수 있습니다. 인터랙티브 모드는 ADB와 마찬가지로 각 명령에서 UnrealAndroidFileTool.exe를 실행할 필요 없이 디바이스 연결을 열고 여러 명령을 보낼 수 있습니다. 종료할 때까지 UnrealAndroidFileTool은 인터랙티브 모드로 유지됩니다.
| 명령 | 설명 |
|---|---|
shell |
인터랙티브 모드를 시작합니다. |
quit 또는 exit |
인터랙티브 모드를 종료합니다. |
쿼리 및 탐색 명령
다음 명령은 디바이스에서 디렉터리 및 파일에 관한 정보를 가져오거나 인터랙티브 모드 도중 베이스 디렉터리의 탐색을 제공합니다.
| 명령 | 설명 |
|---|---|
query [key] |
특정 키를 포함한 모든 변수를 표시합니다. |
getprop [key] |
지정된 키와 연결된 프로퍼티를 가져옵니다. |
cd [path] |
베이스 디렉터리를 설정합니다. 이후 ^^ 를 사용하여 수동으로 입력하는 대신 이 디렉터리를 참조할 수 있습니다. |
pwd |
현재 베이스 디렉터리를 표시합니다. |
direxists [path] |
입력한 경로에 디렉터리가 있는지 여부를 출력합니다. |
ls [-l,-s,-R,-f] [path] |
입력한 경로에 있는 디렉터리의 콘텐츠를 보여줍니다. 아래의 지정자는 출력할 정보를 지정합니다.
|
파일 관리
다음 명령은 디바이스의 파일과 상호작용하거나 파일을 수정합니다.
| 명령 | 설명 |
|---|---|
mkdir [path] |
지정된 경로에 디렉터리를 생성합니다. |
| ` rmdir [path]` | 지정된 경로에서 디렉터리를 삭제합니다. |
fileexists [file] |
이름이 지정된 파일이 있는지 여부를 출력합니다. |
rm [file] |
이름이 지정된 파일을 삭제합니다. |
cp [source] [destination] |
[source] 파일을 디바이스의 지정된 [destination] 디렉터리로 복사합니다. |
mv [source] [destination] |
[source] 파일을 모바일 디바이스의 지정된 [destination] 디렉터리로 이동합니다. |
pull [source] [destination] |
[source] 파일을 모바일 디바이스에서 PC의 지정된 [destination] 디렉터리로 복사합니다. |
push [-c] [source] [destination] |
PC에 있는 [source] 파일을 모바일 디바이스의 지정된 [destination] 디렉터리로 복사합니다. -c 파라미터를 추가하면 UnrealAndroidFileTool에서 데이터를 압축합니다. |
cat [file] |
디바이스에서 출력 로그로 파일 콘텐츠를 씁니다. |
deploy [-c] [file] |
디플로이 소스/대상 쌍에서 텍스트 파일을 읽습니다. -c 파라미터를 추가하면 UnrealAndroidFileTool에서 파일을 압축합니다. |
명령줄 파일 명령
다음 명령은 원격 디바이스에서 프로젝트의 UECommandLine.txt 파일과 상호작용하거나 파일을 수정합니다.
| 명령 | 설명 |
|---|---|
command [data] |
UECommandLine.txt 파일에 데이터를 씁니다. 데이터를 제공하지 않는 경우 파일의 콘텐츠가 표시됩니다. |
addcommand [data] |
UECommandLine.txt 파일에 데이터를 추가합니다. |
delcommand [data] |
UECommandLine.txt 파일에서 데이터를 제거합니다. |