Game Engine on Game Server Services | Docs

Game Engine

Mon, 01 Jan 0001 00:00:00 +0000

SDK 초기화

GS2 이용을 시작하려면 먼저 GS2-SDK의 초기화 처리를 수행합니다. Gs2Client.Create를 호출함으로써 GS2의 클라이언트 인스턴스인 Gs2Domain을 얻을 수 있습니다.

초기화에 필요한 파라미터는 다음과 같습니다.

파라미터

인자명	타입	설명
credential	BasicGs2Credential	크리덴셜 정보
region	Region	접속 대상 GS2 리전

BasicGs2Credential

“클라이언트ID"와 “클라이언트시크릿"을 지정합니다. 이 값들은 GS2-Identifier에서 관리하고 있습니다.

Region

GS2의 데이터센터를 지정합니다. 지정 가능한 값에 대해서는 리전을 참조해 주십시오.

구현 예제

 var gs2 = await Gs2.Unity.Core.Gs2Client.CreateAsync(
 new Gs2.Core.Model.BasicGs2Credential(
 "your client id",
 "your client secret"
 ),
 Gs2.Core.Model.Region.ApNortheast1
 );

 var future = Gs2.Unity.Core.Gs2Client.CreateFuture(
 new Gs2.Core.Model.BasicGs2Credential(
 "your client id",
 "your client secret"
 ),
 Gs2.Core.Model.Region.ApNortheast1
 );
 yield return future;
 if (future.Error != null) {
 throw future.Error;
 }
 var gs2 = future.Result;

 const auto future = Gs2::UE5::Core::FGs2Client::Create(
 MakeShared<Gs2::Core::Model::FBasicGs2Credential>(
 "your client id",
 "your client secret"
 ),
 Gs2::Core::Model::ApNorthEast1
 );
 future->StartSynchronousTask();
 if (future->GetTask().IsError())
 {
 UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(future->GetTask().Error()->String()));
 return future->GetTask().Error();
 }
 const auto Gs2 = future->GetTask().Result();

카오스 모드

카오스 모드를 적용한 SDK 초기화 처리를 호출함으로써 API 요청을 일정한 확률로 실패시킬 수 있습니다. 카오스 모드를 활성화한 클라이언트를 사용하여 개발을 진행함으로써 에러 핸들링을 더욱 견고하게 만들 수 있습니다.

Game Engine

Mon, 01 Jan 0001 00:00:00 +0000

트랜잭션이란

GS2에서의 트랜잭션 처리란, “소비 액션"과 “입수 액션"으로 정의된 리소스 교환 처리를 실행하는 덩어리를 가리킵니다. 트랜잭션을 발행하는 API에는 GS2-Exchange의 교환 실행 함수(Exchange), GS2-Showcase의 상품 구매 함수(Buy), GS2-Quest의 퀘스트 시작 함수(Start)와 같은 것들이 있습니다.

“소비 액션"은 플레이어에게 불리하게 작용하는 사용자 데이터 조작을, 반대로 “입수 액션"은 플레이어에게 이득이 되는 사용자 데이터 조작을 가리킵니다.

구체적으로 GS2-Inventory라면 아이템의 소비가 “소비 액션”, 아이템의 입수가 “입수 액션"이 됩니다. 조금 색다른 예를 들면, GS2-Inbox의 메시지 개봉 플래그를 세우는 조작이 “소비 액션”, 메시지에 첨부된 아이템을 수령하는 것이 “입수 액션"이 됩니다. GS2에서는 사용자 데이터를 다시 쓰는 트랜잭션을 발행하고 실행하는 것을 반복함으로써 게임 사이클을 실현한다고 이해하십시오.

GS2 이용 시작

Mon, 01 Jan 0001 00:00:00 +0000

SDK

Game Engine

Game Server Services는 주요 게임 엔진에서 이용할 수 있는 SDK를 제공합니다.
게임 엔진용 SDK는 게임 내에서 이용하는 것에 초점을 맞춰, 일반 SDK보다 고수준의 API 형태로 제공됩니다.

GS2 SDK for Unity

본 SDK는 Apache License 2.0으로 제공됩니다.
프로그램 어딘가에 Apache License 2.0으로 제공되는 라이브러리를 사용하고 있음을 명시해야 합니다.

샘플 코드 전문

Mon, 01 Jan 0001 00:00:00 +0000

using System.Collections;
using Gs2.Core.Model;
using Gs2.Unity.Core;
using Gs2.Unity.Gs2Account.Model;
using Gs2.Unity.Util;
using UnityEngine;

 public class Tutorial : MonoBehaviour
 {
 IEnumerator Start()
 {
 // Setup variables

 var clientId = "YourClientId";
 var clientSecret = "YourClientSecret";
 var accountNamespaceName = "game-0001";

 // Initialize GS2 SDK
 Gs2Domain gs2;
 {
 var future = Gs2Client.CreateFuture(
 new BasicGs2Credential(
 clientId,
 clientSecret
 ),
 Region.ApNortheast1
 );
 yield return future;
 if (future.Error != null) {
 throw future.Error;
 }
 gs2 = future.Result;
 }

 // define GS2-Account namespace
 var gs2Account = gs2.Account.Namespace(
 accountNamespaceName
 );

 // Create an anonymous account
 EzAccount account;
 {
 Debug.Log("Create an anonymous account");
 var future = gs2Account.CreateFuture();
 yield return future;
 if (future.Error != null) {
 throw future.Error;
 }
 var future2 = future.Result.ModelFuture();
 yield return future2;
 if (future2.Error != null) {
 throw future2.Error;
 }
 account = future2.Result;
 }

 // Dump anonymous account

 Debug.Log($"UserId: {account.UserId}");
 Debug.Log($"Password: {account.Password}");

 // Log-in created anonymous account
 GameSession gameSession;
 {
 var future = gs2.LoginFuture(
 new Gs2AccountAuthenticator(
 accountSetting: new AccountSetting {
 accountNamespaceName = accountNamespaceName,
 }
 ),
 account.UserId,
 account.Password
 );
 yield return future;
 if (future.Error != null) {
 throw future.Error;
 }
 gameSession = future.Result;
 }

 // Load TakeOver settings
 {
 var it = gs2Account.Me(
 gameSession
 ).TakeOvers();
 while (it.HasNext()) {
 yield return it.Next();
 if (it.Error != null)
 {
 throw it.Error;
 }
 if (it.Current != null)
 {
 Debug.Log($"Type: {it.Current.Type}");
 Debug.Log($"Identifier: {it.Current.UserIdentifier}");
 }
 }
 }

 // Finalize GS2-SDK
 {
 var future = gs2.DisconnectFuture();
 yield return future;
 if (future.Error != null) {
 throw future.Error;
 }
 }
 }
 }

 // Gs2Tutorial.cpp

 #include "Sample/Gs2Tutorial.h"

 #include "Core/Gs2Domain.h"
 #include "Util/Gs2AccountAuthenticator.h"

 DEFINE_LOG_CATEGORY(GameLog);

 class EZGS2_API FSampleTask final : public Gs2::Core::Util::TGs2Future<void*>
 {
 public:
 virtual ~FSampleTask() override = default;

 virtual Gs2::Core::Model::FGs2ErrorPtr Action(const TSharedPtr<TSharedPtr<void*>> Result) override
 {
 // Setup variables

 const auto ClientId = "YourClientId";
 const auto ClientSecret = "YourClientSecret";
 const auto AccountNamespaceName = "game-0001";

 // Create GS2 client

 const auto InitializeFuture = Gs2::UE5::Core::FGs2Client::Create(
 MakeShared<Gs2::Core::Model::FBasicGs2Credential>(
 ClientId,
 ClientSecret
 ),
 Gs2::Core::Model::ApNorthEast1
 );
 InitializeFuture->StartSynchronousTask();
 if (InitializeFuture->GetTask().IsError())
 {
 UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(InitializeFuture->GetTask().Error()->String()));
 return InitializeFuture->GetTask().Error();
 }
 const auto Gs2 = InitializeFuture->GetTask().Result();

 // Create an anonymous account

 UE_LOG(GameLog, Display, TEXT("Create anonymous account"));

 const auto CreateFuture = Gs2->Account->Namespace(
 AccountNamespaceName
 )->Create();
 CreateFuture->StartSynchronousTask();
 if (CreateFuture->GetTask().IsError())
 {
 UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(CreateFuture->GetTask().Error()->String()));
 return CreateFuture->GetTask().Error();
 }

 // Load created account

 const auto LoadFuture = CreateFuture->GetTask().Result()->Model();
 LoadFuture->StartSynchronousTask();
 if (LoadFuture->GetTask().IsError())
 {
 UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(LoadFuture->GetTask().Error()->String()));
 return LoadFuture->GetTask().Error();
 }
 const auto Account = LoadFuture->GetTask().Result();

 // Dump anonymous account

 UE_LOG(GameLog, Display, TEXT("UserId: %s"), ToCStr(*Account->GetUserId()));
 UE_LOG(GameLog, Display, TEXT("Password: %s"), ToCStr(*Account->GetPassword()));

 // Log-in created anonymous account

 const auto LoginFuture = Gs2->Login(
 MakeShareable<Gs2::UE5::Util::IAuthenticator>(
 new Gs2::UE5::Util::FGs2AccountAuthenticator(
 MakeShared<Gs2::UE5::Util::FAccountSetting>(
 AccountNamespaceName
 )
 )
 ),
 *Account->GetUserId(),
 *Account->GetPassword()
 );
 LoginFuture->StartSynchronousTask();
 if (LoginFuture->GetTask().IsError())
 {
 UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(LoginFuture->GetTask().Error()->String()));
 return LoginFuture->GetTask().Error();
 }
 const auto GameSession = LoginFuture->GetTask().Result();

 // Load TakeOver settings

 const auto It = Gs2->Account->Namespace(
 AccountNamespaceName
 )->Me(
 GameSession
 )->TakeOvers();
 for (const auto TakeOver : *It)
 {
 UE_LOG(GameLog, Display, TEXT("Type: %d"), *TakeOver->GetType());
 UE_LOG(GameLog, Display, TEXT("Identifier: %s"), ToCStr(*TakeOver->GetUserIdentifier()));
 }

 // Finalize GS2-SDK

 const auto FinalizeFuture = Gs2->Disconnect();
 FinalizeFuture->StartSynchronousTask();
 if (FinalizeFuture->GetTask().IsError())
 {
 UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(FinalizeFuture->GetTask().Error()->String()));
 return FinalizeFuture->GetTask().Error();
 }

 return nullptr;
 }
 };

 AGs2Tutorial::AGs2Tutorial()
 {
 PrimaryActorTick.bCanEverTick = true;
 }

 void AGs2Tutorial::BeginPlay()
 {
 Super::BeginPlay();

 (new FAsyncTask<FSampleTask>())->StartBackgroundTask();
 }

 void AGs2Tutorial::Tick(float DeltaTime)
 {
 Super::Tick(DeltaTime);
 }

 // Gs2Tutorial.h

 #pragma once

 #include "CoreMinimal.h"
 #include "GameFramework/Actor.h"
 #include "Gs2Tutorial.generated.h"

 DECLARE_LOG_CATEGORY_EXTERN(GameLog, Log, All);

 UCLASS()
 class EZGS2_API AGs2Tutorial : public AActor
 {
 GENERATED_BODY()

 public:
 AGs2Tutorial();

 protected:
 virtual void BeginPlay() override;

 public:
 virtual void Tick(float DeltaTime) override;
 };

