에픽은 하나의 SDK를 통해 개발자와 플레이어 모두를 위한 사용자 친화적 생태계를 구축하도록 지원합니다. SDK는 크리에이터와 개발자가 어떤 방식으로 게임을 제작 및 퍼블리싱해도 유용하게 활용할 수 있습니다. 그러면 플레이어는 이러한 게임을 여러 플랫폼의 친구들과 동일한 퀄리티의 경험으로 플레이할 수 있습니다. 에픽의 사명은 어떤 엔진과 스토어에서든 통용되고 모든 주요 플랫폼과 통합되는 SDK를 설계하는 것입니다.
SDK 기초
에픽 온라인 서비스(EOS) SDK는 C와 C# 래퍼 두 가지로 제공됩니다.
EOS SDK 인터페이스를 C로 작성해 안정적인 애플리케이션 바이너리 인터페이스(ABI)를 제공하도록 했습니다. 따라서 컴파일러의 선택, 구현, 호출 규칙, 데이터 크기, 메모리 정렬에 관계없이 통합되어 기능합니다.
이 규칙을 따르면 SDK 코드를 게임 클라이언트와 따로 패치할 수 있습니다. 애플리케이션을 다시 컴파일하지 않고 수정 사항과 업데이트를 배포하는 것은 지속적인 SDK 유지 관리에 중요합니다. 마지막으로 C에 초점을 맞추면 공개 API를 더욱 신중히 공개해야 합니다.
게임 클라이언트를 실행하는 플랫폼에 따라 다음과 같은 다양한 SDK 다운로드 유형을 사용할 수 있습니다.
- Windows, macOS, Linux - C EOS SDK 및 C# EOS SDK
- 모바일 - iOS용 EOS SDK, Android용 EOS SDK
- 콘솔 - C 및 C# 게임 콘솔용 EOS SDK를 다운로드할 수 있습니다.
콘솔용 SDK는 에픽게임즈와 플랫폼 저작권자로부터 승인받은 개발자만 다운로드할 수 있습니다.
플랫폼 저작권자는 다음과 같습니다. Microsoft(Xbox One, Xbox Series X), Sony(PlayStation 4, PlayStation 5), Nintendo(Switch).
콘솔용 SDK 다운로드 액세스 받기 및 관련 문서:- 데브 포털(dev.epicgames.com/dev-portal)에서 플랫폼 저작권자로부터 콘솔 개발자 액세스를 신청하기 위한 지침을 확인하세요.
- 플랫폼 저작권자로부터 승인받으면 eoshelp.epicgames.com에서 에픽 온라인 서비스를 위한 콘솔 개발자 요청 양식을 사용하여 에픽게임즈에 승인을 요청할 수 있습니다.
출시 버전 관리
버전 관리를 사용하면 API가 변경되더라도 이전 버전 SDK를 사용하는 게임과 하위 호환이 가능합니다. 모든 인터페이스, 함수, 데이터 유형에는 각각의 버전이 있습니다.
새로운 SDK가 출시되면 SDK가 이전 버전을 인식하고 지원하며 데이터와 함수 호출에 적절히 반응합니다. 여기에는 내부적으로 함수의 원본 버전을 호출하거나, 원본 입력 구조를 새로운 양식으로 이주하거나 가능한 경우 적절한 디폴트를 설정하는 작업이 포함됩니다.
따라서 SDK를 사용하는 오래된 게임이더라도 EOS와의 호환성을 목적으로 업데이트를 릴리스할 필요가 없습니다.
인터페이스 핸들
모듈형과 특정 서비스 인터페이스 그룹 지원 기능을 통틀어 칭하는 말입니다. 예를 들어 로비 인터페이스는 제품의 로비 생성 및 인터랙션을 처리하며, 친구 인터페이스는 친구 목록 기능을 관리합니다.
EOS SDK는 플랫폼 인터페이스가 제공하는 불투명한 핸들을 통해 인터페이스를 노출합니다. 인터페이스 핸들의 수명은 플랫폼 인터페이스와 같으며, 해당 인터페이스를 사용하는 모든 API 함수의 첫 파라미터로 필요합니다.
명명 규칙
모든 EOS SDK 인터페이스는 일관된 명명 규칙을 사용하여 활용법과 의도를 전달합니다.
| 동사 | 의미 |
|---|---|
| Create | 메모리를 할당하는 함수이며, 보통 Release 함수와 한 쌍입니다. |
| Copy | Query 함수에 대한 이전 호출로부터 캐시된 데이터를 가져오며, 보통 Release 함수와 한 쌍입니다. |
| Release | 메모리를 해제하는 함수입니다. Create 또는 Copy 함수와 대응됩니다. |
| Query | 지정되지 않은 기간 동안 백엔드 서비스와 비동기적으로 상호작용합니다. 연결 상황에 따라 호출이 스로틀 또는 재시도될 수 있습니다. |
| Get | 캐시 값이 구조체를 필요로 하지 않는 단순 값인 경우에 사용됩니다. 버퍼가 필요한 스트링을 위한 Get 을 포함합니다. |
함수 시그니처
EOS SDK의 모든 함수는 유사하고 일정한 시그니처를 갖습니다.
- 첫 파라미터는 항상 관련 인터페이스의 핸들입니다.
- C#의 경우 핸들 파라미터를 전달할 필요가 없습니다.
- 함수의 모든 파라미터를 요약하고 API 버전 관리 정보를 포함하는 'options(옵션)' 데이터 구조가 붙습니다.
- 마지막으로 비동기 함수에는 특정 애플리케이션용 콜백 함수가 들어 있으며 사용자 정의 컨텍스트 정보를 추가로 받아 콜백 함수를 처리할 수 있습니다. 이 콜백 함수는 비동기 작업의 성공 여부와 관계없이 항상 실행되며, 연결 문제로 딜레이가 발생할 때도 실행될 수 있습니다.
오류 처리
EOS C SDK 함수의 오류 코드는 EOS_EResult 타입을 사용합니다. 이 유형에는 일반 오류와 단일 인터페이스별 오류가 포함됩니다. 예를 들어 EOS_Success 값이 있는 열거형 타입 EOS_EResult 는 EOS_EResult::EOS_Success 로 나타납니다.
C#의 경우 오류 코드가 약간 다르며, Result 타입에 일반 오류와 인터페이스별 오류가 포함됩니다. C SDK 예시와 비교하면, Success 값이 있는 열거형 타입 Result 는 Result.Success 로 나타납니다.
일반 오류는 EOS_<ErrorCode> 양식이며, 특정 인터페이스의 오류 코드는 EOS_<Interface>_<ErrorCode> 양식으로 나타납니다. 예를 들면, 다음과 같습니다.
| 오류 코드 | 의미 |
|---|---|
EOS_InvalidParameters | 설정되지 않았거나 유효하지 않은 입력 파라미터 하나 이상이 함수로 전달되었습니다. |
EOS_InvalidUser | 사용자가 필요한 작업이지만, 유효하지 않은 사용자거나 사용자를 지정하지 않았습니다. |
EOS_MissingPermissions | 액세스 제한으로 백엔드 시스템이 요청을 거부했습니다. |
EOS_UnrecognizedResponse | SDK가 백엔드의 응답을 파싱하지 못했습니다. |
EOS_OperationWillRetry | 백엔드 연결에 문제가 발생했으며 SDK가 작업을 다시 시도합니다. |
EOS_IncompatibleVersion | 호출 코드가 전송한 API 버전 파라미터와 SDK 함수의 버전이 일치하지 않습니다. |
EOS_Auth_TokenInvalid | 인증 인터페이스에 해당하는 오류로, 로컬 인증 세션이 만료되었거나 유효하지 않게 되어 사용자가 다시 로그인해야 합니다. |
오류 코드에 관한 자세한 내용은 EOS SDK 오류 코드를 참고하세요.
스트링
스트링은 입력과 출력에 상관없이 UTF-8 양식이어야 합니다.
메모리 할당
SDK 함수가 콜백에 데이터 구조를 제공해야 할 경우, SDK는 데이터에 메모리를 할당하고 콜백 함수가 완료되는 즉시 메모리를 해제합니다. 해당 데이터의 사본을 캐시하려면 콜백 함수의 수명 중에 사본을 만들어야 합니다. 또한, 시스템에 커스텀 메모리 할당이 필요하다면 SDK 생성 시각에서 지정할 수 있습니다.
이름에 Get 동사가 있는 SDK 함수 역시 사용하는 메모리를 소유합니다. 콜백과 마찬가지로, 나중에 데이터에 액세스하려면 데이터 사본을 만들어야 합니다.
이름에 Copy 동사가 있는 SDK 함수는 예외입니다. 이러한 함수는 캐시된 데이터의 사본을 반환하며, 사본의 소유권은 호출자가 가지게 됩니다. C SDK는 절대로 사본을 해제하지 않기 때문에 사용자는 SDK를 종료하기 전에 반드시 대응하는 Release 함수를 호출해야 합니다. C# SDK는 복사된 구조체를 수동으로 해제하지 않아도 됩니다. 래퍼가 자동으로 처리하기 때문입니다.
서비스 사용 제한
모든 사용자에게 안정적이고 신뢰할 수 있는 생태계를 제공하기 위해 에픽 온라인 서비스(EOS)는 클라이언트 요청 속도 제한과 서비스 사용 할당량을 구현합니다. SDK API가 코드에 올바르게 통합되면 요청 제한과 사용 할당량에 도달할 일은 없습니다.
그러나 제한에 유의하고 SDK 로그 출력에 주의를 기울이세요. 내부 플레이 테스트 중에 오류로 보이는 모든 로그 출력을 확인하여 EOS 함수가 EOS_TooManyRequests 결과를 반환하거나 잘못된 사용 패턴을 경고하지 않는지 검증해야 합니다.
클라이언트 요청 스로틀링과 서비스 사용 할당량은 동시에 작동하여 개별 제품이 전체 EOS 생태계에 미치는 영향을 제한합니다.
요청 스로틀링
EOS SDK가 백엔드 서비스 호출이 너무 빠르게 오고 있다고 탐지하면, 로컬 클라이언트가 EOS_TooManyRequests 오류 코드를 표시하며 API 호출을 거절하여 자체적으로 스로틀링합니다.
백엔드 서비스에도 개별 클라이언트 또는 호스팅된 서버로부터 오는 요청이 최대 사용량 가이드라인을 초과하면 거절하는 유사한 기능이 있습니다. EOS SDK는 이를 EOS_TooManyRequests 로 보고하며, HTTP 데이터에 지정된 시간에 따라 내부적으로 재시도 로직을 처리합니다.
서비스 사용 할당량
각 서비스는 백엔드 서비스가 항상 제품에 즉시 사용 가능한 필요 용량을 확보할 수 있도록 디플로이 별로 사용 할당량을 적용합니다.
서비스 유형에 따라 할당량은 각 디플로이의 동시 온라인 사용자 수를 베이스로 고정되거나 조정됩니다. 모든 할당량은 EOS 생태계 내의 모든 제품에 동등하게 적용됩니다.
애플리케이션이 백엔드 서비스의 사용 할당량 제한에 도달하면, 서비스 사용 속도가 허용되는 수준으로 떨어지기 전까지 새 리소스 할당 요청이 실패합니다.
EOS 웹 API 레퍼런스
EOS API 레퍼런스 문서를 참고하세요.
참고: 에픽 온라인 서비스(EOS) SDK를 사용하려면 로컬 네트워크, 라우터, 방화벽에서 특정 호스트 주소에 액세스할 수 있도록 허용해야 합니다. 이러한 호스트 주소의 전체 목록은 방화벽 고려 사항 문서를 참조하세요.