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 클래스를 사용합니다.
다운로드 흐름 (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>();
// 이벤트 등록
downloadComponent.DownloadSuccess += OnDownloadSuccess;
downloadComponent.DownloadFailure += OnDownloadFailure;
downloadComponent.DownloadUpdate += OnDownloadUpdate;
// 다운로드 시작
downloadComponent.Download("https://example.com/file.zip", "Assets/Downloads/file.zip");
C#
복사
범위 다운로드 (Range Downloads)
// 파일의 바이트 1000 ~ 2000만 다운로드
downloadComponent.Download("https://example.com/file.zip", "Assets/Downloads/file.zip", 1000, 2000);
C#
복사
콜백과 함께 다운로드 (With Callbacks)
downloadComponent.Download("https://example.com/file.zip", "Assets/Downloads/file.zip",
new DownloadSuccessCallback(OnDownloadSuccess),
new DownloadFailureCallback(OnDownloadFailure),
new DownloadUpdateCallback(OnDownloadUpdate));
C#
복사
다른 시스템과의 통합 (Integration with Other Systems)
다운로드 시스템은 프레임워크 내 여러 시스템에서 사용됩니다:
•
리소스 시스템(Resource System) : 게임 에셋 및 리소스 파일 다운로드
•
리소스 업데이트(Resource Updater) : 패치 및 업데이트 다운로드
•
Download Component : Unity 친화적인 인터페이스 제공
구현 노트 (Implementation Notes)
•
다운로드 시스템은 스레드 안전(thread-safe) 하며, 여러 다운로드를 동시에 처리할 수 있습니다.
•
다운로드 작업은 일시 중지, 재개, 취소가 가능합니다.
•
다운로드 중 데이터 손상을 방지하기 위해 임시 파일을 사용합니다.
•
진행 상황 보고는 퍼센트(%)와 바이트 단위를 모두 지원합니다.
•
리디렉션 및 인증도 설정 시 지원합니다.
요약 (Summary)
다운로드 시스템은 게임 프레임워크에서 모든 다운로드 관련 작업을 위한 강력한 기반을 제공합니다.
•
원격 리소스를 효율적으로 가져올 수 있으며
•
다운로드 진행 상황과 완료 상태에 대한 상세한 피드백을 제공합니다.
•
이벤트 기반 구조로, 다른 시스템과 쉽게 통합 가능하며
•
패치, 업데이트, 리소스 다운로드까지 폭넓게 활용됩니다.