extends Node


func _ready() -> void:
 # Setup variables
 var client_id = "YourClientId"
 var client_secret = "YourClientSecret"
 var account_namespace_name = "game-0001"
 var account_encryption_key_id = "grn:gs2:{region}:{ownerId}:key:account-encryption-key-namespace:key:account-encryption-key"

 # Initialize GS2 SDK
 var credential = Gs2BasicCredential.new(client_id, client_secret)
 var connection = Gs2Connection.new(credential, Gs2Region.AP_NORTHEAST_1)
 var ez = Gs2EzDomain.new(connection)

 # Define the GS2-Account namespace
 var gs2_account = ez.account.namespace_(
 account_namespace_name
 )

 # Create an anonymous account
 var create_result = await gs2_account.create()
 if create_result.error != null:
 push_error(str(create_result.error))
 return

 # Load the created account
 var model_result = await create_result.result.model()
 if model_result.error != null:
 push_error(str(model_result.error))
 return
 var account = model_result.result

 # Dump the anonymous account
 print("UserId: ", account.user_id)
 print("Password: ", account.password)

 # Log in with the created anonymous account
 var authenticator = Gs2AccountAuthenticator.new(
 account_namespace_name,
 account_encryption_key_id
 )
 var game_session = Gs2GameSession.new(
 authenticator,
 connection,
 account.user_id,
 account.password
 )
 var login_result = await game_session.login()
 if login_result.error != null:
 push_error(str(login_result.error))
 return

 # Load TakeOver settings
 var load_result = await gs2_account.me(
 game_session
 ).take_overs().load()
 if load_result.error != null:
 push_error(str(load_result.error))
 return

 for take_over in load_result.result:
 print("Type: ", take_over.type)
 print("Identifier: ", take_over.user_identifier)

 # Finalize GS2 SDK
 connection.disconnect_session()

GS2-Account SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzAccount

게임 플레이어 계정

게임 플레이어를 식별하는 ID 정보 엔티티입니다.
게임 플레이어 계정은 익명 계정이며 사용자ID(UUID)와 비밀번호(무작위 32자 문자열)로 구성되므로, 게임 플레이어는 이메일 주소 등의 정보를 입력할 필요가 없습니다.

발급된 게임 플레이어 계정은 디바이스의 로컬 스토리지에 저장해 두고, 다음번 로그인부터 사용합니다.

	타입	필수	기본값	값 제한	설명
userId	string	✓	UUID	~ 128자	사용자ID
password	string	✓		~ 128자	비밀번호 계정의 보안을 확보하기 위한 비밀번호를 저장합니다. 비밀번호는 최대 128자 길이를 가지며, 계정 보호에 중요한 역할을 합니다.
createdAt	long	※	현재 시각		생성일시 UNIX 시간・밀리초 ※ 서버가 자동으로 설정

EzTakeOver

인계 정보

GS2-AdReward SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzPoint

광고를 시청함으로써 획득한 포인트

플레이어가 광고 시청을 통해 획득한 포인트의 합계를 나타내는 모델입니다.
플레이어는 광고를 시청할 때마다 포인트를 획득하며, 이 포인트는 보상 교환이나 게임 내 특전 구매 등에 사용할 수 있습니다.

	타입	활성화 조건	필수	기본값	값 제한	설명
point	long			0	0 ~ 9223372036854775805	포인트 보유 수 사용자가 보유하고 있는 포인트 수를 나타냅니다. 이 수치는 사용자가 광고를 시청함으로써 증가하고, 보상이나 특전과 교환함으로써 감소합니다.

메서드

getPoint

광고 시청으로 획득한 포인트의 현재값 조회

GS2-Auth SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzAccessToken

액세스 토큰

사용자 인증 후 발급되는 액세스 토큰을 관리하는 모델입니다.
액세스 토큰은 사용자가 서비스에 로그인되어 있는 동안 해당 세션의 신원을 증명하는 데 사용됩니다.
토큰에는 유효기간이 설정되어 있으며, 만료되면 재인증이 필요합니다.

	타입	필수	기본값	값 제한	설명
token	string	✓		~ 1024자	액세스 토큰 액세스를 인증하기 위한 토큰입니다. 이 토큰은 시스템에 의해 자동으로 생성되며, 사용자의 세션을 식별합니다.
userId	string	✓		~ 128자	사용자ID
expire	long		현재 시각으로부터 1시간 후의 절대 시각		유효기간 토큰의 유효기간을 나타내는 타임스탬프입니다. 이 시각에 도달하면 토큰은 무효화됩니다. UNIX 시간·밀리초

메서드

계정 인증 정보를 사용하여 GS2에 로그인

GS2-Buff SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzBuffEntryModel

버프 엔트리 모델

버프의 적용량은 버프 엔트리 모델로 관리하며, 동일한 대상에 대해 여러 버프 엔트리 모델을 연결할 수 있습니다.
버프 엔트리 모델의 적용 순서는 버프 엔트리 모델의 priority 로 관리하며, priority 값이 작을수록 우선순위가 높아집니다.

버프의 적용 방식은 3종류가 있으며 “Rate Add”, “Mul”, “Value Add"가 있습니다.
Rate Add 는 버프의 적용 레이트에 가산하는 명령이며, Mul 은 버프의 적용 레이트에 곱하는 명령입니다.
Value Add 는 버프 보정 계산 후의 값에 가산을 수행하는 명령입니다.
예를 들어 기본 레이트가 1.0 이고 Rate Add 0.2 를 설정하면 버프 적용 레이트는 1.2 가 됩니다.
Mul 0.5 를 설정하면 버프 적용 레이트는 현재 레이트의 0.5배가 됩니다.

GS2-Chat SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzRoom

룸

룸은 채팅 메시지를 전달할 수 있는 범위를 나타냅니다.
GS2-Chat의 룸에는 참가라는 개념이 없습니다.
따라서 메시지를 수신하려면 룸의 이름만 알고 있으면 되며, 룸에 참가하거나 멤버로 등록할 필요가 없습니다.

룸의 메시지를 열람할 수 있는 게임 플레이어를 제한하고 싶은 경우 두 가지 방법이 있습니다.
첫 번째는 룸에 비밀번호를 설정하는 것입니다.
두 번째는 룸에 설정 가능한 화이트리스트에 게임 플레이어의 사용자 ID를 설정하여 제한하는 것입니다.

비밀번호를 설정한 경우, 비밀번호를 모르면 게임 관리자라도 메시지를 가져올 수 없게 된다는 점에 주의하십시오.
이는 일본국 헌법에서 정한 통신의 비밀에 해당할 가능성이 있기 때문입니다.

GS2-Datastore SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzDataObject

데이터 오브젝트

데이터 오브젝트는 게임 플레이어가 업로드한 데이터입니다.
데이터는 세대 관리되며, 30일분의 과거 데이터도 보관됩니다.

데이터에는 접근 권한을 설정할 수 있습니다.
스코프에는 3종류가 있으며,

누구나 접근할 수 있는 public
지정한 사용자 ID의 게임 플레이어만 접근할 수 있는 protected
본인만 접근할 수 있는 private

가 있습니다.

타입 활성화 조건 필수 기본값 값 제한 설명

dataObjectId

string

※

~ 1024자

데이터 오브젝트 GRN

※ 서버가 자동으로 설정

name

string

✓

UUID

~ 128자

데이터 오브젝트의 이름

데이터 오브젝트를 식별하는 고유한 이름입니다. 기본적으로 UUID 형식으로 자동 생성됩니다. 네임스페이스 내에서 업로드된 데이터를 참조·관리하는 데 사용됩니다.

userId

string

✓

~ 128자

사용자ID

scope

문자열 열거형
enum {
  “public”,
  “protected”,
  “private”
}

“private”

파일 접근 권한

이 데이터 오브젝트에 접근할 수 있는 사용자를 제어합니다. public은 누구나 접근 가능, protected는 allowUserIds에 지정된 사용자 ID만 접근 가능, private은 오너 본인만 접근 가능합니다.

정의	설명
public	공개
protected	지정한 사용자에게만 공개
private	비공개

allowUserIds

List<string>

{scope} == “protected”

[]

0 ~ 100 items

공개할 사용자 ID 목록

스코프가 protected로 설정되어 있는 경우, 이 데이터 오브젝트에 접근할 수 있는 사용자를 지정합니다. 이 목록에 포함된 사용자 ID를 가진 사용자만 읽기 접근이 허용됩니다.

※ scope이(가) “protected” 이면 활성화

status

문자열 열거형
enum {
  “ACTIVE”,
  “UPLOADING”,
  “DELETED”
}

✓

상태

데이터 오브젝트의 현재 라이프사이클 상태입니다. ACTIVE는 데이터에 접근 가능함을 나타내고, UPLOADING은 새로운 버전이 업로드 중임을 나타내며, DELETED는 삭제 예정으로 표시된 상태임을 나타냅니다(실제 삭제는 30일 후에 이루어집니다).

정의	설명
ACTIVE	유효
UPLOADING	업로드 중
DELETED	삭제됨(삭제 처리로부터 30일 후에 실제로 삭제)

generation

string

~ 128자

데이터의 세대

업로드된 데이터의 현재 버전을 나타내는 식별자입니다. 데이터가 재업로드될 때마다 새로운 세대 ID가 할당됩니다.

createdAt

long

※

현재 시각

생성일시

UNIX 시간・밀리초
※ 서버가 자동으로 설정

updatedAt

long

※

현재 시각

최종 갱신일시

UNIX 시간・밀리초
※ 서버가 자동으로 설정

EzDataObjectHistory

데이터 오브젝트 이력

GS2-Dictionary SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzEntry

게임 플레이어가 획득한 엔트리

게임 플레이어가 수집한 도감 엔트리 1건을 나타냅니다. 각 엔트리는 EntryModel에 대응하며, 획득 일시를 기록합니다. 보유 상태는 ‘존재함(수집됨) / 존재하지 않음’의 2가지 값으로 관리되며, 수량의 개념은 없습니다.

	타입	필수	기본값	값 제한	설명
entryId	string	※		~ 1024자	엔트리 GRN ※ 서버가 자동으로 설정
userId	string			~ 128자	사용자ID
name	string	✓		~ 128자	엔트리 모델 이름 엔트리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
acquiredAt	long	※	현재 시각		획득 일시 이 엔트리가 게임 플레이어에 의해 처음 수집된 일시입니다. 등록 시 현재 시각이 자동으로 설정되며, 이후 변경할 수 없습니다.

