Network and IO (네트워크 및 입출력)

Abstract

게임이 인터넷과 주고받는 방식 세 가지 — 한 번 묻고 답 받기(WebRequest), 파일 받아 저장하기(Download), 연결을 유지하며 계속 주고받기(Network) — 를 한 페이지에서 소개합니다. 셋은 용도가 다르지만 뼈대가 같습니다: 요청을 넣으면 번호가 돌아오고, 정해진 수의 일꾼이 순서대로 처리하며, 결과는 이벤트로 옵니다.

셋 중 무엇이 필요한가

graph TD
    Q1{"서버와 무엇을 하나?"}
    Q1 -- "API 를 부르고 응답을 받는다<br>(로그인, 랭킹, 상점)" --> W["WebRequest"]
    Q1 -- "큰 파일을 받아 디스크에 둔다" --> D["Download"]
    Q1 -- "접속을 유지하며 실시간으로 주고받는다" --> Q2{"지연에 얼마나 민감한가?"}
    Q2 -- "턴제, 채팅, MMO 정도" --> N["Network (TCP)"]
    Q2 -- "FPS, 격투, 레이싱" --> X["이 프레임워크 밖의 UDP 솔루션"]

Mermaid

복사

대부분의 싱글플레이 게임은 WebRequest 하나로 끝납니다. Download 는 추가 콘텐츠가, Network 는 자체 실시간 서버가 있을 때만 필요합니다.

세 모듈의 공통 사용법

	WebRequest	Download	Network
시작	AddWebRequest(uri)	AddDownload(저장 경로, uri)	CreateNetworkChannel → Connect
돌아오는 것	요청 번호	요청 번호	채널 객체
동시 처리 수	에이전트 수 (기본 1)	에이전트 수 (기본 3)	채널마다 연결 하나
성공 이벤트	WebRequestSuccessEventArgs	DownloadSuccessEventArgs	NetworkConnectedEventArgs • 패킷 핸들러
취소	RemoveWebRequest(id)	RemoveDownload(id)	channel.Close()
게임 코드가 채워야 할 것	없음	없음	INetworkChannelHelper 구현 필수

앞의 둘은 프레임워크가 다 해 주므로 바로 쓸 수 있고, Network 만 패킷 형식을 정하는 헬퍼를 직접 만들어야 합니다.

ToyboxNightmare 에서는

세 모듈 모두 쓰지 않습니다. 오프라인 싱글플레이 게임입니다. 온라인 기능을 붙인다면 가장 자연스러운 첫걸음은 게임오버 시 최고 점수를 WebRequest 로 올리는 것이고, 그 예제 코드는 Unity 쪽 Networking and I/O (네트워킹 & 입출력) 페이지에 있습니다.

본문을 읽을 때 주의할 점

•

본문 예제의 webRequestManager.WebRequestSuccess += ... 는 코어의 C# 이벤트입니다. 게임 코드에서는 GameEntry.GetComponent<EventComponent>().Subscribe(WebRequestSuccessEventArgs.EventId, handler) 로 받습니다.

•

이벤트는 전역이라 다른 코드가 넣은 요청의 결과도 같이 들어옵니다. Add… 가 돌려준 번호와 SerialId 를 비교해 자기 것만 처리합니다.

•

Network 의 재연결은 자동이 아닙니다. 본문에 "자동으로 … 재연결"이라고 적혀 있던 문장을 고쳤습니다.

•

WebRequest 는 GET 과 POST 만 지원합니다(postData 를 주면 POST, 없으면 GET). 요청 헤더를 붙이는 API 도 없습니다. PUT / DELETE 나 인증 헤더가 필요하면 WebRequestAgentHelperBase 를 상속한 헬퍼를 만들어 userData 로 넘긴 정보를 읽어 처리하게 합니다.

•

세 모듈 모두 "비동기"이지만 메인 스레드의 Update 에서 조금씩 진행됩니다. 별도 스레드가 아닙니다(Network 의 소켓 수신만 예외적으로 .NET 의 비동기 소켓 콜백을 씁니다).

Network and IO (네트워크 및 입출력)

소개

Network 및 IO 시스템은 게임 애플리케이션이 네트워크 연결, 파일 다운로드, 웹 요청 등을 수행할 수 있도록 지원합니다.

이는 온라인 기능 구현, 게임 콘텐츠 업데이트, 원격 서버와의 데이터 교환을 위해 필수적입니다.

개요

GameFramework의 Network 및 IO 시스템은 크게 세 가지 컴포넌트로 이루어져 있습니다:

Network System: 패킷 기반 TCP 소켓 통신 관리

Download System: 파일 다운로드 및 진행 상황 추적, 이어받기 지원

Web Request System: HTTP 요청/응답 관리 (가벼운 서버 통신용)

각 시스템은 공통적으로 다음과 같은 아키텍처 패턴을 따릅니다:

•

중앙 Manager 클래스 (GameFrameworkModule 구현)

•

동시 작업 처리를 위한 Agent/Channel 풀

•

플랫폼별 구현을 위한 Helper 인터페이스

•

이벤트 기반 상태 변경 알림

Network System

네트워크 시스템은 TCP 소켓 기반 통신을 제공합니다.

