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 nameTypeDescription
credentialBasicGs2Credentialcredential information
regionRegionGS2 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 nameTypeDescription
namespaceNamestringGS2-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 nameTypeDescription
authenticatorIAuthenticatorimplementation used for authentication process (GS2-Account)
userIdstringuserID
passwordstringpassword

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 NameTypeDescription
accountSettingAccountSettingInformation to authenticate with GS2-Account
gatewaySettingGatewaySettingInformation for receiving notifications via GS2-Gateway
versionSettingVersionSettingInformation to check the version with GS2-Version

AccountSetting

Argument NameTypeDescription
accountNamespaceNamestringNamespace name of the GS2-Account
keyIdstringEncryption key ID of GS2-Key used for authentication process (if omitted, the default encryption key is used)

GatewaySetting

Argument NameTypeDescription
gatewayNamespaceNamestringNamespace name of GS2-Gateway (default namespace is used if omitted)
allowConcurrentAccessboolWhether 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 nameTypeDescription
versionNamespaceNamestringGS2-Version namespace name (if omitted, no version check is performed)
targetVersionsEzTargetVersiongame 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();