EzLike

즐겨찾기로 등록한 엔트리

GS2-Distributor SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzStampSheetResult

트랜잭션 실행 결과(레거시)

서버사이드 자동 실행으로 처리된 트랜잭션의 실행 결과를 기록합니다.
각 단계의 요청 내용과 응답 결과를 포함합니다: 검증 액션(사전 조건 확인), 소비 액션, 입수 액션. 오류 감지 및 재시도 로직을 위해 HTTP 상태 코드도 추적합니다.

	타입	필수	기본값	값 제한	설명
transactionId	string	✓		36 ~ 36자	트랜잭션 ID 이 트랜잭션을 고유하게 식별하는 UUID입니다. 트랜잭션과 그 실행 결과, 그리고 연쇄되는 후속 트랜잭션의 연결에 사용됩니다.
taskRequests	List<EzConsumeAction>			0 ~ 100 items	소비 액션의 요청 내용 목록
sheetRequest	EzAcquireAction	✓			입수 액션의 요청 내용
taskResults	List<string>		[]	0 ~ 100 items	소비 액션의 실행 결과
sheetResult	string			~ 1048576자	입수 액션의 실행 결과 응답 내용

EzTransactionResult

트랜잭션 실행 결과

GS2-Enchant SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzBalanceParameterStatus

밸런스 파라미터 상태

사용자가 소유한 특정 리소스에 대해 추첨된 파라미터의 실제 값을 나타냅니다. 각 상태는 밸런스 파라미터 모델과 연결되며, 추첨 처리 후 각 파라미터 슬롯에 할당된 구체적인 값을 보유합니다.

	타입	필수	값 제한	설명
parameterName	string	✓	~ 128자	밸런스 파라미터 모델 이름 이 상태의 추첨 조건을 정의하는 밸런스 파라미터 모델의 이름입니다. 합계 값, 배분 방침, 사용 가능한 파라미터 슬롯을 지정하는 모델을 참조합니다.
propertyId	string	✓	~ 1024자	파라미터를 보유한 리소스의 프로퍼티 ID 이러한 밸런스 파라미터가 연결되어 있는 특정 게임 리소스(예: 무기 또는 장비 아이템)를 식별합니다. 일반적으로 GS2-Inventory의 아이템 등의 리소스를 프로퍼티 ID로 참조합니다.
parameterValues	List<EzBalanceParameterValue>	✓	1 ~ 10 items	밸런스 파라미터 값 리스트 추첨 처리 후 각 파라미터 슬롯에 할당된 구체적인 값입니다. 각 엔트리는 모델에서 정의된 파라미터 슬롯에 대응하며, 할당된 실제 수치를 보유합니다. 모든 값의 합계는 모델에서 지정된 합계 값과 같아집니다.

EzRarityParameterStatus

레어리티 파라미터의 상태

GS2-Enhance SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzProgress

강화 진행 상황

강화 시작 시 생성되며, 종료 시 삭제됩니다.

강화 도중에 앱을 종료한 경우에는 이 데이터가 남은 상태가 되며
엔티티가 보유한 진행 중인 강화 정보로부터 게임을 재개할 수 있습니다.

	타입	필수	기본값	값 제한	설명
name	string	✓	UUID	~ 36자	강화 진행 상황 ID 강화 진행 상황의 고유 ID를 보유합니다. ID는 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 강화 진행 상황을 식별하는 데 사용됩니다.
rateName	string	✓		~ 128자	강화 레이트 모델 이름 이 강화 조작의 파라미터를 정의하는 강화 레이트 모델의 이름입니다. 대상 인벤토리, 소재 인벤토리, 경험치 계층, 보너스 레이트를 지정하는 모델을 참조합니다.
propertyId	string	✓		~ 1024자	강화 대상의 프로퍼티 ID 강화되는 GS2-Inventory 아이템의 프로퍼티 ID입니다. 강화 완료 시 경험치를 받는 특정 아이템 인스턴스를 식별합니다.
experienceValue	long	✓		0 ~ 9223372036854775805	획득할 수 있는 경험치 소비한 소재로부터 산출된 기본 경험치입니다. 이 값은 각 소재의 메타데이터에 정의된 경험치에 소재 수량을 곱한 값의 합계로 결정됩니다.
rate	float	✓		0 ~ 100.0	경험치 배율 기본 경험치에 적용되는 보너스 배율입니다. 강화 레이트 모델의 보너스 레이트에서 가중치 추첨으로 결정됩니다. 1.0은 보너스 없음을, 1.0보다 큰 값은 “대성공” 보너스를 나타냅니다(예: 1.5로 경험치 150%).

EzRateModel

강화 레이트 모델

GS2-Exchange SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzAwait

교환 대기

보상을 받기 전에 실시간의 경과가 필요한 교환의 실행 상태를 나타냅니다. 플레이어가 await 타이밍 타입의 교환을 시작했을 때 생성되며, 보상을 사용할 수 있게 될 때까지의 대기 기간을 추적합니다. 대기 시간을 단축하거나 없애는 스킵 기능을 지원하며, 보상 취득 시의 기본 설정값을 저장합니다.

	타입	필수	기본값	값 제한	설명
userId	string	✓		~ 128자	사용자ID
rateName	string	✓		~ 128자	교환 레이트 모델 이름 교환 레이트 모델 종류 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
name	string	✓	UUID	~ 36자	교환 대기의 이름 교환 대기의 고유한 이름을 보유합니다. 이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 교환 대기를 식별하는 데 사용됩니다.
skipSeconds	int		0	0 ~ 2147483646	스킵 초수 대기 시간에서 차감하는 초수입니다. 스킵 초수가 적용되면 acquirableAt 타임스탬프가 이만큼 앞당겨집니다. 플레이어가 리소스를 지불하여 대기 시간을 단축하는 구조를 구현하기 위해 사용됩니다.
config	List<EzConfig>		[]	0 ~ 32 items	보상 취득 시 적용하는 기본 설정값 대기 완료 시 보상이 배포될 때 트랜잭션의 플레이스홀더 변수로 사용되는 키와 값의 쌍입니다. 이 값들은 교환 시작 시 설정되며, 획득 액션의 트랜잭션 파라미터에 적용됩니다.
exchangedAt	long				교환 시간 교환이 시작되어 대기가 생성된 타임스탬프입니다. 보상이 사용 가능해지는 시각을 계산하기 위한 기준 시각으로 사용됩니다(acquirableAt = exchangedAt + lockTime - skipSeconds).
acquirableAt	long				보상을 받을 수 있게 되는 시간 대기 기간이 만료되어 보상을 받을 수 있게 되는 타임스탬프입니다. exchangedAt + lockTime - skipSeconds로 계산됩니다. 현재 시각이 이 타임스탬프를 지나면 플레이어는 취득 API를 호출할 수 있게 됩니다.

EzRateModel

교환 레이트 모델

GS2-Experience SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzStatus

스테이터스

스테이터스란 프로퍼티ID마다 존재하는 엔티티로,
현재의 경험치와 랭크 캡 값을 보유합니다.

프로퍼티ID란 스테이터스 고유의 ID로, 개발자가 임의의 값을 설정할 수 있습니다.
GS2에서는 경험치를 보유한 GS2-Inventory의 아이템 세트GRN이나 GS2-Dictionary의 엔트리GRN 뒤에
경험치 모델이 되는 접미사를 추가한 값을 프로퍼티ID로 사용할 것을 권장합니다.

	타입	필수	기본값	값 제한	설명
experienceName	string	✓		~ 128자	경험치 모델 이름 이 스테이터스의 랭킹 규칙을 정의하는 경험치 모델의 이름입니다. 어떤 랭크업 임계값 테이블과 랭크 캡 설정이 적용되는지를 결정합니다.
propertyId	string	✓		~ 1024자	프로퍼티ID 사용자 스코프 내에서 이 스테이터스를 고유하게 식별하는 개발자 정의 식별자입니다. 경험치를 보유한 GS2-Inventory의 아이템 세트 GRN이나 GS2-Dictionary의 엔트리 GRN 끝에 경험치 모델의 접미사를 붙인 값을 사용할 것을 권장합니다.
experienceValue	long		0	0 ~ 9223372036854775805	누적 획득 경험치 이 스테이터스가 축적한 총 경험치입니다. 현재 랭크는 이 값으로부터 랭크업 임계값 테이블을 사용하여 산출됩니다. 현재 랭크 캡에 대응하는 임계값을 초과하여 경험치를 획득할 수 없습니다.
rankValue	long		0	0 ~ 9223372036854775805	현재 랭크 랭크업 임계값 테이블을 사용하여 누적 경험치로부터 산출되는 랭크(레벨)입니다. 0부터 시작하며 경험치 임계값을 초과할 때마다 증가합니다. 현재 랭크 캡 값을 초과할 수 없습니다.
rankCapValue	long	✓		0 ~ 9223372036854775805	현재 랭크 캡 이 스테이터스가 현재 도달할 수 있는 최대 랭크입니다. 초기값은 경험치 모델의 defaultRankCap으로 설정되며, 한계돌파 등의 랭크 캡 증가 조작을 통해 maxRankCap까지 끌어올릴 수 있습니다.
nextRankUpExperienceValue	long		0	0 ~ 9223372036854775805	다음 랭크업에 필요한 경험치량 다음 랭크에 도달하기 위해 필요한 누적 경험치의 임계값입니다. 스테이터스가 이미 랭크 캡에 도달한 경우 0을 반환합니다. 게임 UI에서 프로그레스 바나 남은 경험치를 표시하는 데 유용합니다.

EzExperienceModel

경험치 모델

GS2-Formation SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzMold

폼 저장 영역

게임 플레이어가 편성한 정보를 보유하는 엔티티입니다.
편성 정보(Form)는 폼 저장 영역(Mold)마다 여러 개 보유할 수 있으며, 몇 개까지 보유할 수 있는지에 대한 캐파시티를 게임 플레이어 × 폼 저장 영역마다 개별적으로 설정할 수 있습니다.

	타입	필수	값 제한	설명
name	string	✓	~ 128자	폼 저장 영역 모델의 이름 폼 저장 영역 모델 고유의 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
userId	string	✓	~ 128자	사용자ID
capacity	int	✓	0 ~ 2147483646	현재 캐파시티 이 저장 영역에서 이 플레이어가 현재 이용할 수 있는 폼 저장 슬롯 수입니다. 초기값은 저장 영역 모델의 initialMaxCapacity로 설정되며, 캐파시티 증가 조작을 통해 maxCapacity까지 확장할 수 있습니다.

EzForm

폼

GS2-Friend SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzProfile

프로필

프로필은 게임 플레이어에 관한 정보를 저장합니다.