여러 개의 독립적인 네트워크 채널, 하트비트 모니터링, 패킷 직렬화, 에러 처리 등을 지원합니다.

아키텍처

•

핵심 클래스: NetworkManager

•

여러 네트워크 채널을 관리 (각 채널은 소켓 연결 단위이며 이름으로 식별)

•

지원 서비스 타입:

◦

TCP: 일반 TCP 소켓 통신

◦

TCP with Sync Receive: 동기식 수신을 포함한 TCP

•

INetworkChannelHelper: 패킷 직렬화/역직렬화 및 하트비트 관리 등 플랫폼별 구현 제공

사용 흐름

네트워크 채널 생성 (고유 이름과 Helper 지정)

패킷 핸들러 등록

원격 서버 연결

패킷 송수신

필요 시 채널 닫기

하트비트 타이머와 에러 보고는 자동으로 처리합니다. 재연결은 자동이 아닙니다 — 연결이 끊기면 NetworkClosed 이벤트를 받아 게임 코드가 직접 Connect 를 다시 불러야 합니다.

Download System

다운로드 시스템은 파일 다운로드를 관리하며, 진행 상황 추적, 우선순위 지정, 에러 처리 등을 지원합니다.

아키텍처

•

핵심 클래스: DownloadManager

•

다운로드 작업(Task) 풀과 다운로드 속도 카운터 유지

•

개별 다운로드는 DownloadAgent가 담당하며, 플랫폼별 작업은 IDownloadAgentHelper가 구현

다운로드 과정

클라이언트 코드에서 다운로드 작업 추가 (경로 및 URI 지정)

매니저가 작업을 풀에 등록

사용 가능한 에이전트가 작업 시작, 파일 스트림 열기

헬퍼가 실제 다운로드 수행

데이터 수신 → 파일에 기록, 진행 상황 추적

이벤트 발생: 시작, 진행, 성공, 실패

주요 기능:

•

이어받기 지원 (부분 다운로드 재개)

•

다운로드 속도 추적 (시간 기반 카운터)

•

우선순위 부여 (다운로드 순서 제어)

•

태그 기반 다운로드 그룹화

•

버퍼 크기 설정 (디스크 기록 제어)

Web Request System

웹 요청 시스템은 서버와의 HTTP 통신을 처리합니다.

데이터 조회, 정보 전송 등 가벼운 네트워크 작업에 적합합니다.

아키텍처

•

핵심 클래스: WebRequestManager

•

요청을 처리하는 WebRequestAgent 풀 관리

•

플랫폼별 구현은 IWebRequestAgentHelper 제공

사용 예시

// GET 요청
int requestId = webRequestManager.AddWebRequest("https://example.com/api/data");

// POST 요청
byte[] postData = Encoding.UTF8.GetBytes("key=value");
int requestId = webRequestManager.AddWebRequest("https://example.com/api/submit", postData);

// 응답 이벤트 핸들링
webRequestManager.WebRequestSuccess += OnWebRequestSuccess;
webRequestManager.WebRequestFailure += OnWebRequestFailure;

복사

지원 기능:

•

GET / POST 요청

•

요청 태깅 (그룹 관리)

•

우선순위 제어

•

요청 타임아웃 관리

공통 패턴

Task Pool 패턴

모든 시스템은 작업 풀을 이용해 동시 작업을 관리:

•

작업 생성 → 큐잉(우선순위 기반) → Agent 할당 → 상태 추적

Agent-Helper 패턴

•

Manager: 전체 관리 및 고수준 작업 처리

•

Agent: 개별 작업 담당

•

Helper Interface: 플랫폼 독립적 계약 정의

•

Helper Implementation: 플랫폼별 구체 구현

→ 일관된 인터페이스, 플랫폼별 확장 용이, 테스트/모킹 가능

이벤트 기반 알림

모든 시스템은 이벤트로 상태를 알림:

•

시작(Start) 이벤트

•

진행(Update) 이벤트

•

성공(Success) 이벤트

•

실패(Failure) 이벤트

→ 클라이언트 코드는 구현에 강하게 결합되지 않고 상태에 반응 가능

요약

Network & IO 시스템은 네트워크 통신, 파일 다운로드, 웹 요청을 위한 종합적인 도구를 제공합니다.

일관된 패턴과 관심사의 분리를 통해 사용과 확장이 용이합니다.

시스템	주요 클래스	목적	핵심 기능
Network	NetworkManager	소켓 기반 통신	다중 채널, 패킷 직렬화, 하트비트
Download	DownloadManager	파일 다운로드	이어받기, 속도 추적, 우선순위
Web Request	WebRequestManager	HTTP 요청/응답 관리	GET/POST, 타임아웃, 태깅

이 시스템들은 GameFramework 기반 게임에서 온라인 플레이, 콘텐츠 업데이트, 서버 통신의 기초를 이룹니다.

Network and IO (네트워크 및 입출력)

Abstract

Network and IO (네트워크 및 입출력)

관련 소스 파일

소개

개요

Network System

아키텍처

사용 흐름

Download System

아키텍처

다운로드 과정

Web Request System

아키텍처

사용 예시

공통 패턴

Task Pool 패턴

Agent-Helper 패턴

이벤트 기반 알림

요약