Game Engine

how to initialize GS2-SDK for Game Engine

Initializing the SDK

To start using GS2, you must first initialize GS2-SDK. In Unity and Unreal Engine, call Gs2Client.Create to obtain the GS2 client instance, Gs2Domain. In Godot, create a Gs2Connection and then initialize Gs2EzDomain, the root of the Ez domain API. The root exposes stable service properties such as ez.account and ez.inventory, matching the service-oriented shape used by the Unity SDK.

The parameters required for initialization are as follows.

Parameters

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

For Godot, the corresponding types are Gs2BasicCredential and Gs2Region.

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

    var account_namespace_name = "account-namespace-0001"
    var account_encryption_key_id = "grn:gs2:{region}:{ownerId}:key:namespace-0001:key:key-0001"

    var credential = Gs2BasicCredential.new(
        "your client id",
        "your client secret"
    )
    var connection = Gs2Connection.new(
        credential,
        Gs2Region.AP_NORTHEAST_1
    )

    # Establish the REST and WebSocket sessions and validate the credentials.
    var connect_result = await connection.connect_session()
    if connect_result.error != null:
        push_error(str(connect_result.error))
        return

    var ez = Gs2EzDomain.new(connection)

Godot reconnects automatically when an API is called after the connection has been closed. To close both the REST and WebSocket sessions explicitly, call connection.disconnect_session().

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

    # The Godot SDK does not currently provide a Chaos mode API.
    # To test error handling, inject failures in the application or test layer.

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 Password = Account->GetPassword();

    var account_domain = ez.account.namespace_(
        account_namespace_name
    )
    var create_result = await account_domain.create()
    if create_result.error != null:
        push_error(str(create_result.error))
        return

    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
    var user_id = account.user_id
    var password = account.password

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.

Parameters

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 authentication implementation that uses GS2-Account and provides sufficient functionality 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

Godot authentication settings

In Godot, pass the account and optional notification/version settings directly to Gs2AccountAuthenticator. Use the encryption key GRN created in GS2-Key for key_id.

Argument name	Type	Description
account_namespace_name	String	Namespace name of GS2-Account
key_id	String	GRN of the GS2-Key encryption key used for authentication
gateway_namespace_name	String	Namespace name of GS2-Gateway; pass `null` when notifications are not used
allow_concurrent_access	bool	Whether multiple logins with the same user ID are allowed
version_namespace_name	String	Namespace name of GS2-Version; pass `null` when version checking is not used
target_versions	Array	Version information checked by GS2-Version

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

    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