프로필은 공개 범위별로 설정할 수 있으며, 3가지 종류가 있습니다.

friend 친구 관계가 성립된 상대방이 열람 가능한 내용
follow 팔로우하고 있는 상대방이 열람 가능한 내용
public 누구나 열람 가능한 내용

	타입	필수	값 제한	설명
userId	string	✓	~ 128자	사용자ID
publicProfile	string		~ 1024자	공개되는 프로필 관계와 상관없이 모든 플레이어에게 표시되는 프로필 정보입니다. 일반적으로 표시 이름, 아바타, 기타 공개 가능한 정보에 사용됩니다.
followerProfile	string		~ 1024자	팔로워에게 공개되는 프로필 이 사용자를 팔로우하고 있는 플레이어에게만 표시되는 프로필 정보입니다. 공개 프로필보다 상세한 정보(게임플레이 통계나 상태 메시지 등)를 포함할 수 있습니다.
friendProfile	string		~ 1024자	친구에게 공개되는 프로필 상호 친구 관계가 성립된 플레이어에게만 표시되는 프로필 정보입니다. 가장 프라이빗한 프로필 수준으로, 연락처나 개인 메시지 등 개인 정보를 공유하기에 적합합니다.

EzBlackList

블랙리스트

GS2-Gateway SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzWebSocketSession

WebSocketSession

WebSocket 세션은 GS2 서버와 클라이언트 간의 지속적인 연결로, 실시간 양방향 통신을 수행합니다.
서버에 대해 클라이언트 측에서 식별자로 사용자 ID를 등록합니다.

	타입	필수	값 제한	설명
connectionId	string	✓	~ 128자	커넥션 ID 이 WebSocket 접속에 할당된 고유 식별자입니다. 알림 송신 시 특정 클라이언트 접속을 식별하는 데 사용됩니다.
namespaceName	string	✓	~ 128자	네임스페이스 이름
userId	string	✓	~ 128자	사용자ID

메서드

setUserId

서버로부터의 푸시 알림을 수신하기 위해 플레이어의 접속을 등록한다

GS2-Grade SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzStatus

스테이터스

스테이터스란 프로퍼티 ID마다 존재하는 엔티티로,
현재 그레이드의 값을 보유합니다.

프로퍼티 ID란 스테이터스 고유의 ID로, 개발자가 임의의 값을 설정할 수 있습니다.
연동되는 GS2-Experience의 프로퍼티 ID와 완전히 일치하는 값을 사용할 것을 강력히 권장합니다.

	타입	필수	기본값	값 제한	설명
gradeName	string	✓		~ 128자	그레이드 모델 이름 이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다.
propertyId	string	✓		~ 1024자	프로퍼티 ID 이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다.
gradeValue	long		1	1 ~ 9223372036854775805	현재 그레이드 이 스테이터스의 현재 그레이드 값입니다. 연동되는 GS2-Experience 모델의 랭크 캡을 결정하기 위해 그레이드 모델의 그레이드 엔트리 배열의 인덱스로 사용됩니다. 이 값이 변경되면 관련된 경험치 스테이터스의 랭크 캡이 해당 그레이드 엔트리에서 정의된 값으로 자동 갱신됩니다.

EzGradeModel

그레이드 모델

GS2-Guild SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzGuild

길드

길드는 최대 5개의 속성을 가질 수 있으며, 길드 검색이나 길드 목록 표시 시 이용할 수 있습니다.

길드에는 참가 정책을 설정할 수 있으며, 자유 참가와 승인제를 선택할 수 있습니다.
자유 참가를 선택한 경우, 길드에 참가 요청을 하면 즉시 길드 멤버가 됩니다.
승인제를 선택한 경우, 길드에 참가 요청을 하면 길드 마스터 또는 길드 멤버가 승인할 때까지 길드 멤버가 되지 않습니다.

길드 멤버에게는 역할을 설정할 수 있으며, 길드 마스터, 길드 멤버에 더해 길드가 독자적으로 정의한 최대 10개의 커스텀 역할을 설정할 수 있습니다.
길드 멤버는 길드에 참가했을 때 기본으로 부여되는 역할을 설정할 수 있습니다.

GS2-Idle SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzStatus

스테이터스

처음으로 GetIdleStatus 를 호출했을 때 생성되며, 그 시점부터 방치 시간의 카운트가 시작됩니다.
방치 시간의 카운트는 보상을 받으면 리셋됩니다.

GS2-Schedule 의 이벤트가 연관되어 있는 경우, 이벤트 개최 전에는 Category 에 액세스할 수 없으며, 스테이터스를 생성할 수도 없습니다.
이벤트가 연관되어 있는 경우, 스테이터스는 이벤트의 반복 횟수를 보유합니다.
현재 이벤트ID와 스테이터스 생성 시의 이벤트ID가 일치하지 않는 경우, 현재 이벤트의 반복 횟수와 스테이터스가 보유한 반복 횟수가 일치하지 않는 경우, 또는 이벤트의 시작 시각보다 앞서 스테이터스가 생성된 경우, 대기 시간은 리셋됩니다.

GS2-Inbox SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzMessage

메시지

게임 플레이어마다 준비되는 메시지 박스에 전달된 메시지 데이터.

메시지에는 개봉 상태가 있으며, 개봉 시 실행할 입수 액션을 설정할 수 있습니다.
메시지에는 유효 기한을 설정할 수 있으며, 유효 기한이 지난 메시지는 미읽음 상태, 개봉 후 읽음 상태와 관계없이 자동으로 삭제됩니다.
첨부된 보상을 받지 않은 경우에도 삭제됩니다.

	타입	필수	기본값	값 제한	설명
messageId	string	※		~ 1024자	메시지 GRN ※ 서버가 자동으로 설정
name	string	✓	UUID	~ 36자	메시지 이름 메시지의 고유한 이름을 유지합니다. 이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 메시지를 식별하는 데 사용됩니다.
metadata	string	✓		~ 4096자	메타데이터 메시지의 제목, 본문, 발신자 정보, 표시 파라미터 등을 포함하는 JSON 문자열 등, 메시지의 내용을 나타내는 임의의 데이터입니다. GS2는 이 값을 해석하지 않으며, 메시지 UI 렌더링을 위해 게임 클라이언트에 그대로 전달됩니다. 최대 4096자입니다.
isRead	bool		false		읽음 상태 메시지가 사용자에 의해 개봉되었는지 여부를 나타냅니다. 메시지가 개봉되면 이 플래그가 true로 설정되고, readAcquireActions가 실행되어 첨부된 보상이 지급되며, readAt 타임스탬프가 기록됩니다. 네임스페이스에서 isAutomaticDeletingEnabled가 설정되어 있는 경우, 읽음 처리 후 메시지가 삭제됩니다.
readAcquireActions	List<EzAcquireAction>		[]	0 ~ 100 items	개봉 시 입수 액션 사용자가 이 메시지를 개봉했을 때 실행되는 입수 액션 목록입니다. 아이템, 화폐, 리소스 등의 보상을 메시지에 첨부하기 위해 사용됩니다. 여러 액션을 조합하여 서로 다른 종류의 보상을 동시에 지급할 수 있습니다. 메시지당 최대 100개의 액션입니다.
receivedAt	long	※	현재 시각		생성일시 UNIX 시간・밀리초 ※ 서버가 자동으로 설정
readAt	long		0		개봉 일시 UNIX 시간·밀리초
expiresAt	long				유효기간 일시 UNIX 시간・밀리초

EzConfig

컨피그 설정

GS2-Inventory SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzInventory

인벤토리

인벤토리는 게임 플레이어가 소유한 아이템을 보관하기 위한 가방과 같은 것입니다.
가방에는 용량이 있으며, 플레이어마다 용량을 확장할 수 있습니다.

	타입	필수	기본값	값 제한	설명
inventoryId	string	※		~ 1024자	인벤토리 GRN ※ 서버가 자동으로 설정
inventoryName	string	✓		~ 128자	인벤토리 모델 이름 이 인벤토리의 구조와 용량 설정을 정의하는 인벤토리 모델의 이름입니다. 사용자의 인벤토리 인스턴스를 모델 정의에 연결하여 사용 가능한 아이템의 종류와 용량 제한을 결정합니다.
currentInventoryCapacityUsage	int		0	0 ~ 2147483646	용량 사용량 아이템 세트에 의해 현재 사용되고 있는 인벤토리 슬롯의 수입니다. 새로운 아이템 스택이 추가될 때(예: allowMultipleStacks에 의해 새로운 슬롯이 생성될 때) 증가하고, 아이템 세트가 완전히 소비되거나 삭제될 때 감소합니다. currentInventoryMaxCapacity를 초과할 수 없습니다.
currentInventoryMaxCapacity	int	✓		1 ~ 2147483646	최대 용량 이 사용자가 사용할 수 있는 인벤토리 슬롯의 현재 최대 수입니다. 인벤토리 모델의 initialCapacity로 초기화되며, 입수 액션 또는 직접적인 API 호출을 통해 모델의 maxCapacity까지 확장할 수 있습니다.

EzItemSet

아이템 세트

GS2-JobQueue SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzJob

잡

잡 큐란 즉시 처리를 완료하지 않고 처리를 지연 실행하기 위한 구조입니다.
예를 들어 캐릭터를 입수했을 때 즉시 실행해야 하는 처리는 소지품에 캐릭터를 저장하는 것입니다.
반면, 즉시 처리하지 않아도 되는 처리로는 도감에 등록한다는 처리가 있습니다.

이처럼 즉시 처리할 필요가 없는 처리를 잡 큐를 경유하여 처리하도록 하면 장애에 강한 설계로 만들 수 있습니다.
왜냐하면 도감 서비스가 어떤 장애로 인해 정지되어 있더라도, 도감에 등록되지 않은 상태로 게임을 계속할 수 있기 때문입니다.
잡 큐에 쌓인 처리는 실패하더라도 장애가 해소된 후 재시도함으로써 결과적으로 올바른 상태로 만들 수 있습니다.

GS2-Limit SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzCounter

사용 횟수 제한의 현재 값

각 사용자의 사용 횟수 제한 모델에 속한 특정 카운터의 현재 사용 횟수를 추적합니다. 하나의 사용 횟수 제한 모델 아래에 여러 카운터를 만들 수 있습니다(예: 1회 한정 보상을 위해 퀘스트마다 하나의 카운터). 카운트 값은 카운트업 조작 시 지정되는 최대값과 비교되며, 사용 횟수 제한 모델의 리셋 일정에 따라 자동으로 0으로 리셋됩니다.

	타입	필수	기본값	값 제한	설명
