Game Engine

how to initialize GS2-SDK for Game Engine

Initializing the SDK

To start using GS2, you must first initialize GS2-SDK. You can get a GS2 client instance, Gs2Domain, by calling Gs2Client.Create.

The parameters required for initialization are as follows.

Parameter

Argument name	Type	Description
credential	BasicGs2Credential	credential information
region	Region	GS2 region

BasicGs2Credential

Specify the “Client ID” and “Client Secret”. These values are managed by GS2-Identifier.

Region

Specifies the GS2 data center. See region for possible values.

Implementation example

    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();

Chaos mode

By calling the SDK initialization process with chaos mode applied, API requests can be made to fail with a certain probability. Development can proceed using clients with chaos mode enabled to ensure robust error handling.

    var gs2 = await Gs2.Unity.Core.Gs2Client.CreateChaosAsync(
        new Gs2.Core.Model.BasicGs2Credential(
            "your client id",
            "your client secret"
        ),
        0.1f, // 10% chance of error requiring a retry when making an API request
        Gs2.Core.Model.Region.ApNortheast1
    );

    var future = Gs2.Unity.Core.Gs2Client.CreateChaosFuture(
        new Gs2.Core.Model.BasicGs2Credential(
            "your client id",
            "your client secret"
        ),
        0.1f, // 10% chance of error requiring a retry when making an API request
        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::CreateChaos(
        MakeShared<Gs2::Core::Model::FBasicGs2Credential>(
            "your client id",
            "your client secret"
        ),
        0.1f, // 10% chance of error requiring a retry when making an API request
        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();

Create an account

Many GS2 features require players to login by specifying their GS2-Account account information. In order to log in, an account must be created.

To create an account, use Gs2Domain::Account::Namespace()::Create.

Parameter

Argument name	Type	Description
namespaceName	string	GS2-Account’s namespace name

Implementation example

    var account = await (
        await gs2.Account.Namespace(
            this.accountNamespaceName
        ).CreateAsync()
    ).ModelAsync();

    var userId = account.UserId;
    var password = account.Password;

    var future = gs2.Account.Namespace(
        this.accountNamespaceName
    ).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;
    }
    var account = future2.Result;

    var userId = account.UserId;
    var password = account.Password;

    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();
    }

    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();

    auto UserId = Account->GetUserId();
    auto Uassword = Account->GetPasswordId();

Log in

Now that you have initialized the SDK and created your account, you are ready to login. You can use Gs2Domain::Login to perform the login.

As a result, you will get a GameSession object. Many APIs require a GameSession to be passed, which gives you access to the user data of the player who is logging in.

Parameter

Argument name	Type	Description
authenticator	IAuthenticator	implementation used for authentication process (GS2-Account)
userId	string	userID
password	string	password

IAuthenticator

The authentication process is interface-defined and can be implemented without using GS2-Account, replacing it with authentication on your own authentication infrastructure.

Gs2AccountAuthenticator

Gs2AccountAuthenticator is an implementation that authenticates with GS2-Account, which is sufficient for common use cases.

Argument Name	Type	Description
accountSetting	AccountSetting	Information to authenticate with GS2-Account
gatewaySetting	GatewaySetting	Information for receiving notifications via GS2-Gateway
versionSetting	VersionSetting	Information to check the version with GS2-Version

AccountSetting

Argument Name	Type	Description
accountNamespaceName	string	Namespace name of the GS2-Account
keyId	string	Encryption key ID of GS2-Key used for authentication process (if omitted, the default encryption key is used)

GatewaySetting

Argument Name	Type	Description
gatewayNamespaceName	string	Namespace name of GS2-Gateway (default namespace is used if omitted)
allowConcurrentAccess	bool	Whether multiple logins with the same user ID are allowed (default: true)

VersionSetting

VersionSetting can be applied to automatically perform a version check using GS2-Version at login or session reconnection. If an error occurs as a result of the version check, the event handler registered with Gs2AccountAuthenticator::onDetectVersionUp will be called.

Argument name	Type	Description
versionNamespaceName	string	GS2-Version namespace name (if omitted, no version check is performed)
targetVersions	EzTargetVersion	game version information

Implementation example

    var gameSession = await gs2.LoginAsync(
        new Gs2AccountAuthenticator(
            accountSetting: new AccountSetting {
                accountNamespaceName = this.accountNamespaceName,
            }
        ),
        account.UserId,
        account.Password
    );

    var future = gs2.LoginFuture(
        new Gs2AccountAuthenticator(
            accountSetting: new AccountSetting {
                accountNamespaceName = this.accountNamespaceName,
            }
        ),
        account.UserId,
        account.Password
    );
    yield return future;
    if (future.Error != null) {
        throw future.Error;
    }
    var gameSession = future.Result;

    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();