> 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.
You can get a GS2 client instance, `Gs2Domain`, by calling `Gs2Client.Create`.

The parameters required for initialization are as follows.

### Parameters

| 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



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


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


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

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

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