counterId	string	※		~ 1024자	카운터 GRN ※ 서버가 자동으로 설정
limitName	string	✓		~ 128자	사용 횟수 제한 모델 이름 이 카운터가 속한 사용 횟수 제한 모델의 이름입니다. 이 카운터 값에 적용되는 리셋 일정(매일, 매주, 매월 등)을 결정합니다.
name	string	✓		~ 128자	카운터 이름 사용 횟수 제한 모델 내에서 이 카운터를 고유하게 식별하는 이름입니다. 동일한 사용 횟수 제한 모델을 서로 다른 이름의 여러 카운터로 공유할 수 있어, 개별 사용 횟수 제한 모델을 만들지 않고도 별도의 사용 횟수 추적(예: 퀘스트별 또는 상품별로 카운터 1개)이 가능합니다.
count	int		0	0 ~ 2147483646	카운트 값 이 카운터의 현재 사용 횟수입니다. countUp 조작으로 증가하며, 이때 지정된 최대값과 비교됩니다. 사용 횟수 제한 모델의 리셋 시점에 도달하면 자동으로 0으로 리셋됩니다.
createdAt	long	※	현재 시각		생성일시 UNIX 시간・밀리초 ※ 서버가 자동으로 설정
updatedAt	long	※	현재 시각		최종 갱신일시 UNIX 시간・밀리초 ※ 서버가 자동으로 설정

EzLimitModel

횟수 제한 모델

GS2-Lock SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzMutex

뮤텍스

GS2가 제공하는 뮤텍스는 재진입 가능한 락의 일종입니다.

잠금을 획득할 때 트랜잭션 ID를 지정하며, 동일한 트랜잭션 ID를 지정한 경우에만 다시 잠금을 획득할 수 있습니다.
참조 카운터를 가지므로, 해제할 때에는 동일한 횟수만큼 잠금 해제 처리가 필요합니다.

	타입	필수	기본값	값 제한	설명
mutexId	string	※		~ 1024자	뮤텍스 GRN ※ 서버가 자동으로 설정
propertyId	string	✓		~ 1024자	프로퍼티 ID 잠금 대상 리소스를 식별하기 위한 ID로, 어떤 리소스에 대한 잠금인지를 결정합니다. 여러 처리가 동일한 리소스에 대한 배타적 접근을 필요로 하는 경우, 동일한 프로퍼티 ID를 지정해야 합니다.
transactionId	string	✓		~ 256자	트랜잭션 ID 잠금을 획득하는 트랜잭션의 식별자입니다. 이 ID는 재진입 가능한 잠금을 구현하는 데 사용됩니다. 잠금 요청이 현재 잠금을 보유한 것과 동일한 트랜잭션 ID를 지정한 경우, 잠금은 재획득에 성공하며 참조 카운터가 증가합니다. 다른 트랜잭션 ID로의 잠금 요청은 잠금이 유지되는 동안 거부됩니다.
ttlAt	long		현재 시각으로부터 1시간 후의 절대 시각		유효기간 일시 UNIX 시간・밀리초

메서드

get

뮤텍스 상태 조회

GS2-Log SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzInGameLog

인게임 로그

게임 클라이언트 또는 서버 사이드 스크립트에서 전송되는 커스텀 로그 엔트리입니다. GS2 API 호출로 자동 생성되는 액세스 로그와 달리, 인게임 로그는 게임 개발자가 플레이어의 행동, 게임 상태 변화, 비즈니스 메트릭 등 게임 고유의 이벤트를 기록하기 위해 명시적으로 전송합니다.

	타입	필수	기본값	값 제한	설명
timestamp	long	✓			일시 인게임 로그가 전송된 일시입니다.
userId	string			~ 128자	사용자ID
tags	List<EzInGameLogTag>		[]	0 ~ 20 items	태그 필터링과 분류를 위해 로그 엔트리에 부여된 키-값 쌍입니다. 태그를 통해 인게임 로그의 효율적인 검색과 집계가 가능합니다(예: 이벤트 타입, 스테이지 ID, 아이템 카테고리).
payload	string	✓		~ 10485760자	페이로드 JSON 형식의 커스텀 로그 데이터입니다. 플레이어의 행동, 게임 상태, 비즈니스 메트릭 등 게임 고유의 임의의 정보를 포함할 수 있습니다. 최대 10MB까지 가능합니다.

EzInGameLogTag

게임 내 로그의 태그

GS2-LoginReward SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzReceiveStatus

수신 상태

사용자별·보너스 모델별 로그인 보너스의 수신 상태를 추적합니다.
각 항목이 해당 날짜의 보상을 수신했는지 여부를 나타내는 불리언 배열(receivedSteps)을 보유합니다.
또한 일별 수신 자격을 판정하기 위해 마지막으로 보너스를 수신한 시각(lastReceivedAt)을 기록합니다.
receivedSteps는 보너스 사이클이 재시작될 때(반복이 활성화된 스트리밍 모드 등) 초기화될 수 있습니다.

	타입	필수	기본값	값 제한	설명
bonusModelName	string	✓		~ 128자	보너스 모델 이름 이 수신 상태가 연결된 로그인 보너스 모델의 이름. 사용자의 수신 진행 상황을 특정 보너스 모델 정의와 연결하여, 어떤 보상 목록과 배포 규칙이 적용되는지를 결정합니다.
receivedSteps	List<bool>		[]	0 ~ 100 items	수신 스텝 보상 목록의 각 날짜에 대응하는 순서가 있는 불리언 배열. true는 사용자가 해당 날짜의 보상을 수신했음을 나타내고, false는 놓쳤거나 아직 수신하지 않았음을 나타냅니다. 배열의 인덱스는 관련된 BonusModel의 rewards 배열과 대응합니다. 스트리밍 모드에서 반복이 활성화된 경우, 사이클이 재시작될 때 이 배열은 초기화됩니다.
lastReceivedAt	long				마지막 수신 시각 사용자가 마지막으로 로그인 보너스를 수신한 시각의 타임스탬프. 보너스 모델에 정의된 리셋 시각을 기준으로, 사용자가 오늘의 보너스를 이미 수신했는지 여부를 판정하는 데 사용됩니다. 수신 상태가 초기화될 때(반복 모드에서의 사이클 재시작 시 등) 0으로 재설정됩니다.

EzBonusModel

로그인 보너스 모델

GS2-Lottery SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzProbability

배출 확률

특정 경품의 산출된 배출 확률을 나타냅니다. 확률은 배출 확률 테이블 내 전체 경품 가중치의 합에 대한 이 경품의 가중치로 계산됩니다. 박스 가챠의 경우, 경품이 박스에서 배출됨에 따라 확률이 동적으로 변화합니다.

	타입	활성화 조건	필수	기본값	값 제한	설명
prize	EzDrawnPrize		✓			경품 이 확률이 대응하는 경품으로, ID와 입수 액션을 포함합니다.
rate	float		✓		0 ~ 1.0	배출 확률 (0.0~1.0) 이 경품이 배출될 확률로, 0.0에서 1.0 사이의 값으로 표현됩니다. 이 경품의 가중치를 테이블 내 전체 경품 가중치의 합으로 나누어 산출됩니다.

EzDrawnPrize

배출된 경품

GS2-Matchmaking SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzGathering

개더링

매치메이킹에 의해 모인 게임 플레이어 그룹을 나타내는 엔티티입니다.
매치메이킹용 파라미터를 여러 개 가지고 있으며, 파라미터를 종합적으로 판단하여 플레이어를 그룹화합니다.
플레이어는 자신의 역할·속성값·거부 리스트(함께 플레이하고 싶지 않은 사용자)를 지정하여 개더링에 참가합니다.
참가 시에는 속성값 범위 조건, 역할의 정원, 화이트리스트 제한(allowUserIds)이 검증됩니다.
모든 역할 슬롯이 정원에 도달하면 개더링은 완성 상태가 되어 매치메이킹이 완료됩니다.
개더링 이름은 UUID 형식으로 자동 생성되며, 유효기간을 설정하여 자동 정리(클린업)하는 것도 가능합니다.

	타입	필수	기본값	값 제한	설명
gatheringId	string	※		~ 1024자	개더링 GRN ※ 서버가 자동으로 설정
name	string	✓	UUID	~ 128자	개더링 이름 개더링의 고유한 이름을 보유합니다. 이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 개더링을 식별하기 위해 사용됩니다.
attributeRanges	List<EzAttributeRange>		[]	0 ~ 5 items	모집 조건 이 개더링에 참가하기 위해 플레이어가 충족해야 하는 속성 범위 조건의 목록입니다. 각 항목은 속성 이름과 허용되는 최소값·최대값 범위를 지정합니다. 플레이어 자신의 속성값이 이 범위 내에 있지 않으면 참가할 수 없습니다. 최대 5건.
capacityOfRoles	List<EzCapacityOfRole>		[]	1 ~ 5 items	모집 슬롯 목록 이 개더링의 모집 슬롯을 정의합니다. 각 항목은 역할 이름, 그 별칭, 그리고 해당 역할에 참가 가능한 최대 인원수를 지정합니다. 모든 역할 슬롯이 정원에 도달하면 매치메이킹이 완료됩니다. 최소 1건, 최대 5건.
allowUserIds	List<string>		[]	0 ~ 100 items	참가 허용 사용자 ID 목록 이 게더링에 참가하는 것이 허용된 사용자 ID의 화이트리스트입니다. 지정한 경우, 목록에 포함된 사용자만 이 게더링의 매치메이킹에 참가할 수 있습니다. 친구 전용 매치메이킹이나 초대제 매치메이킹 시나리오에 유용합니다. 최대 100건.
metadata	string			~ 1024자	메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
expiresAt	long				게더링 유효 기간 이 게더링이 자동으로 만료되어 삭제되는 시각입니다. 이 시각까지 매치메이킹이 완료되지 않으면 게더링은 정리됩니다. 지정하지 않은 경우, 매치메이킹이 완료되거나 수동으로 삭제될 때까지 게더링이 유지됩니다.
createdAt	long	※	현재 시각		생성일시 UNIX 시간・밀리초 ※ 서버가 자동으로 설정
updatedAt	long	※	현재 시각		최종 갱신일시 UNIX 시간・밀리초 ※ 서버가 자동으로 설정

EzRating

레이팅

GS2-MegaField SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzSpatial

공간 정보

	타입	필수	값 제한	설명
userId	string	✓	~ 128자	사용자ID
areaModelName	string	✓	~ 128자	에어리어 이름
layerModelName	string	✓	~ 128자	레이어 이름
position	EzPosition	✓		좌표
vector	EzVector	✓		방향

EzAreaModel

에어리어는 공간을 분할하는 것으로, 같은 좌표라도 에어리어가 다르면 별도의 공간으로 취급할 수 있습니다.

GS2-Mission SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzComplete

미션 달성 상황

특정 미션 그룹에 대한 사용자의 미션 달성 상황과 보상 수령 상황을 추적합니다. 달성 완료된 태스크명과 보상 수령 완료된 태스크명을 각각 별도의 목록으로 관리하여, 달성된 태스크와 실제로 보상을 수령한 태스크를 구분합니다.

	타입	필수	기본값	값 제한	설명
