> For the complete documentation index, see [llms.txt](/llms.txt)

# 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



**Unity (UniTask)**
```csharp

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

    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;
```
**Unreal Engine 5**
```cpp

    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();
```
**Godot**
```gdscript

    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.



**Unity (UniTask)**
```csharp

    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
    );
```
**Unity (Vanilla)**
```cs

    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;
```
**Unreal Engine 5**
```cpp

    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();
```
**Godot**
```gdscript

    # 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



**Unity (UniTask)**
```csharp

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

    var userId = account.UserId;
    var password = account.Password;
```
**Unity (Vanilla)**
```cs

    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;
```
**Unreal Engine 5**
```cpp

    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();
```
**Godot**
```gdscript

    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
```


## Login

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



**Unity (UniTask)**
```csharp

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

    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;
```
**Unreal Engine 5**
```cpp

    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();
```
**Godot**
```gdscript

    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
```