Abstract
다운로드 시스템은 주소와 저장 경로만 주면 파일을 받아 디스크에 써 주는 대기열입니다. 여러 개를 넣으면 정해진 개수만큼 동시에 받고 나머지는 줄을 세웁니다. 중간에 끊기면 받은 데까지는 남겨 두었다가 다음에 이어 받습니다.
실무에서 필요한 순간
•
설치 후 추가 콘텐츠(스테이지 팩, 고화질 리소스)를 내려받을 때
•
유저가 만든 콘텐츠나 리플레이 파일을 받을 때
•
큰 파일이라 "끊겨도 처음부터 다시 받지 않는 것"이 중요할 때
서버 API 를 호출해 JSON 을 받는 일은 다운로드가 아니라 WebRequest 의 몫입니다. 응답을 파일로 저장할 필요가 없기 때문입니다.
사용 흐름
graph LR
A["AddDownload(저장 경로, 주소)"] --> B["대기열"]
B --> C["에이전트 3개가<br>동시에 처리"]
C --> D["파일.download 에<br>조금씩 기록"]
D --> E["완료 시 이름 변경<br>+ DownloadSuccess 이벤트"]Mermaid
복사
설정값 — GameFramework.prefab 의 Download 오브젝트
필드 | 기본값 | 의미 |
Download Agent Helper Count | 3 | 동시에 받는 파일 수 |
Timeout | 30초 | 이 시간 동안 데이터가 안 오면 실패 처리 |
Flush Size | 1 MB | 이만큼 받을 때마다 디스크에 확정 기록. 작을수록 끊겼을 때 잃는 양이 적다 |
ToyboxNightmare 에서는
쓰지 않습니다. 원작 GameFramework 에서는 리소스 업데이트(핫 패치)가 이 모듈로 번들을 받았지만, 이 에디션은 원격 리소스를 Addressables 가 직접 받습니다. 그래서 이 모듈은 "게임 코드가 직접 임의의 파일을 받고 싶을 때"만 쓰입니다.
자주 걸리는 곳
•
메서드 이름은 Download 가 아니라 AddDownload, 인자 순서는 (저장 경로, 주소) 입니다.
•
결과는 EventComponent 로 옵니다. DownloadStart / DownloadUpdate / DownloadSuccess / DownloadFailure 네 가지 ...EventArgs 가 있습니다.
•
저장 경로는 쓰기 가능한 절대 경로여야 합니다. Application.persistentDataPath 아래를 쓰세요. Assets/... 는 에디터에서만 존재하는 경로입니다.
•
이벤트는 전역이라 다른 코드의 다운로드 결과도 같이 들어옵니다. AddDownload 가 돌려준 번호와 SerialId 를 비교해 가려냅니다.
Download System (다운로드 시스템)
목적과 통합 (Purpose and Integration)
다운로드 시스템은 게임 프레임워크 내에서 원격 소스로부터 파일을 다운로드하는 기능을 제공합니다.
이 시스템은 이벤트 기반의 파일 다운로드 방식을 제공하며, **범위 요청(range request, 부분 다운로드)**과 **진행 상황 추적(progress tracking)**을 지원합니다.
이 시스템은 다음과 같은 작업을 위해 주로 사용됩니다:
•
게임 에셋 및 리소스 다운로드
•
패치 및 업데이트 가져오기
•
설정 파일 가져오기
웹 기반 API 요청의 경우 파일 다운로드가 아닌 일반 HTTP/HTTPS 통신에 적합한 **웹 요청 시스템(Web Request System)**을 사용하는 것이 더 적절합니다.
아키텍처 (Architecture)
다운로드 시스템은 게임 프레임워크 전반에서 사용되는 컴포넌트-매니저-헬퍼 패턴을 따릅니다.
주요 컴포넌트 (Key Components)
DownloadAgentHelperBase
다운로드 에이전트 헬퍼의 인터페이스를 정의하는 추상 클래스입니다. 다운로드 진행, 완료, 오류 처리에 대한 이벤트를 제공합니다.
UnityWebRequestDownloadAgentHelper
현대적인 Unity 버전(Unity 5.4+)에서 사용되는 기본 구현체로, Unity의 UnityWebRequest API를 사용하여 파일을 다운로드합니다.
WWWDownloadAgentHelper
오래된 Unity 버전(2018.3 이전)을 위한 레거시 구현체로, 더 이상 권장되지 않는 WWW 클래스를 사용합니다. #if !UNITY_2018_3_OR_NEWER 로 감싸져 있어 현재 Unity 에서는 컴파일에서 제외됩니다.
다운로드 흐름 (Download Flow)
다운로드는 다음 단계를 통해 이루어집니다:
1.
UnityWebRequest 또는 WWW 인스턴스를 생성
2.
부분 다운로드가 필요하면 Range 헤더 설정
3.
요청을 비동기로 시작
4.
진행 상황을 Update 메서드에서 모니터링
5.
이벤트를 통해 다운로드 상태(진행, 완료, 실패) 전달
구현 세부사항 (Implementation Details)
다운로드 모드 (Download Methods)
다운로드 시스템은 세 가지 모드를 지원합니다:
•
전체 다운로드 (Full Download): 파일 전체 다운로드
•
특정 위치부터 다운로드 (From Position): 지정된 바이트 위치부터 끝까지 다운로드
•
범위 다운로드 (Range Download): 지정된 바이트 구간(from-to)만 다운로드
다운로드 에이전트 헬퍼 이벤트 (Download Agent Helper Events)
이벤트 | 설명 |
DownloadAgentHelperUpdateBytes | 새로운 바이트가 수신될 때 발생 |
DownloadAgentHelperUpdateLength | 다운로드 길이가 갱신될 때 발생 |
DownloadAgentHelperComplete | 다운로드가 완료되면 발생 |
DownloadAgentHelperError | 다운로드 중 오류가 발생하면 발생 |
UnityWebRequestDownloadAgentHelper 구현 (UnityWebRequestDownloadAgentHelper Implementation)
•
Unity의 UnityWebRequest API를 사용하여 다운로드 수행
•
필요한 경우 Range 헤더를 설정하여 부분 다운로드 지원
•
요청은 비동기로 수행되며 진행 상황을 실시간으로 추적
•
다운로드 완료, 업데이트, 에러 발생 시 이벤트를 발생시킴
•
Unity 버전별 API 차이를 #if 전처리기 지시문으로 처리 (예: Unity 2017.2, 2020.2 등)
오류 처리 (Error Handling)
다운로드 시스템은 다음과 같은 오류 상황을 처리합니다:
•
네트워크 연결 문제
•
HTTP 오류 (404, 500 등)
•
Range 요청 불가 오류 (416)
•
타임아웃 오류
오류가 발생하면 DownloadAgentHelperError 이벤트가 발생하며, 오류 세부 정보가 함께 전달됩니다.
사용 예제 (Usage Examples)
기본 다운로드 (Basic Usage)
// DownloadComponent 가져오기
DownloadComponent downloadComponent = GameEntry.GetComponent<DownloadComponent>();
// 이벤트 등록 — C# 이벤트가 아니라 EventComponent 로 받는다
EventComponent events = GameEntry.GetComponent<EventComponent>();
events.Subscribe(DownloadSuccessEventArgs.EventId, OnDownloadSuccess);
events.Subscribe(DownloadFailureEventArgs.EventId, OnDownloadFailure);
events.Subscribe(DownloadUpdateEventArgs.EventId, OnDownloadUpdate);
// 다운로드 시작 — 인자 순서는 (저장 경로, 주소). 반환값은 요청 번호
string savePath = Path.Combine(Application.persistentDataPath, "file.zip");
int serialId = downloadComponent.AddDownload(savePath, "https://example.com/file.zip");
C#
복사
이벤트 핸들러 (Handlers)
private void OnDownloadSuccess(object sender, GameEventArgs e)
{
DownloadSuccessEventArgs ne = (DownloadSuccessEventArgs)e;
Log.Info("완료: {0} ({1} bytes)", ne.DownloadPath, ne.CurrentLength);
}
private void OnDownloadUpdate(object sender, GameEventArgs e)
{
DownloadUpdateEventArgs ne = (DownloadUpdateEventArgs)e;
// ne.CurrentLength = 지금까지 받은 바이트 수
}
private void OnDownloadFailure(object sender, GameEventArgs e)
{
DownloadFailureEventArgs ne = (DownloadFailureEventArgs)e;
Log.Warning("실패: {0}", ne.ErrorMessage);
}
C#
복사
취소와 일시정지 (Cancel / Pause)
downloadComponent.RemoveDownload(serialId); // 요청 하나 취소
downloadComponent.RemoveAllDownloads(); // 전부 취소
downloadComponent.Paused = true; // 전체 일시정지 (개별 일시정지는 없다)
C#
복사
범위 다운로드(Range)는 게임 코드가 직접 지정하는 API 가 아닙니다. 다운로드가 끊겼다가 같은 경로로 다시 요청되면, 프레임워크가 남아 있는 임시 파일(.download)의 크기를 보고 그 지점부터 이어받기 위해 내부적으로 사용합니다.
다른 시스템과의 통합 (Integration with Other Systems)
다운로드 시스템은 프레임워크 내 여러 시스템에서 사용됩니다:
•
리소스 시스템(Resource System) : 게임 에셋 및 리소스 파일 다운로드
•
리소스 업데이트(Resource Updater) : 패치 및 업데이트 다운로드
•
Download Component : Unity 친화적인 인터페이스 제공
구현 노트 (Implementation Notes)
•
다운로드 시스템은 메인 스레드에서 돌며, 에이전트 수(기본 3)만큼 여러 다운로드를 동시에 처리합니다. 나머지는 대기열에서 기다립니다.
•
다운로드 작업은 취소가 가능하고, 시스템 전체를 일시 중지/재개할 수 있습니다.
•
다운로드 중 데이터 손상을 방지하기 위해 임시 파일을 사용합니다.
•
진행 상황 보고는 퍼센트(%)와 바이트 단위를 모두 지원합니다.
•
인증 헤더를 붙이는 API 는 없습니다. 필요하면 DownloadAgentHelperBase 를 상속한 헬퍼를 만들어 교체합니다.
요약 (Summary)
다운로드 시스템은 게임 프레임워크에서 모든 다운로드 관련 작업을 위한 강력한 기반을 제공합니다.
•
원격 리소스를 효율적으로 가져올 수 있으며
•
다운로드 진행 상황과 완료 상태에 대한 상세한 피드백을 제공합니다.
•
이벤트 기반 구조로, 다른 시스템과 쉽게 통합 가능하며
•
패치, 업데이트, 리소스 다운로드까지 폭넓게 활용됩니다.