missionGroupName	string	✓		~ 128자	미션 그룹명 이 달성 상황 레코드가 속한 미션 그룹의 이름입니다. 사용자별·미션 그룹별로 하나의 달성 상황 레코드가 존재합니다.
completedMissionTaskNames	List<string>		[]	0 ~ 1000 items	달성 완료된 태스크명 목록 사용자가 달성한(달성 조건을 충족한) 미션 태스크의 이름입니다. 카운터가 목표값에 도달하거나 검증 액션이 성공한 시점에 이 목록에 추가됩니다. 보상 수령 여부는 관계없습니다.
receivedMissionTaskNames	List<string>		[]	0 ~ 1000 items	보상 수령 완료된 태스크명 목록 사용자가 달성 보상을 이미 수령한 미션 태스크의 이름입니다. 보상을 받으려면 태스크가 달성 완료 목록에 포함되어 있어야 합니다.

EzCounter

카운터

GS2-Money SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzWallet

지갑

지갑 내 통화는 유료로 구매한 통화와 무료로 얻은 통화로 크게 나누어 관리됩니다.
유료로 구매한 통화는 다시 구매 시점의 단가별로 관리되어, 서비스가 종료되었을 때의 환불이나 자금결제법에 해당하는 잔액이 존재하는지를 집계할 수 있습니다.

지갑에는 슬롯이 있으며, 슬롯마다 서로 다른 잔액을 관리할 수 있습니다.
플랫폼 간에 잔액을 공유할 수 없는 경우에는 플랫폼마다 다른 슬롯을 사용함으로써 나누어 관리할 수 있습니다.
이때 무료로 얻은 통화는 모든 플랫폼에서 공통된 값을 사용할 수도 있습니다.

GS2-Money2 SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzWallet

지갑

GS2-News SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzNews

공지사항 게시글

Hugo 사이트 데이터로부터 생성된 개별 뉴스 게시글을 나타냅니다.
각 게시글은 섹션과 콘텐츠 경로에 속하며, 제목, 타임스탬프, Front Matter 메타데이터를 가집니다.
게시글은 필요에 따라 GS2-Schedule의 이벤트와 연결하여 표시 기간을 제어할 수 있습니다.
Front Matter에는 JSON 형식의 추가 메타데이터가 포함되며, 표시 순서를 제어하기 위한 선택적 weight 필드도 포함됩니다.

	타입	필수	값 제한	설명
section	string	✓	~ 1024자	섹션 이름 이 게시글이 속한 섹션(카테고리)이며, Hugo의 콘텐츠 디렉터리 구조에 대응합니다. 게시글을 표시용 논리 그룹으로 구성하는 데 사용됩니다.
content	string	✓	~ 1024자	콘텐츠 섹션 내에서 이 게시글의 콘텐츠 경로 식별자입니다. 섹션과 함께 Hugo 콘텐츠 구조 내에서 게시글의 위치를 고유하게 식별합니다.
title	string	✓	~ 1024자	게시글 제목 뉴스 게시글의 제목이며, 일반적으로 Hugo의 Front Matter에서 정의됩니다. 플레이어에게 게시글 목록을 표시할 때 제목으로 표시됩니다.
scheduleEventId	string		~ 1024자	GS2-Schedule 이벤트 GRN
timestamp	long	✓		타임스탬프 UNIX 시간(밀리초)
frontMatter	string	✓	~ 1024자	Front Matter 게시글에 연결된 JSON 형식의 메타데이터이며, 원래 Hugo 마크다운의 Front Matter에서 정의됩니다. weight(표시 순서 제어용), 태그, 카테고리 등 임의의 사용자 정의 속성 필드를 포함할 수 있습니다.

EzSetCookieRequestEntry

Cookie 설정 요청 엔트리

GS2-Quest SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzProgress

퀘스트 진행 상황

퀘스트 시작 시 생성되며, 종료 시 삭제됩니다.

인게임 도중 앱을 종료한 경우 이 데이터가 남은 상태가 되며
엔티티가 보유한 진행 중인 퀘스트 정보를 통해 게임을 재개할 수 있습니다.

	타입	필수	기본값	값 제한	설명
progressId	string	※		~ 1024자	퀘스트 진행 상황 GRN ※ 서버가 자동으로 설정
transactionId	string	✓	UUID	~ 36자	트랜잭션 ID 퀘스트 트랜잭션의 고유 식별자입니다. 퀘스트 진행 상황과 보상 배포를 관리하는 트랜잭션을 연결하는 데 사용됩니다.
questModelId	string	✓		~ 1024자	퀘스트 모델 GRN 현재 진행 중인 퀘스트 모델의 GRN입니다. 사용자가 플레이 중인 퀘스트를 식별하며, 퀘스트 도중 앱을 종료한 경우 게임 재개를 가능하게 합니다.
randomSeed	long	✓		0 ~ 9223372036854775805	난수 시드 퀘스트 시작 시 할당되는 난수 시드입니다. 이 퀘스트 시도에서 선택되는 콘텐츠 배리에이션(보상 세트)을 결정하는 데 사용되며, 재현 가능한 결과를 보장합니다.
metadata	string			~ 256자	메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
rewards	List<EzReward>		[]	0 ~ 1000 items	클리어 보상 목록 퀘스트 클리어 시 지급되는 보상의 목록입니다. 난수 시드로 선택된 콘텐츠 배리에이션에 기반하여 퀘스트 시작 시 결정됩니다.
failedRewards	List<EzReward>		[]	0 ~ 1000 items	실패 시 보상 목록 퀘스트 실패 시 지급되는 보상의 목록입니다. 퀘스트 시작 시 결정되며, 실패에 대한 위로 보상이나 비용 일부 반환으로 제공됩니다.

EzCompletedQuestList

클리어 완료 퀘스트 목록

GS2-Ranking SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzScore

스코어

게임 플레이어별·카테고리별로 등록된 스코어를 보유하는 엔티티입니다.
각 스코어 엔트리는 고유 ID로 식별되며, 카테고리 및 스코어 등록 사용자와 연결됩니다.
합산 모드에서는 새로운 스코어가 별도의 엔트리를 생성하는 대신 AddScore 조작을 통해 기존 합계에 가산됩니다.
카테고리의 최소값·최대값 범위를 벗어나는 스코어는 등록 시 거부됩니다.

	타입	필수	기본값	값 제한	설명
categoryName	string	✓		~ 128자	카테고리명
userId	string	✓		~ 128자	사용자ID
uniqueId	string	✓	UUID	~ 36자	고유 ID 이 스코어 엔트리를 고유하게 식별하는 UUID입니다. 생성 시 자동으로 생성됩니다. uniqueByUserId가 비활성화된 경우, 동일 사용자의 동일 카테고리 내 여러 스코어 엔트리를 구분하기 위해 사용됩니다.
scorerUserId	string	✓		~ 128자	사용자ID
score	long	✓		0 ~ 9223372036854775805	스코어 플레이어가 등록한 스코어 값입니다. 카테고리에 설정된 최소값·최대값 범위 내여야 합니다. 합산 모드에서는 AddScore 조작을 통해 이 값을 증가시킬 수 있습니다.
metadata	string			~ 512자	메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.

EzRanking

랭킹

GS2-Ranking2 SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzGlobalRankingData

글로벌 랭킹

특정 시즌의 글로벌 랭킹에서의 랭킹 엔트리를 나타냅니다. 사용자의 스코어, 0부터 시작하는 인덱스(정렬 위치), 1부터 시작하는 순위(동점을 고려)를 포함합니다. 순위는 인덱스 + 1로 계산됩니다.

	타입	필수	기본값	값 제한	설명
rankingName	string	✓		~ 128자	글로벌 랭킹 모델 이름 글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
season	long	✓		0 ~ 9223372036854775805	시즌 GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. 새로운 랭킹 기간마다 증가합니다.
userId	string	✓		~ 128자	사용자ID
index	int			0 ~ 2147483646	인덱스 랭킹 내 이 엔트리의 0부터 시작하는 고유한 정렬 위치입니다. 순위와 달리, 스코어가 동점이어도 인덱스는 항상 고유합니다. 인덱스 기반 보상 계산에 사용됩니다.
rank	int			0 ~ 2147483646	순위 1부터 시작하는 랭킹 순위입니다. 스코어가 같은 플레이어는 동일한 순위를 공유합니다. 인덱스 + 1로 계산됩니다. 순위 기반 보상 계산에 사용됩니다.
score	long	✓		0 ~ 9223372036854775805	스코어
metadata	string			~ 512자	메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
updatedAt	long	※	현재 시각		최종 갱신일시 UNIX 시간・밀리초 ※ 서버가 자동으로 설정

EzGlobalRankingReceivedReward

글로벌 랭킹 보상 수령 이력

GS2-Realtime SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzRoom

룸

멀티플레이어 대전에서 실시간 통신을 처리하기 위한 전용 게임 서버 인스턴스를 나타냅니다.
룸 생성은 비동기로 이루어지며, 요청 후 시스템이 서버를 프로비저닝하고 인스턴스 준비가 완료되면 IP 주소, 포트, 암호화 키가 할당됩니다.
클라이언트는 접속을 시도하기 전에 생성 완료 알림을 기다리거나 폴링해야 합니다.
암호화 키는 게임 클라이언트와 릴레이 서버 간의 안전한 통신 채널을 확립하는 데 사용됩니다.

	타입	필수	값 제한	설명
name	string	✓	~ 128자	룸 이름 룸 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
ipAddress	string		~ 128자	IP 주소 프로비저닝된 게임 서버의 IP 주소. 룸의 서버 인스턴스 준비가 완료된 후 시스템에 의해 자동으로 할당됩니다. 룸 생성 직후에는 이용할 수 없습니다. 최대 128자.
port	int		0 ~ 65535	대기 포트 프로비저닝된 게임 서버의 대기 포트 번호. 서버 인스턴스 준비가 완료된 후 IP 주소와 함께 자동으로 할당됩니다. 범위: 0~65535.
encryptionKey	string		~ 256자	암호화 키 게임 클라이언트와 릴레이 서버 간의 통신을 암호화하기 위한 키. 서버 인스턴스 준비가 완료된 후 IP 주소 및 포트와 함께 자동으로 할당됩니다. 클라이언트는 릴레이 서버를 통해 송수신하는 메시지의 암호화·복호화에 이 키를 사용해야 합니다. 최대 256자.

메서드

now

현재 서버 시각 취득

GS2-Schedule SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzTrigger

트리거

상대 이벤트 스케줄링의 기점을 정의하여 플레이어별 이벤트 기간을 구현합니다.
플레이어에게 트리거가 발동되면 유효 기간(expiresAt)이 설정됩니다.
“relative” 스케줄 타입으로 설정된 이벤트는 트리거를 이름으로 참조하며, 해당 플레이어의 이벤트 기간은 트리거가 발동된 시각부터 유효 기간까지 지속됩니다.
트리거는 갱신할 수 있으며, 유효 기간이 지나면 TTL에 의해 자동으로 정리됩니다.

	타입	필수	기본값	값 제한	설명
triggerId	string	※		~ 1024자	트리거 GRN ※ 서버가 자동으로 설정
name	string	✓		~ 128자	트리거 이름 트리거 고유 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
triggeredAt	long	※	현재 시각		트리거 발동 일시 이 트리거가 발동된 타임스탬프입니다. 상대 이벤트 스케줄링의 기준 시작점 역할을 합니다. 명시적으로 지정하지 않으면 현재 시각이 자동으로 설정됩니다. UNIX 시간(밀리초)으로 표현됩니다.
expiresAt	long	✓			유효 기간 이 트리거가 만료되어 상대 이벤트 기간이 종료되는 타임스탬프입니다. 이 시각 이후 트리거는 만료된 것으로 간주되며(IsExpire가 true를 반환), 해당 플레이어에 대한 관련 상대 이벤트는 더 이상 유효하지 않습니다. 트리거 데이터는 만료 후 DynamoDB TTL에 의해 자동으로 정리됩니다. UNIX 시간(밀리초)으로 표현됩니다.

EzEvent

이벤트

GS2-SeasonRating SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzBallot

투표용지

특정 매치 세션에 대해 각 플레이어에게 발급되는 투표권입니다.
대전 컨텍스트(시즌, 세션, 참가 인원 수)와 플레이어의 사용자 ID를 포함합니다.
투표용지는 서버에 의해 서명되어 플레이어에게 반환되며, 플레이어는 게임 결과를 기입하여 WrittenBallot으로 다시 제출합니다.
투표 집계 시, 모든 참가자의 투표용지를 다수결로 비교하여 결과 조작을 방지합니다.

	타입	필수	값 제한	설명
userId	string	✓	~ 128자	사용자ID
seasonName	string	✓	~ 128자	시즌 이름 이 대전의 레이팅 계산에 사용되는 시즌 모델의 이름. 이 대전에 적용되는 티어 구조와 포인트 변동 규칙을 정의하는 SeasonModel을 참조합니다.
sessionName	string	✓	~ 128자	세션 이름 이 투표용지가 속한 매치 세션의 이름. 동일한 세션 내의 모든 투표용지는 투표 프로세스에서 함께 집계됩니다.
numberOfPlayer	int	✓	2 ~ 10	참가 인원 수 이 대전의 총 참가자 수. 투표 완료 여부 판정에 사용됩니다. 결과 확정에는 전체 투표용지의 수집(또는 과반수 성립)이 필요합니다. 유효 범위: 2~10.

EzSeasonModel

시즌 모델

GS2-SerialKey SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzSerialKey

시리얼 코드

발급된 시리얼 코드는 한 번만 사용할 수 있습니다.
시리얼 코드는 “RPCLP-FP7N-NCDMJ-FLVA-IRI4"와 같은 형식으로 발급되며 데이터 길이는 변경할 수 없습니다.
시리얼 코드 내에는 캠페인 종류에 대한 정보도 포함되어 있으며, 시리얼 코드를 사용할 때는 네임스페이스만 지정하면 사용할 수 있습니다.

타입

활성화 조건

필수

기본값

값 제한

설명

campaignModelName

string

✓

~ 128자

캠페인 이름

이 시리얼 코드가 속한 캠페인 모델의 이름입니다. 캠페인 정보는 시리얼 코드 자체에 포함되어 있으므로 코드를 사용할 때는 네임스페이스만 지정하면 됩니다.

metadata

string

~ 2048자

메타데이터

메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.

code

string

✓

~ 48자

시리얼 코드

“XXXXX-XXXX-XXXXX-XXXX-XXXX” 형식의 시리얼 코드 문자열입니다. 각 코드는 고유하며 캠페인 식별 정보를 포함합니다. 코드의 형식과 데이터 길이는 고정되어 있어 변경할 수 없습니다.

status

문자열 열거형
enum {
  “ACTIVE”,
  “USED”,
  “INACTIVE”
}

“ACTIVE”

상태

이 시리얼 코드의 현재 사용 상태입니다. 사용자가 소비하면 ACTIVE에서 USED로 전환됩니다. 이중 사용을 방지하기 위해 낙관적 잠금(optimistic locking)으로 보호됩니다. INACTIVE 상태의 코드는 사용할 수 없습니다.

정의	설명
ACTIVE	사용 가능
USED	사용됨
INACTIVE	비활성(사용 불가)

EzCampaignModel

캠페인 모델

GS2-Showcase SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzShowcase

진열대

진열대에는 진열할 상품을 정의할 수 있습니다.
또한 진열대의 상품 판매 기간을 설정할 수 있습니다.

	타입	필수	기본값	값 제한	설명
name	string	✓		~ 128자	진열대 이름 진열대 고유의 이름. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
metadata	string			~ 2048자	메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
displayItems	List<EzDisplayItem>		[]	1 ~ 1000 items	진열할 상품 리스트 이 진열대에 진열되는 상품의 리스트입니다. 각 진열 상품은 단일 상품 또는 상품 그룹 중 하나입니다. 판매 기간 이벤트가 종료되었거나 유효하지 않은 상품은 진열대 조회 시 자동으로 필터링됩니다.
salesPeriodEventId	string			~ 1024자	진열대의 판매 기간을 설정한 GS2-Schedule 이벤트 GRN 이 진열대 전체의 판매 기간을 제어합니다. 지정한 경우, 연관된 GS2-Schedule 이벤트 기간 중에만 진열대를 이용할 수 있습니다. 이벤트가 유효하지 않은 경우, 진열대는 비어 있는 상태로 반환됩니다.

EzDisplayItem

진열 상품

GS2-SkillTree SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzStatus

스킬 트리 해방 상황

특정 플레이어와 프로퍼티에 대한 스킬 트리의 해방 상태를 추적하는 모델입니다.
해방(언락)된 노드명의 목록을 관리합니다. 노드는 해방(목록에 추가), 구속(목록에서 제거), 초기화(전체 삭제)할 수 있습니다.
이미 해방된 노드를 해방하려 하거나, 미해방 노드를 구속하려 하면 오류가 발생합니다.
사용자가 처음 접근했을 때 자동으로 생성됩니다.

	타입	필수	기본값	값 제한	설명
statusId	string	※		~ 1024자	상태 GRN ※ 서버가 자동으로 설정
userId	string	✓		~ 128자	사용자ID
releasedNodeNames	List<string>		[]	0 ~ 1000 items	해제된 노드 모델명 리스트 이 스킬트리에서 플레이어가 잠금 해제한 노드 모델명 리스트입니다. 해제(추가), 구속(삭제), 리셋(전체 초기화) 작업으로 갱신됩니다. 최대 1000건.

EzNodeModel

노드 모델

GS2-Stamina SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzStamina

스태미나

스태미나란 현실 시간의 경과에 따라 회복되는 포인트입니다.
일반적으로 이 스태미나를 소비해야 게임을 플레이할 수 있도록 함으로써, 플레이어의 하루 플레이 횟수를 제한하고 게임의 진행 속도를 게임 제공사가 제어할 목적으로 사용됩니다.

	타입	필수	값 제한	설명
staminaName	string	✓	~ 128자	스태미나 모델 이름 이 스태미나 인스턴스의 회복 파라미터, 용량, 테이블 참조를 정의하는 StaminaModel의 이름입니다. 사용자별 스태미나 상태를 대응하는 모델 정의와 연결합니다.
value	int	✓	0 ~ 2147483646	스태미나 값 오버플로우분을 제외한, 이 사용자의 현재 스태미나 양입니다. 회복 간격과 회복량에 기반하여 시간 경과에 따라 자동으로 증가하며, maxValue까지 회복됩니다. lastRecoveredAt로부터의 경과 시간을 사용하여 recoverSteps = elapsedMinutes / recoverIntervalMinutes 식으로 계산됩니다.
overflowValue	int	✓	0 ~ 2147483646	오버플로우 값 통상의 최대값(maxValue)을 초과하여 저장되어 있는 스태미나량입니다. StaminaModel의 isOverflow가 활성화된 경우에만 사용됩니다. 실효 스태미나의 합계는 value + overflowValue이며, maxCapacity가 상한입니다. 스태미나 소비 시 오버플로우분이 먼저 소비됩니다.
maxValue	int	✓	1 ~ 2147483646	스태미나 최대값 StaminaModel로부터 결정되며, 옵션으로 플레이어의 GS2-Experience 랭크에 따라 MaxStaminaTable로 오버라이드되는 사용자별 스태미나 최대값입니다. 오버플로우가 비활성화된 경우 initialCapacity가 하한이 됩니다. 오버플로우가 활성화된 경우 maxCapacity가 상한이 됩니다. 자연 회복은 이 값에서 멈춥니다.
recoverIntervalMinutes	int		1 ~ 2147483646	스태미나 회복 간격(분) StaminaModel로부터 결정되며, 옵션으로 플레이어의 GS2-Experience 랭크에 따라 RecoverIntervalTable로 오버라이드되는 사용자별 회복 간격(분)입니다. 테이블이 설정되어 있지 않은 경우, 모델의 기본값인 recoverIntervalMinutes로 대체됩니다.
recoverValue	int		1 ~ 2147483646	스태미나 회복량 StaminaModel로부터 결정되며, 옵션으로 플레이어의 GS2-Experience 랭크에 따라 RecoverValueTable로 오버라이드되는 사용자별 틱당 회복량입니다. 테이블이 설정되어 있지 않은 경우, 모델의 기본값인 recoverValue로 대체됩니다.
nextRecoverAt	long			다음 회복 시각 다음 스태미나 회복 틱이 발생하는 Unix 타임스탬프(밀리초)입니다. lastRecoveredAt + recoverIntervalMinutes * 60 * 1000으로 계산됩니다. 스태미나가 이미 maxValue인 경우, 이 필드는 설정되지 않을 수 있습니다.

EzStaminaModel

스태미나 모델

GS2-StateMachine SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzStatus

스테이트 머신의 상태

특정 사용자에 대한 스테이트 머신의 실행 인스턴스를 나타냅니다. 변수, 서브 스테이트 머신용 콜 스택, 전이 횟수, 난수 상태를 포함한 현재 실행 상태를 추적합니다. 스테이터스는 Running, Wait, Pass(성공), Error 상태를 전이합니다.

타입

활성화 조건

필수

기본값

값 제한

설명

statusId

string

※

~ 1024자

스테이트 머신 상태 GRN

※ 서버가 자동으로 설정

name

string

✓

UUID

~ 36자

스테이터스 이름

스테이트 머신 상태의 고유한 이름을 보유합니다.
이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 스테이트 머신의 상태를 식별하는 데 사용됩니다.

enableSpeculativeExecution

문자열 열거형
enum {
“enable”,
“disable”
}

“disable”

투기적 실행을 활성화할지 여부

활성화하면 스테이트 머신 정의와 난수 상태가 이 Status 엔티티에 포함됩니다. 이를 통해 클라이언트가 서버 확인 전에 로컬에서 전이를 시뮬레이션할 수 있어 체감 지연을 줄일 수 있습니다.

정의	설명
enable	활성화
disable	비활성화

stateMachineDefinition

string

{enableSpeculativeExecution} == “enable”

~ 16777216자

스테이트 머신 정의

투기적 실행을 위해 이 스테이터스에 포함된 GSL 정의입니다. enableSpeculativeExecution이 활성화된 경우에만 존재합니다. 일반적인 API 응답에서는 필터링되며, 클라이언트 측 시뮬레이션에 필요한 경우에만 포함됩니다.

※ enableSpeculativeExecution이(가) “enable” 이면 활성화

randomStatus

EzRandomStatus

{enableSpeculativeExecution} == “enable”

난수 상태

이 실행 인스턴스의 난수 생성 상태입니다. 투기적 실행 시 클라이언트와 서버에서 결정론적인 난수 동작을 보장하기 위해 사용됩니다. enableSpeculativeExecution이 활성화된 경우에만 존재합니다.

※ enableSpeculativeExecution이(가) “enable” 이면 활성화

stacks

List<EzStackEntry>

[]

0 ~ 1024 items

스택

서브 스테이트 머신 호출의 콜 스택입니다. 스테이트 머신이 서브 스테이트 머신을 호출하면 호출한 쪽의 스테이트 머신 이름과 반환 태스크가 푸시됩니다. 서브 스테이트 머신이 완료되면 엔트리가 팝되고 반환 태스크에서 실행이 재개됩니다.

variables

List<EzVariable>

[]

0 ~ 1000 items

스테이트 머신별 상태 변수

콜 계층 내 각 스테이트 머신의 현재 변수 값입니다. 각 엔트리는 스테이트 머신 이름과, int, float, string, bool, array, map 타입을 지원하는 JSON 직렬화된 값을 보유합니다. 변수는 동일한 실행 인스턴스 내 상태 전이를 거쳐 유지됩니다.

status

문자열 열거형
enum {
  “Running”,
  “Wait”,
  “Pass”,
  “Error”
}

“Running”

스테이터스

이 스테이트 머신 인스턴스의 현재 실행 상태입니다. “Running"은 머신이 전이를 처리 중임을 의미합니다. “Wait"는 머신이 외부 이벤트(emit)를 대기 중임을 의미합니다. “Pass"는 정상적으로 완료되었음을 의미합니다. “Error"는 에러로 종료되었음을 의미합니다.

정의	설명
Running	실행 중
Wait	대기 중
Pass	정상 종료
Error	이상 종료

lastError

string

~ 1024자

마지막 에러

마지막으로 발생한 에러의 메시지입니다. 스테이터스가 “Error"로 전이되었을 때 설정됩니다. 스테이트 머신이 이상 종료된 원인의 상세 내용을 포함합니다.

transitionCount

int

0 ~ 2147483645

전이 횟수

이 실행 인스턴스에서 수행된 상태 전이의 총 횟수입니다. 전이할 때마다 증가합니다. 이 값이 1000을 초과하면 무한 루프를 방지하기 위해 스테이트 머신은 에러로 종료됩니다.

EzStackEntry

스택 엔트리

GS2-Version SDK for Game Engine API 레퍼런스

Mon, 01 Jan 0001 00:00:00 +0000

모델

EzAcceptVersion

승인한 버전

앱 버전이나 에셋 버전처럼 데이터에 연결된 버전이 아니라
동의한 이용약관의 버전처럼 사용자별로 버전 관리가 필요한 엔티티에서 사용합니다.

	타입	필수	값 제한	설명
versionName	string	✓	~ 128자	버전 이름 이 승인 레코드가 연결되어 있는 버전 모델의 이름입니다. 사용자의 승인을 특정 버전 모델 정의에 연결합니다.
userId	string	✓	~ 128자	사용자ID
version	EzVersion	✓		버전 사용자가 승인 또는 거부한 버전 번호입니다. “active” 스코프의 버전 모델에서 사용되는 경우, 버전 체크 시 모델의 현재 버전과 비교됩니다.

EzVersionModel

버전 모델

GS2 UIKit for Unity 튜토리얼

Mon, 01 Jan 0001 00:00:00 +0000

중간까지는 일반적인 튜토리얼과 동일한 절차입니다.

클라이언트 초기화

환경 정보 생성

먼저 환경 정보를 정의하는 ScriptableObject를 생성합니다.

Project에서 컨텍스트 메뉴를 열어 Create > Game Server Services > Core > Environment를 생성합니다.

생성한 ScriptableObject에 크리덴셜(API 키) 생성에서 생성한 clientId / clientSecret을 설정합니다. Name에는 환경 이름을 입력합니다.

클라이언트 홀더 생성

다음으로 GS2 클라이언트를 보유하는 GameObject를 생성합니다.

SDK 설정

Mon, 01 Jan 0001 00:00:00 +0000

이 섹션에서는 Game Engine 용 SDK인 GS2 SDK for Unity, GS2 SDK for Unreal Engine 5, GS2 SDK for Godot 의 설치 절차에 대해 자세히 설명합니다.

GS2 SDK for Unity 설치 절차

GS2 SDK for Unity Installer Version 2024.4.1

위 링크에서 UnityPackage 형식의 설치 프로그램을 다운로드합니다.

새로 Unity 프로젝트를 생성하거나 기존 Unity 프로젝트를 준비하여 Unity Editor 에서 엽니다.

메뉴의 『Assets > Import Package > Custum Packages…』 에서 gs2-unity-installer_2024.4.1.unitypackage 파일을 임포트합니다.

UI Kit을 사용하여 텍스트 채팅 구현

Mon, 01 Jan 0001 00:00:00 +0000

UI 구성

먼저 씬의 전체 모습을 보여드리겠습니다.

화면 상단에 메시지 리스트, 하단에 텍스트 입력 필드와 전송 버튼을 배치했습니다.

컨텍스트

Context 배치에 대해 설명합니다.

A는 GS2-Chat의 룸 컨텍스트입니다.

B는 GS2-Chat의 메시지 리스트 컨텍스트입니다.

C는 GS2-Chat의 메시지 컨텍스트입니다.

구현 해설

메시지 목록 조회

룸 컨텍스트에는 사전에 GS2-Chat에서 생성해 둔 룸의 정보를 설정합니다.

메시지 리스트 컨텍스트에는 2개의 컴포넌트를 붙여 두었습니다.

Gs2ChatMessageListFetcher는 룸 컨텍스트에서 지정된 룸 내 메시지 목록을 조회합니다.

GS2-SDK for UE5 Blueprint 튜토리얼

Mon, 01 Jan 0001 00:00:00 +0000

중간까지는 일반적인 튜토리얼과 동일한 순서로 진행됩니다.

클라이언트 초기화

GS2::Core::Action::Initialize 노드를 생성하고, clientId / clientSecret / 접속할 리전을 설정합니다. clientId / clientSecret 에는 크리덴셜(API 키) 생성 에서 생성한 값을 설정합니다.

초기화에 성공한 경우 OnSuccess 가 호출되고, 실패한 경우 OnError 가 호출됩니다.

성공 시에는 Client 에 GS2 클라이언트 객체가, 실패 시에는 Error 에 실패 사유의 에러 객체가 반환됩니다.

GS2-Account 클라이언트 생성

UI Kit을 사용하여 아이템 인벤토리 구현

Mon, 01 Jan 0001 00:00:00 +0000

UI 구성

먼저 씬의 전체 모습을 보여드리겠습니다.

화면 상단에 인벤토리의 용량 사용 현황을 표시하고, 중앙에 보유 아이템 목록, 하단에 아이템을 입수하는 버튼을 배치했습니다.

컨텍스트

Context 배치에 대해 설명합니다.

A는 GS2-Inventory의 인벤토리 컨텍스트입니다.

B는 GS2-Inventory의 아이템 리스트 컨텍스트입니다.

C는 GS2-Inventory의 아이템 컨텍스트입니다.

D는 GS2-Exchange에서 무상으로 Potion을 입수하는 교환 레이트 컨텍스트입니다.

E는 GS2-Exchange에서 무상으로 Ether를 입수하는 교환 레이트 컨텍스트입니다.

구현 해설

인벤토리의 소비 용량 표시

구현

Mon, 01 Jan 0001 00:00:00 +0000

여기서는 GS2 SDK를 사용하여 계정 생성과 로그인을 수행하는 최소한의 구현 방법을 설명합니다.

각 플랫폼별 전체 코드는 샘플 코드 전문을 확인해 주세요.

Unity에서의 구현에 대해

Unity SDK에서는 비동기 처리에 Coroutine을 사용합니다. 아래 코드 예시는 Coroutine 내부(IEnumerator를 반환하는 메서드 내부)에서 실행하는 것을 상정하고 있습니다.

GS2 SDK 초기화

 // Setup variables

 var clientId = "YourClientId";
 var clientSecret = "YourClientSecret";
 var accountNamespaceName = "game-0001";

 // Setup general setting
 Gs2Domain gs2;
 {
 var future = Gs2Client.CreateFuture(
 new BasicGs2Credential(
 clientId,
 clientSecret
 ),
 Region.ApNortheast1
 );
 yield return future;
 if (future.Error != null) {
 throw future.Error;
 }
 gs2 = future.Result;
 }

	// Setup variables

	const auto ClientId = "YourClientId";
	const auto ClientSecret = "YourClientSecret";
	const auto AccountNamespaceName = "game-0001";

 // Create GS2 client

 const auto InitializeFuture = Gs2::UE5::Core::FGs2Client::Create(
 MakeShared<Gs2::Core::Model::FBasicGs2Credential>(
 ClientId,
 ClientSecret
 ),
 Gs2::Core::Model::ApNorthEast1
 );
 InitializeFuture->StartSynchronousTask();
 if (InitializeFuture->GetTask().IsError())
 {
 UE_LOG(GameLog, Error, TEXT("%s"), ToCStr(InitializeFuture->GetTask().Error()->String()));
 return InitializeFuture->GetTask().Error();
 }
 const auto Gs2 = InitializeFuture->GetTask().Result();

 # Setup variables

 var client_id = "YourClientId"
 var client_secret = "YourClientSecret"
 var account_namespace_name = "game-0001"
 var account_encryption_key_id = "grn:gs2:{region}:{ownerId}:key:account-encryption-key-namespace:key:account-encryption-key"

 # Initialize GS2 SDK

 var credential = Gs2BasicCredential.new(client_id, client_secret)
 var connection = Gs2Connection.new(credential, Gs2Region.AP_NORTHEAST_1)
 var ez = Gs2EzDomain.new(connection)

Setup variables

먼저 4개의 변수를 정의하고 있습니다.